Graph Memory

Ein lokaler Knowledge-Graph-Speicher für KI-Codierungsagenten – ein projektübergreifender Graph, den jede Konversation abfragen kann, sodass ein Agent in einer Sitzung auf Wissen zugreift, das in jeder anderen Sitzung erfasst wurde.

Ein lokales Knowledge-Graph-Speichersystem, das die nach Sitzungen getrennte Speicherung herkömmlicher Agenten ersetzt. Mit Knowledge-Graph + PageRank-Diffusionsabruf werden konzeptübergreifende Verknüpfungen realisiert, sodass ein Agent in einer Sitzung auf das Wissen aller Projekte zugreifen kann.

Englische Zusammenfassung: Graph Memory ersetzt den sitzungsbasierten Speicher durch einen einzigen lokalen Knowledge-Graph. Der Abruf startet bei semantischen nächsten Nachbarn und breitet sich über personalisierten PageRank über automatisch erstellte Kanten aus, wobei 50 % semantische + 50 % Graph-Diffusions-Scores fusioniert werden. Es stellt Agenten über MCP 5 Tools zur Verfügung und enthält eine Cytoscape.js-Visualisierung. Alles läuft lokal – Embeddings stammen aus einem lokalen sentence-transformers-Modell, der Graph ist eine JSON-Datei, und das LLM wird (optional) nur für die Wissensextraktion verwendet.

Funktionen / Features

• Graphbasierte assoziative Suche – PageRank breitet sich entlang des Graphen aus und bringt von einem technischen Punkt aus zugehörige Bereitstellungsdetails, Erfahrungen oder Benutzerpräferenzen hervor

• LLM-Wissensextraktion – automatische Extraktion strukturierter Wissensknoten aus Konversationen/Erinnerungen

• Drei-Ebenen-Deduplizierung – MD5 → Embedding-Ähnlichkeit >0,85 → neu erstellen

• Speicherkorrektur – veraltete Informationen können erkannt und vorhandene Knoten aktualisiert werden

• MCP-Integration – stellt über MCP automatisch 5 Tools für jeden Agenten bereit

• Visualisierung – Cytoscape.js mit dunklem Thema, Filter/CRUD

• Lokaler Betrieb – Daten verlassen den Rechner nicht, Embedding-Modell wird lokal geladen

Schnellstart

1. Installation

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

2. Konfiguration

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

3. Start

python -m graph_memory.server

Öffnen Sie http://127.0.0.1:9121/, um die Visualisierungsoberfläche zu sehen.

Beim ersten Start wird das Embedding-Modell heruntergeladen (Standard: BAAI/bge-base-zh-v1.5, ca. 400 MB) und anschließend lokal zwischengespeichert.

3a. Beispieldaten (optional)

Für den ersten Eindruck kann eine Reihe allgemeiner technischer Wissensbeispiele eingepflanzt werden, sodass ein leeres Projekt sofort nutzbar ist:

python seed_demo.py

Anschließend ist unter http://127.0.0.1:9121/ ein kleiner Graph sichtbar. Beispieldaten löschen: data/graph.json und data/embeddings.npz entfernen und den Server neu starten.

3b. Docker-Ein-Klick-Start

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

4. Vorhandene Erinnerungen importieren

Beim ersten Gebrauch vorhandene Erinnerungen aus Hermes / Claude Code / Codex importieren:

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

Es können auch Claude-Code-Sitzungsverläufe in Stapeln extrahiert werden:

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

Die Importpfade können über Umgebungsvariablen überschrieben werden (HERMES_HOME / CLAUDE_HOME / CODEX_HOME); standardmäßig zeigen sie auf die üblichen Speicherorte der jeweiligen Agenten im Benutzerverzeichnis.

Verwendung im Agenten

MCP-Server (automatisch verfügbar)

Fügen Sie den graph-memory-MCP-Server zur MCP-Konfiguration Ihres Agenten hinzu; nach dem Neustart stehen automatisch 5 Tools zur Verfügung:

Der Agent kann diese Tools direkt im Gespräch aufrufen, ohne manuelle Eingriffe.

Der MCP-Server läuft über stdio und fungiert als HTTP-Client, der an das FastAPI-Backend weiterleitet. Er lädt selbst kein Modell, um zu vermeiden, dass Backend und MCP-Server zwei inkonsistente Kopien der Graphdaten halten.

Skill (Agenten-Anleitung)

SKILL.md ist die Nutzungsanleitung für den Agenten. Nach dem Laden befolgt der Agent folgende Regeln:

• Vor der Antwort zuerst den Graph-Speicher abrufen

• Nach der Antwort wertvolles neues Wissen extrahieren und schreiben

• Bei veralteten Informationen proaktiv aktualisieren

Verwendungsweisen

Methode 1: Direkt mit dem Agenten sprechen

„Schau dir bitte das Inferenzprojekt auf einem bestimmten Server an."

Der Agent ruft automatisch retrieve auf, um relevantes Wissen abzurufen, und antwortet mit Projektpfad/Port/Branch-Informationen.

Methode 2: Den Agenten neues Wissen merken lassen

„Merke dir: vLLM 0.25 hat Unterstützung für speculative decoding hinzugefügt."

Der Agent ruft write auf, um in den Knowledge-Graph zu schreiben und automatisch mit vorhandenen Knoten zu verknüpfen.

Methode 3: Veraltete Informationen korrigieren

„Der Port eines Dienstes wurde geändert, er ist nicht mehr 8000."

Der Agent ruft update auf, um vorhandene Knoten zu aktualisieren.

Methode 4: Visuelles Durchsuchen

Öffnen Sie http://127.0.0.1:9121/, um zu suchen, zu filtern und CRUD-Operationen durchzuführen.

Architektur

┌──────────────────────────────────────────┐
│  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       │              │
│  └─────────┘  └────────────┘              │
└─────────────────────────────────────────────┘

Der MCP-Server ist ein leichter HTTP-Client und lädt kein Embedding-Modell. Alle Berechnungen erfolgen im FastAPI-Server, um Dateninkonsistenzen durch zwei Prozesse mit jeweils eigener Engine zu vermeiden.

API

Bewertung

python benchmark.py

30 Fragen × 3 Runden × LLM-Bewertung, Vergleich der Antwortqualität von „nur MEMORY.md" vs. „mit Graph-Speicher".

Der Fragensatz muss an Ihre eigene Wissensbasis angepasst werden (siehe Kommentare am Anfang von benchmark.py). Für Regressionstests des Abrufverhaltens selbst wird regression.py verwendet (deterministischer Snapshot-Vergleich, ohne LLM):

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

Tests

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

Die Engine-Tests verwenden einen deterministischen Fake-Embedder, laden kein echtes Modell herunter und laufen offline.

Wissensverwaltung (gegen Aufblähung)

Bei längerer täglicher Nutzung bläht sich der Graph auf. Verwaltungstools regelmäßig ausführen:

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              # 执行清理

Bereinigungsregeln:

• Knoten mit Grad <2 und ohne Aktualisierung seit 90 Tagen werden gelöscht (verknüpfte bleiben erhalten)

• Beim Zusammenführen ähnlicher Knoten wird der längere/detailliertere Inhalt beibehalten

• Alle Operationen unterstützen --dry-run zur Vorschau

Konfigurationsoptionen

License

MIT