robo-cortex

robo-cortex

AI コーディングエージェント向けの、Git と連携したナレッジの整合性管理。

AI エージェントがバグをデバッグして教訓を学んでも、翌週には忘れてしまう。さらに悪いことに、コードがすでに事実ではなくなった「教訓」を引用し続けることがあります。robo-cortex は、まさにこの問題に対応するローカルのナレッジベースです。記憶は git blob ハッシュに結び付けられるため、関連するコードが変更されると、記憶は黙って信頼されたり失われたりするのではなく、自動的にレビュー対象としてフラグ付けされます。つまり、AI エージェントの記憶に対するドリフト検出と古くなった記憶の検出を、LLM による推測や埋め込み類似度のヒューリスティックではなく、git の履歴から決定論的に行います。

---

robo-cortex がほかのメモリツールと異なる理由

ほとんどのエージェント用メモリツールは、埋め込みとベクトルデータベース、そしてクラウドへの依存で構成されています。robo-cortex は意図的にそのどれも採用していません。汎用的なキー・バリュー型メモリストアにはない、4 つの特徴があります。

1. Git と連携した古さ（ドリフト）の検出。 各記憶には、記録時に git blob ハッシュで取得した特定のファイルパスを関連付けられます。関連するコードが変更されると、次の retrieve／search／affected 呼び出し時に記憶が自動的に needs_review としてフラグ付けされます。また、コミット済みのリバートによって自動的に状態が回復します。回復には 3 つの条件が必要です。（a）リバートがコミット済みであること（git blob ハッシュが再び HEAD と一致すること）、（b）記憶がシステムによってフラグ付けされていること（change_status による手動操作ではないこと）、（c）リバート後に変更をスキャンするため、遅延トリガー（retrieve／search／affected）を実行することです。実際のコードの履歴にこれほど決定論的に結び付くメモリツールはほとんどありません。埋め込み類似度も、LLM による判断もなく、git blob ハッシュが一致するかどうかだけで判定します。
2. 雰囲気ではなく証拠。 記憶には、機械的に算出される強度とともに、添付証拠（テスト出力、コミット、再実行可能なコマンド）を持たせることができます。これは主観的な判断ではありません。provisional の記憶が active になるのは、実際の証拠によって裏付けられた場合、または人間が明示的に昇格させた場合に限られます。
3. 依存関係ゼロで、完全にローカル。 標準ライブラリと SQLite のみを使用します（検索には FTS5 を使用）。埋め込み、API キー、ネットワーク呼び出しは不要です。ただし、Gitea による証拠検証を明示的に設定した場合は除きます。.cortex/memory.db は単なるファイルなので、いつでも sqlite3 で調べられます。
4. 監査証跡を備えた実際のライフサイクル。 すべての状態変更（active → superseded → archived など）には --reason が必要で、その内容は永久に記録されます。何も黙って消えることはありません。誤った教訓は削除されるのではなく、invalidated としてマークされます。

測定された効果（ベンチマーク、誠実な報告）

30 セッションのベンチマーク（このリポジトリに実際にあった過去のバグ 3 件を再導入し、小型モデル — Claude Haiku 4.5 — が robo-cortex のメモリーパックあり／なしでそれぞれ 10 回解決）では、**修正品質が同一（30/30 件正解、失格ゼロ）**の条件で、新たに使用するトークンが約 12％少なく、API 相当のコストが約 15％低い（タスクごとの対応する差分の中央値）ことが測定されました。自力では修正箇所の特定が最も難しかったタスクでは、トークンが 26％減、コストが 39％減に達しました。教訓の記録自体にもコストがかかりますが、メモリーは再利用される約 1〜6 セッションで元が取れます（中央値は約 5 セッション）。実時間に関する主張はしていません。時間の差はノイズの影響が大きかったためです。完全な方法論、実行ごとの生データ（使用ログ、差分、プロンプト）、再利用可能なハーネスは、リポジトリにあります：docs/benchmark-results.md、benchmark-results-20260718/、scripts/benchmark/。既知の制限も率直に示します。対象モデルは 1 つ（小型モデル。以前に実施した大型モデルでの n=3 の予備試験では、効果はより小さい 2.7％でした。詳細は EVALUATION.md §9 を参照）、十分に文書化されたコードベースは 1 つ（効果が小さく見積もられる可能性があります）、タスクの種類は 3 つです。測定していない劇的な数値よりも、実際に測定した控えめな数値を公表したいと考えています。

---

クイックスタート

前提条件： robo-cortex には git リポジトリが必要です（古さの検出で比較するには git の履歴が必要です）。

git init && git add -A && git commit -m "initial commit"

インストール

pip install robo-cortex

pip install が error: externally-managed-environment で拒否される場合（最近の Debian／Ubuntu でよくあります）は、仮想環境または pipx を使用してください。

python3 -m venv .venv && source .venv/bin/activate && pip install robo-cortex
# or: pipx install robo-cortex

MCP 対応のエージェント（Claude Desktop／Code など）で robo-cortex を使う場合は、代わりに MCP エクストラをインストールしてください。

pip install 'robo-cortex[mcp]'

使い方

cd /path/to/your/project
roco init

# Record a project-specific lesson (scope=repo: no extra fields needed)
roco record --type lesson --scope repo \
  --statement "Copy-to-clipboard fails on HTTP; use a textarea+execCommand fallback." \
  --confidence high

# Retrieve it later
roco retrieve --task "copy to clipboard http"

matched=1 returned=1 needs_review=0 contradicted=0
[1] score=0.650 repo   lesson       Copy-to-clipboard fails on HTTP; use a textarea+execCommand fallback.

--path はメモリーをファイルに紐付けますが、HEAD にすでに存在するパスのみ指定できます（存在しないリンクを指すメモリーが作成されることはありません）。書いたばかりで、まだコミットしていないコードの場合は、今は --path なしでメモリーを記録し、コミットしてからパスを紐付けてください。

roco record --type decision --scope repo --statement "..." --confidence high
# id=7, no linked path yet

git add new_module.py && git commit -m "add new_module.py"
roco record 7 --add-path new_module.py

再利用可能な教訓（このプロジェクトに固有ではないもの）には scope=global を使用し、--assumptions を指定する必要があります。これは教訓が適用される条件であり、誤ってどこでも提案されないようにするためのものです。

roco record --type lesson --scope global \
  --statement "Safari 14 breaks CSS grid+gap. Use flexbox+margin instead." \
  --confidence high \
  --assumptions "css grid gap safari"

グローバルスコープのコマンド（record --scope global、show、search、status、link、evidence、list）は、git リポジトリの外を含め、どこからでも実行できます。グローバルストア（~/.cortex/global.db）はプロジェクトに紐付いていません。唯一の例外は retrieve です。これは設計上、ローカルリポジトリを認識するため、初期化済みのリポジトリが引き続き必要です。

強制を有効にする（推奨）

roco hooks install

git のプリコミットフックをインストールします。コミット対象に、active／provisional／needs_review のメモリに関連付けられたコードが含まれている場合、そのメモリの ID とレビューを促すメッセージを表示してコミットをブロックします。レビューするか、明示的に回避するまでブロックされます。たとえば、src/scanner.py に関連付けられたメモリがあり、そのファイルがコミットに含まれる場合：

robo-cortex: this commit touches code linked to memories that need review:
  [1] path_changed:src/scanner.py@working_tree  scanner batches at 50 items deliberately

Review with: roco show <id>
Then either re-verify (roco status <id> activate --reason "...") or supersede it, and commit again.
To bypass this check: git commit --no-verify

回避方法は実際に利用でき、ドキュメントにも記載されています。git commit --no-verify を実行すると、他の git フックと同様にこのフックをスキップできます。これは「デフォルトで強制し、回避には明示的な操作が必要」という仕組みであり、「回避不可能」という意味ではありません。uninstall／status については roco hooks --help を参照してください。ローカルコミットの代わりに、またはそれに加えて、プルリクエストで CI レベルのチェックを行う場合は、docs/ci-example.yml を参照してください。

また、任意でポストコミットフックをインストールできます。これは情報を通知するだけで、ブロックすることはありません（実行時には、通知対象のコミットはすでに完了しています）。

roco hooks install --post-commit

各コミット後に roco affected --diff-range HEAD~1..HEAD を実行して、リスクのある項目を報告します。そのため、次の retrieve／search／affected の呼び出しを待たずに、フラグをすぐに確認できます。--post-commit は、プリコミットフックとは独立して uninstall／status でも使用できます。

---

短縮形：roco

robo-cortex と roco は同じコマンドです（同じバイナリに対する 2 つのスクリプトエントリーポイント）。使いやすい方を使用してください。

roco retrieve --task "..."          # Shorter alias
robo-cortex retrieve --task "..."   # Full name, backwards compatible

名前の競合に関する注意： PyPI には、無関係なパッケージ「Runtime Config Generator」がすでに roco という名前で公開されています。同じ環境にこのパッケージもインストールされている場合、後からインストールした方が roco コマンドを使用します。名前の競合を避けるには、正式な robo-cortex 名を使用するか、roco --version を実行して実際に実行されるコマンドを確認してください。

シェル補完

roco completion bash >> ~/.bashrc

サブコマンド名と、各サブコマンド固有のフラグを補完します（フラグの値や、hooks install のような入れ子のサブサブコマンドは補完しません）。インストール済みのバージョンから生成される静的スクリプトです。新しいコマンドやフラグを反映するには、アップグレード後にこのコマンドを再実行してください。

---

3 つの使用方法

シナリオ	最適な方法	理由
単発の CLI コマンド（シェル、スクリプト、手動テスト）	CLI：roco retrieve --task "..."	最も簡単で、依存関係がなく、すぐに使えます
独自のコードを実行する Python エージェントまたはスクリプト	Python SDK：from robo_cortex import retrieve, record	プロセス内で実行され（サブプロセスを使用せず）、例外がそのまま発生するため、エラーを文字列として解析する必要がありません
ツール呼び出しを行う LLM エージェント（Claude Code、または任意の MCP クライアント）	MCP サーバー：MCP 設定に追加	エージェントが呼び出すタイミングを判断し、ツールの説明はパッケージに含まれています

3 つの方法はすべて、同じ基盤の robo_cortex.core 関数を呼び出します。呼び出し元のコードですでに使用しているものに合わせて選んでください。

MCP の設定

{
  "mcpServers": {
    "robo-cortex": {
      "command": "roco",
      "args": ["mcp", "--repo", "/path/to/project"]
    }
  }
}

利用可能なツール：retrieve_context、record_memory、search_memory、attach_evidence、verify_evidence、change_status、get_memory、list_affected。完全な仕様については、MCP_TOOLS.md を参照してください。

Python SDK

from robo_cortex import retrieve, record

memories = retrieve("feature description", repo_path="/srv/project")
if memories["data"]:
    print(f"Found solution: {memories['data'][0]['statement']}")

record(
    type="lesson",
    statement="What you learned",
    confidence="high",
    repo_path="/srv/project",
)

同じリポジトリに対する複数回の呼び出しに使用する RoboCortex クラスを含む完全な API については、PYTHON_SDK.md を参照してください。

---

メモリーのライフサイクル：ステータスの遷移

各メモリーには、確信度と適用範囲を示すステータスがあります。新しいメモリーは provisional から始まり、手動レビューまたは証拠によってステータスが変わります。

ステータス	意味	遷移先
provisional	新しいメモリーで、まだ検証されていません	active, needs_review, abandoned
active	信頼でき、今後の作業に適用できます	needs_review, superseded, invalidated, archived, abandoned
needs_review	疑わしい、またはコンテキストに依存しており、人による判断が必要です	active, superseded, invalidated
superseded	より優れた解決策に置き換えられています（置き換え先の ID へのリンクが必要です）	archived
invalidated	誤りである、または適用できなくなったことが証明されています	archived
abandoned	行き詰まった教訓です。探索が行き止まりになっています	archived
archived	終端状態（読み取り専用）	—

自動遷移

• provisional → active：メモリーに証拠を追加すると自動的に発生します（roco evidence add）。最初の裏付けデータによって、メモリーは信頼できる状態に昇格します。

手動遷移

roco status <id> <verb> --reason "..." を使って、ステータスを手動で変更します。

# Promote a provisional memory (no evidence yet)
roco status 5 activate --reason "Tested and validated on three projects"

# Mark a memory as superseded by a better lesson
roco status 7 supersede --supersedes 12 --reason "Version 2 of this pattern handles edge cases better"

# Mark as proven false
roco status 9 invalidate --reason "Benchmark shows this optimization actually makes things slower"

# Archive old/resolved items
roco status 3 archive --reason "No longer applicable after database migration"

--reason は必須で、永続的に記録されます。メモリーの監査履歴の一部となり、編集できません。

---

スコープの決定（グローバルとリポジトリ）

プロジェクト固有の知見には scope=repo を使用します。

• このコードベースで採用しているパターン（FastAPI + SQLAlchemy を使用しています）
• プロジェクト固有の決定事項（自社インフラに合わせて調整したバッチサイズ）
• テスト：「これは自分たちのコード、インフラ、またはチームの決定を参照していますか？」

再利用可能な教訓には scope=global を使用します。

• ブラウザー／ライブラリの不具合（Safari の CSS、Node.js の非同期パターン）
• 言語／フレームワークのパターン
• ベストプラクティス（SQL インジェクションの防止）

scope=global には、その教訓が適用される前提条件を示す assumptions が必要です。

{
  "type": "lesson",
  "scope": "global",
  "statement": "Copy-to-clipboard fails on HTTP. Use textarea + execCommand() fallback.",
  "assumptions": "Web app with clipboard feature, needs to work on HTTP",
  "confidence": "high"
}

---

プロジェクト間での知識の共有

roco export --scope global --output kb.jsonl
# In another project:
roco import kb.jsonl

インポートは冪等です（同じファイルを再インポートすると、id+scope によって重複がスキップされます）。また、record とまったく同じ方法で検証されます。assumptions がない scope=global の行や、無効な type／confidence は、警告とともにスキップされ、通知なしに挿入されたり、生のデータベースエラーになったりすることはありません。

独立して学習した 2 つのプロジェクトは、roco merge で統合できます。

roco merge kb_a.jsonl kb_b.jsonl --output kb_merged.jsonl
# Both projects then: roco import kb_merged.jsonl

ID+scope によって重複を排除します。競合は確信度で解決され（高い方を優先）、同じ場合はタイムスタンプで決まります。チームのナレッジベースやバックアップのユースケースを含むワークフロー全体については、EXPORT_IMPORT.md を参照してください。

「共有チームメモリー」のために ROBO_CORTEX_GLOBAL_DB をネットワークファイルシステム（NFS/SMB）に設定しないでください。 SQLite はネットワークマウント上での同時書き込みに対応しておらず、データベースが破損する可能性があります。代わりに、git を使ってエクスポート／インポートで共有してください。バージョン管理と監査が可能であり、常時共有されるファイルにはない利点があります。

---

FAQ

Q: git リポジトリは必要ですか？ A: はい。古さの検出、パスのリンク、affected はすべて git の履歴と比較します。git がなくても、エクスポート／インポート／マージを使ってマシン間でナレッジを移動できますが、git を利用する機能は動作しません。

Q: 自分（またはエージェント）がメモリの確認を忘れたらどうなりますか？ A: roco hooks install は、未レビューのメモリにリンクされたコードに変更がある場合、コミットをブロックします。ただし、回避策（git commit --no-verify）は実際に利用でき、他の git フックと同様、常に実行可能です。これは明示的な回避手段を備えたデフォルトの強制であり、無条件の保証ではありません。

Q: 古くなったメモは危険です。 A: メモリにリンクされたコードが変更されると、メモリには自動で needs_review のフラグが設定されます。信頼する前にレビューするか、置き換え済みとしてマークしてください。何かが気づかれないまま誤解を招くことはありません。

Q: チーム間でメモリを共有できますか？ A: 2 つの方法があります。

• スナップショットの共有（バージョン管理、監査可能）：あるプロジェクトからエクスポートし、JSONL を git にコミットして、チームメンバーがインポートします。
• ライブ共有データベース：すべての roco 呼び出しからアクセスできる ローカル パスを指定して、ROBO_CORTEX_GLOBAL_DB=/path/to/shared/global.db を設定します。ネットワークマウントは使用しないでください（上記の警告を参照）。

Q: オフラインで使えますか？ A: はい。すべてローカルの SQLite で動作します。Gitea のエビデンス検証（ROBO_CORTEX_GITEA_URL）を明示的に設定しない限り、ネットワーク呼び出しは一切ありません。

Q: 誤った教訓だった場合は？ A: 理由を添えて invalidated としてマークしてください。履歴には保持され、以後は提案されません。

Q: データベースが読み取り専用の場合は？ A: 読み取り専用の .cortex/memory.db（読み取り専用のチェックアウトや一部の CI 設定など）では、retrieve／search／affected は正常に機能を縮退します。読み取りでは結果が返され、書き込み（古さの更新、使用状況の追跡）はスキップされ、meta には警告が含まれます。正確性に影響しない付随的な書き込みが行われないだけで、メモリの中核機能は引き続き動作します。

Q: グローバルストアを無効にするには？ A: ROBO_CORTEX_NO_GLOBAL=1 を設定します。CLI と MCP はどちらも ~/.cortex/global.db を開かず、retrieve／search の対象は現在のリポジトリに厳密に限定され、プロジェクト間でナレッジを共有する経路はありません。プロジェクトごとに厳密に分離したい場合に便利です。

Q: 想定される規模はどのくらいですか？ A: robo-cortex は、ストアあたり数千件のメモリ（リポジトリ単位とグローバルの合計）を想定して設計・テストされています。それを超えてもパフォーマンスは段階的に低下します。スコアリングは候補ごとに O(n) のままで、各ストアの FTS 候補数は 200 件に制限されます。これを大幅に上回る数のメモリがある場合は、複数のプロジェクトに分割するか、古いメモリをアーカイブすることを検討してください。詳細は ARCHITECTURE.md を参照してください。

---

アーキテクチャ

Codebase
    ↓
git pre-commit hook (roco hooks install) -- blocks commits touching unreviewed memories
    ↓
robo-cortex Memory (SQLite + FTS5)
    ↓
.cortex/memory.db (repo)  +  ~/.cortex/global.db (shared)
    ↓
retrieve_context() → ranked memories with evidence, gated by staleness + assumptions

埋め込みなし。クラウドなし。SQLite、git の認識機能、そして内容を確認できる明示的な強制レイヤーだけです（.git/hooks/pre-commit はプレーンなシェルスクリプトで、5 秒で読めます）。

---

詳細情報

• ARCHITECTURE.md — 設計とデータモデル
• MCP_TOOLS.md — エージェント向けのツール仕様
• PYTHON_SDK.md — プロセス内 Python API
• EXPORT_IMPORT.md — プロジェクト間でナレッジを共有する方法
• EVALUATION.md — テスト結果とベンチマーク。上記で引用した、率直なトークン効率の数値も含みます
• ROADMAP.md — 意図的にまだ実装していない機能と、その理由
• CHANGELOG.md — リリース履歴

---

制作元

無料でご利用いただけます。 Robotel Limited UK（https://robotel.top）が提供しています。

このアーキテクチャは、Robotel Limitedの開発者が持つ、本番環境でAIコーディングエージェントを構築・運用してきた3年以上の実務経験を活かし、2026年7月にAI開発エージェントとしてAnthropicのClaude（Fable）を使用して設計されました。

MITライセンスです。オープンソースです。テレメトリーはありません。ベンダーロックインもありません。