Claude Code CLI Persistent Memory

Give the Claude Code CLI assistant persistent, local-only memory across different terminal sessions and shell environments.

Claude Code supports stdio-based MCP servers natively using simple commands in your terminal. No external signup is needed to use the local memory tier.

Installation

To add the sovseal-memory server to Claude Code, execute the following command in your terminal:

claude mcp add sovseal-memory npx -y @sovseal/mcp-server

This command will download the @sovseal/mcp-server package and add its stdio transport mapping to Claude Code's config.

Verifying the Installation

To verify that Claude Code can interact with the memory node:

Run claude in your terminal to start an interactive session.
Verify the available tools by typing:
```
/tools
```
You should see store_memory and recall_memory in the active tool list.
Test the memory lifecycle by running the onboard tool command:
```
/mem0:onboard
```
(Note: The onboard command validates that the embedding model successfully warms up and LanceDB local commits pass successfully.)

Configuration Details

Claude Code stores its configured MCP servers in a JSON configuration file. You can inspect or modify it manually:

Location: ~/.claude.json (or platform equivalent)

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

How It Works

Warmup and Cache

Upon your first tool execution or startup, Claude Code will trigger the initialization. The server:

Warmups the embedding pipeline using the CPU-bound Xenova/all-MiniLM-L6-v2 model.
If not already cached, it downloads the model parameters (~22 MB) directly to ~/.sovseal/models/.
Validates model integrity using SHA-256 pins.

Memory Storage

All memories are saved securely on your device inside a serverless LanceDB table:

Location: ~/.sovseal/db/memories.lance
Key data is encrypted using client-side AES-256-GCM if you choose to enable the write-behind background replication worker to sync encrypted snapshots to the cloud.