Repo Memory

repo-memory

コードベースを共有する AI エージェントのための、Git で追跡される共有ワーキングメモリです。 ある Claude ／ Cursor ／ Cline がリポジトリについて学んだことを、次のエージェントが 自動的に引き継ぎます。データベースも SaaS も不要です。リポジトリ内のファイルだけで実現します。

---

問題

リポジトリに触れる AI セッションは、毎回ゼロから始まります。同じファイルを再び grep し、 同じ規約を再発見し、3 セッション前にすでに回答した質問を繰り返します。複数のユーザーや ツールが関わると、さらに状況は悪化します。チームメイトの Cursor と自分の Claude Code が 同じコードベースをそれぞれ独立して学習することになります。

人間が記述するルールには CLAUDE.md ／ .cursorrules があります。しかし、エージェントが 検証した事実を記録するものはありません。「認証ミドルウェアは src/auth/middleware.py:42 にある」「PR #387 では HTTP/2 を理由に requests ではなく httpx を 選んだ」「ピーク時間帯にマイグレーションを実行しない」といった情報です。

repo-memory は、そのための仕組みです。リポジトリにコミットする .ai-memory/ ディレクトリを 用意します。すべての AI ツールがそこから読み込み、そこに書き込みます。データベースの役割を 果たすのは Git です。

---

構成

your-repo/
├── .ai-memory/
│   ├── README.md           # explains the convention
│   ├── facts.jsonl         # append-only structured facts with evidence
│   ├── decisions/          # one markdown per non-trivial decision
│   │   └── 2026-05-19-pick-httpx.md
│   └── gotchas.md          # one-line "watch out for X" notes
├── src/
└── README.md

ファイルだけで完結します。Git で同期できます。デーモンも DB も認証も不要です。オフラインでも 動作します。

---

インストール

pip install repo-memory-mcp
# or
uvx repo-memory-mcp --help

Python ≥3.10 が必要です。依存するのは公式の mcp SDK（MCP サーバー用）だけです。

---

クイックスタート

cd your-repo
repo-memory init                              # creates .ai-memory/ + adds CLAUDE.md hint
repo-memory add-fact "Auth middleware lives in src/auth/middleware.py" \
                     --file src/auth/middleware.py --lines 42-180 --tool grep
repo-memory add-decision "Use httpx not requests" \
                         --body "HTTP/2 + async support; we already use anyio."
repo-memory add-gotcha "Don't run migrations during 9-11am UTC peak"

repo-memory show                              # render everything as Markdown
repo-memory list-facts --tag auth

続いて、ほかのファイルと同じように .ai-memory/ をコミットします。

git add .ai-memory/
git commit -m "memory: record auth middleware location + httpx decision"
git push

リポジトリをプルしたほかの人（人間または AI）は、すぐにその事実や決定を参照できます。

---

LLM と AI エージェントが読み取れる仕様

検索または MCP インデックスを通じてこのリポジトリを見つけたエージェント向けです。

識別情報

• name：repo-memory
• purpose：現在のコードベースに関する構造化された、Git で追跡されるメモリーストアを読み書きし、複数の AI エージェント（および人間）が同じ情報を再学習せずに済むようにします。
• transport：CLI（repo-memory）および MCP stdio（repo-memory-mcp）。
• storage：リポジトリ内の .ai-memory/ に保存されるプレーンファイルです。同期には Git を使います。

各ツールを呼び出すタイミング

ツール	タイミング
get_repo_memory	このリポジトリで作業を始めるとき。
add_fact	自明ではない事実（場所、動作、規約）を検証した後。次のエージェントが簡単に再検証できるよう、evidence を含めてください。
add_decision	重要な選択（アーキテクチャ、ライブラリ、トレードオフ）をした後。本文では単に「何を」ではなく、「なぜ」を説明してください。
add_gotcha	時間を無駄にする予想外の事態が起きた後。
list_facts	特定の領域（tag、source_file）の事実だけを確認したいとき。

推奨されるエージェントのワークフロー

1. agent.call("get_repo_memory")            -> absorb prior context
2. ...do task, run tools, verify things...
3. agent.call("add_fact", claim, evidence)  -> for each new fact
4. agent.call("add_decision", title, body)  -> if a choice was made
5. session ends, human commits .ai-memory/   -> shared via git

MCP サーバーのインストール

クライアント設定に追加します（Claude Desktop ／ Cursor ／ Cline）。

{
  "mcpServers": {
    "repo-memory": {
      "command": "uvx",
      "args": ["repo-memory-mcp", "--repo", "/abs/path/to/the/repo"]
    }
  }
}

または、--repo の代わりに REPO_MEMORY_ROOT 環境変数を設定します。

5 つのツールを公開します：get_repo_memory、add_fact、list_facts、 add_decision、add_gotcha。

---

データベースではなく Git を使う理由

• インフラ不要。 ホストするサービスも、作成するアカウントも、ローテーションする API キーも 必要ありません。
• すでに信頼できる情報源です。 Git の履歴が唯一の信頼できる情報源です。 git blame を使えば、どのエージェントがいつどの事実を追加したかがわかります。
• オフラインでも動作。 飛行機、電車、カンファレンス会場の Wi-Fi など、どこでも問題ありません。
• PR レビュー。 疑わしい事実や誤った事実は、通常のコードレビューを通じて除外できます。
• リポジトリ単位のスコープ。 リポジトリ A の事実がリポジトリ B に漏れることはありません。 ストアはリポジトリごとにローカルに保存されます。

---

スキーマ（ツール作成者向け）

facts.jsonl — 1 行につき JSON オブジェクト 1 つ：

{
  "id": "abc123def456",
  "ts": "2026-05-19T18:00:00Z",
  "claim": "Auth middleware lives in src/auth/middleware.py",
  "evidence": {
    "file": "src/auth/middleware.py",
    "lines": "42-180",
    "tool": "grep",
    "command": "rg 'def authenticate' src/",
    "verified_at": "2026-05-19T18:00:00Z"
  },
  "tags": ["auth"],
  "added_by": "claude-opus-4.7"
}

追記専用です。古くなった項目も残ります。読み取り側は verified_at を確認し、必要に応じて 再検証します。

---

自動検出のヒント

repo-memory init は、リポジトリの CLAUDE.md（すでに AGENTS.md がある場合はそちら）にも、短い検出用セクションを追加します。リポジトリに入った AI エージェントに、まず .ai-memory/ を確認し、新たに判明したことをそこに記録するよう伝えます。冪等性があるため、再実行しても重複しません。

--no-claude-md で無効にできます。

追加されたブロックは と で区切られているため、CLAUDE.md の他の部分は 自由に手動編集できます。

---

CLI リファレンス

コマンド	動作
repo-memory init [--no-claude-md]	.ai-memory/ の骨組みを作成し、（デフォルトで）CLAUDE.md/AGENTS.md を更新します。
repo-memory show [--limit N]	すべての内容を 1 つの Markdown ドキュメントとして出力します。
repo-memory add-fact "<claim>" [--file F --lines L --tool T --command C --tag T --by AGENT]	事実を追加します。
repo-memory list-facts [--tag T] [--source-file F] [--since ISO] [--limit N] [--json]	事実を一覧表示／絞り込みます。
repo-memory add-decision "<title>" [--body MD]	決定事項ファイルを作成します。
repo-memory list-decisions	決定事項ファイルのパスを一覧表示します。
repo-memory add-gotcha "<note>"	注意点を 1 行追加します。

CWD がリポジトリのルートでない場合は、すべてのコマンドで --root PATH を指定できます。

---

作者について

yubinkim444 が開発しました。同氏は Kay's Records という iOS および Android 向けアプリも制作しています。

このプロジェクトで時間を節約できたなら、アプリを試していただくことが何よりのお礼になります。

ライセンス

MIT © yubinkim444