claude-memory

Memory + project tracking for Claude Code. One MCP server.

• Semantic search over all past Claude Code transcripts — new sessions recall old ones, way past the context window

• Durable notes (remember) — per-project or global

• Structured tracking: projects → milestones → epics → tickets → todos, rendered as roadmap

• Tracking items embedded into same vector space — tickets show up in semantic search

• Per-project system prompts, stored in DB, injectable at session start

Stack: Voyage AI embeddings + Qdrant vector DB + SQLite + FastMCP. All free: Voyage free tier easily covers personal use, Qdrant Cloud free tier holds 1M vectors (or run local docker). $0 to operate.

Setup

Two keys:

• Voyage → https://dashboard.voyageai.com

• Qdrant → free cluster at https://cloud.qdrant.io, or docker run -p 6333:6333 qdrant/qdrant

git clone https://github.com/mathis-sperlich/claude-memory
cd claude-memory
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# fill VOYAGE_API_KEY, QDRANT_URL, QDRANT_API_KEY

Point SCAN_PROJECTS in ingest.py at your transcript dirs (Claude Code writes them to ~/.claude/projects/<encoded-project-dir>/*.jsonl).

Ingest

.venv/bin/python ingest.py --dry-run   # sanity-check chunking
.venv/bin/python ingest.py             # embed + upsert

Idempotent — re-runs only embed new chunks. Safe as cron job. Hourly launchd template: launchd/com.mathis.claude-memory.plist (edit paths, cp to ~/Library/LaunchAgents/, launchctl load).

Test retrieval from CLI:

.venv/bin/python query.py "how did the auth token refresh bug get fixed?"

Bad results? Lower MAX_CHUNK_CHARS in ingest.py, or try bigger EMBED_MODEL in .env and re-ingest with --reset.

Wire into Claude Code

~/.claude/settings.json:

{
  "mcpServers": {
    "claude-memory": {
      "command": "/path/to/claude-memory/.venv/bin/python",
      "args": ["/path/to/claude-memory/mcp_server.py"]
    }
  }
}

Restart Claude Code. Done — Claude now has query_history, remember, tracking tools, system-prompt tools.

Tools

Memory

Tracking

Hierarchy: project → milestone (optional) → epic → ticket → todo.

status: open / in_progress / done. priority: P0–P3.

System prompts

set_system_prompt(content, project=) / get_system_prompt(project=) / list_system_prompts() / delete_system_prompt(project=). Global + per-project layers, composed on read. Stored in tracking.db. Falls back to docs/usage.md when unset.

Hooks (optional, deterministic)

MCP tools fire when model decides. Hooks fire always. hooks/session_start.py injects current project's open tickets + system prompt at every session start:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/path/to/claude-memory/.venv/bin/python /path/to/claude-memory/hooks/session_start.py"
      }]
    }]
  }
}

Remote access (optional)

Default = local stdio, zero network. Want same memory from claude.ai or other machines? HTTP transport + Cloudflare tunnel + GitHub OAuth with login allowlist:

.venv/bin/python mcp_server.py --transport http --port 8765

Full walkthrough incl. launchd services + self-healing watchdog: CLOUD_SETUP.md.

Notes

• Privacy: Voyage sees text at embed time (no training on customer data per TOS), Qdrant Cloud stores vectors + payloads. Both concern you → local Qdrant + local embedder, same code.

• Stalled embed requests bounded by VOYAGE_TIMEOUT / VOYAGE_MAX_RETRIES env vars (default 20s / 2).