Graph Memory

AI コーディングエージェントのためのローカル知識グラフメモリ — あらゆる会話がクエリできる単一のクロスプロジェクトグラフ。あるセッションのエージェントが、他のすべてのセッションで獲得された知識にアクセスできます。

従来のエージェントのセッション単位メモリを、ローカル知識グラフに置き換えます。知識グラフ + PageRank 拡散検索によるクロスコンセプト関連付けで、エージェントが1つのセッション内で全プロジェクトの知識にアクセスできるようにします。

English summary: Graph Memory replaces per-session memory with a single local knowledge graph. Retrieval seeds from semantic nearest-neighbors and spreads via Personalized PageRank over auto-built edges, fusing 50% semantic + 50% graph-diffusion scores. It exposes 5 tools to agents over MCP and ships a Cytoscape.js visualization. Everything runs locally — embeddings are a local sentence-transformers model, the graph is a JSON file, and the LLM is only used (optionally) for knowledge extraction.

特徴 / Features

• グラフ連想検索 — PageRank がグラフ上を拡散し、ある技術ポイントから関連するデプロイ詳細、教訓、ユーザー設定を導き出します

• LLM 知識抽出 — 会話/メモリから構造化知識ノードを自動抽出

• 3層の重複排除 — MD5 → embedding 類似度 >0.85 → 新規作成

• メモリ修正 — 古い情報を発見したら既存ノードを更新可能

• MCP 統合 — MCP 経由で各 Agent に5つのツールを自動公開

• 可視化 — Cytoscape.js ダークテーマ、フィルタリング/CRUD 操作

• ローカル実行 — データはマシン外に出ず、embedding モデルはローカルで読み込み

クイックスタート

1. インストール

git clone https://github.com/yourname/graph-memory.git
cd graph-memory
pip install -e ".[mcp,dotenv]"

2. 設定

cp .env.example .env
# 编辑 .env 填入 LLM API key 和 base_url(检索/写入不需要 LLM,只有 extract 需要)

3. 起動

python -m graph_memory.server

http://127.0.0.1:9121/ を開いて可視化インターフェースを確認します。

初回起動時に embedding モデル(デフォルト BAAI/bge-base-zh-v1.5、約400MB)をダウンロードし、以降はローカルにキャッシュされます。

3a. デモデータ(任意)

初回体験用に、汎用技術知識のサンプルセットを投入して、空のプロジェクトをすぐ使える状態にできます:

python seed_demo.py

その後 http://127.0.0.1:9121/ で小さなグラフを確認できます。デモデータのクリア: data/graph.json と data/embeddings.npz を削除して server を再起動します。

3b. Docker ワンコマンド実行

docker build -t graph-memory .
docker run -p 9121:9121 -v gm_data:/app/data -v gm_models:/root/.cache/huggingface graph-memory

4. 既存メモリのインポート

初回使用時に、Hermes / Claude Code / Codex から既存メモリをインポート:

curl -X POST http://127.0.0.1:9121/api/import?source=all

Claude Code のセッション履歴を一括抽出することも可能:

curl -X POST http://127.0.0.1:9121/api/extract/sessions

インポートパスは環境変数で上書き可能(HERMES_HOME / CLAUDE_HOME / CODEX_HOME)。デフォルトは各 Agent のユーザーホームディレクトリ配下の標準位置を指します。

Agent での使用

MCP Server(自動利用可能)

Agent の MCP 設定に graph-memory MCP server を追加し、再起動すると自動的に5つのツールが使えます:

agent は会話中にこれらのツールを直接呼び出せます。手動操作は不要です。

MCP server は stdio で動作し、HTTP クライアントとして FastAPI バックエンドにプロキシします。モデル自体は読み込まず、バックエンドと不整合な2つのグラフデータを持つことを回避します。

Skill(agent 向けガイド)

SKILL.md は agent 向けの使用ガイドです。agent が読み込むと以下のルールに従います:

• 回答前にまずグラフメモリを検索

• 回答後に価値のある新知識を抽出して書き込み

• 古い情報を発見したら積極的に更新

使用方法

方法 1: agent と直接会話

"あるサーバー上の推論プロジェクトを確認して"

agent は自動的に retrieve を呼び出して関連知識を検索し、プロジェクトパス/ポート/ブランチ情報を取得して回答します。

方法 2: agent に新知識を記憶させる

"覚えておいて、vLLM 0.25 は speculative decoding をサポートした"

agent は write を呼び出して知識グラフに書き込み、既存ノードと自動的に関連付けます。

方法 3: 古い情報の修正

"あるサービスのポートが変更された。8000 ではない"

agent は update を呼び出して既存ノードを更新します。

方法 4: 可視化ブラウズ

http://127.0.0.1:9121/ を開いて検索、フィルタリング、CRUD 操作。

アーキテクチャ

┌──────────────────────────────────────────┐
│  Agent (Hermes / Claude Code / ...)       │
│  ┌─────────────┐  ┌──────────────────┐   │
│  │ MCP Client  │  │ Skill (指导)     │   │
│  └──────┬──────┘  └──────────────────┘   │
│         │ stdio                           │
│  ┌──────▼──────┐                          │
│  │ MCP Server  │  (轻量, 不加载模型)       │
│  │ mcp_server  │                          │
│  └──────┬──────┘                          │
└─────────┼─────────────────────────────────┘
          │ HTTP
┌─────────▼─────────────────────────────────┐
│  FastAPI Server (port 9121)              │
│  ┌───────────┐  ┌──────────┐  ┌────────┐ │
│  │ GraphEngine│  │ LLM提取  │  │ 导入器 │ │
│  │ NetworkX  │  │ OpenAI   │  │        │ │
│  │ PageRank  │  │ 兼容API  │  └────────┘ │
│  │ bge embed │  └──────────┘              │
│  └───────────┘                            │
│       │                                   │
│  ┌────▼────┐  ┌────────────┐              │
│  │ graph   │  │ embeddings │              │
│  │ .json   │  │ .npz       │              │
│  └─────────┘  └────────────┘              │
└─────────────────────────────────────────────┘

MCP server は軽量 HTTP クライアントで、embedding モデルは読み込みません。すべての計算は FastAPI server で行われ、2つのプロセスがそれぞれエンジンを持つことによるデータ不整合を回避します。

API

評価

python benchmark.py

30問 × 3ラウンド × LLM スコアリングで、「MEMORY.md のみ」vs「グラフメモリ追加」の回答品質を比較します。

問題セットは自身の知識ベースに合わせてカスタマイズする必要があります(benchmark.py 冒頭のコメント参照)。検索動作自体の回帰テストは regression.py を使用します(決定的スナップショット比較、LLM 非依存):

python regression.py snapshot baseline      # 改代码前
python regression.py snapshot after-change  # 改代码后
python regression.py compare baseline after-change

テスト

pip install -e ".[test]"
pytest tests/ -q

エンジン層のテストは決定的なフェイク embedder を使用し、実際のモデルをダウンロードせずオフラインで実行可能です。

知識管理(肥大化防止)

日常使用でグラフが肥大化します。定期的に管理ツールを実行:

python manage.py status        # 查看图健康状态
python manage.py dedup         # 扫描重复节点报告
python manage.py merge          # 合并相似节点(embedding >0.85)
python manage.py prune --dry-run   # 预览孤立+过时节点
python manage.py prune              # 执行清理

クリーンアップルール:

• 次数 <2 かつ 90日間更新されていないノードは削除(関連付けがあるものは保持)

• 類似ノードのマージ時は、より長く詳細な内容を保持

• すべての操作は --dry-run でプレビュー可能

設定項目

License

MIT