claude-memory

Speicher + Projektverfolgung für Claude Code. Ein MCP-Server.

• Semantische Suche über alle bisherigen Claude-Code-Transkripte – neue Sitzungen rufen alte ab, weit über das Kontextfenster hinaus

• Dauerhafte Notizen (remember) – pro Projekt oder global

• Strukturierte Verfolgung: Projekte → Meilensteine → Epics → Tickets → Todos, als Roadmap dargestellt

• Verfolgungselemente in denselben Vektorraum eingebettet – Tickets tauchen in der semantischen Suche auf

• Projektspezifische Systemprompts, in der Datenbank gespeichert, beim Sitzungsstart injizierbar

Stack: Voyage-AI-Embeddings + Qdrant-Vektordatenbank + SQLite + FastMCP. Alles kostenlos: Das Voyage-Kostenloskontingent deckt die private Nutzung problemlos ab, das Qdrant-Cloud-Kostenloskontingent fasst 1 Million Vektoren (oder lokalen Docker ausführen). 0 $ Betriebskosten.

Einrichtung

Zwei Schlüssel:

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

• Qdrant → Kostenloser Cluster unter https://cloud.qdrant.io oder 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

Zeige mit SCAN_PROJECTS in ingest.py auf deine Transkriptverzeichnisse (Claude Code schreibt sie nach ~/.claude/projects/<codiertes-projektverzeichnis>/*.jsonl).

Erfassen

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

Idempotent – bei erneuter Ausführung werden nur neue Blöcke eingebettet. Als Cron-Job geeignet. Stündliche launchd-Vorlage: launchd/com.mathis.claude-memory.plist (Pfade bearbeiten, cp nach ~/Library/LaunchAgents/, launchctl load).

Abruf über die Befehlszeile testen:

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

Schlechte Ergebnisse? Verringere MAX_CHUNK_CHARS in ingest.py oder verwende ein größeres EMBED_MODEL in .env und führe die Erfassung mit --reset erneut aus.

In Claude Code einbinden

~/.claude/settings.json:

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

Claude Code neu starten. Fertig – Claude hat jetzt query_history, remember, Tracking-Tools und Systemprompt-Tools.

Werkzeuge

Speicher

Verfolgung

Hierarchie: Projekt → Meilenstein (optional) → Epic → Ticket → Todo.

status: open / in_progress / done. priorität: P0–P3.

Systemprompts

set_system_prompt(inhalt, projekt=) / get_system_prompt(projekt=) / list_system_prompts() / delete_system_prompt(projekt=). Globale und projektspezifische Ebenen, beim Lesen zusammengesetzt. Gespeichert in tracking.db. Fällt auf docs/usage.md zurück, wenn nicht gesetzt.

Hooks (optional, deterministisch)

MCP-Werkzeuge werden ausgelöst, wenn das Modell es entscheidet. Hooks werden immer ausgelöst. hooks/session_start.py injiziert bei jedem Sitzungsstart die offenen Tickets und den Systemprompt des aktuellen Projekts:

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

Fernzugriff (optional)

Standard = lokales stdio, null Netzwerkverkehr. Möchtest du denselben Speicher von claude.ai oder anderen Rechnern aus? HTTP-Transport + Cloudflare-Tunnel + GitHub-OAuth mit Anmelde-Zulassungsliste:

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

Vollständige Anleitung inkl. launchd-Diensten und selbstheilendem Watchdog: CLOUD_SETUP.md.

Hinweise

• Datenschutz: Voyage sieht Text beim Einbetten (kein Training mit Kundendaten laut AGB), Qdrant Cloud speichert Vektoren und Nutzdaten. Wenn dich beides betrifft → lokales Qdrant + lokaler Embedder, gleicher Code.

• Steckengebliebene Einbettungsanfragen werden durch die Umgebungsvariablen VOYAGE_TIMEOUT / VOYAGE_MAX_RETRIES begrenzt (Standard 20 s / 2).