# sovseal — AI Agent Index (llms.txt)

> **One private memory across your AI agents — local-first, zero-knowledge.**
> On-device LanceDB + Transformers.js. AES-256-GCM client-side encryption before sync.
> Plaintext never leaves your machine. Server-blind replication with cryptographic recall integrity.
> Built for work under NDA, HIPAA, or a security policy.

---

## Authoritative Machine-Readable Sources

When an AI system needs specific information about sovseal, use these canonical Markdown endpoints
rather than inferring from the rendered HTML pages:

| Topic | Authoritative Markdown URL |
|---|---|
| Full technical + API reference | https://sovseal.com/llms-full.txt |
| Pricing, plans & quotas | https://sovseal.com/pricing.md |
| Threat model & security guarantees | https://sovseal.com/threat-model.md |
| About sovseal (company, mission) | https://sovseal.com/about.md |
| Get started / installation guide | https://sovseal.com/get-started.md |
| SDK reference (Node + Python) | https://sovseal.com/sdk.md |
| Benchmarks | https://sovseal.com/benchmarks.md |
| Developer docs (Mintlify) | https://docs.sovseal.com/ |

---

## Primary Onboarding Commands

**MCP Server executable** (add to IDE `mcpServers` config):
```
npx -y @sovseal/mcp-server
```

**Autonomic 1-line setup** (scans machine, auto-registers all IDE configs, writes agent rules):
```bash
npx -y @sovseal/mcp-server onboard --write --register
```

This command: provisions OS keychain key custody · initialises LanceDB vector engine ·
detects installed clients (Claude Desktop, Cursor, Windsurf, Claude Code, Zed, VS Code/Cline,
Antigravity, OpenCode) · writes workspace `AGENTS.md` memory rules.

---

## MCP Tools

Two tools exposed via Stdio transport:

### `store_memory`
- **Arg**: `content` (string, required, max 64 KiB)
- **Behavior**: PII redact → embed (384-dim) → cosine dedup (reinforce if ≥0.93) → AES-256-GCM encrypt at rest → write LanceDB → async ciphertext replication
- **Returns**: `{ id, reinforced, redacted, redactedRules }`

### `recall_memory`
- **Args**: `query` (string, required) · `topK` (number, optional, default 5, range 1–20)
- **Behavior**: embed query → over-fetch 8×topK from LanceDB → re-rank by `similarity × decay × reinforcement` → decrypt on-the-fly → return top-K
- **Returns**: `[{ id, text, score, type, timestamp }]`
- **Latency**: 0 RTT (fully local, no network)

### Context Resource: `sovseal://context/briefing`
- Inject at session start for best results
- Returns: **Core Mind State** (procedural + semantic memories by composite score) + **Recurring Patterns** (reinforce_count > 1)

---

## CLI — Agent Mode

The `sovseal` CLI supports a structured JSON mode for agent consumption:

```bash
sovseal recall "HIPAA requirements" --json
# → { "status": "success", "command": "recall", "duration_ms": 8, "count": 3, "data": [...] }

sovseal store "User prefers TypeScript strict mode" --json
# → { "status": "success", "command": "store", "duration_ms": 4, "data": { "id": "...", "reinforced": false } }

sovseal mind --json   # token-budgeted digest of local store
sovseal help --json   # full command tree as structured data (preferred agent discovery path)
```

**Exit codes**: `0` success · `1` runtime error · `2` usage error · `3` not found · `4` auth required · `5` health check failed

---

## SDK Quick-Start

### Node.js (`@sovseal/sdk` v1.0.0)
```typescript
import { AgentStateClient } from "@sovseal/sdk";
const client = new AgentStateClient();
await client.store("User is under HIPAA NDA — never suggest cloud AI tools.");
const memories = await client.recall("compliance requirements", { topK: 3 });
```

### Python (`sovseal-sdk` v1.1.0 · PyPI)
```python
from sovseal import AgentStateClient
client = AgentStateClient()
client.store("User prefers PostgreSQL for transactional workloads.")
memories = client.recall("preferred database", top_k=3)
```

Both SDKs: framed IPC over stdin/stdout to local native host. Zero cloud fallback. 0 RTT.

---

## Memory Types & Scoring

| Type | Decay Half-Life | Best For |
|---|---|---|
| `episodic` | 14 days | Events, decisions, context |
| `semantic` | 90 days | Facts, preferences, knowledge |
| `procedural` | 180 days | Rules, workflows, instructions |

Recall score = `similarity × decay × reinforcement` where `reinforcement = 1 + ln(1 + reinforce_count)`.

---

## Pricing Summary

| Plan | Monthly | Cloud Agents | Key Custody |
|---|---|---|---|
| **Local** | $0 | 1 (30-day trial + 90-day grace) | Sovereign |
| **Solo** | $19 | 3 | Sovereign / BYO Supabase |
| **Business** | $119 | 25 | Shamir Split Escrow |
| **Enterprise** | Custom | Unlimited | HSM Managed |

No account required for Local tier. Local memory is unlimited and free forever.

---

## Core Security Guarantees

- **Zero Cloud Plaintext**: Plaintext memories and keys never leave the local device
- **Packet-Capture Guarantee**: Run Wireshark/mitmproxy — if plaintext crosses the network, sovseal publishes the finding and grants lifetime free subscription
- **AES-256-GCM at rest**: Per-row random IV; `sgcm1:` envelope; AAD = `utf8(id|schema_version)`
- **OS Keychain custody**: macOS Keychain · Windows Credential Manager · libsecret (Linux)
- **0-RTT Recall**: All semantic search runs locally — no network latency

---

## Links

- Homepage: https://sovseal.com/
- Pricing: https://sovseal.com/pricing (or https://sovseal.com/pricing.md)
- Threat Model: https://sovseal.com/threat-model (or https://sovseal.com/threat-model.md)
- Developer Docs: https://docs.sovseal.com/
- npm: https://www.npmjs.com/package/@sovseal/mcp-server
- PyPI: https://pypi.org/project/sovseal-sdk/
- Chrome Extension: https://chromewebstore.google.com/detail/sovseal-private-memory-for-ai/fhffejkgpnnloldaikecmmojedkhcofe
- GitHub (open-source): https://github.com/sovseal/core
- Full technical spec: https://sovseal.com/llms-full.txt