Claude Desktop Persistent Memory

Give Claude Desktop persistent, local-only memory via the sovseal MCP server.

Installation

Add the sovseal-memory configuration block to your Claude Desktop configuration file:

Configuration File Paths

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

Add the following JSON configuration:

{
  "mcpServers": {
    "sovseal-memory": {
      "command": "npx",
      "args": ["-y", "@sovseal/mcp-server"]
    }
  }
}

Restart your Claude Desktop application. The store_memory and recall_memory tools will now appear in your Claude Chat UI.

Under the Hood: Warmup & Local Files

1. Model Warmup on First Launch

On the very first launch, the MCP server will download the quantized Xenova/all-MiniLM-L6-v2 embedding model (~22 MB).

• The model files are cached on disk at ~/.sovseal/models/.
• During this download, Claude Desktop might show a loading spinner for the tool. Warmup takes between 5 to 30 seconds depending on your connection speed.
• Subsequent startups are instant (sub-25ms) as the model is loaded entirely from your local cache on your CPU.

2. Local Database Location

All stored memories are written to an on-device serverless vector database:

• Location: ~/.sovseal/db/memories.lance (a LanceDB vector store).
• Because LanceDB operates serverless, no local database daemon or connection management is required.

Verifying the Installation

To verify that the memory layer is working, ask Claude Desktop a direct personal fact in a chat session:

1. Store a fact:

   User: "Keep in mind that I prefer working on TypeScript projects using ESLint."

   Claude Desktop should call store_memory with:

   {
     "content": "User prefers working on TypeScript projects using ESLint"
   }

   The tool returns { "success": true, "id": "<uuid>" }.

2. Recall the fact: Start a brand new chat session to clear the active context, and ask:

   User: "What is my preferred programming stack?"

   Claude will call recall_memory with:

   {
     "query": "preferred programming stack"
   }

   It will retrieve your stored preference and personalize the answer.

Configuring Cloud Replication

By default, memories are stored only on your local disk. If you want multi-device synchronization, you can enable server-blind replication.

1. Generate a project token and write-behind credentials from your sovseal Dashboard.
2. Set the variables in your shell environment, or add them directly to your ~/.sovseal/config.json:

{
  "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 stores the AES-256-GCM ciphertext, meaning your data remains completely private.

Troubleshooting

MCP Server Fails to Connect

• Check node version: Ensure Node.js >= 20.0.0 is installed and globally accessible in your system path.
• Log Verification: Open your Claude Desktop log file to inspect 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 node binary or shell wrapper.