OKF Agent Memory – AIコーディングエージェントのためのGitネイティブ永続メモリ

OKF Agent Memory

Open Knowledge Format (OKF) v0.2 に基づく、AIエージェントのためのドメインニュートラルなGitネイティブ永続プロジェクトメモリ。

［画像: Specification］ ［画像: Tooling］ ［画像: CI］ ［画像: Trendshift］ ［画像: On StackMap］ ［画像: Protocol］ ［画像: License］ ［画像: Sponsor］

---

🌟 概要

AIエージェントとの会話は、コンテキストウィンドウが閉じるとリセットされます。貴重なアーキテクチャ上の決定、ドメインの発見、運用上の事実などは、永続的に保存されない限り失われます。

従来ののアプローチは、2つの致命的な障害モードに苦しんでいます。

1. プロンプトモノリス: すべてのドメイン知識とルールを AGENTS.md または CLAUDE.md に詰め込むと、巨大なコンテキストの肥大化を引き起こし、注意のドリフト（エージェントが重要な指示を無視する）が発生します。
2. RAGの盲点: 行動ルールをベクトルデータベースにダンプしても、エージェントは一般的なタスク中に運用上の制約（例: フォーマットやセキュリティルール）を意味論的に検索しないため失敗します。

OKF Agent Memory は、デュアルメモリAIアーキテクチャ（DMAA）でこのジレンマを解決します。

flowchart TD
    subgraph PUSH["1. 正規のワーキングメモリ（プッシュレイヤー）"]
        direction TB
        C1["標準的なAGENTS.md（400トークン上限）"]
        C2["ドメインコデックス（不変、倫理、トーン）"]
        C3["OKFメモリブリッジ（決定論的トリガー）"]
        C4["エージェントアクショングラマー（AAG）マイクロシンタックス"]
    end

    subgraph PULL["2. 意味論的ドメインメモリ（プルレイヤー）"]
        direction TB
        O1["OKF v0.2 ナレッジバンドル（knowledge/）"]
        O2["システムプロンプトのベースラインは0トークン"]
        O3["okf_search / okf_show による選択的取得"]
        O4["決定、事実、ランブックの永続グラフ"]
    end

    INPUT["ユーザーリクエスト"] --> PUSH
    PUSH -->|ドメインコデックスとトリガーを強制|
    AGENT["AIエージェント（LLM）"]
    AGENT -->|選択的取得|
    PULL
    PULL -->|コンテキストと事実|
    AGENT
    AGENT --> OUTPUT["決定論的な応答"]

読み込み中

ユニバーサルコンポジションモデル

DMAAでは、すべてのエージェント設定はユニバーサルコンポジションによって構造化されます。

$$\text{AGENTS.md} = \underbrace{\text{ドメインコデックス（AAG)}}_\text{プロジェクトの不変性、トーン、ガードレール} + \underbrace{\text{OKFメモリブリッジ}}_\text{標準化されたトリガー：書き込み前の検索}}$$

• レイヤー1：正規のワーキングメモリ（プッシュレイヤー）: Agent Action Grammar (AAG)で表現された、永続的で超コンパクトな行動コデックス（400トークン上限）。セッション開始時にロードされ、ゼロトレランスの不変性を強制します。
• レイヤー2：意味論的ドメインメモリ（プルレイヤー）: ベースラインで0トークンを消費し、マイクロ秒単位でオンデマンドでクエリされるOKF v0.2ナレッジバンドル（knowledge/）。

flowchart TD
    L1["1. OKF v0.2 仕様<br/>（正規のMarkdown & YAML形式）"]
    L2["2. エージェントメモリ規約 & DMAA<br/>（デュアルメモリモデル、書き込み前の検索、信頼）"]
    L3["3. エージェントスキル & AAGコデックス<br/>（Agent Action Grammar、ワークフロー、トリガー）"]
    L4["4. ツーリングレイヤー：Goライブラリ & CLI<br/>（決定論的解析、検証、BM25、MCP）"]
    L5["5. プロジェクトナレッジコーパス<br/>（knowledge/ OKFバンドル）"]

    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> L5

読み込み中

---

⚡ 主なハイライト

• デュアルメモリ認知アーキテクチャ（DMAA）: 正規のプッシュワーキングメモリ（AGENTS.mdコデックス）と意味論的プルドメインメモリ（knowledge/バンドル）を分離し、プロンプトの肥大化を完全に排除します。
• Agent Action Grammar（AAG）: 自然言語のプロンプト指示と比較して約78〜85%のトークンを節約する、超コンパクトで決定論的なASCIIマイクロシンタックス。
• 驚異的な高速パフォーマンス（<300µs検索、約4msグラフ検証）: インメモリBM25検索とバンドル検証は、VMの起動やネットワークラウンドトリップなしでマイクロ秒単位で実行されます。
• 100% Gitネイティブ & ベンダーロックインゼロ: すべてがバージョン管理されたプレーンテキストです。標準的なgit diffとgit logを使用して、エージェントのメモリを検査、監査、レビューできます。外部データベースは不要です。
• メモリ取得のためのAPIコストゼロ: ローカルの辞書的BM25インデックスにより、継続的なベクトル埋め込みAPIコストとネットワークラウンドトリップが不要になります。
• Google OKF v0.2上に構築: プロビナンス（sources）、信頼レベル（generated対verified）、ライフサイクルメタデータ（status、stale_after）を完全にサポートする、エージェント知識のためのオープン標準フォーマットを使用します。
• コンテキストの肥大化とメモリの腐敗を解決: プログレッシブ開示（階層的なindex.mdファイルとリンクグラフ）を採用し、エージェントが必要な概念のみを正確にロードできるようにします。
• 書き込み前の検索原則: 概念の重複や幻覚による逸脱を防ぐため、作成前に既存のメモリをクエリすることを義務付けます。
• ガバナンスとコードから知識へのバインディング: code_refsを介してアーキテクチャの決定をソースファイルに直接バインドし、コードを変更する前に--for-pathを介してアクティブな制約/ホールドをクエリします。
• 真にドメインニュートラル: ソフトウェアエンジニアリング、コーチング、科学研究、文献レビュー、運用向けに設計されています。

---

📊 パフォーマンスベンチマーク

Goで外部依存関係なしに構築されたokfは、高頻度のエージェントツール呼び出しループのために設計されています。

ヒント

独自のLLMでローカルに再現: 純粋なGoで自動化されたベンチマークランナーを提供し、ローカルハードウェア（LM Studio / Ollama with Gemma, Qwen, Llama）でTime-To-First-Token（TTFT）の高速化とトークン削減（-80%）を検証します。make benchmarkを実行するか、Progressive Disclosure Benchmark Suiteをご覧ください。

---

🚀 クイックスタート

1. ツーリングのビルド

リポジトリをクローンし、スタンドアロンのokf実行可能ファイルをコンパイルします。

make build

これにより、bin/okfにスタンドアロンバイナリが生成されます。

2. 基本的なCLIコマンド

# バンドルの準拠性、グラフ接続性、説明のドリフトを検証
./bin/okf validate knowledge --strict --drift

# バンドルの品質スコアカードを評価（3つの柱：メンテナンス、スチュワードシップ、整合性）
./bin/okf validate knowledge --scorecard

# CIまたはプリコミットパイプラインでバンドル品質をゲート（スコアが80未満の場合は失敗）
./bin/okf validate knowledge --min-score 80

# インメモリBM25スコアリングによる概念検索
./bin/okf search "architecture layers" knowledge

# 編集前に特定のソースファイルを管理する制約とアクティブなホールドを発見
./bin/okf search --for-path pkg/okf/types.go knowledge

# JSONサポート付きで概念とその関係を検査
./bin/okf show architecture/layers knowledge --json

# 自動化されたlog.mdとindex.mdのブックキーピングで新しい概念を作成
./bin/okf create decisions/auth-flow knowledge \
  --type Decision \
  --title "OAuth2 Authorization Flow" \
  --desc "Standardized on PKCE for client authentication."

# 既存の概念を更新
./bin/okf update decisions/auth-flow knowledge \
  --desc "Updated OAuth2 PKCE token refresh interval."

# 任意のターゲットプロジェクトにフルエージェントメモリスタックをブートストラップ
./bin/okf bootstrap /path/to/project --name "My Project"

# 任意のディレクトリに最小限のOKFバンドルのみを初期化
./bin/okf init my-project/knowledge

# ゼロナレッジ同期：ボールトを初期化し、緊急キットを印刷
./bin/okf hub init-vault knowledge

# Hubとの変更をプッシュまたは同期（オプション：--tokenまたはOKF_HUB_TOKEN）
./bin/okf hub push knowledge --password "pass" --secret-key "XXXX-..." --auth-token "my-token"
./bin/okf hub sync knowledge --password "pass" --secret-key "XXXX-..."

# OKFレジストリ（registry.okf-memory.dev）またはGitから外部ナレッジバンドルをプル
./bin/okf pull nextjs-15
./bin/okf pull nextjs-15 --min-score 80   # インストール前にバンドル品質をゲート
./bin/okf pull peter/django-5-rules
./bin/okf pull github.com/acme/agent-rules@v1.0.0

# ロックされたすべてのベンダーバンドルを新しい環境に復元
./bin/okf restore
./bin/okf restore --min-score 80          # すべての復元されたバンドルをゲート

# インストールされたベンダーバンドルを検査および管理
./bin/okf vendor list
./bin/okf vendor remove nextjs-15

3. マルチスコープメモリレイヤリングとスコープ付き解決

OKF Agent Memoryは、4つの決定論的なメモリスコープにわたって知識を整理します。検索中に上位レイヤーは、ローカルプロジェクトの決定が常に外部の上流パッケージやマシンベースラインよりも優先されることを保証するために、下位レイヤーの同一の概念IDを厳密にシャドウします。

flowchart TD
    subgraph Scopes ["OKF 4ティアメモリ階層"]
        P["<b>プロジェクト</b>（優先度100）<br/>プレフィックス：<i>なし</i>（例: decisions/auth）<br/>場所：./knowledge/"]
        V["<b>ベンダー</b>（優先度70）<br/>プレフィックス：@bundle/...（例: @nextjs-15/routing）<br/>場所：.okf/vendor/"]
        U["<b>ユーザー</b>（優先度50）<br/>プレフィックス：user:...（例: user:guidelines/style）<br/>場所：~/.okf/"]
        S["<b>システム</b>（優先度10）<br/>プレフィックス：system:...（例: system:corp/policy）<br/>場所：/etc/okf/"]
    end

    P -->|シャドウする|
    V
    V -->|シャドウする|
    U
    U -->|シャドウする|
    S

読み込み中

スコープ仕様マトリックス

スコープによる検索と表示のフィルタリング

# デフォルト（--scope all）：自動シャドウイングと優先順位付けで全レイヤーを検索
./bin/okf search "authentication"

# ベンダーパッケージ内のみを厳密に検索
./bin/okf search "routing" --scope vendor

# ローカルプロジェクトメモリ内のみを厳密に検索（またはエイリアス--scope bundleを使用）
./bin/okf search "architecture" --scope project

# ユーザーまたはシステムレイヤーを検索
./bin/okf search "style" --scope user
./bin/okf search "compliance" --scope system

# スコープを横断して概念を検査
./bin/okf show decisions/auth                        # ローカルプロジェクトの概念
./bin/okf show @nextjs-15/decisions/routing         # ベンダーパッケージの概念
./bin/okf show user:guidelines/style                # 個人のユーザー概念
./bin/okf show system:corp/policies                 # システムコンプライアンス概念

4. バンドル品質スコアカード（OpenSSFスタイル）

メンテナンスの手間なしに「再現可能に間違った」コンテキストを排除するために、3つの加重された柱にわたってナレッジバンドルを評価します。

1. 認識論的メンテナンス（35%）: stale_afterのない不変のバージョンバインドされた事実はデフォルトで100%有効です。ペナルティは、期限切れのレビュー期限または非推奨ステータスにのみ適用されます。
2. 人間によるスチュワードシップ（35%）: 検証済みの人間の署名（verified.by: human/*またはuser/*）と、レビューされていない合成ボットダンプを厳密に区別します。人間以外の検証はスチュワードシップポイントを0獲得します。
3. グラフ整合性（30%）: OKF v0.2グラフの厳密なヘルスチェック（リンク切れ0、孤立ノード0、有効なDAG）。

# 人間が読めるスコアカードの内訳と評価（A-F）
./bin/okf validate knowledge --scorecard

# 機械が読めるJSON出力
./bin/okf validate knowledge --scorecard --json

# CIでの品質ゲート（スコアが80未満の場合は終了コード1で失敗）
./bin/okf validate knowledge --min-score 80

# 事前プル品質ゲート（スコアが80未満の場合はインストールを中止しロールバック）
./bin/okf pull nextjs-15 --min-score 80

5. 任意のプロジェクトでのエージェントメモリのブートストラップ

単一のコマンドで、完全なOKF Agent Memoryアーキテクチャを任意の新規または既存のリポジトリにスキャフォールディングします。

# ターゲットプロジェクトにフルメモリスタックをブートストラップ
./bin/okf bootstrap /path/to/my-project --name "My Service"

これにより、以下が自動的にセットアップされます。

• knowledge/ — OKF v0.2準拠の永続メモリバンドル（index.md、log.md）
• .agents/skills/okf-memory/ — 埋め込みエージェントスキル定義と機能ガイド
• AGENTS.md — AIコーディングエージェント向けのプロジェクトに合わせた運用指示
• Makefile — 検証（make validate）と検索（make search q="..."）のための便利なタスク

6. MCPサーバーとしての実行

okfは、Claude Code、Cursor、Codex、その他のエージェントプラットフォームとシームレスに接続するために、stdio経由のネイティブModel Context Protocol（MCP）サーバーを搭載しています。

./bin/okf mcp knowledge

例MCP設定（claude_desktop_config.jsonまたはCursor）:

{
  "mcpServers": {
    "okf-memory": {
      "command": "/path/to/okf-agent-memory/bin/okf",
      "args": ["mcp", "/path/to/project/knowledge"]
    }
  }
}

---

📂 リポジトリ構造

okf-agent-memory/
├── .agents/                # アクティブなエージェントスキルとエージェント設定
│   └── skills/okf-memory/  # AIエージェントのための権威あるOKFメモリスキル（単一の真実の源）
├── benchmarks/             # プログレッシブ開示ベンチマークスイート & ハードウェアテストデータ
│   ├── data/               # モノリスドキュメント vs OKFバンドルテストフィクスチャ
│   └── results/            # 8つ以上のローカル & クラウドLLMにわたる再現可能なベンチマークログ
├── cmd/
│   ├── okf/                # スタンドアロンCLIと埋め込みMCPサーバー（stdio）
│   └── okf-benchmark/      # LLM TTFT & トークン測定のための自動ベンチマークランナー
├── docs/                   # ガイド、仕様、アーキテクチャ & リリースプレイブック
│   ├── README.md           # 中央ドキュメントインデックス & ナビゲーション
│   ├── guides/             # ユーザーガイド、CLI/MCPリファレンス & AI指示のベストプラクティス
│   ├── spec/               # OKF規約v0.1、互換性分析 & アーキテクチャRFC
│   ├── security/           # データガバナンス、秘密の防止 & 敵対的セキュリティ監査
│   ├── project/            # プロジェクトロードマップ、リリースプレイブック & マルチエージェントテスト
│   └── releases/           # バージョン管理されたリリースノート & 変更履歴アーカイブ（v0.1.0 - v0.6.2）
├── examples/               # ドメインニュートラルな参照DMAAプロジェクト（AGENTS.md + OKF v0.2 knowledge/）
│   ├── books/              # 文献 & 編集分析リポジトリ
│   ├── coaching/           # エグゼクティブコーチング & クライアントセッションリポジトリ
│   └── software/           # マイクロサービスアーキテクチャ & ADRエンジニアリングリポジトリ
├── knowledge/              # プロジェクト独自のOKF v0.2永続メモリバンドル
│   ├── index.md            # ルートプログレッシブ開示インデックス（okf_version: "0.2"）
│   ├── log.md              # 日付付き変更ログ（ISO 8601 YYYY-MM-DD）
│   ├── project/            # 概要 & バリュープロポジション
│   ├── architecture/       # 5ティアアーキテクチャ、ガバナンスモデル & 決定事項
│   ├── convention/         # 原則 & ライフサイクルワークフロー
│   └── roadmap/            # マイルストーン
├── packaging/              # ディストリビューションパッケージング
│   └── homebrew/           # 公式Homebrewフォーミュラ & タップ手順
├── pkg/
│   ├── lock/               # ゼロ依存OKF.lockパーサー & シリアライザー
│   ├── okf/                # コアライブラリ（パーサー、バリデーター、BM25、MCP、ブートストラップ）
│   │   └── assets/         # `make sync-assets`経由でミラーリングされた埋め込みブートストラップテンプレート & スキル
│   ├── registry/           # 分散型OKFレジストリクライアント & アーカイブアンパッカー
│   ├── sync/               # ブラインド同期エンジン、3者間調整 & ハブクライアント/サーバー
│   └── vault/              # AES-256-GCMエンベロープ暗号、Argon2id KDF & CASブラインドストレージ
├── scripts/                # 検証 & 自動監査レビューヘルパー（例: Jules統合）
├── AGENTS.md               # AIコーディングエージェントのための運用指示
├── CONTRIBUTING.md         # 貢献ガイドライン & 開発ワークフロー
├── CONTRIBUTORS.md         # コミュニティ貢献者 & 謝辞
├── CODE_OF_CONDUCT.md      # コントリビューター協定v2.1行動規範
├── Makefile                # ビルド、テスト、リント、検証 & リリースターゲット
├── LICENSE                 # MITライセンス
├── README.md               # メインリポジトリドキュメント
└── SECURITY.md             # セキュリティポリシー & レポートガイドライン

---

🧪 テストと検証

フルテストスイートを実行し、リポジトリの自己文書化ナレッジバンドルを検証します。

make check

---

📖 詳細ドキュメント

• ドキュメントインデックス — すべてのプロジェクトドキュメントの中央ディレクトリ。
• はじめにガイド — エージェントと人間向けの包括的なオンボーディングガイド。
• CLI & MCPリファレンス — 完全なコマンドラインおよびプロトコルツールのリファレンス。
• デュアルメモリAIアーキテクチャRFC — 認知的な2層エージェントメモリモデル（プッシュコデックス + プルナレッジ）。
• Agent Action Grammar RFC — AGENTS.mdのための決定論的でトークン効率の良いAAGマイクロシンタックス仕様。
• エージェント指示のベストプラクティス — 決定論的な指示設計とトークン最適化のガイド。
• OKF Agent Memory規約 v0.1 — 行動ルールとライフサイクル仕様。
• 貢献ガイド — 開発セットアップ、品質ゲート、プルリクエスト基準。
• セキュリティとプライバシーガイドライン — データガバナンス、秘密の防止、PII保護ルール。
• マルチエージェントテストと評価 — テストシナリオ、互換性マトリックス、およびベンチマーク。
• プロジェクトロードマップとマイルストーン — フェーズ化された開発計画。
• リリースプレイブック — バージョニング、CI/CDパイプライン、および配布手順。
• リリースノートと履歴 — バージョン管理された変更ログと過去のリリースノートアーカイブ。
• OKF v0.2互換性マトリックス — 仕様検証分析。
• なぜOKF Agent Memoryなのか？ — 詳細なバリュープロポジションと差別化要因。
• 代替案とエコシステム比較 — Mem0、Letta、およびアドホックなMarkdownファイルとの比較。

---

👥 貢献者

OKF Agent Memoryの構築と改善に貢献してくれたすべての素晴らしい貢献者に感謝します！

［画像: OKF Agent Memory Contributors］

あらゆる種類の貢献を歓迎します！詳細はCONTRIBUTING.mdおよびCONTRIBUTORS.mdをご覧ください。

---

💖 サポートとスポンサーシップ

OKF Agent Memoryが自律エージェントワークフローに役立つと感じた場合は、GitHubでプロジェクトをスポンサーすることを検討して、継続的な開発、セキュリティ強化、および仕様準拠をサポートしてください！

---

📄 ライセンス

MITライセンス。詳細はLICENSEを参照してください。