Memory Fabric

Memory Fabric

MCP に対応した AI コーディングアシスタント向けの、ファイル優先・ローカル優先のメモリレイヤーです。

Memory Fabric は、Claude Code、Cursor、GitHub Copilot などの AI ツールに、一貫性のあるプロジェクトを認識したコンテキストレイヤーを提供します。特定のモデル、エディター、クラウドプロバイダー、オペレーティングシステムに縛られることはありません。

メモリは YAML フロントマター付きの、人が読みやすい Markdown として保存されます。ベクトルデータベースは不要です。クラウドアカウントも不要です。埋め込みも必要ありません。

---

機能

• MCP ネイティブ：標準の Model Context Protocol を通じてメモリツールを公開します
• ファイル優先：Markdown ファイルを信頼できる唯一の情報源とし、内容を確認でき、コミットにも対応しています
• ローカル優先：コアの読み書きはオフラインで動作します
• ストア優先：事実は memory-store/ にファイルごとに保存されます。ルートのマップ（architecture.md、decisions.md など）は Dreaming によって再構築される生成ビューであり、手動では作成しません
• 自動記録：すべての git commit がエピソード記憶として自動的に記録されます。エージェントの協力は不要で、オプトインの post-commit フックを介して実行されます
• Git ネイティブのマージ：オプションのカスタムマージドライバーにより、共有タイムスタンプ行で競合させるのではなく、コードと同じように 2 つのブランチのメモリをきれいにマージできます
• 自己検証機能：メモリでは、依存するファイル、行、コミットを引用できます。ai-memory verify は古くなった引用を検出します
• 失敗から学習：write_failure_memory_tool は同じエラーの繰り返しを重複排除し、類似した記録が散在する代わりに、1 つの記録を蓄積していきます
• シークレットを安全に保護：API キーと認証情報は書き込む前にマスキングされます
• トークン予算を考慮：制限内にコンテキストを組み立て、ファイルを文書の途中で切り取りません
• 品質評価：メモリの有用性と、Dreaming の実行前後の結果をローカルでスコア化します
• Unicode に対応：あらゆる言語で動作します
• 段階的な機能低下：rg、git フック、Dreaming が設定されていなくても動作します

---

ステータス

v1.4.4 — 1.4.3 と同じ製品修正に加えて、公開アーティファクトを整理し、git 履歴を新しくしました。PyPI で公開中。 コア CLI と MCP ツールは一連の処理を完了できる状態です。リリース済みの内容、進行中の内容、今後の予定については ROADMAP.md をご覧ください。

---

デモ

CLI と自動記録の流れ：プロジェクトを初期化し、リポジトリ内にプレーンな Markdown ファイルとしてメモリを書き込み、エージェントの協力なしに git commit がエピソード記憶として記録される様子を確認できます。あるツールでエージェントがメモリを書き込み、別のツールがそれを読み取るという、ツール間の連携については、動画全編のストーリーボードを DEMO.md でご覧ください。

---

プライバシー — テレメトリなし

Memory Fabric はデータを外部に送信しません。アカウントも、クラウドも、分析機能も、ホームへの送信もありません。コアの読み書き処理ではネットワーク通信を一切行いません。オプションで行われるネットワークリクエストは、PyPI のバージョン差異チェックと LLM プロバイダーの事前確認のみで、どちらも --offline で無効にできます。メモリは自身の git 履歴に保存されるプレーンな Markdown であり、プッシュしない限りマシンの外に出ることはありません。

オプションで、初期設定では無効のフィールド日誌を有効にすると、ai-memory diary approve の実行後に、運用上のカウントをマシン上に記録できます。これはセッションジャーナルではなく、テレメトリでもありません。データが送信されることはありません。MEMORY_FABRIC_DIARY=0 は緊急停止スイッチです。これは意図的に保証されていることであり、変更される可能性のある初期設定ではありません。

---

インストール

PyPI から（推奨）

Python ≥ 3.11 が必要です。

pipx install memory-fabric          # CLI only
pipx install "memory-fabric[mcp]"   # CLI + MCP server

または、通常の pip を使用します（仮想環境内で実行してください）。

pip install memory-fabric          # CLI only
pip install "memory-fabric[mcp]"   # CLI + MCP server

インストールせずに一度だけ実行する場合（uv が必要です）：

uvx --from "memory-fabric[mcp]" memory-fabric-mcp   # starts the MCP server on stdio

GitHub から（最新版、プレリリース）

# CLI only
pipx install "git+https://github.com/elViRafa/agentic-memory.git"

# CLI + MCP server
pipx install "memory-fabric[mcp] @ git+https://github.com/elViRafa/agentic-memory.git"

または、通常の pip を使用します（仮想環境内で実行してください）。

pip install "git+https://github.com/elViRafa/agentic-memory.git"          # CLI only
pip install "memory-fabric[mcp] @ git+https://github.com/elViRafa/agentic-memory.git"  # + MCP

アップグレード

Memory Fabric は活発に開発されているため、定期的なアップグレードをおすすめします。

1. パッケージをアップグレードする：

   # If installed via pipx:
   pipx upgrade memory-fabric
   
   # If installed in a virtual environment via pip:
   pip install --upgrade "memory-fabric[mcp]"
   
   # If installed from GitHub (pre-release):
   pipx install --force "memory-fabric[mcp] @ git+https://github.com/elViRafa/agentic-memory.git"
   

2. MCP クライアントの設定を更新する（uvx インストールの場合）： クライアント設定で uvx を使ってサーバーを起動している場合（古い ai-memory install の実行時に書き込まれるデフォルト設定）、uv は初回にキャッシュしたビルドを提供し続け、バージョンを固定していない仕様を再解決しません。クライアントを再起動するだけでは不十分で、何の通知もなくサーバーが数リリース前のままになることがあります。アップグレード後は、次のいずれかを行ってください。

   # Re-write the client config (now pins the exact installed version, or points
   # at the local memory-fabric-mcp binary when one sits next to the CLI):
   ai-memory install --client <your-client> --project
   
   # ...or drop the stale cached build so uvx re-resolves:
   uv cache clean memory-fabric
   

   ai-memory doctor は、ローカルのバージョンが PyPI の最新バージョンと異なる場合や、別の ai-memory インストールが PATH 上でこのインストールより優先される場合に警告します。

3. MCP クライアントを再起動する： アップグレード後、クライアントが更新された memory-fabric-mcp サーバーを再読み込みできるよう、IDE（Cursor、VS Code）またはアシスタントのプロセス（Claude Code）を再起動してください。

4. ローカルプロジェクトを更新する（任意）： 古いバージョンの Memory Fabric で初期化したプロジェクトがある場合は、プロジェクトディレクトリに移動して、次を実行してください。

   ai-memory init --install-hooks
   

   既存のメモリ Markdown ファイルを上書きせずに、スターターテンプレートとローカルの git フック連携を最新の形式に安全に更新します。

Windows のターミナル：CLI は UTF-8 を出力します（メモリの内容にはダッシュや箇条書き記号が含まれることがあります）。Windows Terminal と PowerShell 7 ではそのまま表示できます。旧式のコンソール（OEM コードページを使用する PowerShell 5.1）で文字化けする場合は、chcp 65001 または PYTHONUTF8=1 を設定してください。

または、ローカル開発用にクローンして編集可能モードでインストールします。

git clone https://github.com/elViRafa/agentic-memory.git
cd agentic-memory
pip install -e .          # CLI only
pip install -e ".[mcp]"   # CLI + MCP server

---

クイックスタート

1. プロジェクトを初期化する

ai-memory init

現在のディレクトリに、スターターセクションと .gitignore を含む .ai-memory/ を作成します。

2. ヘルスチェックを行う

ai-memory doctor

3. メモリの品質を評価する

ai-memory eval
ai-memory eval --json

eval は、メモリがコーディングアシスタントにとって有用かどうかをスコア化します。セクションの網羅性、スターターテンプレートの内容、要約の品質、メタデータ、検索への対応状況、秘密情報の可能性をチェックします。

.ai-memory/ が存在する場合、レポートは無視対象のローカルファイルに保存されます。

.ai-memory/evals/latest.json
.ai-memory/evals/latest.md
.ai-memory/evals/<timestamp>-memory.json
.ai-memory/evals/<timestamp>-memory.md

.ai-memory/ がまだ存在しない場合、eval は初期化前のレポートのみを出力し、ファイルは作成しません。

4. メモリをクエリする

ai-memory query "authentication"

5. メンテナンスを実行する（Dreaming）

ai-memory dream --mode light
ai-memory dream --mode deep

Dreaming はメンテナンスの前にスナップショットを作成します。Dreaming の実行によってメモリの品質が向上したかどうかを評価できます。

ai-memory eval --dream latest
ai-memory dream --mode light --eval

Dream eval は、Dreaming 前のスナップショットと現在のメモリを比較し、スコアの変化、変更されたファイル、改善点、悪化点を報告します。

---

MCP サーバー — インストール

クライアントごとにコマンドは 1 つです。安全に再実行できます。既存の設定とマージし、上書きすることはありません。解析できない場合は元のファイルをバックアップします。

ワンクリックインストール

内部では uvx --from "memory-fabric[mcp]" memory-fabric-mcp を実行します。これは CLI の手順を省いた、ai-memory install と同じ正式な呼び出し方法です。
uv が必要です。

クライアント	コマンド
Claude Code	ai-memory install --client claude-code
Claude Desktop	ai-memory install --client claude-desktop
VS Code	ai-memory install --client vscode
Cursor	ai-memory install --client cursor
Windsurf	ai-memory install --client windsurf
Codex	ai-memory install --client codex
Antigravity	ai-memory install --client antigravity
Gemini CLI	ai-memory install --client gemini-cli
Cline	ai-memory install --client cline
検出されたすべてのクライアント	ai-memory install --client all

--project を追加すると、グローバル／ユーザー設定ではなく、プロジェクト単位の設定を書き込みます（クライアントが対応している場合）。--dry-run を追加すると、何も書き込まずに変更を統合差分でプレビューできます。--uninstall を追加すると、ファイル内のその他の内容には触れず、memory-fabric の項目のみを削除します。

利用可能な MCP ツール

ツール	説明
initialize_memory_fabric_tool	プロジェクトに .ai-memory/ のひな形を作成します
read_combined_context_tool	Tier 0 の指示と、トークン予算内で優先度付けされたメモリを読み込みます
read_section_tool	名前を指定して、単一のメモリセクションを読み込みます
keyword_search_tool	ripgrep または Python のフォールバックを使ってメモリを検索します
write_local_memory_tool	ステアリングセクション（framework-rules、ubiquitous-language）のみを更新します。事実やルートマップの書き込みは拒否されます（ストア優先）。ルートマップは memory-store/ から生成されます。write_memory_store_tool を使用してください
propose_memory_patch_tool	適用せずに、提案されたメモリの変更をプレビューします
dream_tool	メモリのメンテナンス／統合を実行します（--mode light
prepare_dream_payload_tool	候補スナップショットを準備し、クライアント主導の Dreaming 用の統合プロンプトを返します
apply_dream_results_tool	LLM が統合した JSON 出力を候補スナップショットに適用し、変更を保存します
evaluate_memory_fabric_tool	ローカルメモリの品質を評価します
evaluate_dream_quality_tool	スナップショットに対して Dreaming の実行品質を評価します
write_memory_store_tool	メモリファイルをセマンティックストアのパス（例：architecture/decisions/auth）に書き込みます。任意の evidence 引用リストを指定できます
read_memory_store_tool	セマンティックパスを指定して、単一のメモリストアファイルを読み込みます
list_memory_store_tool	メモリストア内のファイルを一覧表示します。プレフィックス／タグで絞り込むこともできます
delete_memory_store_tool	セマンティックパスを指定して、メモリストアのファイルを削除します
write_session_journal_tool	タイムスタンプ付きのセッションジャーナル項目を追記します（エピソード記憶）
write_failure_memory_tool	エラーと修正の組み合わせを記録します。同じエラーが再発した場合は、1つの項目に追記されます

---

エージェント型アーキテクチャ（エージェントが Memory Fabric を自動的に使えるようにする）

MCP サーバーを登録することは必要ですが、それだけでは不十分です。AI エージェントは、明示的に指示されない限り、そのツールを使用しません。

Memory Fabric には、これを自動で処理する エージェント型アーキテクチャ が用意されています。

プロジェクトで ai-memory init を実行すると、CLI が主要な AI ツールごとに最適化されたエージェント指示ファイル一式を自動的に配置します。

対象	作成されるファイル
Gemini CLI / Codex / Antigravity	AGENTS.md
Grok (TUI / Build / Agent harness)	AGENTS.md（プロジェクトの基本ルール）；完全なドキュメントと MCP 登録は ~/.grok/config.toml または .mcp.json に配置されます。クライアントにインストールされている場合は .grok/docs/user-guide/13-memory-fabric.md も参照してください
Cursor IDE	.cursor/rules/memory-fabric.mdc
Windsurf IDE	.windsurf/rules/memory-fabric.md
Cline / 汎用 IDE エージェント	.agents/rules/memory-store.md、.agents/rules/dreaming.md
Claude Code	CLAUDE.md（作成または追記）
GitHub Copilot	.github/copilot-instructions.md（作成または追記）

信頼できる唯一の情報源（同期）

これらのファイルはすべて、Memory Fabric の Python パッケージ内にある2つの標準コンテンツブロックから生成されます。ai-memory sync-agents を実行すると、これらのテンプレートから各プラットフォーム向けのファイルが再生成され、一貫性が確保されます。ai-memory init --install-hooks を使用した場合は、pre-commit git フックがコミットのたびにこの同期を自動実行します。

共有ユーザーファイル（AGENTS.md、CLAUDE.md、.github/copilot-instructions.md）では、ファブリックのコンテンツは管理対象のマーカーブロック（…）内に配置されます。同期時に書き換えられるのはマーカー間のコンテンツだけなので、その外側に追加した内容はバイト単位でそのまま保持されます。

プロジェクト指示（v1.1）

パッケージ独自のプロトコル指示に加えて、リポジトリで作業するすべての AI エージェントが共有する、手作業で作成した開発ガイドラインであるプロジェクト指示を定義できます。指示とは、role: steering のフロントマターを持つルートセクションファイル .ai-memory/<name>.md（組み込みの framework-rules や ubiquitous-language と同様）と、任意の2つのブール値の振り分けキーから成るものです。

キー	意味	デフォルト
sync	sync-agents が生成するツールごとのファイルに指示を含める	true
context	指示を Tier 0 として read_combined_context に注入する	組み込み指示では true、ユーザー指示では false（ファイルを読み込むエージェントは同期済みのコピーをすでに取得するため）

ai-memory sync-agents は、sync: true のすべての steering セクションを1つのプロジェクト指示ドキュメントにまとめ、.agents/rules/project-directives.md、.cursor/rules/project-directives.mdc、.windsurf/rules/project-directives.md と、AGENTS.md／CLAUDE.md／.github/copilot-instructions.md 内の管理対象マーカーブロックに配置します。これにより、AGENTS.md のみを読む Codex、OpenCode、Gemini にもプロジェクト指示が届きます。最後の同期対象の指示を削除すると、これらはすべて削除されます。

CI では、ai-memory sync-agents --check がドリフトを検出します。このコマンドはファイルを書き換えず、生成されたファイルのいずれかが最新でない場合は終了コード 1 を返します。ai-memory doctor はさらに、常時読み込まれるコンテキストのトークン予算（デフォルトは 3000、MEMORY_FABRIC_DIRECTIVE_BUDGET）超過の有無、手作業で編集した steering ファイルに秘密情報と思われる内容が含まれていないか、古い 1.1 以前のファブリックブロックが管理対象マーカーの外側に残っていないかについても警告します。

アーキテクチャの詳細については、AGENTIC_ARCHITECTURE.md を参照してください。

これが重要な理由

これらの指示ファイルがないと、エージェントは「MCP ツールを自動的には使いません」と説明することがよくあります。さらに悪い場合は、ネイティブのファイルシステムツールを使ってメモリの Markdown ファイルを直接書き込み、秘密情報のスキャン、トークン予算の管理、バックグラウンドでの Dreaming 管理を回避してしまいます。

ai-memory init を実行するだけで、エージェントのエコシステム全体で、設定不要ですぐに使える機能を利用できます。

---

他のプロジェクトで Memory Fabric を使用する

インストール済みの Memory Fabric を、すべてのコーディングプロジェクトで共通して使用できます。

1. 対象プロジェクトをスキャフォールドする： 対象プロジェクトのルートフォルダーに移動し、初期化します。

   cd /path/to/other-project
   ai-memory init --install-hooks
   

   これにより .ai-memory/ が自動的に作成され、Agentic Architecture のルールファイルが配置され、.gitignore が設定され、git の post-commit フックがインストールされます。

2. グローバル MCP 設定： AI アシスタントの設定が、グローバルにインストールされた memory-fabric-mcp 実行可能ファイルを参照していることを確認してください。MCP ツールは、アシスタントから cwd 引数として渡されるアクティブなプロジェクトのパスを自動的に解析して使用するため、グローバルな MCP サーバー登録 1 つで、すべてのローカルワークスペースに対応できます。

---

プロジェクトのメモリレイアウト

Memory Fabric はストア優先です。エージェントが手動で事実を書き込む場所は memory-store/ のみで、1 ファイルにつき 1 つの事実を記録します。ルートのマップファイル（architecture.md、decisions.md、debt.md、schemas.md、index.md）は、対応する memory-store/<category>/ サブツリーから Dreaming によって再構築される生成ビューです。直接編集しないでください。これらのファイルには generated: true のフロントマターがあり、手動で編集した内容は次回の Dream でレビュー用にストアへ反映されます。 例外はステアリング層です。role: steering のフロントマターを持つルートセクション（組み込みの framework-rules.md と ubiquitous-language.md、および作成したプロジェクト指示）は、手動で管理します。人間とエージェントはこれらのファイルを直接編集できます（MR でレビューしてください）。組み込みファイルは常に全体がコンテキストに読み込まれ、生成されることも、トークン予算によって削除されることもありません。ユーザー指示はデフォルトで context: false となり、代わりにツールごとの sync-agents ファイルを通じてエージェントに届きます。

.ai-memory/
|-- index.md                  # generated discovery index
|-- architecture.md           # generated map of memory-store/architecture/
|-- schemas.md                # generated map of memory-store/schemas/
|-- decisions.md              # generated map of memory-store/decisions/
|-- debt.md                   # generated map of memory-store/debt/
|-- ubiquitous-language.md    # hand-curated steering directive (always loaded)
|-- framework-rules.md        # hand-curated steering directive (always loaded)
|-- memory-store/             # the source of truth — one fact per file
|   |-- index.md              # generated store-wide index
|   |-- architecture/...
|   |-- decisions/...
|   |-- debt/...
|   |-- schemas/...
|   |-- failures/<slug>.md    # error -> fix pairs, deduplicated by normalized signature
|   |-- episodic/<date>.md    # agent-written session journals
|   `-- episodic/commits/<date>/<short-hash>.md  # one passively captured commit each
|-- evals/       # ignored local quality reports
|-- snapshots/   # ignored rollback baselines
|-- private/     # ignored personal notes + session markers
`-- .gitignore

すべてのメモリファイルは YAML フロントマターを使用します。

---
store_path: architecture/decisions/auth-service
summary: "One-line fallback used when the file exceeds the token budget."
priority: high
tags: [api, auth]
schema_version: "1.3"
last_updated: 2026-06-01T12:00:00-04:00
evidence: [src/auth.py:42, "commit:abc1234"]
---

Your memory content here.

任意の evidence フィールドを使用すると、メモリが依存する対象（ファイル、file:line、または commit:<hash>）を記載できます。ai-memory verify を実行して、それらの参照先が引き続き解決可能か確認してください。名前が変更または削除されたファイルを参照するメモリは、ひそかに古くなるのではなく、問題としてフラグ付けされます。

---

記録の信頼性

エージェント向けの指示ファイルを使えば、セッション開始時にエージェントがメモリを確実に読み取るようにできますが、書き込みはそれほど一貫しません。長いセッションでは指示が圧縮されて失われることがあり、ルールファイルをまったく読み込まないクライアントもあります。エージェントの協力に依存せず、このギャップを埋める仕組みが 2 つあります。コミットするとプロジェクトのブレインが自動更新され、ジャーナルを書かずにセッションを終了すると Stop フックが終了をブロックします。

パッシブキャプチャ。 ai-memory init --install-hooks を使うと、すべてのコミットがエピソード記憶として自動的に記録されます。

ai-memory capture              # capture HEAD (this is what the post-commit hook runs)
ai-memory capture --commit abc1234

各キャプチャでは、コミットごとに memory-store/episodic/commits/<date>/<short-hash>.md に 1 つのファイルが作成されます。フロントマターには source: passive-capture と review_status: pending が記録され、レビュー可能で、エージェントが書いたジャーナルエントリとは区別されます。コミットハッシュごとに冪等で、LLM を必要とせず、次回の ai-memory dream が統合または事実を抽出するための生データとなります。

1 日に 1 つの共有ファイルではなく、コミットごとに 1 つのファイルを作成することで、ツリーをマージ可能な状態に保てます。キャプチャはコミットの後に実行されるため、コミット N の記録をコミットできるのはコミット N+1 だけです。つまり、その記録は常に未コミットの状態で一時的に置かれます。共有の日次ファイルを使うと、常に追跡対象の変更済みファイルとなり、git はそれをマージしようとすると（error: Your local changes to the following files would be overwritten by merge）拒否します。これは、競合を解決できたはずのセマンティックマージドライバーを含め、マージ処理が実行される前の段階で起こります。コミットごとに異なる新規ファイルを作成すれば、そのファイルは未追跡のため、git はそのままマージでき、2 人の開発者が同じパスに書き込むこともありません。 ノイズコミット（マージ、[bot] の作成者、chore:／style:／ci:／build(deps) のプレフィックス、ロックファイルのみの変更）は、デフォルトでスキップされます。スキップは skipped_reason と --no-filter によるオプトアウトで明示され、決して黙って行われません。また、ai-memory dream --mode deep は14日より古いコミット記録を週次サマリーにまとめるため、 episodic/commits/ が際限なく増えることはありません。設計の全容については、ROADMAP_CAPTURE_HOOKS.md をご覧ください。

セッション終了時の強制。 ai-memory session-start はセッションの開始時刻を記録します。 ai-memory guard-journal は、write_session_journal_tool がそれ以降に呼び出されていない場合、 ゼロ以外の終了コード（理由は標準エラー出力）を返します。ai-memory install --client <claude-code|gemini-cli|codex> --with-hooks を使うと、これが自動的に組み込まれます。SessionStart はセッションを記録して 短いコンテキストリマインダーを挿入し、Stop はジャーナルが作成されるまでセッションの終了をブロックします。また、 圧縮前イベントでは、ブロックしないローカル統合チェックポイントが実行されます。ai-memory status はローカルのキャプチャ統計（最新のジャーナル、コミットキャプチャ、直近7日間に書き込まれた メモリー）を報告するため、キャプチャが実際に行われているか確認できます。

主張だけでなく、実証。 scripts/capture_rate_benchmark.py は、完全に非協力的なシミュレーション済みエージェント（自発的には write_session_journal_tool を決して呼び出さないエージェント）を、それぞれのモードで20セッション実行します。

モード	ジャーナルが記録されたセッション数	コミットキャプチャ率
手順のみ（フックなし）	0 / 20（0%）	20 / 20（100%）
フック有効（guard-journal による強制）	20 / 20（100%）	20 / 20（100%）

パッシブなコミットキャプチャは、クライアント側のセッションフックではなく git の post-commit フックで実行されるため、どちらの場合も100%を維持します。セッションジャーナルの記録率が0%から100%になるのは、 Stop フックを組み込んだ場合のみです。これは、強制の仕組みを実証するものであり（強制の基本機構は黙って スキップできません）、実環境でのエージェントの遵守状況を統計的に調査するものではありません。後者は別途実施する より大規模なベンチマーク作業です（ROADMAP.md のフェーズ5をご覧ください）。次のコマンドで再現できます。 python scripts/capture_rate_benchmark.py --sessions 20。

失敗の記憶。 コーディングエージェントにとって最も価値の高いカテゴリです。「以前まったく同じ エラーが発生したとき、こうすれば解決できました」：

ai-memory failure --error "KeyError: 'user_id' in handlers.py:12" --fix "Added a default value."

エラーのテキストは正規化され（パスと行番号が除去され）、安定したシグネチャに変換されます。 そのため、同じ種類のエラーが再発すると、類似した重複ファイルが散在するのではなく、 memory-store/failures/<slug>.md の1つのエントリーに蓄積され、occurrences カウンターも 増加します。

---

Git ネイティブの信頼性

メモリが、その内容を記述するコードと同じ git リポジトリにあるからこそ実現できる 2 つの機能です。ベクトルデータベースやクラウドのメモリ製品では、どちらも提供できません。

セマンティックマージドライバー。 以前は、同じストアファイルに新しい事実を追記した 2 つのブランチで、実際に追加された内容が重複していなくても、共通の last_updated 行で競合が発生していました。ai-memory init --merge-driver は、チームメモリで実際に使われる変更の形を解決するカスタムドライバーを登録します。安全に解決できない場合は、git 独自のテキストマージにフォールバックするため、インストールしていない場合より悪化することはありません。

ai-memory init --merge-driver

優先順位の高い順に、次の変更をマージします。

変更の形	解決方法
フロントマターのみ	タグを統合し、より緊急度の高い優先度を採用し、後の日付の last_updated を採用
生成ビュー（index.md、failures.md、その他のルートマップ）	統合 — 競合は発生しません。次の Dreaming 実行時に memory-store/ から再構築されるためです
両方のブランチで新しい事実を追記	両方を保持し、ほぼ重複する行は削除
両方のブランチで異なる ## エントリを記述（2 つのエージェントが同じ日に記録）	ブロック単位でマージ
同じ ## エントリを両方で書き換え	git のテキストマージに委ねます — 実際に意見が食い違っているため、人が選択します

.gitattributes に .ai-memory/**/*.md merge=memory-fabric を書き込み（コミットされ、共有されます）、ドライバーコマンドをローカルの git config に登録します（git の設計上、クローンごとに設定されます）。

チーム向け：クローンごとに設定が必要な点が問題になります。 .gitattributes はリポジトリとともに共有されますが、ドライバーコマンドは共有されません。登録せずにクローンしてマージするチームメイトには、理由の説明もないまま .ai-memory/ で通常のテキスト競合が発生します。この問題を解決する方法は 2 つあります。ai-memory doctor は、クローンでドライバーが宣言されているのに登録されていない場合に警告します。また、そのようなクローンで ai-memory init を実行すると、ドライバーが自動的に登録されます。

すでにマージの途中ですか？ マージをやり直す必要はありません。resolve-conflicts は git がすでに記録した競合に同じ解決方法を適用し、解決できた内容をステージします。

ai-memory resolve-conflicts
# resolved: .ai-memory/failures.md, .ai-memory/memory-store/episodic/2026-07-28.md
git commit

人の判断が必要な内容については、終了コードに非ゼロを返し、競合マーカーも含めてファイルを変更しません。そのため、競合のあるマージ全体に対して安全に実行できます。

検証可能な引用。 上記の evidence フィールドをご覧ください。引用が引き続き解決できることを確認し、解決できない引用にフラグを付けるコマンドは ai-memory verify です。

---

グローバルメモリ

すべてのプロジェクトに適用される開発者レベルの設定は、次の場所に保存されます。

プラットフォーム	パス
Windows	%APPDATA%\memory-fabric\global\
macOS	~/Library/Application Support/memory-fabric/global/
Linux	$XDG_CONFIG_HOME/memory-fabric/global/

global/directives.md は Tier 0 です。トークン予算の制約を受けず、常に全体が読み込まれます。

---

CLI リファレンス

ai-memory [--cwd <path>] [--json] [--debug-llm] <command>

Commands:
  init            Create .ai-memory/ scaffolding (--install-hooks, --merge-driver)
  status          Show memory status and capture stats
  doctor          Validate memory files and environment
  verify          Check evidence citations still resolve (--no-mark for a read-only report)
  failure         Record an error -> fix pair (--error, --fix, --tags)
  merge-driver    Git merge driver backend (invoked by git itself, not for direct use)
  resolve-conflicts  Resolve conflicted .ai-memory files of an in-progress merge (--all)
  capture         Record a commit as episodic memory (--commit, default HEAD)
  session-start   Mark session start (for client SessionStart hooks)
  guard-journal   Exit non-zero if no session journal was written (for client Stop hooks)
  install         Configure an MCP client to use memory-fabric (--client <name|all>)
  eval            Score memory quality or Dreaming quality
  bench           Coding-memory benchmark: memory-on vs memory-off retrieval
  dream           Run memory maintenance (--mode light|deep)
  migrate         Split legacy hand-written sections into store entries (--dry-run, --section, --no-llm)
  query           Search memory
  store           CRUD operations on semantic memory store
  sync-agents     Regenerate agent instruction files from canonical templates
  sync-global     Preview local-to-global promotions
  rollback        Restore from a snapshot (--to <name>, or --list to discover valid names)
  clean           Prune old snapshots/candidates (--keep-snapshots, --keep-candidates, --dry-run)
  diary           Local field diary (approve|revoke|mute|unmute|status|checkpoint|wipe) — off by default, never sent

評価の例：

ai-memory eval
ai-memory eval --json
ai-memory eval --llm-review
ai-memory eval --dream latest
ai-memory eval --dream memory-20260601T140000_0400

オプションの LLM レビューは、デフォルトでは有効になりません。リクエストされた場合も、決定論的なローカルスコアが引き続き正解の基準となります。LLM のメモは補助的なものであり、レビュー前に入力はサニタイズされます。

ai-memory bench
ai-memory bench --json
ai-memory bench --fixture . --suite .ai-memory/evals/bench.yaml

bench は、後のセッションでの質問により以前の決定を思い出せるかを評価します（メモリありと空のストアを比較）。組み込みのフィクスチャと評価方法は benchmarks/coding-memory/ にあります。LLM は必要ありません。

組み込みフィクスチャ（2026-08-15、ai-memory bench）：

タスク	メモリありの再現率	メモリなしの再現率
TOT_LOCAL の CAD とシステム列	1.00	0.00
test_*.py の命名規則	1.00	0.00
Django REST Framework を使用しない	1.00	0.00
urnas_add_pos_calc PRD 0008/0009 の取り消し	1.00	0.00
平均／向上幅	1.00	0.00（向上幅 1.00）

---

LLM 設定と MCP Sampling

Memory Fabric は、セマンティックなメモリ統合（Dreaming）と定性的な評価に大規模言語モデル（LLM）を使用します。設定方法は、環境変数による直接設定と、ゼロコンフィグの MCP Sampling の 2 通りです。

解決の優先順位

操作で LLM が必要な場合、Memory Fabric は次の順序でプロバイダーを解決します。

1. 直接 LLM プロバイダー：環境変数 MEMORY_FABRIC_LLM_PROVIDER が対応する API キーとともに設定されている場合、直接 API を呼び出します。
2. ネイティブ MCP サンプリング：直接プロバイダーが設定されていない（または設定されたキーが不足している）場合、かつ、親エージェントがサンプリングに対応しているアクティブな MCP セッション内でコマンドが実行される場合、Memory Fabric は LLM の呼び出しをエージェント自体に委ねます。
3. ローカルへのフォールバック：どちらも利用できない場合、意味的な統合は行わず、ローカルの決定論的な正規表現ベースの重複排除に段階的に切り替えます。

Dreaming で MCP サンプリングを使用する

MCP サンプリングを使うと、ローカルの API キーやプロバイダー環境変数を設定せずに、Memory Fabric で意味的な Dreaming と評価を実行できます。代わりに、ホストクライアント（例：Claude Code）のネイティブ LLM 接続を使用します。

仕組み

1. AI アシスタントが MCP 経由で dream_tool または evaluate_memory_fabric_tool を呼び出すと、Memory Fabric サーバーはクライアントセッションがサンプリング機能に対応しているか確認します。
2. 対応していて、直接プロバイダーが設定されていない場合、サーバーはクライアントに create_message リクエストを送信します。
3. クライアントのアシスタントが内部で LLM による推論を実行し、統合されたメモリ JSON または評価メモを返します。

主なメリット

• **設定不要：**バックグラウンドの MCP サーバープロセスに GEMINI_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY を設定したり、公開したりする必要はありません。
• **コンテキストの統一：**統合には、メインのコーディングアシスタントで設定されているものと同じモデルおよび設定が使用されます。

重要

**CLI の制限：**MCP サンプリングは、アクティブなクライアントとサーバーのセッションを必要とします。スタンドアロンのターミナル CLI（ai-memory）は MCP クライアントの外部で実行されるため、コマンドラインから ai-memory dream を実行しても MCP サンプリングは使用できません。CLI 経由で LLM ベースの統合を行うには、直接 LLM プロバイダーを設定する必要があります。

クライアント主導型／分割ツールによる Dreaming（デッドロックとタイムアウトの回避）

逐次処理型またはブロッキング型の MCP クライアント環境（IDE 拡張機能やエージェント型ループなど）では、クライアントがツールの応答を待っている間に、ネストされた MCP サンプリングリクエスト（create_message）を実行すると、JSON-RPC のデッドロックや実行タイムアウトが発生することがあります。

この再入可能性の問題を完全に回避するため、Memory Fabric はクライアント主導型の分割ツールによる Dreaming プロトコルを提供しています。

1. ペイロードの準備：エージェント／クライアントは、最初に prepare_dream_payload_tool を呼び出します。このツールは consolidation_prompt と candidate_store ID を返しますが、ブロッキングを伴う LLM 推論は実行しません。
2. ローカルで実行：クライアントは独自のローカル LLM 接続／コンテキストを使って、返された consolidation_prompt を実行し、未加工の JSON 出力を取得します。
3. 結果の適用：クライアントは apply_dream_results_tool(candidate_store=..., llm_response=...) を呼び出して、未加工の LLM JSON 応答を送り返します。Memory Fabric は応答を解析し、統合した変更を候補フォルダーに適用して、新しいメモリ状態を保存します。

LLM プロバイダーの直接設定

CLI で LLM を使用する場合、または特定のプロバイダーを使用して MCP Sampling をバイパスする場合は、次の環境変数を設定してください。

プロバイダー	環境変数	備考
Gemini	MEMORY_FABRIC_LLM_PROVIDER=gemini GEMINI_API_KEY=your_key	デフォルトは gemini-2.5-flash です
OpenAI	MEMORY_FABRIC_LLM_PROVIDER=openai OPENAI_API_KEY=your_key OPENAI_MODEL=gpt-4o-mini (任意) OPENAI_API_BASE=... (任意)	カスタムのローカル／リモートの OpenAI 互換エンドポイントに接続できます
Anthropic	MEMORY_FABRIC_LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=your_key	デフォルトは claude-3-5-haiku-20241022 です
Ollama	MEMORY_FABRIC_LLM_PROVIDER=ollama OLLAMA_HOST=... (任意) OLLAMA_MODEL=gemma2 (任意)	オフラインでのローカル推論

深い Dreaming ではモデルの品質が重要です。 統合の品質、特に矛盾の検出は、小規模なローカルモデルでは低下します。また、この失敗は表面化しません（モデルが単に空の contradictions リストを返します）。私たちのテストでは、8B クラスのモデル（qwen3-vl:8b）は意図的に仕込んだ TTL の競合を見逃しました。意味的な競合検出に dream --mode deep を利用する場合は、約 14B 以上のモデル（またはホステッドプロバイダー）を推奨します。安全策として、Memory Fabric は LLM の回答に関係なく、文言が重複している一方で数値が異なるストアファイルにフラグを付ける決定論的なヒューリスティックも常に実行します。

---

LLM のデバッグ

LLM プロバイダー（Gemini、OpenAI、Anthropic、Ollama）に送信された正確なプロンプトと受信した応答を確認するには、LLM デバッグログを有効にします。

• CLI から：サブコマンドの前にグローバルフラグ --debug-llm を指定します。

  ai-memory --debug-llm dream --mode deep
  

  ログは自動的に sys.stderr に出力され、llm_debug.log という名前のファイル（.ai-memory/llm_debug.log ディレクトリが存在する場合はその中、存在しない場合は現在の作業ディレクトリ）にも追記されます。

• 環境変数から：環境変数 MEMORY_FABRIC_LLM_DEBUG を設定します。

  • stderr：プロンプトと生の JSON 応答のみを sys.stderr に出力します。
  • 1 または true：sys.stderr に出力し、デフォルトの llm_debug.log ファイルにも書き込みます。
  • /path/to/log.txt（またはその他のカスタム値）：指定したカスタムファイルパスにログを追記します。

認証情報と API キーを保護するため、Authorization や x-api-key などのヘッダーは、デバッグログ内で自動的に [REDACTED] に置き換えられます。

---

書き込みの安全性

すべての書き込み処理では、保存前にシークレットを検出します。検出されたシークレットは [REDACTED_SECRET] に置き換えられ、応答の redactions フィールドに返されます。ファイルロックにより、同時書き込みによる破損を防ぎます。

Eval は既存のメモリをスキャンして、シークレットの可能性があるものを検出しますが、既存ファイルは書き換えません。手動で確認が必要な箇所を報告します。

---

要件

• Python >= 3.11
• mcp >= 1.0.0（任意。MCP サーバーのみで必要）
• rg（任意。ripgrep を使うとキーワード検索が高速になります。利用できない場合は Python によるフォールバックを使用します）

---

コントリビューション

コントリビューションを歓迎します。セットアップ、CI で適用されるチェック、およびストア優先の規約については、CONTRIBUTING.md をご覧ください。セキュリティに関わる内容については、公開イシューを作成するのではなく、SECURITY.md をご覧ください。

ライセンス

MIT — © 2026 Memory Fabric Contributors。テレメトリー、アカウント、クラウドは不要です。