持久化向量存储服务

claude-memory

Persistent vector memory for Claude Code. Stores your Claude sessions, notes, and conversations in a local PostgreSQL database with semantic search — so every new session can recall what you've worked on before. Automatically learns your preferences and working patterns by analysing session behaviour, building a richer picture of how you work over time.

Watch the explainer →

What's new

How it works

Two Docker containers:

• PostgreSQL 16 + pgvector — stores memories as text + 768-dimensional embeddings
• FastMCP server (port 3333) — exposes 18 MCP tools to Claude over SSE, a REST API with 10 HTTP endpoints, and a browser UI at GET /ui

When registered as an MCP server, Claude can search your memory by meaning (semantic_search), keyword (search_memories), or hybrid scoring (hybrid_search) — and save new memories automatically during a session. A connection pool keeps 1–5 persistent DB connections so tool calls are fast.

Open http://localhost:3333/ui for a visual browser: Timeline River SVG of your memory history, semantic search with similarity scores, full-content reader overlay, and a Preferences dashboard that surfaces what the system has inferred about how you work.

Quick start

Prerequisites: Docker, Claude Code

Ollama is included — the stack ships with an in-stack Ollama service (docker-compose.yml). No separate host install needed. Pull the model once after first start: docker exec claude-memory-ollama ollama pull qwen2.5:7b

# Clone and start
git clone https://github.com/daringanitch/claude-memory
cd claude-memory
bash quickstart.sh

quickstart.sh handles everything in order:

1. Starts Docker services and waits for the DB to be healthy
2. Imports your existing ~/.claude/projects session history
3. Distills sessions into durable memories using a local Ollama LLM (no API key required)
4. Registers the MCP server with Claude Code at user scope (available in every project)
5. Optionally installs the auto-import LaunchAgent (every 30 min, macOS)

Then open a new claude session and try list_memories.

Manual setup

# Start services (includes an in-stack ollama on CPU; see note below)
docker compose up -d

# GPU acceleration (NVIDIA + Docker passthrough):
#   docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

# Register with Claude Code (user scope — works in any directory)
claude mcp add --scope user --transport sse claude-memory http://localhost:3333/sse

# Verify
claude mcp get claude-memory

Importing past sessions

Run import scripts inside the container (sentence-transformers isn't available via brew):

# Claude Code session history (~/.claude/projects/)
docker compose run --rm -T \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  -v $(pwd)/import_memories.py:/app/import_memories.py:ro \
  mcp-server python /app/import_memories.py --claude-code

# Filter to one project
  mcp-server python /app/import_memories.py --claude-code --project my-project

# Claude.ai export (Settings → Privacy → Export data → conversations.json)
  mcp-server python /app/import_memories.py --claude-ai /path/to/conversations.json

# Plain text or markdown files (chunked at 1500 chars, 200-char overlap)
  mcp-server python /app/import_memories.py --text notes.md

# Raise minimum message length (default: 50 chars)
  mcp-server python /app/import_memories.py --claude-code --min-length 100

After a bulk import, clear the search cache so results reflect the new data:

curl -X POST http://localhost:3333/cache/invalidate

Distilling sessions

Raw imported messages are verbose. distill_sessions.py uses a local Ollama LLM to extract durable knowledge — decisions, patterns, bug root causes — and replaces raw messages with concise, searchable memories. No API key required.

Ollama is included in the stack — no separate install. Pull a model once after first start:

docker exec claude-memory-ollama ollama pull qwen2.5:7b   # ~4.7GB, best quality
# or: docker exec claude-memory-ollama ollama pull llama3.2:3b  (~2GB, faster)

# Distill all pending sessions (4 parallel workers by default)
# OLLAMA_URL defaults to the in-stack service (http://ollama:11434/v1)
docker compose run --rm -T \
  -v $(pwd)/distill_sessions.py:/app/distill_sessions.py:ro \
  mcp-server python /app/distill_sessions.py

# Preview without writing to DB
  mcp-server python /app/distill_sessions.py --dry-run

# Filter to one project
  mcp-server python /app/distill_sessions.py --project my-project

# Tune parallelism or swap models
  mcp-server python /app/distill_sessions.py --workers 8 --model llama3.2:3b

# Reset distillation failures so capped sessions can be retried
  mcp-server python /app/distill_sessions.py --reset-failures           # reset all capped
  mcp-server python /app/distill_sessions.py --reset-failures abc12345  # reset one session

Sessions that fail distillation 3 times are capped and skipped automatically. Use --reset-failures to retry them.

Speed notes: sessions are processed in parallel (--workers, default 4), embeddings are batched per session, and DB inserts are bulk operations — roughly 4x faster than sequential processing.

Behavioral signal extraction ✨ New

extract_signals.py parses session JSONL files directly — no LLM required — to produce two classes of memory:

Per-session (saved immediately):

• Correction signals — user messages that negate or correct Claude's previous action (e.g. "don't do that", "stop", "actually no") are saved as type:preference memories, building an automatic picture of your implicit preferences over time.

Per-project (aggregated, refreshed on every run):

• Workflow fingerprint — breakdown of tool categories used (execution, file editing, search, web, etc.)
• Command habits — most frequently run shell commands
• File hotspots — files accessed 2+ times across sessions

# Preview what would be extracted (no DB writes)
docker compose run --rm -T \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  -v $(pwd)/extract_signals.py:/app/extract_signals.py:ro \
  mcp-server python /app/extract_signals.py --dry-run

# Run for real
docker compose run --rm -T \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  -v $(pwd)/extract_signals.py:/app/extract_signals.py:ro \
  mcp-server python /app/extract_signals.py

# Filter to one project
  mcp-server python /app/extract_signals.py --project my-project

Signal memories are tagged type:preference, type:pattern, or type:behavior with source:signals so they're distinguishable from distilled or manually saved memories. Aggregate pattern memories are upserted on each run so they stay current as new sessions accumulate.

Behavioral pass (LLM extraction)

behavioral_pass.py runs a targeted LLM pass over already-distilled sessions to extract implicit behavioral observations — HOW the user works, not just what was built. It reads transcripts directly from the original JSONL files on disk (raw messages are deleted from the DB after distillation).

What it extracts: workflow habits, tooling instincts, communication style (terse vs. detailed), decision-making speed, quality habits (tests, docs, diffs), correction patterns.

Results are stored as type:behavior memories and surface in the Inferred tier of GET /api/preferences and the Preferences section of the web UI.

# Run on all distilled sessions (skips already-processed ones)
python behavioral_pass.py

# Filter to one project
python behavioral_pass.py --project my-project

# Preview without writing to DB
python behavioral_pass.py --dry-run

# Re-run even if behavioral memories already exist
python behavioral_pass.py --force

Uses the in-stack ollama service by default (OLLAMA_URL=http://ollama:11434/v1). Override via OLLAMA_URL to target a different endpoint. Uses DISTILL_MODEL env var (default: qwen2.5:7b).

Quality filters applied automatically:

• Sessions with fewer than 10 messages are skipped — behavioral patterns can't be observed in short exchanges
• distill_sessions.py skips sessions with fewer than 5 messages and deduplicates new memories against existing ones at ≥0.85 cosine similarity

Auto-import (macOS)

Install a LaunchAgent that runs import-cron.sh every 30 minutes — importing new Claude Code sessions, distilling them, and extracting behavioral signals automatically:

The pipeline runs four steps in sequence:

1. import_memories.py — imports new sessions from ~/.claude/projects
2. distill_sessions.py — summarises sessions into durable memories via Ollama
3. extract_signals.py — extracts behavioral signals without an LLM
4. behavioral_pass.py — LLM pass over distilled sessions to extract type:behavior memories

bash setup-launchagent.sh

# Check logs
tail -f /tmp/claude-memory-import.log

# Trigger manually
launchctl start com.claude-memory.import

Backup and restore

# Snapshot the database (saved to ./backups/)
bash backup.sh

# Restore from a snapshot (destructive — prompts for confirmation)
bash restore.sh backups/claude-memory-2026-03-08T12-00-00.pgdump

MCP tools

since and before accept ISO date strings: "2026-01-01" or "2026-01-01T12:00:00".

HTTP endpoints

Web UI

REST API

Migrations

Schema changes that need to be applied to existing databases are in migrations/:

# Apply migration (idempotent — safe to re-run)
docker exec -i claude-memory-db psql -U claude -d memory \
  < migrations/003_distill_failure_cap.sql

Tests

brew install pytest   # one-time
pytest tests/ -v      # 138 tests, no Docker or GPU required

All heavy dependencies (sentence-transformers, psycopg2, openai) are mocked by tests/conftest.py.

Global Claude Code integration

Add to ~/.claude/CLAUDE.md to instruct Claude to recall context automatically at the start of every session:

## Session Start — Memory Recall

At the start of every new session, use the claude-memory MCP server:
1. Call startup_context with the last segment of the current working directory as the project name
   (e.g. cwd /home/user/projects/my-app → startup_context("my-app"))
2. Call semantic_search for deeper recall on specific topics if needed
3. Briefly summarize what was found

Save key decisions, bug root causes, and user preferences using save_memory
with descriptive tags like ["project:name", "type:decision|bug|preference|pattern"].

Database schema

CREATE TABLE memories (
  id           SERIAL PRIMARY KEY,
  content      TEXT         NOT NULL,
  content_hash TEXT         GENERATED ALWAYS AS (encode(digest(content, 'sha256'), 'hex')) STORED,
  tags         TEXT[]       DEFAULT '{}',
  source       VARCHAR(100) DEFAULT 'claude-code',
  project      VARCHAR(100) DEFAULT '',
  embedding    vector(768),
  created_at   TIMESTAMP    DEFAULT NOW(),
  updated_at   TIMESTAMP    DEFAULT NOW(),
  deleted_at   TIMESTAMP    DEFAULT NULL
);

CREATE TABLE imported_sessions (
  session_id        VARCHAR(100) PRIMARY KEY,
  project           VARCHAR(100) DEFAULT '',
  imported_at       TIMESTAMP    DEFAULT NOW(),
  message_count     INT          DEFAULT 0,
  distilled           BOOLEAN      DEFAULT FALSE,
  distill_failures    INT          DEFAULT 0,
  signals_extracted   BOOLEAN      DEFAULT FALSE
);

Indexes: IVFFlat for vector cosine search, GIN for tag arrays and full-text search, BTREE on created_at, project, and deleted_at.

Configuration

Data is persisted to ./data/postgres/. The HuggingFace model cache is stored in a named Docker volume (model_cache) so all-mpnet-base-v2 isn't re-downloaded on restart.

Stack

• pgvector — vector similarity search for PostgreSQL
• FastMCP — MCP server framework
• sentence-transformers — all-mpnet-base-v2 for 768-dim embeddings
• Model Context Protocol — tool interface for Claude
• Ollama — local LLM inference for session distillation (Qwen2.5, Llama3.2, etc.)