Global Agent Memory

グローバルエージェントメモリ

Claude Code、Codex、その他の MCP 対応エージェントのための、ローカルファーストでプロジェクトを認識する永続的なメモリです。

Global Agent Memory は、ホスト型サービスにナレッジベースの管理を委ねることなく、複数のコーディングエージェントで共有でき、内容を確認可能なメモリを提供します。Markdown ファイルを正規のデータとして扱い、ハイブリッドなローカル MCP ランタイムをエージェント向けの公開インターフェイスとし、ダッシュボードから人がエージェントの記憶内容を承認、編集、保護、削除できます。エージェントのコマンドはバックグラウンドサーバーなしで動作します。認証済みのローカルホストサーバーは、ダッシュボードのために必要に応じて起動し、ファイルのリアルタイム監視や埋め込み処理の共有のために継続的に実行することもできます。

1 つの Vault。複数のエージェント。人が管理するメモリ。

クイックスタート · Obsidian Vault · ダッシュボード · 仕組み · セキュリティ · MCP コントラクト · ドキュメント

Global Agent Memory を選ぶ理由

コーディングエージェントはセッション中には役立ちますが、重要なコンテキストはセッション間で失われたり、個々のクライアント間に分散したりしがちです。Global Agent Memory は、次のような知識を永続的に保持するレイヤーを提供します。

• アーキテクチャ上の決定事項やプロジェクトの規約。
• 検証済みのワークフローや運用手順書。
• 繰り返し発生する問題と、実証済みの解決策。
• プロジェクトの設定、エンティティ、引き継ぎの要約。
• 新しいタスクやエージェントセッションのための、範囲を限定したコンテキスト。

エージェントはメモリを候補として提案します。永続化する前に人が確認し、表示範囲を管理できます。また、後から更新、置き換え、アーカイブ、完全削除することもできます。

比較

アプローチ	エージェント間で共有	人が確認可能	プロジェクトを認識	所有者がアクセスを管理	持ち運び可能な信頼できる情報源
CLAUDE.md / AGENTS.md	限定的	✓	✓	—	✓
基本的なメモリ MCP	✓	さまざま	さまざま	さまざま	さまざま
ホスト型エージェントメモリ	✓	さまざま	✓	プロバイダーが定義	—
Global Agent Memory	✓	✓	✓	✓	Markdown

常にプロンプトに含めるべき簡潔なルールには、プロジェクトの指示ファイルを使いましょう。知識を検索可能にし、クライアント間で共有し、人が確認でき、時間とともに更新できるようにする場合や、明示的な権限の背後に隠す場合は、Global Agent Memory を使いましょう。

主な特徴

• エージェント間で共有 — Claude Code、Codex、その他の MCP クライアントが、同じサービスと不変のメモリ ID を使用します。
• デフォルトでプロジェクトを認識 — Git のルート、リモート、エイリアス、プロジェクトレジストリにより、検索範囲がアクティブなプロジェクト内に限定されます。
• Markdown を正本として使用 — Vault は読みやすく、移植性とバックアップ性に優れ、Obsidian でも利用できます。
• 人によるレビューのワークフロー — エージェントが候補を作成し、オーナーがダッシュボードで承認、編集、却下、または競合の解決を行います。
• 保護・封印されたメモリ — 機密性の高い知識は通常の検索対象から除外し、オーナーがアクセスを管理する領域に配置できます。
• ハイブリッドなローカル検索 — SQLite FTS5 によるキーワード検索に、オプションの Ollama 埋め込みと sqlite-vec を組み合わせて、セマンティックランキングを追加できます。
• オフラインでも利用しやすい設計 — Ollama が利用できない場合も、キーワード検索とライフサイクル操作は引き続き実行できます。
• 再構築可能な生成状態 — SQLite、FTS、ベクトル、キュー、キャッシュは Markdown から再作成できます。
• 固定された MCP V1 契約 — ツール、リソース、プロンプト、エンベロープ、互換性ルールはリポジトリでバージョン管理されています。
• バックグラウンドサーバーは必須ではありません： オプションのデーモンがオフラインの場合、Claude Code、Codex、CLI コマンドは同じ MCP アプリケーションサービスにインプロセスでフォールバックします。
• ローカルのセキュリティ境界： ダッシュボードまたは HTTP MCP がアクティブな場合、サーバーは 127.0.0.1 にバインドし、Vault の外部に保存された生成済みベアラートークンを要求します。

実際のプロジェクト Vault 向け

オプトイン方式のパフォーマンススイートでは、10,000 件の合成メモリを作成し、両方の実行モードで使われるものと同じインデックス作成および検索処理を実行します。記録済みの macOS ARM64 ベースラインでは、全件の再構築に 36.5 秒、ウォーム状態のキーワード検索 P95 に 56 ms、ウォーム状態のハイブリッド検索 P95 に 76 ms、増分 stdio プロキシのオーバーヘッドに 1.5 ms かかります。結果はマシンによって異なります。変更ノート、検索、プロキシの各予算は、リグレッションゲートとして実行されます。測定方法と完全なベースラインをご覧ください。

3 つのインターフェース、1 つのメモリシステム

Global Agent Memory は MCP サーバーにとどまりません。エージェント、オーナー、ナレッジワーカーは、用途に合わせて設計された 3 つのインターフェースを通じて、同じ正本メモリを利用します。

インターフェース	対象	提供する機能
MCP	Claude Code、Codex、その他のエージェント	固定された V1 契約を通じた、プロジェクトを認識したコンテキスト、検索、候補の作成、安全な更新、ライフサイクル操作、権限リクエスト
Obsidian Vault	閲覧、記述、リンク、長期的な知識管理	移植可能な Markdown と YAML、テンプレート、ネイティブの Bases ビュー、プロジェクト概要ハブ、ウィキリンク、バックリンク、グラフナビゲーション、直接編集の同期
ローカルダッシュボード	オーナーによる迅速なレビューと管理	候補の承認と編集、競合の比較、公開範囲の分類、保護データへのアクセス判断、検索、プロジェクト、アクティビティ、バックアップ、システムの健全性

Vault が永続的な信頼できる唯一の情報源です。ダッシュボードはそれを補完するコントロールプレーンであり、MCP インターフェースはエージェントが使用する安全な自動化レイヤーです。Obsidian、ダッシュボード、またはその両方を使っても、メモリの別コピーが作られることはありません。

ダッシュボードの概要

_{合成 Atlas プロジェクトデータを使用した実際のダッシュボード UI です。非公開の Vault コンテンツは表示されません。}

クイックスタート

Claude Code、Codex、その他の MCP クライアントで永続メモリを使うための最短手順です。ガイド付きインストーラーにより、ローカルサービス、Obsidian 互換 Vault、ダッシュボード、MCP 登録、エージェントスキルをまとめて作成できます。

要件

• macOS または Linux
• Python 3.12 以降
• uv
• 管理対象クライアントとの連携には Claude Code または Codex
• 任意：Markdown Vault の閲覧には Obsidian
• 任意：セマンティック検索には Ollama

1. インストール

uv tool install global-memory-mcp

未リリースの最新ソースをインストールするには、 uv tool install git+https://github.com/ozankasikci/global-agent-memory.git を使用します。ローカルの チェックアウトには、uv tool install . を使用します。

2. ガイド付きセットアップを実行する

global-memory setup

セットアップでは、1 つのプランが表示され、変更を加える前に一度だけ確認を求められます。ローカル Vault を初期化し、保護されたトークンを作成して、Claude Code と Codex を検出し、それらの MCP 連携とスキルをインストールして、正常なクライアントであることを確認し、ダッシュボードを開きます。ダッシュボードを開くと、認証された localhost サーバーが必要に応じて起動します。このコマンドは べき等であるため、再度実行すると、無関係なクライアント設定を置き換えることなく、管理対象のコンポーネントを修復または更新します。

デフォルト以外のセットアップが必要な場合は、フラグを使用します。

# Non-interactive installation
global-memory setup --yes

# Choose a different Vault on first setup
global-memory setup --vault "$HOME/Memory"

# Install only one client, or no client yet
global-memory setup --clients claude-code
global-memory setup --clients none

# Optional: install an always-on native service for live watching and shared indexing
global-memory setup --service

# Preview without changing files or services
global-memory setup --dry-run

3. インストール済みのエージェントショートカットを使用する

セットアップでは、検出された各クライアントに 5 つの基本ショートカットがインストールされます。

ショートカット	目的
gam-context	タスクに必要な、プロジェクトに応じたコンテキストを読み込む
gam-search	判断、事実、エラー、規約、解決策を検索する
gam-remember	明示的に提供された、長期保存すべき知識を候補として提案する
gam-review	変更を加えずに候補キューを表示する
gam-dashboard	認証済みのダッシュボードを開く

Claude Code では、たとえば /gam-context fix the upload retry bug のように直接呼び出します。 Codex では、/skills と入力してスキルを選択するか、たとえば $gam-context fix the upload retry bug のように直接指定します。

4. ダッシュボードを再度開く

global-memory dashboard

接続済みのエージェントに次のように依頼することもできます。

Global Agent Memory のダッシュボードを開いてください。

エージェントは memory_dashboard_open を呼び出し、同じ認証済みローカル ダッシュボードを開きます。

手動でのインストールと修復

高度なセットアップやトラブルシューティングでは、個別のコマンドも引き続き使用できます。

global-memory init --vault "$HOME/Documents/Global Agent Memory"
global-memory daemon install-service --kind launchd  # use systemd on Linux
global-memory integrations install all
global-memory integrations verify all
global-memory doctor

エージェントでの使用方法

連携後は通常、メモリーコマンドを手動で実行するのではなく、意図を説明します。

作業前にコンテキストを取得する

作業を始める前に、このプロジェクトに関連するメモリーを読み込み、規約と最近の決定事項を要約してください。

長期保存するメモリーを提案する

本番環境の ARM64 バイナリはローカルでビルドしてサーバーにアップロードする必要があることを記憶してください。デプロイに関する議論を根拠として、プロジェクトの規約に追加してください。

エージェントは候補を作成します。承認されるまでは、何も有効になりません。

既存の知識を更新する

デプロイに関するメモリーを見つけ、新しいヘルスチェックコマンドで更新してください。重複は作成しないでください。

レビュー画面を開く

候補をレビューできるよう、メモリーダッシュボードを開いてください。

共有の連携スキルにより、対応するエージェントは、メモリーを取得、提案、更新するタイミングや、重複を避ける方法を学びます。

Obsidian Vault

設定された Obsidian Vault は、人が読める永続的な信頼できる情報源であり、不透明なデータベースのエクスポートではありません。管理対象のメモリはすべて、YAML プロパティ、安定したメモリ ID、ライフサイクルのメタデータ、プロジェクトを考慮したリンクを備えた通常の Markdown ファイルです。

初期化では、既存のファイルを置き換えることなく、Obsidian ワークスペースが追加されます。

• 決定、事実、解決策、規約、設定、エンティティ、参照、セッションの要約、プロジェクト概要のテンプレート；
• 候補レビューキュー、アクティブなナレッジ、最近の更新、プロジェクト別の決定、検証済みの解決策、ライフサイクル履歴を表示するネイティブの Bases ビュー；
• プロジェクトのメモリを埋め込み、メモが候補、アクティブ、却下、置き換え済み、アーカイブ済みの各フォルダー間を移動しても安定して維持されるプロジェクト概要ハブ；
• バックリンクとグラフナビゲーションのための Wiki リンクと相互の置き換えリンク；
• リクエスト時の同期により、Obsidian で編集した通常のコンテンツや説明用プロパティが、バックグラウンドサービスなしで検索可能になります；
• バックグラウンドサービスが有効な場合、即時にインデックスを作成するオプションのウォッチャー同期。

Obsidian は任意です。同じ Markdown は、どのテキストエディターでも読み取り・編集できます。ライフサイクルとアクセス制御ポリシーの変更は、検証、楽観的同時実行制御、監査記録を維持するため、ダッシュボード、MCP、または CLI から行ってください。

Dashboard

認証済みダッシュボードは、所有者向けのコントロールプレーンで、次の機能を利用できます。

• プロジェクト概要と最近のプロジェクトアクティビティ；
• 候補を一度に 1 件ずつレビューして編集；
• 重複および競合の比較；
• メモリの検索とライフサイクル管理；
• Standard、Protected、Sealed の分類；
• アクセスリクエストの承認と有効な許可の取り消し；
• 監査記録付きの、Sealed メモリに対する所有者のロック解除；
• プロジェクトの切り替え、システムの健全性確認、再インデックス、バックアップ；
• 正規の Markdown を Obsidian またはローカルファイルビューアで開く。

_{候補レビューでは、所有者が永続的なメモリを承認する前に、エビデンスと競合を確認できます。}

ダッシュボードの起動 URL は 60 秒後に期限切れとなり、1 回のみ交換でき、ローカルの HttpOnly セッションが作成されます。起動 URL を共有しないでください。

メモリの可視性とアクセス

レベル	エージェントのデフォルト動作	所有者による制御
Standard	通常のスコープ付き検索結果に含まれます	通常の候補レビューとライフサイクルレビュー
Protected	デフォルトの結果から除外されます。エージェントには中立的な関連性シグナルのみが返されます	所有者が対象のメモリ、権限、期間、ポリシー、許可対象プロジェクトを正確に選択します
Sealed	本文はインデックスに登録されず、エージェントツールから返されません	所有者がロック解除したダッシュボードでの 1 回の表示。アクセスはすべて監査されます

Protected の許可は、目的、プロジェクト、エージェント、権限、対象のメモリ ID、期間によってスコープが設定されます。所有者はリクエストの権限を引き下げることはできますが、引き上げることはできません。エージェントはアクセスをリクエストして状態を確認できますが、許可の承認、拒否、取り消しはできません。

重要

Protected と Sealed のメモリは、秘密情報管理ツールではありません。Global Agent Memory にパスワード、認証情報、秘密鍵、API キー、ベアラートークンを保存しないでください。

仕組み

flowchart LR
    A[Claude Code] -->|stdio MCP| H[Hybrid MCP runtime]
    B[Codex] -->|stdio MCP| H
    C[CLI] -->|MCP| H

    H -->|daemonless default| E[Application and domain services]
    H -.->|optional localhost daemon| D[Watcher, shared indexing, dashboard]
    D --> E
    E --> V[Markdown Vault<br/>canonical state]
    E --> I[SQLite FTS5 and sqlite-vec<br/>generated state]
    E --> O[Ollama embeddings<br/>optional]
    D --> W[Local dashboard<br/>owner control]

global-memory-mcp ブリッジは、正常に稼働している共有デーモンを優先し、利用できない場合は、同じ MCP サーバーとアプリケーションサービスをプロセス内で実行します。どちらの経路も、同じ固定された MCP V1 コントラクトと、同じ正規の Markdown および生成された SQLite の状態を使用します。オプションのデーモンは、Vault のリアルタイム監視、バックグラウンドでの埋め込み再試行、HTTP MCP、ダッシュボードセッションを担います。エージェントのメモリ操作は、デーモンが利用できるかどうかに依存しません。

依存関係の方向は次のとおりです。

transport and client adapters → application services → domain

Vault、SQLite、ベクトル、埋め込み、Git、Watchdog、クライアント連携はアダプターです。ドメイン層はこれらに依存しません。

MCP インターフェース

MCP インターフェースは、AI 向けの唯一のパブリック API です。クライアントが Vault、SQLite データベース、ベクトル、トークン、ランタイムログを直接読み取ることはありません。

固定された V1 のディスカバリースナップショットには、現在、17 個のツール、10 個のリソース、6 個のプロンプトが含まれています。

機能	MCP ツール
検索	memory_search、memory_context、memory_get、memory_status
候補とライフサイクル	memory_remember、memory_update、memory_approve、memory_reject、memory_supersede、memory_archive
ナビゲーションと操作	memory_open、memory_dashboard_open、memory_reindex、memory_projects、memory_tags
保護されたアクセス	memory_access_request、memory_access_status

すべての変更操作は、request_id によって再実行しても安全です。更新には楽観的同時実行制御が適用され、古いバージョンを使用した場合は、新しい知識を黙って上書きするのではなく、VERSION_CONFLICT エラーになります。

完全なコントラクトについては、MCP Contract V1 と生成された contracts/mcp/v1/ スキーマを参照してください。

CLI の例

CLI は、接続されたエージェントと同じ MCP 経路を使用します。オプションのデーモンを優先し、利用できない場合は、インメモリトランスポートを介して固定された MCP コントラクトを呼び出します。Markdown や SQLite を直接読み取ってアクセス制御を迂回することはありません。

# Check health
global-memory status
global-memory doctor

# Register and detect a project
global-memory project add my-project --root "$HOME/Projects/my-project"
global-memory project detect "$HOME/Projects/my-project"

# Search and build bounded task context
global-memory search "deployment rollback" --project my-project
global-memory context "Prepare the next release" --project my-project --token-budget 3000

# Create a review candidate
global-memory remember \
  "Release rollback procedure" \
  "Use the blue-green rollback task and verify both health endpoints." \
  --type reference \
  --scope project \
  --project my-project

# Rebuild generated indexes
global-memory reindex --full

# Back up canonical Markdown
global-memory backup "$HOME/Backups/global-agent-memory.zip"

コマンドの完全なリファレンスを確認するには、global-memory --help または global-memory <command> --help を実行してください。

セキュリティモデル

Global Agent Memory は、リモートに公開するメモリ API ではなく、ローカルサービスとして設計されています。

• オプションの HTTP サーバーとダッシュボードサーバーは、127.0.0.1 に制限されています。
• ストリーミング可能な HTTP には、生成されたローカルのベアラートークンが必要です。
• トークン、データベース、ログ、ロック、生成された状態は、Vault の外部に保持されます。
• トークンファイルのアクセス権限は、ユーザーのみに制限されます。
• ダッシュボードセッションは、有効期間が短く、ローカル限定で、HttpOnly です。
• パスは設定された Vault 内に限定され、パストラバーサルやシンボリックリンクによる逸脱がないか確認されます。
• 通常のログでは、本文、プロンプト、埋め込み、シークレット、認証情報を秘匿します。
• 生成された状態は削除でき、正規の Markdown から再構築できます。
• エージェント向けの検索では、Protected および Sealed のメモリはフェイルクローズ方式で扱われます。

セキュリティ上の問題は、SECURITY.md に従って報告してください。

開発

リポジトリをクローンしてから、Python とダッシュボードの依存関係をインストールします。

uv sync
npm ci --prefix dashboard

標準の品質チェックを実行します。

make check

品質チェックでは、Ruff によるフォーマットとリンティング、厳格な MyPy チェック、TypeScript の本番ビルド、単体／統合／コントラクト／E2E テスト、カバレッジ、決定論的な MCP コントラクトの再生成を実施します。

目的を絞った便利なコマンド：

make unit
make integration
make contract
make e2e
make dashboard-check
make performance   # opt-in 10,000-note performance suite

MCP コントラクトを変更する場合：

make contract-generate
make contract-check

コントリビューションを歓迎します。CONTRIBUTING.md を参照し、新しいメジャーコントラクトを並行して導入する意図がない限り、変更が固定された V1 コントラクトと互換性を保つようにしてください。

コミュニティとロードマップ

• 利用方法に関する質問をしたり、エージェントのワークフローを共有したりするには、 GitHub Discussionsをご利用ください。
• good first issue またはhelp wanted の一覧から、範囲が明確な貢献を選んでください。
• 今後予定されている配布、セキュリティ、統合作業については、 公開ロードマップをご確認ください。
• このプロジェクトが役に立った場合は、リポジトリにスターを付けると、ほかのエージェントツール利用者が 見つけやすくなります。

ドキュメント

ガイド	目的
運用	インストール、デーモン管理、診断、バックアップ、復元、アップグレード、復旧
Claude Code	Claude Code 用のスキルと MCP の管理登録
Codex	Codex 用のスキルと MCP の管理登録
Hermes Agent	手動での stdio MCP 登録と、検証済みの検索スモークテスト
アーキテクチャ	依存関係の方向性とハイブリッドランタイムの所有権モデル
設定	プラットフォーム標準の保存場所、環境変数、セキュリティのデフォルト設定
MCP Contract V1	公開互換性とレスポンスエンベロープのルール
テスト	標準、パフォーマンス、ライブ受け入れのテスト戦略
パフォーマンスのベースライン	10,000 件のノートのベンチマーク手法と予算
リリースチェックリスト	現在の V1 受け入れエビデンスと、残るリリースゲート
実装計画	当初の製品要件と段階的な実装計画

プロジェクトの状況

Global Agent Memory は現在 V1 の積極的な開発中であり、 GitHub Releasesおよび PyPIを通じて配布されています。現在の GitHub リリースと ソースパッケージのバージョンは0.1.7、MCP コントラクトのバージョンはv1です。

製品名はGlobal Agent Memoryです。技術識別子global-memory、 global-memory-mcp、global-memoryd、global_memory、product: global-memory は、V1 との互換性のため変更されません。

検証済みのシナリオと、今後残っているライブ受け入れ作業については、 V1 リリースチェックリストをご覧ください。

ライセンス

Global Agent Memory は、pyproject.tomlに記載された MIT ライセンスの下で 利用できます。