mcncarl/agent-memory-vault

Markdown-first shared memory vault for Claude Code and Codex with SQLite, Zvec, Git, closeout, and audit

Agent Memory Vault – Claude Code、Codex などの AI コーディングエージェント向けのローカルで Git バックアップされた長期記憶ストア

概要 – AI コーディングエージェントが自分のマシン上で永続的で監査可能なナレッジベースを維持できるようにする Python ベースのツールキット。真実のソースはプレーンテキストの Markdown ディレクトリ（ボールト）です。Git がすべての変更を追跡し、SQLite が高速なキーワード/FTS 検索を提供し、オプションのローカル埋め込みモデル（EmbeddingGemma + Zvec）がセマンティック検索を追加します。すべてのデータはプライベートのままです。公開リポジトリには再利用可能なスクリプトとテンプレートのみが含まれています。

重要性 – 現在の AI コーディングアシスタント（Claude Code、Codex など）は、現在のチャットセッションで話されたことだけを覚えています。プロジェクトが多くのセッションにまたがる場合、重要な事実、決定、コードスニペットが失われます。Agent Memory Vault は、これらのエージェントに共有されバージョン管理されたメモリを提供します。それは：

セッションをまたいで永続化します。
すべての書き込みがレビューされ、署名され、Git に記録されることを保証します。
複数のエージェント（Codex、Claude、サードパーティの「Ailu」）による安全な同時使用を可能にします。
権威ある Markdown を変更せずに、キーワード検索とオプションのベクトル検索の両方を提供します。

コアコンポーネント

コンポーネント	役割
`templates/vault/`	プライベートフォルダにコピーできる既製の Markdown レイアウト。
`scripts/bootstrap.py`	新しいボールトを作成し、プライベート Git リポジトリを初期化し、初期の `INDEX.md` を書き込みます。
`scripts/memoryctl`	エージェントが検索、取得、書き込み、移行、ヘルスチェックなどに使用する統合コマンドラインインターフェース。
`scripts/agent_memory_index.py`	ボールトから SQLite FTS インデックスを構築します。
`scripts/agent_memory_search.py`	キーワード + オプションのベクトル（Zvec）検索を実行し、ランク付けされた候補を返します。
`scripts/agent_memory_retrieve.py`	選択した Markdown ファイルを再度開き、ハッシュを検証し、制限付きの抜粋を返します。
`scripts/agent_memory_write.py`	フェンシングトークンと Git コミットを使用した読み取り-準備-承認-適用書き込みフローを実装します。
`scripts/agent_memory_migrate.py`	明示的なバックアップと監査手順を使用して、ボールトスキーマ（v1 → v4）のアップグレードを処理します。
`scripts/agent_memory_closeout.py`	書き込みを完了し、Git に領収書を記録し、監査台帳を更新します。
`scripts/agent_memory_doctor.py`	ボールト、インデックス、ランタイム設定を検証するエンドツーエンドのヘルスチェックスイート。

仕組み（高レベルのフロー）

ボールトを作成 – bootstrap.py はプライベートディレクトリを作成し、Markdown テンプレートをコピーし、新しい Git リポジトリにコミットします。
インデックス – agent_memory_index.py はボールトをスキャンし、SQLite FTS テーブルを構築します。オプションで Zvec ベクトルインデックスが追加されます。
検索 – エージェントは memoryctl --actor <agent> search "query" を呼び出します。CLI はキーワード一致をマージし、有効な場合はベクトルスコア（ハイブリッド RRF）もマージし、memory_id のリストを返します。
取得 – memoryctl retrieve --view section … は正確なファイルを再度開き、保存されたハッシュが現在のファイルと一致するか確認し、安全な抜粋を返します。
書き込み – 書き込みプロトコルは次のとおりです。
- write read-target → 現在のバイトとリーストークンを取得します。
- write prepare → 新しいバージョンを提案し、単調増加するフェンシングトークンを取得します。
- 承認（人間またはポリシー）→ 提案を承認します。
- write apply → CLI はリース、トークン、Git ベースを検証し、ファイルを原子的に置き換えて領収書を記録します。
- closeout → 最終監査エントリと Git コミット。
移行/アップグレード – memoryctl --actor migration … は計画された読み取り専用の移行を実行し、状態 DB をバックアップし、明示的なレビュー後にのみ変更を適用します。

主要な安全保証

Git バックアップされた不変性 – 受け入れられたすべての変更は署名付き Git コミットです。ボールトはロールバックできます。
フェンシングトークン – 古いライターが新しい提案を上書きするのを防ぎます。
監査台帳 – すべての読み取り、書き込み、状態遷移は、ハッシュ、タイムスタンプ、リスク分類とともに記録されます。
プライバシー優先のログ – 検索ログにはハッシュと分類のみが保存され、生のクエリやユーザーを特定するデータは決して保存されません。
明示的なリスククラス – action_sensitive とマークされたアクションは、より厳格な証拠を必要とし、ダウングレードできません。

インストール（クイックスタート）

# リポジトリをクローン
git clone https://github.com/mcncarl/agent-memory-vault.git
cd agent-memory-vault

# POSIX エントリポイントをインストール（計画してから適用）
python3 scripts/install-posix.py --plan \
  --memory-root "$HOME/agent-memory-vault" --no-host-hooks --json
python3 scripts/install-posix.py --apply \
  --memory-root "$HOME/agent-memory-vault" --no-host-hooks \
  --launchagent-backup-dir "$HOME/.config/agent-memory/backups/launchagent-NEW" \
  --json

--plan ステップは何が起こるかを読み取って報告するだけです。--apply は実際のブートストラップ、Git 初期化、インデックス作成を実行します。

AI エージェントによる一般的な使用法

# 関連するプロジェクトノートを検索
scripts/memoryctl --actor codex search "deployment boundary" --limit 5

# 特定のセクションを安全に取得
scripts/memoryctl --actor codex retrieve --view section \
  --file "项目/example.md" --project-id example-app \
  --section-id s0002 --expected-sha256 '<outline-sha256>' --json

# 新しい決定記録を提案（エージェントがマークダウンを準備し、人間に承認を求める）
scripts/memoryctl --actor codex write read-target --json <<'JSON'
{"schema_version":2,"target_relative_path":"决策/2024-10-17-deploy.md","app_id":"example-app","project_id":"example-project"}
JSON
# …人間が提案 JSON をレビューし、次に：
 scripts/memoryctl --actor codex write apply <proposal-id> --json

すべての書き込みは同じゲート付きフローを通過し、ボールトに未レビューの編集が含まれることは決してないことを保証します。

オプションのセマンティック検索 – ベクトルベースの取得が必要な場合は、追加の環境をインストールします：

python3 -m venv .venv-vector
.venv-vector/bin/pip install -r requirements-vector.lock

ベクトル層は候補 ID のみを提供します。権威ある SQLite/Markdown 層が最終フィルタリングを実行します。

サポートされているプラットフォーム – macOS、Linux（POSIX インストーラー）、Windows 10/11（PowerShell インストーラー）。コアコードは純粋な Python 3.10+ で、外部サービスはありません。すべてのデータはローカルマシンに残ります。

成熟度 – リポジトリには完全なテストスイート（scripts/run_tests_isolated.py）と「doctor」ヘルスチェックコマンドが含まれています。設計はローカル AI エージェント向けの本番グレードの安全性を目指していますが、依然としてニッチな自己ホスト型ツールであり、独自の環境で Claude Code、Codex、または類似のエージェントを実行する開発者を対象としています。

結論 – Agent Memory Vault は、複数の AI コーディングエージェントが安全に読み書きできる、プライベートでバージョン管理され検索可能なナレッジベースを提供します。一時的なチャットセッションのメモリと永続的なプロジェクトドキュメントの間のギャップを埋め、データを自分の管理下に置きます。