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

# Persistent Dev Session Memory with Claude and Cursor

> Wire sovseal's local MCP server into Claude Desktop and Cursor for cross-session state persistence with zero cloud exposure of your codebase.

Every time you quit Claude Desktop or restart Cursor, your assistant forgets the architectural decisions, migration constraints, and config paths you spent the last hour explaining. sovseal solves this by running a local Model Context Protocol (MCP) server that persists those facts in an on-disk LanceDB vector store — encrypted at rest, recalled in \~6.1 ms, and never uploaded to a cloud database in plaintext. This cookbook walks you through the complete setup for both Claude Desktop and Cursor, including the system prompt rules that make recall automatic rather than manual.

## Why Session Memory Matters for Coding Assistants

Without persistent memory, every new chat window is a blank slate. You re-explain your stack, re-state constraints ("use Prisma, never raw SQL"), and re-describe folder layouts. With sovseal as a background MCP server:

* **Design decisions persist** — migration plans, chosen libraries, and tradeoffs survive restarts.
* **Stack constraints are recalled automatically** — the agent queries memory at the start of each task.
* **Config paths are always known** — schema files, env files, and service URLs are stored as structural facts.
* **Your IP stays local** — proprietary code layouts and internal service names are stored in LanceDB on your machine, not in a SaaS database.

<Note>
  sovseal stores plaintext locally in `~/.sovseal/db/memories.lance`. If you enable cloud sync, only AES-256-GCM ciphertext is transmitted — the server never sees your raw code context.
</Note>

## Setup

<Steps>
  <Step title="Install the MCP server">
    The sovseal MCP server ships as an npm package and runs on-demand via `npx`. You don't need a separate install step — the configuration blocks below pull the latest version automatically. If you want to pin a version for reproducibility, replace `@sovseal/mcp-server` with `@sovseal/mcp-server@0.3.8`.
  </Step>

  <Step title="Configure Claude Desktop">
    Open the Claude Desktop configuration file in your text editor:

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

    Add the `sovseal` block inside `mcpServers`:

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

    There's no encryption-key environment variable to set — the master key is generated on first run and held in your OS keychain automatically. See [Key Management & Custody](/components/encryption/key-derivation).

    Restart Claude Desktop. The `store_memory` and `recall_memory` tools will appear automatically in the active model's tool shelf.
  </Step>

  <Step title="Configure Cursor IDE">
    1. Open **Settings → Features → MCP**.
    2. Click **+ Add New MCP Server**.
    3. Fill in the form:

    | Field   | Value                        |
    | ------- | ---------------------------- |
    | Name    | `sovseal`                    |
    | Type    | `stdio`                      |
    | Command | `npx -y @sovseal/mcp-server` |

    4. Save and confirm the status indicator turns green. Cursor will now pass `store_memory` and `recall_memory` as available tools to your active model.

    <Tip>
      You can also add sovseal to your Cursor project's `.cursor/mcp.json` to version-control the configuration alongside your codebase, so every team member gets the same memory setup automatically.
    </Tip>
  </Step>

  <Step title="Add proactive recall rules">
    To make the assistant query memory automatically — without you typing "remember" or "recall" — add the following instruction block to your Claude system prompt or your Cursor `.cursorrules` file:

    ```text .cursorrules (or Claude system prompt) theme={null}
    # Persistent Memory Instructions
    You are connected to a local `sovseal` memory server containing developer
    state across editor sessions.

    ## Execution Rules:
    1. At the start of every conversation or task, immediately call `recall_memory`
       with queries like "active project layout", "recent decisions", or
       "workflow instructions".
    2. When the user explains an architectural decision, completes a task, or
       sets a project preference, call `store_memory` with a concise fact
       (e.g., "The project uses Prisma, with schema at /db/schema.prisma").
    3. Do not store temporary variables, syntax errors, or intermediate logs.
       Only store structural facts and decisions.
    ```
  </Step>

  <Step title="Test the setup">
    Start a new chat in Claude Desktop or Cursor and state a constraint:

    > "We are migrating from Express to NestJS. The database uses PostgreSQL. Do not write any raw SQL — always use Prisma."

    The assistant calls `store_memory` and commits the fact locally in \~3.8 ms. Close the chat window completely, open a new one, and ask:

    > "What are the rules for writing database queries in this project?"

    The assistant calls `recall_memory`, and the local vector search returns the constraint in \~6.1 ms:

    > "Since you are migrating to NestJS and PostgreSQL, all database access must go through Prisma. Raw SQL queries are prohibited."

    You've confirmed end-to-end cross-session persistence.
  </Step>
</Steps>

## What Gets Remembered

The system prompt rules above instruct the assistant to store only **structural facts** — information that remains true across multiple sessions and affects how code should be written. Good examples:

<CodeGroup>
  ```text Stack choice theme={null}
  "The project uses Prisma, with schema at /db/schema.prisma."
  ```

  ```text Architectural decision theme={null}
  "Project migration state: Express to NestJS. DB: PostgreSQL.
  Constraint: Use Prisma for database access, no raw SQL."
  ```

  ```text Config paths theme={null}
  "The main environment file is at .env.local. The Docker
  Compose file lives at infra/docker-compose.yml."
  ```

  ```text Design decision theme={null}
  "All API routes follow REST conventions except /ws/*, which
  uses WebSocket over the /realtime path."
  ```
</CodeGroup>

The assistant will **not** store temporary variables, syntax error messages, linter output, or intermediate debugging logs — only facts that affect future work.

## Managing and Pruning Context

sovseal stores your memory index as an on-disk LanceDB database. You can inspect and clean it directly:

| Item                        | Path                           |
| --------------------------- | ------------------------------ |
| Memory database             | `~/.sovseal/db/memories.lance` |
| Config and project mappings | `~/.sovseal/config.json`       |

<Warning>
  `~/.sovseal/config.json` holds your project ID and endpoint configuration. Keep this file secure (`chmod 600`) and out of version control.
</Warning>

To wipe all stored memories and start fresh:

```bash theme={null}
rm -rf ~/.sovseal/db/memories.lance
```

To get a token-budgeted summary of everything the agent currently "knows" — useful for auditing before a new project phase:

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

This prints a ranked digest of procedural and semantic memories (\~1,200 tokens) and exits without starting the full server.