codeagent-memory

cam

English · 中文 · 日本語 · 한국어 · العربية · 🌐 Web サイト

コーディングエージェント向けに構築された、ローカルのマルチターン会話メモリーシステム

コードグラフ＋メモリー · 必要な箇所だけを読み取り · 100％ローカル · MCP＋CLI

Rust で記述されたカーネル

目次

• cam を選ぶ理由
• はじめに
• 主な機能
• 仕組み
• エージェントのワークフロー
• CLI リファレンス
• メモリールール
• 設定
• ベンチマーク
• 対応エージェント
• 対応言語
• 対応プラットフォーム
• ライセンス

ガイド：インタラクティブショーケース（Web サイト） · メインエージェントとサブエージェント · IDE 別の MCP 設定 · 中文说明

cam を選ぶ理由

AI コーディングエージェントがリポジトリを調べる際、通常はファイルを 1 つずつ grep、glob、全文の Read を実行するという遠回りな方法で構造を再発見し、次のセッションではそれをすべて忘れてしまいます。

cam は、単一のバイナリで 2 つのローカル検索基盤をエージェントに提供します。

1 つのバイナリに 2 つのインターフェース： メインエージェントは MCP（cam mcp）経由で cam を呼び出します。サブエージェント（MCP ツールを引き継ぐことがほとんどありません）は、まったく同じ CLI（cam --json …）を使います。どちらもディスク上の .cam/cam.db を共有し、100％ローカルで、API コストはゼロです。

はじめに

オプション 1：一文でエージェントにインストール（推奨）

このプロンプトをコーディングエージェント（Cursor、Claude Code、Codex、Windsurf、GitHub Copilot、Cline など）に直接貼り付けると、インストール、インデックス作成、cam の接続までエージェントが行います。

Install cam from https://github.com/HanochZhu/codeagent_memory: require a working Rust toolchain (rustup), run `cargo install --git https://github.com/HanochZhu/codeagent_memory --locked`, ensure ~/.cargo/bin (or %USERPROFILE%\.cargo\bin on Windows) is on PATH, then verify with `cam --help`. In this repo run `cam index`. For the main agent, register MCP stdio: command `cam`, args `["mcp"]` (Cursor: .cursor/mcp.json; Claude Code: .mcp.json). Subagents call `cam --json` in the shell. Do not add extra docs.

オプション 2：手動でセットアップ

1. CLI をインストールする

Rust ツールチェーンが必要です。

cargo install --git https://github.com/HanochZhu/codeagent_memory --locked
cam --help

git clone https://github.com/HanochZhu/codeagent_memory.git
cd codeagent_memory
cargo install --path . --locked

docker pull ghcr.io/hanochzhu/codeagent-memory:0.1.5
docker run -i --rm -v "$PWD:/work" -w /work ghcr.io/hanochzhu/codeagent-memory:0.1.5

2. プロジェクトのインデックスを作成してクエリする

cd your-project
cam index                                              # parse repo into .cam/cam.db

# Query the code graph
cam ls src/                                            # list files or symbols in a file
cam read src/main.rs/main                              # read a single symbol body
cam ref main --dir in                                  # 1-hop callers (in) or callees (out)

# Query & write to the memory tree
cam recall "how does hybrid recall fuse BM25 and vectors"
cam add --summary "..." < notes.md

_{cam は初回使用時に .cam/ を自動で初期化します。ファイルの変更時にグラフをライブで増分更新するには、バックグラウンドで cam watch を実行してください。}

3. メインエージェント用に MCP を接続する

ホストの MCP 設定（例：.cursor/mcp.json または .mcp.json）に cam mcp を追加します。

{
  "mcpServers": {
    "cam": {
      "command": "cam",
      "args": ["mcp"]
    }
  }
}

ホストごとの設定ファイルパスについては docs/mcp.md を、メインエージェント／サブエージェントのプロンプトルールについては docs/agents.md を参照してください。

_{初回の recall または add の実行時に、デフォルトの埋め込みモデル（potion-multilingual-128M）が ~/.cam/models/ にダウンロードされます。オフラインの場合は、字句ハッシュ埋め込み器にフォールバックします。}

主な機能

動作の仕組み

1. 抽出 — tree-sitter がワークスペースを走査し、シンボル定義と呼び出し関係を .cam/cam.db に保存します。
2. ピンポイントな読み取り — エージェントは仮想パス（ls → find → read → ref）を使って移動します。ファイルを読み取るとシンボルの概要が返され、file/symbol を読み取ると、そのシンボルのソース部分のみが返されます。
3. ハイブリッド検索 — recall は英語のクエリを受け取り、ローカルで埋め込みを生成し、識別子を考慮した BM25（snake_case、kebab-case、camelCase の分割と英語の語幹処理）を実行して、信頼度の低い候補を除外し、両方のリストを RRF（$k=60$）で統合します。スコアは $0.9 + 0.1 \times R$ で調整されます。置き換えられた過去のリビジョンは、最新の置き換え先まで自動的に展開されます。
4. 書き戻し — エージェントが簡単ではないタスクを解決したときは、事実を原子的な単位に分け、各 add に1つの事実だけを保存します（英語の要約。本文では非ラテン文字にも対応します）。関連する事実は --link / links で結び付けてナレッジグラフを作成します（mem show で確認できます。現時点では recall はグラフのリンクをたどりません）。--parent はメモリーを構造上のトピックに関連付け、--supersedes は系譜を保持したまま古いメモリーを置き換えます。

アーキテクチャの詳細（中国語）：DESIGN.md。

エージェントのワークフロー

すべてのコーディングタスクで、次の4段階のループに従います。

1. まず検索する — grep を実行する前に、英語で cam_recall / cam recall を検索します。検索結果が latest で needs_update ではない場合は、再利用します。
2. インデックスを確認する — グラフツールが not_indexed を返した場合は、プロジェクトに対して一度 cam_index / cam index を実行します。
3. グラフをたどる — メモリーが見つからない場合は、find または ls でシンボルを特定し、read <file>/<symbol> でシンボルの本文を読み、ref <symbol> --dir in|out で呼び出し元／呼び出し先を追跡します。
4. 書き戻す — 新たに判明したアーキテクチャ上の事実や修正を、cam_add / cam add で原子的な事実として保存します（1つのメモリーにつき1つの事実、英語の要約。本文では非ラテン文字にも対応します）。links / --link で関連する事実を結び付けます。

エージェントのルールとコピーして使えるシステムプロンプトの全文：docs/agents.md。

CLI リファレンス

コードグラフのコマンド

メモリーコマンド

サーバーと設定のコマンド

グローバルフラグと規則：

• --project <dir>（または CAM_PROJECT 環境変数）を指定すると、自動的な上位ディレクトリへの .cam ／ .git ルート検出が上書きされます。
• --json はコンパクトな JSON を出力します（整形された JSON を出力するには --pretty を指定します）。--json 使用時のエラーは stdout に {"error":{"code":…,"message":…}} を出力し、ゼロ以外の終了コードで終了します。
• 曖昧なシンボル： read または ref が複数の定義に一致する場合、cam は候補となるノード ID（例：src/main.rs:function:main:12）とともに status: "ambiguous" を返します。候補のノード ID はそのまま read または ref に渡せます。
• 無視ルールと複数リポジトリのディレクトリ： 任意の階層にある .gitignore と .camignore を尊重します。Git サブモジュールとリンクされたワークツリーはスキップし、ネストされた独立クローンは kind: "project" としてインデックス化します（--scope に渡せます）。

メモリーのルール

• アトミックな事実とナレッジグラフのリンク： 1 つのエントリに情報を詰め込みすぎないよう、各メモリーにはアトミックな事実を 1 つだけ保存します。複数の事実に関連がある場合は、--link ／ links で接続し、ナレッジグラフを形成します（グラフ検索はまだ有効になっていません）。
• 英語のクエリと要約： 検索クエリとメモリーの要約は英語で記述する必要があります。メモリーの本文は非ラテン文字に対応しています。
• 保持と強化： エビングハウスの保持率 $R = e^{-t / S}$ によって、検索スコアは $\text{relevance} \times (0.9 + 0.1 \times R)$ に調整されます。$R < 0.3$ のエントリは needs_update とマークされ、stale_days（デフォルトは 30）より古いエントリは stale とマークされます。有効な検索ヒット（needs_update = false）があるたびに最終アクセス時刻が更新され、安定性 $S$ に 1.7 が乗算されます。
• 非破壊的な系譜： メモリーは削除されません。--parent は分岐ツリーを形成し、--supersedes は直線的なリビジョンチェーンを形成します。latest とマークされるのは末尾のリビジョンのみで、古いリビジョンはデフォルトの検索結果から除外されます。

設定

グローバル設定は ~/.cam/config.toml に保存されます。

stale_days = 30
# embedding_model = "minishlab/potion-multilingual-128M" # default (cached under ~/.cam/models/)
# embedding_model = "minishlab/potion-base-8M"           # lighter Hugging Face model2vec repo
# embedding_model = "/path/to/local/model2vec"           # dir with tokenizer.json, config.json, model.safetensors
# embedding_model = "hash"                               # zero-download lexical hash embedder

CAM_EMBED_MODEL を使用すると、単一プロセスでモデルを上書きできます。または cam config set embedding_model default を実行してリセットします。埋め込みモデルを変更すると、次回の recall でスコアリングの前に既存のメモリーが自動的に再埋め込みされます。

ベンチマーク

cam は、同一のコーパスを使い、最も近いオープンソースシステムと比較して、コードグラフとメモリプレーンを個別に評価します。

_{一般的なチャットメモリフレームワーク（Mem0、Zep、Letta）は、これらのコーディングエージェント用コーパスではなく会話ログを対象とするため、以下の表から除外しています。}

システム比較

1. メモリ — coding-agent-life-v1

15セッション、15クエリ、$k=5$（agentmemory の score.ts と同じスコアリング方式。P@5 の上限は 0.240 です）。

リビジョンチェーン（--lineage）： 各ターンを --supersedes リビジョンとして再取り込みし、top-$k$ が各正解チェーンの最新ノードを返すか（newest R@k）、また置き換えられたノードが誤って latest を名乗っていないか（stale latest）を検証します。

2. 長期メモリ — LongMemEval-S

クリーニング済みの LongMemEval-S からシード42で抽出した、回答を棄権しない質問100件です。検索では埋め込みと BM25 を $k=10$ の RRF で統合し、LLM リーダーは使用しません。

3. ワークフロー検索 — Agent Retrieval Bench V2（edit2ripple）

44 件の固定されたリポジトリスナップショットに対する、58 件の変更箇所指定クエリ（LLM 不使用。BCY は、標準の 8K トークンファイルパッキングプロトコルにおける予算内コンテキスト利得です）。

cam graph は最初にヒットする順位が最も高く（MRR 0.297、クエリ P95 7.3 ms）、一方で語彙検索は複数ファイルをより広くカバーするため、グラフと語彙検索の順位融合が有効です。

4. コードグラフ — LongMemCode（clap）

SCIP のゴールドデータに対する clap v4.6.1 の 536 シナリオ（LLM 不使用、P95 ≈ 5.2 ms、$/1k = 0）。

5. マルチターンでのトークン削減 — DeepSeek

完全なコンテキストのダンプと、ターンごとの cam 検索の比較（deepseek-flash、ハッシュ埋め込み、2026-10-13）：

python3 eval/coding_life/run.py --adapter grep
python3 eval/coding_life/run.py                                             # potion; errors if the model fails
python3 eval/coding_life/run.py --hash-embed                                # hash embedder
python3 eval/longmemeval/run.py --sample 100 --seed 42 --workers 8          # potion
python3 eval/longmemeval/run.py --sample 100 --seed 42 --workers 8 --hash-embed
python3 eval/locomo/run.py --workers 4                                      # potion, evidence recall

git clone --depth 1 https://github.com/eyuansu62/agent-retrieval-bench \
  eval/agent_retrieval/vendor/agent-retrieval-bench
python3 -m pip install -e eval/agent_retrieval/vendor/agent-retrieval-bench
arb download-benchmark --version v2_edit2ripple --local-dir eval/agent_retrieval/data --force
python3 eval/agent_retrieval/run.py --workers 8

python3 eval/llm_multiturn/run.py --track both   # potion; requires DEEPSEEK_API_KEY
python3 eval/longmemcode/run.py --corpus clap
python3 eval/charts/generate.py

対応エージェント

メインエージェントには cam mcp（stdio）を登録します。サブエージェントは追加設定なしで cam --json CLI を直接使用します。

コピーして使える設定例：docs/mcp.md · システムプロンプト：docs/agents.md。

対応言語

対応プラットフォーム

cam は、cargo install --git https://github.com/HanochZhu/codeagent_memory --locked を使って macOS、Linux、Windows 上でネイティブにコンパイルするか、Docker（ghcr.io/hanochzhu/codeagent-memory:0.1.5）を使ってどこでも実行できます。使い始めるをご覧ください。

ライセンス

MIT