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

# Add Persistent Memory to Claude Desktop with sovseal

> Configure the sovseal MCP server in Claude Desktop to give Claude local-first, zero-knowledge memory that persists across every chat session.

sovseal turns Claude Desktop into a personalized assistant that remembers your preferences, project constraints, and past decisions — without ever sending that data to a third-party service. Setup requires a single JSON block in `claude_desktop_config.json`. No email signup or API key is needed for the free local-only tier. On first launch, sovseal automatically creates `~/.sovseal/config.json` containing a local project token and a secure AES-256 encryption key, both of which stay exclusively on your device.

## Installation

<Steps>
  <Step title="Open your Claude Desktop configuration file">
    Locate the config file for your operating system:

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
    * **Linux:** `~/.config/Claude/claude_desktop_config.json`

    Create the file if it does not already exist.
  </Step>

  <Step title="Add the sovseal-memory server block">
    Paste the following JSON into `claude_desktop_config.json`. If the file already has an `mcpServers` key, add the `sovseal-memory` entry inside the existing object.

    ```json claude_desktop_config.json theme={null}
    {
      "mcpServers": {
        "sovseal-memory": {
          "command": "npx",
          "args": ["-y", "@sovseal/mcp-server"]
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Fully quit and relaunch the application. The `store_memory` and `recall_memory` tools will appear in your Claude Chat UI once the server connects successfully.
  </Step>
</Steps>

<Note>
  **Cold start on first run:** The MCP server downloads the quantized `Xenova/all-MiniLM-L6-v2` embedding model (\~22 MB) the very first time it launches. Claude Desktop may show a loading spinner for 5–30 seconds depending on your connection speed. All subsequent startups load the model from the local cache at `~/.sovseal/models/` in under 25 ms.
</Note>

## Verify the installation

Test the full store-and-recall cycle to confirm the memory layer is working.

<Steps>
  <Step title="Store a fact">
    In a new chat session, tell Claude something you want it to remember:

    > *"Keep in mind that I prefer working on TypeScript projects using ESLint."*

    Claude should call `store_memory` with the following payload and return `{ "success": true, "id": "<uuid>" }`:

    ```json theme={null}
    {
      "content": "User prefers working on TypeScript projects using ESLint"
    }
    ```
  </Step>

  <Step title="Recall the fact in a fresh session">
    Start a **brand-new** chat session to clear the active context window, then ask:

    > *"What is my preferred programming stack?"*

    Claude will call `recall_memory` with `{ "query": "preferred programming stack" }` and return a personalized answer based on what you stored.
  </Step>
</Steps>

## Local storage details

All stored memories are written to an on-device serverless vector database at `~/.sovseal/db/memories.lance` (a LanceDB vector store). Because LanceDB operates serverlessly, no local database daemon or connection management is required.

## Configure cloud replication (optional)

By default, memories live only on your local disk. If you want encrypted multi-device sync, you can enable server-blind replication from the [sovseal Dashboard](https://sovseal.com/dashboard).

<Steps>
  <Step title="Generate credentials">
    Create a project token and write-behind API key from the [sovseal Dashboard](https://sovseal.com/dashboard).
  </Step>

  <Step title="Add credentials to your sovseal config">
    Set the values in `~/.sovseal/config.json`:

    ```json ~/.sovseal/config.json theme={null}
    {
      "schema_version": 1,
      "project_id": "your-project-uuid",
      "api_key": "sov_live_your-api-key",
      "endpoint": "https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state"
    }
    ```

    Replication runs in the background. The server only ever stores AES-256-GCM ciphertext — your plaintext data never leaves your device.
  </Step>
</Steps>

## Troubleshooting

**MCP server fails to connect**

* **Node.js version:** Ensure Node.js `>= 20.0.0` is installed and accessible on your system `PATH`. Run `node -v` in a terminal to verify.
* **Check the log file** for connection errors:
  * macOS: `~/Library/Logs/Claude/mcp.log`
  * Windows: `%APPDATA%\Claude\Logs\mcp.log`
* If you see `npx: command not found`, specify the absolute path to your `npx` binary in the `command` field.