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

Tool	Purpose
query_history(question, k=, project=, since=, kind=)	Semantic search over everything. kind: note, transcript, tracking, or subtype
list_recent_sessions(days=, project=)	What was I working on lately
remember(content, title=, tags=, project=)	Save durable note. project scopes it; omit → global (surfaces in every project's search)
list_notes(tag=, limit=) / forget(note_id)	Manage notes

Tracking

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

Tool	Purpose
create_project(name, description=)	Top of hierarchy
create_milestone(project, name, body=, target_date=)	What ships together
create_epic(project, title, body=, milestone=, priority=)	Group tickets toward goal
create_ticket(project, title, body=, epic=, priority=)	Unit of work
create_todo(project, title, body=, ticket=, priority=)	Small step
list_items(kind=, project=, status=, parent_id=)	Filtered list
get_item(id)	One item + children
update_item(id, status=, title=, body=, priority=, ...)	Partial update, errors on fields that don't apply
delete_item(id)	Delete. Projects must be empty first
get_roadmap(project)	Markdown roadmap: milestones → epics → tickets + progress
list_projects()	Every project name across all stores

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).