agent-context-substrate

基盤は資産であり、モデルは交換可能なクライアントです。

git clone https://github.com/thomaskawas/agent-context-substrate.git
cd agent-context-substrate
make setup && make demo

要件: Python 3.12+、Docker、make。make setup は venv を作成し、依存関係をインストールします。デモは CPU で実行され CUDA ホイールをスキップするため、約 1.4 GB です。低速な接続では数分かかります。データベースは 127.0.0.1:5432 にバインドされるため、そのポートを既に使用しているものは停止してください。

これが存在する理由

私はAIエージェントを使った長期プロジェクトを構築しており、毎セッションの開始時にコンテキストを再確立することが最も頻繁に支払うコストでした。同じファイルをアップロードし、同じ決定を再説明し、モデルがすでに2回見た資料でウィンドウの有用な部分が埋まるのを見ていました。より良いモデルがリリースされても、そのどれも移行されませんでした。問題はコンテキストが欠けていることではなく、コンテキストがアドレス可能でないことでした。質問をして、それに答えるものだけを取得する方法がなく、すべてを送信して期待するしかなかったのです。修正は、コンテキストをセッションに持ち込むものとして扱うのをやめ、クエリするものとして扱うことでした。

AIエージェント向けのモデル非依存メモリ基盤のリファレンス実装です。プロジェクトメモリはモデルの外部の、クエリ可能でバージョン管理されたストアに置かれ、1つのMCPゲートウェイを通じて公開されます。モデルを交換しても、すべてを維持できます。今日はClaude、明日はGeminiやGPT、その下には同じプロジェクトメモリがあります。毎セッションに履歴を貼り付ける代わりに、検索が現在のタスクに実際に必要な小さなレコードセットを選択します。

このリポジトリは、そのパターンのクリーンルーム実装であり、合成コーパスに対してゼロから書かれているため、このページのすべての数値は、固定された依存関係を持つクリーンなクローンから再現できます。これはパターンであり、私自身の仕事で実行しているシステムではありません。

APIキーは不要です。make demo は完全にローカルコンポーネントで実行されます。固定されたローカルモデル（名前とリビジョン）はデフォルトのアダプタープロファイルである local です（make warmup は make demo によって自動的に実行され、約180MBを一度だけ事前ダウンロードします）。密閉されたゼロダウンロードの deterministic プロファイルは、テストと常時稼働のCIゲートを支えます。

Related MCP server: AI Memory MCP Server

レイアウト

src/acs/adapters/base.py はコードで表現されたテーゼです。すべての外部機能が背後に置かれる4つの小さなインターフェースです。src/acs/store/ はメモリを記録のシステムとして扱います（バージョン管理、監査可能、真に削除可能）。src/acs/retrieval/ はパイプラインを小さな、個別にテスト可能なステージとして扱います。eval/ はゲートです。変更は baseline.lock.json に一致するかそれを上回る場合にのみ出荷され、そうでなければ出荷されません。

設計の根拠は docs/adr/ にあります。9つの決定記録です。ほとんどは半ページですが、3つは長く、議論にスペースが必要でした。

また docs/ には、各レイヤーが存在する理由についての architecture.md、敵対的境界と各防御がどこにあるかについての threat-model.md、残りが従うルールについての principles.md、そしてこのリポジトリが従ったビルド順序についての build-your-own.md があります。

これが示すもの

• 取り込みは、1回のパスで両方の表現を書き込みます。類似性のための埋め込みと、構造のためのエンティティ/関係グラフです。すべてのドキュメントが埋め込まれます。関係を述べないドキュメントはエッジを追加しません。

• 検索は4段階のパイプラインです。調整可能なブレンドによるハイブリッドベクトル+全文検索、マルチクエリ融合（RRF）、クロスエンコーダー再ランク、そしてエンティティアンカー分割です。グラフが再ランクされたリストを再順序付けし、トピック再ランカーが類似した名前の兄弟コンポーネントと混同するのを防ぎます。コンシューマーごとの検索プロファイルはコードではなくデータです。

• ガバナンス: 検索の変更は、ロックされた評価ベースラインに一致するかそれを上回る場合にのみ出荷されます。メモリはSCD2でバージョン管理され、タイムトラベル読み取りが可能で、パージは真に削除し（ベクトルも含む）、監査ログはデータベースレベルで変更を拒否します。

• アクセス: 1つのMCPゲートウェイが基盤を任意のMCPクライアントに提供し、呼び出し元ごとにスコープされます。隔離された研究ループは、引用必須の書き戻しでギャップを埋めます。

• 移植性: すべてのプロバイダーはアダプターの背後にあります。埋め込み器は意図的に固定されています。

系統IDとタイムスタンプはどちらも make history から取得します。裸で実行すると現在のメモリとそのIDを一覧表示し、LINEAGE=<id> を指定すると1つのメモリのバージョンチェーンを辿り、各バージョンの有効期間ウィンドウを出力します。これらのウィンドウはISOタイムスタンプであるため、貼り付けた TS= は、その前後の1秒ではなく、実際に読んだバージョンに解決されます。IDはクローンごとに生成されるため、あなたのIDはここに示されているものとは一致しません。

make purge は真に削除します（パージされたサブジェクトに属する場合、ゴールデンセットのターゲットも含む）。そのため、パージされたコーパスに対するベンチマークは、静かに低い再現率を報告するのではなく、不完全として実行を拒否します。make demo はクリーンなコーパスにリセットします。

このページのすべてのベンチマーク数値は、シード付き合成コーパス（corpus/generate.py）に対するアブレーションから得られています。クリーンなクローンから再現可能で、CIでゲートされています（毎プッシュで決定論的プロファイル、bench-local ラベルでローカルプロファイル）。ロックされたベースラインはコーパスダイジェストもロックします。絶対値ではなく差分を読んでください。合成コーパスでの recall@5 / mrr@5 は、各ステージが何に貢献するかを示すものであり、実際の品質を示すものではありません。ステージがどこで差分を得るかを確認するには、.venv/bin/python eval/run_benchmark.py --by-family を実行してください。

アブレーション、ローカルプロファイル

各ステージは異なるものを提供します。これは、1つのより良い検索器ではなくパイプラインを支持する論拠です。tests/test_readme_table.py は、このテーブルと eval/baseline.lock.json が一致しない場合に失敗するため、テーブルはゲートが強制する数値から乖離できません。ゲートは下限であるため、メトリクスを改善する変更は合格し、ここに示す数値は、ベースラインが意図的に make lock-baseline で再ロックされるまで維持されます。その場合、このテーブルは一致するまで更新されるまで失敗します。ローカルプロファイル、120のゴールデンクエリ、k=5、ステージ1のマージ rank、コーパスダイジェスト ad7bf7ca。make demo で再現できます。

これらの数値が何を支持し、何を支持しないか（モデルレーンの比較が曲線ではなく境界である理由を含む）は、docs/limitations.md に記載されています。