> ## 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.

# Give Claude Code CLI Persistent Memory via sovseal

> Add the sovseal MCP server to Claude Code in one terminal command so the CLI remembers context across every session and shell environment.

sovseal gives the Claude Code CLI a persistent memory layer that works across terminal sessions, shell environments, and machine restarts. Because Claude Code supports stdio-based MCP servers natively, you can wire up the entire integration with a single command — no external signup required for the free local-only tier.

## Installation

Run the following command in any terminal to register the sovseal MCP server with Claude Code:

```bash theme={null}
claude mcp add sovseal-memory npx -y @sovseal/mcp-server@0.3.8
```

This command downloads the `@sovseal/mcp-server` package and adds its stdio transport mapping to Claude Code's configuration. The entry is saved to `~/.claude.json` automatically.

## Verify the installation

<Steps>
  <Step title="Start an interactive Claude Code session">
    Open a new terminal and run:

    ```bash theme={null}
    claude
    ```
  </Step>

  <Step title="List available tools">
    Inside the interactive session, type:

    ```text theme={null}
    /tools
    ```

    You should see `store_memory` and `recall_memory` listed among the active tools.
  </Step>

  <Step title="Run the onboard validation prompt">
    In your Claude Code session, prompt Claude to store and recall a test fact:

    ```text theme={null}
    "Remember that our stack uses Vite and React in apps/dashboard, then recall what framework we use."
    ```

    Claude will execute `store_memory` followed by `recall_memory`, confirming the ONNX embedding pipeline warmed up and LanceDB local commits pass.
  </Step>
</Steps>

## Configuration file location

Claude Code persists its MCP server registrations in a JSON file you can inspect or edit manually:

* **Location:** `~/.claude.json`

The sovseal entry looks like this:

```json ~/.claude.json theme={null}
{
  "mcpServers": {
    "sovseal-memory": {
      "command": "npx",
      "args": ["-y", "@sovseal/mcp-server@0.3.8"]
    }
  }
}
```

## How it works

### Warmup and model cache

On first tool execution, the MCP server:

1. Starts the embedding pipeline using the CPU-bound `Xenova/all-MiniLM-L6-v2` model (\~22 MB).
2. Downloads the ONNX model parameters to `~/.sovseal/models/` if they are not already cached.
3. Validates model integrity with SHA-256 pins (`ensureAndVerifyModel`) before accepting any requests.

After the initial download, all subsequent loads complete from disk cache in under 25 ms.

### Memory storage

Every memory you store is written to a serverless LanceDB table at `~/.sovseal/db/memories.lance`. No local database daemon is required. If you enable the write-behind replication worker, the client encrypts data with AES-256-GCM before any bytes leave your device, so the remote endpoint only ever stores ciphertext.

<Note>
  The cold start download (\~22 MB) happens only once. After the model is cached, you will not notice any startup delay between sessions.
</Note>