okf-memory/okf-agent-memory

Git-native persistent memory for AI coding agents. Implements Google OKF v0.2 with sub-300µs in-memory BM25 search, embedded MCP server, and progressive disclosure. Slashes token bloat by 80% with zero external databases or dependencies. Built in pure Go.

OKF Agent Memory – 概要

OKF Agent Memory は、AI 駆動のコーディングアシスタントに永続的でバージョン管理されたナレッジベースを提供できる Go ベースのツールキットです。オープンナレッジフォーマット (OKF) v0.2 仕様に従い、事実、決定、ランブック、その他の「ドメイン知識」を、コードと同じ Git リポジトリ内にある knowledge/ フォルダ内のプレーンテキストの Markdown/YAML ファイルとして保存します。

重要な理由

コンテキスト損失の排除 – LLM とのチャットが終了すると、モデルは伝えたすべてを忘れます。構造化されたナレッジバンドルを Git に保持することで、エージェントは次のリクエストに必要な概念を正確に取得できます。
プロンプト肥大化の回避 – 巨大な AGENTS.md ファイルをすべてのプロンプトに詰め込む代わりに、システムはエージェントの「作業記憶」（約 400 トークンの小さなコードックス）を、オンデマンドでクエリされるより大きな意味的記憶から分離します。
ベンダーロックインなし – すべてのデータはプレーンテキストです。git diff で変更を検査し、出所を監査でき、リモートのベクターデータベースに依存することはありません。
高速で安価な検索 – 組み込みの BM25 エンジンはインメモリで語彙検索（< 300 µs）を行い、API 費用はかかりません。

中核概念

概念	機能
デュアルメモリーエージェントアーキテクチャ (DMAA)	プッシュ層（`AGENTS.md` の規範的ルール、約 400 トークンに制限）とプル層（必要なときのみクエリされる `knowledge/` バンドル）を分離します。
エージェントアクション文法 (AAG)	決定的なエージェント命令を記述するためのコンパクトな ASCII マイクロ構文で、自由形式の散文と比較して約 80% のトークンを節約します。
4 層メモリ階層	`project`（ローカルバンドル）→ `vendor`（プルされたバンドル）→ `user`（個人メモ）→ `system`（エンタープライズポリシー）。上位層は下位層をシャドウします。
OKF v0.2 バンドル	組み込みの出所（`sources`）、信頼層（`generated` と `verified`）、ライフサイクルメタデータ（`status`、`stale_after`）を持つ Markdown/YAML ファイルのセット。
検索前書き込み原則	エージェントは新しい概念を追加する前に既存のバンドルをクエリし、重複と幻覚を防ぐ必要があります。

提供内容（ツールボックス）

okf CLI – 単一のコンパイル済みバイナリ（bin/okf）で、以下が可能：
- バンドルのスキーマ、グラフ整合性、品質スコアカードを検証。
- BM25 で概念を検索（okf search "..." knowledge）。
- 概念とその関係を表示（okf show <id> knowledge）。
- バンドルの作成、更新、またはブートストラップ（okf create ...、okf bootstrap ...）。
- MCP（モデルコンテキストプロトコル）サーバーとして実行し、Claude、Cursor、Codex などのエージェントが stdio 経由で呼び出せるようにします。
ゼロ依存 Go ライブラリ（pkg/okf）– カスタム統合を構築したい場合、他のツールに埋め込むことができます。
ベンダーバンドル処理 – OKF レジストリまたは Git から既製のナレッジバンドルをプルし、オプションの品質ゲート（--min-score）付き。
ベンチマークスイート – サブミリ秒の検索と数ミリ秒のフルバンドル検証を示す再現可能なパフォーマンステスト。

クイックスタートウォークスルー

バイナリをビルド：
```
make build   # bin/okf を生成
```
既存バンドルを検証（スコア < 80 の場合 CI が失敗）：
```
./bin/okf validate knowledge --min-score 80
```

概念を検索：

./bin/okf search "authentication" knowledge

メモリスタック全体を新しいプロジェクトにブートストラップ：
```
./bin/okf bootstrap /path/to/my-project --name "My Service"
```
これにより、knowledge/ フォルダ、プロジェクト固有の AGENTS.md、ヘルパー Makefile ターゲットが作成されます。
MCP 経由でエージェントを接続（Claude Desktop の例）：
```
{
  "mcpServers": { "okf-memory": { "command": "./bin/okf", "args": ["mcp", "./knowledge"] } }
}
```
エージェントはコーディングセッション中に search または show 呼び出しを発行できるようになります。

パフォーマンスとコストのハイライト（README より）

指標	OKF Agent Memory (Go)	一般的な代替案
概念検索レイテンシ	< 300 µs（インメモリ BM25）	40 ms – 800 ms（埋め込み + ベクター DB）
フルバンドル解析とグラフ検証	~4 ms（50+ 概念）	80 ms – 1.5 s
コールドスタートオーバーヘッド	< 4 ms（単一バイナリ）	80 ms – 600 ms（Python/Node ランタイム）
1000 クエリあたりの検索コスト	$0.00（ローカル）	$0.10 – $0.50（埋め込み API）
メモリフットプリント	< 15 MB	60 MB – 350 MB

誰が使うべきか？

ソフトウェアチーム – LLM 搭載のコードアシスタントに依存し、プロジェクト固有のルール、アーキテクチャ決定、ランブックの信頼できる監査可能なソースを望むチーム。
研究またはコーチングプロジェクト – 同じ LLM を繰り返し利用し、Git とともに進化する安定した「ナレッジベース」を必要とするプロジェクト。
エンタープライズ – 外部のベクターサービスに費用を払わずに、多くのエージェント間でコンプライアンスポリシー（セキュリティ、スタイル、ライセンス）を強制する必要がある企業。

詳細情報

ドキュメントインデックス – docs/README.md
入門ガイド – docs/guides/GETTING_STARTED.md
エージェントアクション文法仕様 – docs/spec/AGENT_ACTION_GRAMMAR_RFC.md
デュアルメモリーアーキテクチャ RFC – docs/spec/DUAL_MEMORY_AGENT_ARCHITECTURE_RFC.md
スコアカードと品質ゲート – docs/guides/CLI.md（--scorecard フラグを参照）

要約： OKF Agent Memory は、AI コーディングエージェントが必要とする知識を保存および取得するための、Git ネイティブでトークン効率が高く、超高速な方法を提供し、プロンプト肥大化と高価なベクター DB 呼び出しを排除しながら、すべてを監査可能でバージョン管理された状態に保ちます。