Claude Memory MCP

A persistent memory layer for Claude Code that stores knowledge across sessions. Operates as an MCP (Model Context Protocol) server with optional PostgreSQL API backend and Vault integration for secrets.

Operating Modes

Mode	Storage	Auth	Use Case
Local	SQLite + FTS5	None	Single user, local Claude Code
Server	PostgreSQL via HTTP API	API key	Remote access, multi-session
Full	PostgreSQL + Vault	API keys + Vault	Multi-user, team deployment

Setting Up a New Agent

1. Install the package

pip install claude-memory-mcp

Or install from source for development:

git clone https://github.com/ViktorBarzin/claude-memory-mcp.git
cd claude-memory-mcp
pip install -e .

2. Choose your mode and configure

Local Mode (SQLite, zero config)

No server needed. Memories are stored in a local SQLite database.

Add to your Claude Code MCP settings (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "claude_memory.mcp_server"]
    }
  }
}

The database defaults to ~/.claude/claude-memory/memory/memory.db. Override with:

{
  "env": {
    "MEMORY_HOME": "/path/to/memory/dir"
  }
}

Server Mode (shared PostgreSQL API)

Point the MCP server at a running API instance. This allows multiple sessions/machines to share the same memory.

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "claude_memory.mcp_server"],
      "env": {
        "MEMORY_API_URL": "https://claude-memory.example.com",
        "MEMORY_API_KEY": "your-api-key"
      }
    }
  }
}

Full Mode (with Vault for secrets)

Same as Server Mode but with Vault for automatic credential detection and secure storage:

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "claude_memory.mcp_server"],
      "env": {
        "MEMORY_API_URL": "https://claude-memory.example.com",
        "MEMORY_API_KEY": "your-api-key",
        "VAULT_ADDR": "https://vault.example.com",
        "VAULT_TOKEN": "your-vault-token"
      }
    }
  }
}

3. Verify it works

Start a Claude Code session and test:

> Store a test memory: "Claude Memory MCP is working"
> Recall memories about "Claude Memory"

You should see the MCP tools memory_store, memory_recall, memory_list, memory_delete, and secret_get available.

Environment Variable Aliases

For backward compatibility, these aliases are supported:

Primary	Alias
MEMORY_API_URL	CLAUDE_MEMORY_API_URL
MEMORY_API_KEY	CLAUDE_MEMORY_API_KEY

Running the API Server

Docker Compose (recommended)

cd docker
docker compose up -d

This starts the API + PostgreSQL. Vault is available as an optional profile:

docker compose --profile vault up -d

Manual

pip install claude-memory-mcp[api]

export DATABASE_URL="postgresql://user:pass@localhost:5432/claude_memory"
export API_KEY="your-secret-key"

# Run migrations
alembic upgrade head

# Start server
uvicorn claude_memory.api.app:app --host 0.0.0.0 --port 8000

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	Required
API_KEY	Single-user API key	None
API_KEYS	Multi-user JSON map {"user": "key"}	None
VAULT_ADDR	Vault server address	None
VAULT_TOKEN	Vault authentication token	None
MEMORY_ENCRYPTION_KEY	AES-256 key (hex or passphrase) for non-Vault encryption	None

Multi-User Setup

For team deployments, use API_KEYS with a JSON mapping:

export API_KEYS='{"alice": "key-alice-xxx", "bob": "key-bob-yyy"}'

Each user gets isolated memory storage — users cannot see each other's memories. Each agent/user gets their own API key in their MCP config.

Adding a new user

1. Generate a key: openssl rand -base64 32
2. Add to API_KEYS: {"existing": "...", "newuser": "generated-key"}
3. Restart the API server
4. Give the new user their MCP config with their key

MCP Tools

Tool	Description
memory_store	Store a fact with category, tags, importance, and expanded keywords
memory_recall	Search memories using full-text search with expanded query terms
memory_list	List recent memories, optionally filtered by category
memory_delete	Delete a memory by ID
secret_get	Retrieve the actual content of a sensitive/redacted memory

API Reference

Health Check

GET /health

Store Memory

POST /api/memories
Authorization: Bearer <api-key>

{"content": "...", "category": "facts", "tags": "tag1,tag2", "expanded_keywords": "related terms", "importance": 0.8}

Recall Memories

POST /api/memories/recall
Authorization: Bearer <api-key>

{"context": "search terms", "expanded_query": "additional search terms", "category": "facts", "limit": 10}

List Memories

GET /api/memories?category=facts&limit=20
Authorization: Bearer <api-key>

Delete Memory

DELETE /api/memories/{id}
Authorization: Bearer <api-key>

Get Secret Content

POST /api/memories/{id}/secret
Authorization: Bearer <api-key>

Migrate Existing Secrets

POST /api/memories/migrate-secrets
Authorization: Bearer <api-key>

Bulk Import

POST /api/memories/import
Authorization: Bearer <api-key>

[{"content": "...", "category": "facts"}, ...]

Database Migrations

This project uses Alembic for database migrations. Migrations run automatically on API server startup.

To run manually:

export DATABASE_URL="postgresql://user:pass@localhost:5432/claude_memory"
alembic upgrade head

To create a new migration:

alembic revision -m "description of change"

Kubernetes Deployment

Helm

helm install claude-memory deploy/helm/claude-memory \
  --set env.DATABASE_URL="postgresql://user:pass@host:5432/db" \
  --set env.API_KEY="your-key" \
  --set ingress.host="claude-memory.yourdomain.com"

Raw Manifests

kubectl apply -f deploy/kubernetes/namespace.yaml
kubectl create secret generic claude-memory-secrets \
  -n claude-memory \
  --from-literal=database-url="postgresql://user:pass@host:5432/db" \
  --from-literal=api-key="your-key"
kubectl apply -f deploy/kubernetes/

Development

git clone https://github.com/ViktorBarzin/claude-memory-mcp.git
cd claude-memory-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[api,dev]"
pytest tests/ -v
ruff check src/ tests/

License

Apache License 2.0. See LICENSE for details.