> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# @sovseal/mcp-server: MCP Tools for AI Client Memory

> Reference for @sovseal/mcp-server — stdio transport config, key custody, store_memory and recall_memory tool schemas, and the bundled sovseal CLI.

The `@sovseal/mcp-server` package runs a local Model Context Protocol server over stdio, giving AI clients like Claude Desktop, Claude Code, Cursor, Windsurf, and Antigravity persistent zero-knowledge memory with 0 RTT local latency on every read or write. The embedding model (`Xenova/all-MiniLM-L6-v2`, SHA-256-pinned) and the LanceDB vector index live entirely on your device — no plaintext ever reaches a remote server.

## Stdio transport configuration

Register the server with your AI client by adding a single JSON block to its configuration file. The server launches on demand via `npx` and communicates over stdin/stdout.

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "sovseal": {
      "command": "npx",
      "args": [
        "-y",
        "@sovseal/mcp-server@0.3.8"
      ],
      "env": {
        "SOVSEAL_PROJECT_ID": "sov_proj_00000000-0000-4000-8000-000000000000",
        "SOVSEAL_VERBOSE": "true"
      }
    }
  }
}
```

Place this block in the appropriate config file for your client:

| Client         | Config file location                                                      |
| -------------- | ------------------------------------------------------------------------- |
| Claude Code    | Run `claude mcp add sovseal-memory npx -y @sovseal/mcp-server@0.3.8`      |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
| Cursor         | `~/.cursor/mcp.json`                                                      |
| Windsurf       | `~/.codeium/windsurf/mcp_config.json`                                     |

## Key custody

sovseal uses a layered key custody model so that your encryption master key is never stored in a plaintext configuration file:

* **OS keychain**: The master key is held in the operating system keychain (`@napi-rs/keyring`: macOS Keychain, GNOME Secret Service, or Windows Credential Manager).
* **HKDF subkeys**: Derived per purpose — `k_rest` for local LanceDB at-rest encryption and `k_sync` for replication.
* **Headless hosts**: Set `SOVSEAL_KEY_FALLBACK=file` to use 0600 file permissions fallback when an OS keychain is unavailable.

## Tool reference

### `store_memory`

Masks high-risk PII (SSN, Luhn-validated credit cards, API keys) → embeds (384-dim) on cleaned text → encrypts `text` at rest (`k_rest`) → writes to local LanceDB index. Exact duplicate facts increment `reinforce_count` rather than inserting a duplicate row.

**Parameters**

<ParamField body="content" type="string" required>
  A self-contained, third-person factual statement to store (e.g., `"User prefers TypeScript and Vite for dashboard apps"`).
</ParamField>

**Example MCP response**

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"success\": true,\n  \"id\": \"7a8b9c0d-e1f2-3a4b-5c6d-7e8f9a0b1c2d\",\n  \"reinforced\": false,\n  \"redacted\": 0,\n  \"redactedRules\": []\n}"
    }
  ]
}
```

***

### `recall_memory`

Embeds query → over-fetches 8×K candidates by vector distance → re-ranks candidates by composite score:

$\text{score} = \text{similarity} \times \text{decay} \times \text{reinforcement}$

Returns top-K `{id, text, score}` with 0 network round-trips.

**Parameters**

<ParamField body="query" type="string" required>
  Natural-language search string (e.g., `"frontend stack preferences"`).
</ParamField>

<ParamField body="topK" type="integer">
  Number of results to return (1–20, default 5).
</ParamField>

## `sovseal` CLI

The package also installs a `sovseal` binary, so the same build that serves MCP tools gives you terminal access to the identical vault — memory commands, health diagnostics, and device linking. See the [CLI reference](/sdk-reference/cli) for the full surface.

```bash theme={null}
npx -y --package=@sovseal/mcp-server sovseal doctor
```

The most-used subcommand is `mind`, a one-shot token-budgeted digest (\~1,200 tokens) of your local memory store that never starts the stdio server:

```bash theme={null}
sovseal mind
```

Prints two sections:

1. **Core Mind State** — procedural & semantic memories ranked by composite score.
2. **Recurring Patterns** — memories reinforced more than once (`reinforce_count > 1`).

For scripts and agents, every command accepts `--json` and emits a structured envelope; `sovseal help --json` publishes the entire command tree as machine-readable data.

## MCP Resources

| Resource URI                 | Purpose                                                                    |
| ---------------------------- | -------------------------------------------------------------------------- |
| `sovseal://context/briefing` | Returns the full `sovseal mind` digest for session-start prompt injection. |
| `sovseal://context/recent`   | **Deprecated.** Superseded by `sovseal://context/briefing`.                |