MemoryGraph

あなたのエージェントは、関連する記憶を見つけました。MemoryGraph は、その記憶が今も正しいかどうかをエージェントに伝えます。

MemoryGraph は、AI エージェントの信念に対するローカルファーストのエビデンス層および改訂層です。ソースからの観測を保持し、クレームをテンポラルグラフとして表現し、クレームが現在・過去・論争中である理由を説明します。

MVP ステータス

決定論的な MVP は稼働しています。正式なアーキテクチャは 00-architecture-index.md から始まり、実装済みのカーネルは以下をカバーします：

• 不変なソース観測。

• 型付きエンティティノードと、正確なエビデンス範囲を持つアトミックなクレームエッジ。

• 現時点と過去の信念を扱うバイテンポラルなクエリ。

• 明示的な確認、矛盾、およびアトミックな取って代わり。

• recall、history、explain コマンド。

• ハードバンク分離と、追記のみのミューテーションイベントログ。

• プロバイダに依存しないドリーム提案検証器（エビデンス、ウォーターマーク、クレームバージョン、冪等性、信頼度、チャレンジャー、レビューのゲート付き）。

• 永続化されたドリーム実行、タスク、提案、レビュー項目、リース、イベントウォーターマーク、アトミックな提案コミット。

• ソースデータを外部モデルに送信せずに、完全なドリームサイクルを実行する決定的なメタデータプロバイダ。

• MemoryRotBench のフィクスチャ、ベースライン、検索の採点、エンジン統合。

• 依存のないローカルベースラインと置換可能なエンベーダを備えたハイブリッド FTS/ベクトル再呼（recall）。

• 信頼できない指示に似たコンテンツの検索時隔離。

• リース、ハートビート更新、リトライ、リプレイ安全な再開を備えたクラッシュから復旧可能な Dream ワーカー。

• 候補のみを提案できる OpenAI 互換の構造化出力プロバイダ。

• recall、record、explain、correct、forget の 5 ツールを持つ STDIO MCP サーバー。

• ユーザー承認済みの Codex JSONL の取り込みと、プロジェクト範囲の Codex インストーラー。

• 決定的な Obsidian 互換 Markdown レビュープロジェクション。

• 成功したコーディング試行と失敗したコーディング試行の、制限された再利用を実現する一級の手続きエピソード。

• 再現可能な no-memory、Markdown、BM25、フラットコンテキスト、外部/Graphify のベンチマークアダプタ。

• クロスプラットフォームの CI、パッケージ検証、実行可能な doctor 診断。

実際のエンジンは現在、公開されている MemoryRetrieval クエリ 12 個すべてと、本番のカオス・コントラクト 7 件すべてを満たしています。このチェックポイントでのリポジトリのテストスイートは 196 個のテストに合格しています。最初のフィンガプリント付き公開マトリクスでは、最も強い単純なベースラインが 7/12 であるのに対し、MemoryGraph は 12/12 に合格しています。

クイックスタート

uv sync
uv run memorygraph init --database /tmp/memorygraph.db
uv run memorygraph doctor --database /tmp/memorygraph.db
uv run memorygraph bank create personal:founder --database /tmp/memorygraph.db
uv run memorygraph dogfood bootstrap --database /tmp/memorygraph.db
uv run memorygraph predicate define works_at \
  --bank personal:founder --cardinality one --volatility volatile \
  --database /tmp/memorygraph.db

まずエビデンスを記録し、それをクレームに変換します：

OBSERVATION_ID=$(uv run memorygraph observe "Abrar works at Acme." \
  --bank personal:founder --source-key event:acme \
  --database /tmp/memorygraph.db)

CLAIM_ID=$(uv run memorygraph claim assert Abrar works_at Acme \
  --bank personal:founder --observation "$OBSERVATION_ID" \
  --database /tmp/memorygraph.db)

Python API は、組み込みアプリケーション向けに confirm_claim、contradict_claim、supersede_claim、recall、history、explain も公開しています。

将来のエージェントが成功した戦略を再利用できるように—または既知の失敗を避けられるように—コーディング試行を記録します。ただし、それが普遍的な知識であると偽ることはありません：

memorygraph record-attempt "Run migrations before starting the worker" \
  --bank project:my-app --source-key attempt:migrate-worker \
  --task "start durable worker" --outcome success \
  --applicability-json '{"database":"sqlite"}'

ドリームサイクルを実行

組み込みプロバイダは metadata.memorygraph から型付き候補を読み取り、グラフ変更を提案し、エビデンスと時間的な前提条件を検証して、適格な提案を 1 つのトランザクションでコミットします。モデルプロバイダは同じ候補専用プロトコルを実装し、データベースへの直接的な書き込み経路を持つことはありません。

PYTHONPATH=src:. uv run python examples/run_dream_cycle.py \
  --database /tmp/memorygraph-dream.db

uv run memorygraph dream status RUN_ID \
  --bank personal:founder --database /tmp/memorygraph-dream.db

uv run memorygraph dream reviews \
  --bank personal:founder --database /tmp/memorygraph-dream.db

uv run memorygraph dream rollback RUN_ID \
  --bank personal:founder --database /tmp/memorygraph-dream.db

CLI を取り込みでは、observe --metadata-file FILE.json で候補エンベロープを渡し、その後に memorygraph dream run --bank BANK を実行します。--mode dry_run は提案を検証して永続化しますが、観測を消費せず、クレームも変更しません。

永続的な実行の場合は、作業をキューに入れ、ワーカーを別途実行します：

uv run memorygraph dream queue \
  --bank personal:founder --database /tmp/memorygraph-dream.db

uv run memorygraph dream worker \
  --bank personal:founder --database /tmp/memorygraph-dream.db

OpenAI 互換の Responses エンドポイントを使用するには、操作対象のキー変数を設定し、キューとワーカーの両方にモデルを渡します。プロバイダの出力は厳密な構造化データとしてと解析され、同じ決定論的なエビデンスゲートとコミットゲートを通過します。

export OPENAI_API_KEY=...
uv run memorygraph dream queue --bank personal:founder \
  --provider-model YOUR_MODEL --database /tmp/memorygraph-dream.db
uv run memorygraph dream worker --bank personal:founder \
  --provider-model YOUR_MODEL --database /tmp/memorygraph-dream.db

Codex を接続

パッケージをインストールし、プロジェクト銀行を初期化し、プロジェクト スコープの MCP 設定を追加します：

uv run memorygraph init
uv run memorygraph bank create project:my-app
uv run memorygraph install-codex --project .
uv run memorygraph probe-codex --project .

インストーラーは .codex/config.toml に [mcp_servers.memorygraph] ブロックを作成または修復し、現在の Python 環境の memorygraph.mcp STDIO モジュールを指すよう設定し、書き込みを許可確認するように Codex を設定します。グローバルな Codex 設定は変更しません。5 つの MCP 操作は、明示的なバンクスコープが必要です。

probe-codex はプロジェクト設定を検証し、実際の MCP サブプロセスのライフサイクルを実行します。.project-database を指定すると、使い捨ての一時的なプローブ DB の代わりに、設定済みのプロジェクトデータベースを調べます。

セッションコンテンツのインポートはオプションです。JSONL レコードには bank、session_id、turn_id、role、content、approved の指定が必須で、承認されていない録音はデフォルトでスキップされます：

memorygraph ingest-codex approved-session.jsonl

Dogfood アルファ

公式のオフライン 6 アーム フィクスチャマトリクスは以下の通りです：

PYTHONPATH=src:. uv run python examples/run_dogfood_fixture_matrix.py

実プロジェクトでは、最初に運用対約を初期化します：

uv run memorygraph dogfood bootstrap \
  --database .memorygraph/memory.db \
  --bank project:my-app \
  --workspace my-app

このフィクスチャマトリクスは、以下のアームを実行します：

• no_memory

• markdown

• memorygraph_graph_only

• memorygraph_gated_dream

• memorygraph_always_dream

• graphify_compatible

タスクの成功/失敗、有効な再取得の制度、禁止または古い再取得の漏洩、繰り返された誤り、レイテンシ、トークン見積、ツール呼び出し、リトライ、推定コストフィールド、Dream レビューの負荷を測定します。結果は benchmarks/reports/dogfood-offline-mvp.json と、追記のみの台帳 benchmarks/reports/dogfood-offline-mvp.jsonl に書込みます。タスクの成功/失敗はクエリの期待に従います。Dream レビューのバックログは、それ自体で表示されるコストとして残ります。

このフィクスチャに対する現在のオフライン結果（2026-08-22 時点）：

• memorygraph_always_dream: 3/3

• memorygraph_graph_only: 1/3

• memorygraph_gated_dream: 1/3

• graphify_compatible: 1/3

• markdown: 1/3、ただし禁じられたフラグメントの漏洩を伴う

graphify_compatible は、外部のリトリーバーが同じマニフェスト、時間制限、および採点契約に沿って競えるようにするプロトコルアダプタです。これは、このリポジトリが既にライブの Graphify 比較を完了したと主張するものではありません。

Obsidian での人間によるレビュー

現在のクレーム、正確な来歴、関係、Dream レビュー待ちキューを含む Markdown ボールトを生成します：

memorygraph project-obsidian --bank project:my-app \
  --output .memorygraph/obsidian

Markdown は使い捨てで、マニフェスト管理下にあります。SQLite の観測と追記のみのイベントログは権威性を保ちます。生成したノートを編集しても、黙ってメモリが変更されることはありません。

なぜグラフか？

グラフはエージェントに組み立て可能な構造を与えます。エンティティはノードとなり、Abrar --works_at--> Stripe のようなクレームは型付きエッジになります。MemoryGraph はエッジを普遍の真実として扱いません。各クレームバージョンは、有効時間、システム時間、ライフサイクル、来歴、正確なソースエビデンスを保持します。それが、役立つメモリグラフと古い事実ストアの違いです。

開発

uv sync --extra dev
uv run pytest
uv run ruff check .
PYTHONPATH=src:. python examples/run_memoryrotbench_memorygraph.py
PYTHONPATH=src:. python examples/run_memoryrotbench_chaos_memorygraph.py
python examples/run_memoryrotbench_baseline_matrix.py
PYTHONPATH=src:. uv run python examples/run_dogfood_fixture_matrix.py

期待される結果：公開検索ケースが 12/12、本番カオオスケースが 7/7 です。マトリクスは、ミュータブル不可能で、コーパスと評価者双方のフィンガープリントされた記録を benchmarks/reports/public-baseline-matrix.jsonl に追記します。--graphify-command を指定すると、外部の Graphify アダプタを同じ公開コーパスと採点契約の下で実行できます。

次の製品レイヤー

次のゲートは、実際の運用実証です：ライブのモデル連携によるドッグフードセッション、実際の Graphify との対決、実コーディングでのトライアルパートナー利用です。完全パイプラインの削除残余は監査され報告されます。履歴を書き換えない限り安全に消去できない識別子の残渣は、隠すのではなく公開します。Dream 検証器は、すべてのプロバイダとワーカーが、必ず通過しなければならない安全の帯であり続けます。

Apache-2.0 ライセンスの下で提供されます。