claude-memory

Claude Code のためのメモリ＋プロジェクト追跡。1つのMCPサーバー。

• 過去のすべてのClaude Codeトランスクリプトに対するセマンティック検索 — 新しいセッションが古いセッションを思い出し、コンテキストウィンドウをはるかに超える

• 永続的なメモ（remember）— プロジェクト単位またはグローバル

• 構造化された追跡: プロジェクト → マイルストーン → エピック → チケット → タスク、ロードマップとして表示

• 追跡アイテムを同じベクトル空間に埋め込む — チケットがセマンティック検索に表示される

• プロジェクトごとのシステムプロンプト。DBに保存され、セッション開始時に注入可能

スタック: Voyage AI 埋め込み + Qdrant ベクトルDB + SQLite + FastMCP。 すべて無料: Voyageの無料枠は個人利用を簡単にカバーし、Qdrant Cloudの無料枠は100万ベクトルを保持（またはローカルdockerを実行）。運用コストは$0。

セットアップ

2つのキー:

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

• Qdrant → https://cloud.qdrant.io の無料クラスター、または 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

ingest.py の SCAN_PROJECTS をトランスクリプトディレクトリに指定してください（Claude Codeは ~/.claude/projects/<encoded-project-dir>/*.jsonl に書き込みます）。

取り込み

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

冪等 — 再実行しても新しいチャンクのみを埋め込む。cronジョブとして安全。毎時のlaunchdテンプレート: launchd/com.mathis.claude-memory.plist（パスを編集し、cp で ~/Library/LaunchAgents/ にコピー、launchctl load）。

CLIから取得をテスト:

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

結果が悪い? ingest.py の MAX_CHUNK_CHARS を下げるか、.env でより大きな EMBED_MODEL を試し、--reset で再取り込みしてください。

Claude Codeに接続

~/.claude/settings.json:

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

Claude Codeを再起動。完了 — Claudeは query_history、remember、追跡ツール、システムプロンプトツールを利用できます。

ツール

メモリ

追跡

階層: プロジェクト → マイルストーン（任意） → エピック → チケット → タスク。

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

システムプロンプト

set_system_prompt(content, project=) / get_system_prompt(project=) / list_system_prompts() / delete_system_prompt(project=)。グローバル＋プロジェクトごとのレイヤー。読み取り時に合成。tracking.db に保存。未設定の場合は docs/usage.md にフォールバック。

フック（任意、決定的）

MCPツールはモデルが決定したときに発火。フックは常に発火。hooks/session_start.py は各セッション開始時に現在のプロジェクトのオープンチケットとシステムプロンプトを注入:

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

リモートアクセス（任意）

デフォルト = ローカルstdio、ネットワークゼロ。claude.aiや他のマシンから同じメモリを使いたい? HTTPトランスポート＋Cloudflareトンネル＋ログイン許可リスト付きGitHub OAuth:

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

launchdサービス＋自己修復ウォッチドッグを含む完全なウォークスルー: CLOUD_SETUP.md。

注意事項

• プライバシー: Voyageは埋め込み時にテキストを参照（TOSに基づき顧客データのトレーニングはなし）、Qdrant Cloudはベクトルとペイロードを保存。両方が気になる場合 → ローカルQdrant＋ローカル埋め込みモデル、同じコード。

• 停止した埋め込みリクエストは VOYAGE_TIMEOUT / VOYAGE_MAX_RETRIES 環境変数（デフォルト20秒 / 2）で制限。