Understanding Graph: Ein rekursives Medium für dauerhaftes Verständnis

Ein rekursives Medium für dauerhaftes, überprüfbares Verständnis.

Understanding Graph ist ein MCP-Server, der KI-Agenten strukturierten, dauerhaften Speicher bietet. Im Gegensatz zu Wissensdatenbanken, die Fakten speichern, speichert er extern nützliche Verständnis-Updates – Spannungen, Überraschungen, Entscheidungen, Belege und wie sich Überzeugungen im Laufe der Zeit entwickelt haben. Er erfordert keine private Gedankenkette. Mehrere Agenten können sich über den Graphen selbst koordinieren: Jeder Agent liest, was andere geschrieben haben, baut darauf auf und hinterlässt überprüfbare Spuren für den nächsten – Stigmergie.

Warum Understanding Graph?

Kernaussage: KI-Agenten müssen sich nicht nur Fakten merken – sie brauchen den nutzbaren Vorher-Zustand, pivotierende Belege, aktualisierte Schlussfolgerung und verbleibende Unsicherheit. Das ermöglicht spätere Arbeit, eine Schlussfolgerung zu testen oder zu revidieren, ohne versteckte Überlegungen zu rekonstruieren.

Related MCP server: Loxo

Schnellstart

Empfohlen: Nutzen Sie Ihr Codex- oder Claude-Abonnement

Führen Sie den Initialisierer in dem Verzeichnis aus, in dem die graphgestützte Arbeit stattfinden soll:

cd your-project
npx -y understanding-graph@0.1.30 init

Er erstellt projektspezifische MCP-Konfigurationen für Codex und Claude Code, installiert denselben fließenden Verständnisvertrag in AGENTS.md und CLAUDE.md, installiert eine projektspezifische reading-mode-Fähigkeit für beide Clients und fügt den lokalen projects/-Pfad zu den Ignorierregeln hinzu, ohne einen Startgraphen zu installieren. Öffnen Sie einen der Clients, melden Sie sich mit Ihrem normalen ChatGPT- oder Claude-Abonnement an und bitten Sie um die eigentliche Recherche-, Schreib-, Programmier- oder Entscheidungsaufgabe. Der Agent erstellt einen beschreibend benannten Graphen, wenn die echte Arbeit beginnt. Sie müssen nicht „den Graphen nutzen“ sagen. Das Modell läuft im Abonnement-Client; Understanding Graph selbst tätigt keine Modell-API-Aufrufe.

Für eine frische chronologische Lektüre geben Sie dem Agenten einen Dateipfad und bitten Sie ihn, den Lesemodus zu aktivieren. Er stützt die Quelle, ohne deren Inhalt zurückzugeben oder zu sampeln, und begegnet dann nur der nächsten geordneten Passage durch source_read und kann gewöhnliches, passagenbasiertes Verständnis anbringen, bevor er fortfährt. Codex bietet auch $reading-mode; Claude Code bietet /reading-mode. Direkt in den Chat eingefügter Text wurde bereits begegnet, verwenden Sie also einen Dateipfad, wenn eine wirklich frische Lektüre wichtig ist.

Codex ist über berechtigte ChatGPT-Pläne verfügbar, und Claude Code kann Claude Pro oder Max nutzen. Die normalen Planlimits gelten weiterhin.

Installierbares Plugin (Workflow-Fähigkeit + MCP-Server)

Das Paket enthält sowohl .codex-plugin- als auch .claude-plugin-Manifeste. Das Plugin kombiniert die MCP-Fähigkeiten mit einer understanding-work-Fähigkeit. Während der Modus aktiv ist, entwickelt sich materielles, kommunizierbares Verständnis, das für die Arbeit oder eine zukünftige Anfrage relevant sein könnte, im Graphen. Der Graph rollt eine kleine zustandsabhängige Menge konkreter nächster Schritte aus; das Modell bewertet ihre Gewichte gegen die Benutzeraufgabe und wählt, kombiniert, ändert oder verwirft sie frei. Der obige Initialisierer bietet denselben Vertrag, ohne auf eine Plugin-Verzeichnisliste zu warten.

Für Claude Code ist der bestehende Marktplatz-Ablauf:

# One-time: add the Emergent Wisdom marketplace
claude plugin marketplace add emergent-wisdom/marketplace

# Install the plugin
claude plugin install understanding-graph

Für lokale Entwicklung:

claude --plugin-dir /path/to/understanding-graph

Dies gibt Ihnen den MCP-Server und diese Fähigkeiten:

Der rohe MCP-Server funktioniert mit jedem kompatiblen Client, aber die gebündelte Fähigkeit oder die generierten Projektanweisungen sind die empfohlene Erfahrung. Nur Tool-Schemata aktivieren zuverlässig keinen mehrstufigen Verständnis-Workflow.

Was der Initialisierer erstellt

Dies erstellt:

• .codex/config.toml – Codex-MCP-Konfiguration

• .mcp.json – Claude-Code-Projekt-MCP-Konfiguration

• AGENTS.md und CLAUDE.md – denselben kanonischen Verständnis-Workflow

• .agents/skills/reading-mode/SKILL.md – expliziter Codex-Leser-Workflow

• .claude/skills/reading-mode/SKILL.md – expliziter Claude-Code-Leser-Workflow

• .gitignore-Eintrag für projects/ – hält Graphdaten lokal; kein Startprojekt wird erstellt

Jede in dem Verzeichnis geöffnete Sitzung teilt dieselbe Projektwurzel. Sobald ein benannter Graph ausgewählt ist, teilen sich dort arbeitende Agenten ihn. Verwenden Sie zusätzliche Agenten nur, wenn die Arbeit echte unabhängige Nahtstellen hat.

Rohe MCP-Konfiguration (fortgeschritten)

Wenn ein Client keine Plugins installieren oder den Initialisierer ausführen kann, verbinden Sie den MCP-Server direkt:

claude mcp add ug -- npx -y understanding-graph@0.1.30 mcp

Die MCP-Initialisierung liefert weiterhin einen prägnanten Graphnutzungsvertrag, aber die Client-Unterstützung für Serveranweisungen variiert. Für konsistentes Verhalten stellen Sie auch die gebündelte understanding-work-Fähigkeit oder ihre generierten Projektanweisungen bereit.

Client-spezifische Einrichtungsanleitungen: Claude Code · Claude Desktop · Cursor · mcporter

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "understanding-graph@0.1.30", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects",
        "UG_SOURCE_ROOT": "/path/to/your/source-project"
      }
    }
  }
}

UG_SOURCE_ROOT begrenzt das dateibasierte Quellenladen auf dieses Verzeichnis. Der Projektinitialisierer setzt es automatisch auf die Projektwurzel.

Cursor / Windsurf

Fügen Sie zu Ihrer MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "understanding-graph@0.1.30", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects"
      }
    }
  }
}

Web-UI / 3D-Visualisierung

Das Root-npm-Paket enthält das gebaute Frontend und hängt vom Webserver ab, sodass das veröffentlichte Paket die UI direkt starten kann:

PROJECT_DIR=/path/to/your/projects npx -y understanding-graph@0.1.30 start
# open http://localhost:3000

Führen Sie unabhängige Sidecars aus, indem Sie jedem Prozess einen eigenen Port und eine eigene Projekt-Store-Wurzel geben. Die Wurzeln können Geschwisterverzeichnisse auf demselben Volume sein:

PORT=3101 PROJECT_DIR=/srv/undergraph/worker-1 npx -y understanding-graph@0.1.30 start
PORT=3102 PROJECT_DIR=/srv/undergraph/worker-2 npx -y understanding-graph@0.1.30 start

Verwenden Sie absolute Pfade in Bereitstellungen. Das Teilen des installierten Pakets und seines schreibgeschützten Frontends ist sicher; zeigen Sie nicht mit unabhängigen Sidecars auf dasselbe PROJECT_DIR.

Der Server bindet standardmäßig an Loopback. Um einen Worker auf einem anderen Host auszuführen, setzen Sie explizit HOST und ein privates Worker-Token; Nicht-Loopback-Start schlägt ohne beides geschlossen fehl:

HOST=0.0.0.0 PORT=3101 \
UG_WORKER_TOKEN=replace-with-a-long-random-secret \
PROJECT_DIR=/srv/undergraph/worker-1 \
npx -y understanding-graph@0.1.30 start

Der vertrauenswürdige Aufrufer muss bei jeder /api- oder /admin-Anfrage Authorization: Bearer <UG_WORKER_TOKEN> senden. Legen Sie Remote-Verkehr hinter TLS oder ein privates authentifiziertes Netzwerk.

Um die UI stattdessen aus einem Checkout zu entwickeln:

git clone https://github.com/emergent-wisdom/understanding-graph.git
cd understanding-graph
npm install
npm run build
npm run start:web
# open http://localhost:3000

Optional: Einbettungsbasierte Suche aktivieren

graph_semantic_search, graph_similar, graph_semantic_gaps und graph_backfill_embeddings können @huggingface/transformers verwenden (ein lokales Einbettungsmodell, nach der Kompilierung etwa 160 MB). Es ist eine optionale Peer-Abhängigkeit, damit die Standardinstallation klein bleibt. Für ein npx-basiertes Projekt installieren Sie beide Pakete lokal, damit Node den Peer aus demselben Abhängigkeitsbaum auflösen kann:

npm install --save-dev understanding-graph@0.1.30 @huggingface/transformers@4.2.0
npx understanding-graph@0.1.30 init

Eine separate globale @huggingface/transformers-Installation erfüllt eine isolierte npx-Cache-Installation nicht zuverlässig.

Ohne sie funktioniert der Rest des Graphen normal. graph_understand und graph_semantic_search verwenden deterministische lexikalische Abfrage, wenn Einbettungen nicht verfügbar sind; semantikbasierte Analysetools erklären, wann das optionale Modell benötigt wird.

So funktioniert es

Direkte Konzept- und Kantenmutationen laufen über graph_batch. Relevante Workflow-Modi setzen auch Dokumenthilfen auf oberster Ebene aus; verwenden Sie eine Batch, wenn zusammenhängende Dokument-, Konzept- und Kantenänderungen zusammen landen müssen. Jede Batch erfordert eine commit_message und läuft in einer SQLite-Transaktion: Wenn eine Operation fehlschlägt, wird die gesamte Batch zurückgerollt, als ob sie nie gelaufen wäre. Workflow-Tools wie source_read verwalten ihre eigenen atomaren Updates. Gewöhnliche Arbeit revidiert, archiviert oder ersetzt Knoten, während ihre Geschichte erhalten bleibt; irreversible Bereinigung ist eine separate, explizit ausgewählte administrative Aktion. Der Commit-Stream wird zu einem überprüfbaren Update-Protokoll – die Commit-Nachricht jedes Knotens wird zu seiner Ursprungsgeschichte.

1. project_switch({ project: "my-project" })
2a. DIRECT: use graph_understand, graph_batch, or another graph tool immediately
2b. GUIDED: graph_suggest_next({ task, workflow: "coding" })
3. [if guided, judge, modify, reject, skip, or choose a sampled route]
4. graph_batch({ commit_message, agent_name, ... }) # preserve artifact + understanding

Der optionale Chooser ist eine Hilfe, um graphspezifische Hinweise zu oberflächen, die das Verständnis vertiefen oder diversifizieren, vernachlässigtes Material zurückgewinnen, die aktuelle Sicht testen oder eine nützliche Verbindung aufdecken können. Vorschläge werden serverseitig aus graph- und workflowgewichteten Drücken gesampelt, enthalten konkrete Knoten oder Regionen, wenn möglich, und gewichten kürzlich vorgeschlagene Aktionsarten vorübergehend herunter. Das Modell bleibt für die Aufgabenpassung verantwortlich und kann immer direkt arbeiten, etwas anderes tun oder aufhören, anstatt Arbeit zu erfinden. Setzen Sie UG_GUIDANCE_MODE auf direct, um umgebende Vorschlagsaufforderungen zu entfernen; graph_suggest_next bleibt auf Abruf verfügbar.

Atomare Commits

graph_batch ist der Einstiegspunkt für Konzept- und Kantenmutationen sowie für atomare mehrstufige Dokumentänderungen. Innerhalb eines Batches können Sie graph_add_concept, graph_connect, graph_question, graph_supersede, doc_create und andere verketten. Die Vorvalidierungsprüfung akzeptiert sowohl ID- als auch Titel-Referenzen für graph_connect und berechnet transitive Erreichbarkeit (so ist eine Kette A → B → existing gültig, auch wenn A nicht direkt existing berührt). Bei einem Fehler mitten im Batch wird die gesamte Transaktion zurückgerollt; es gibt keinen halben Zustand.

Projektübergreifende Referenzen

Ein Graphknoten in einem Projekt kann über graph_add_reference({ refProject, refNodeId }) auf einen Knoten in einem anderen Projekt verweisen. Andere Projekte können ihn dann ohne Wechsel über graph_lookup_external lesen oder allein über die ID über graph_global_lookup finden. Dies ist die Grundlage für den Hierarchical Understanding Graph, der von der entangled-alignment chronologischen Annotationspipeline verwendet wird, in der Epochen und Dokumente Querverweise ziehen.

Kernkonzepte

Knoten (Verständniseinheiten)

Jeder kognitive Knoten erfasst eine verfasste Verständnisaktualisierung mit einem Trigger, der markiert, warum er erstellt wurde:

Trigger sind kognitive Handlungen, keine Kategorien – sie erfassen, warum der Agent den Knoten genau in diesem Moment erstellt hat, nicht um welche Art von Sache es sich handelt. Die sieben, die Sie am häufigsten verwenden werden:

Weniger häufig, aber verfügbar: hypothesis, model, evaluation, analysis, experiment, serendipity, repetition, randomness, reference, library. Diese gewöhnlichen kognitiven Knoten können reichhaltige, vorläufige, ungelöste Zeugnisse bewahren – nicht nur abgeschlossene Schlussfolgerungen – wenn es einem zukünftigen Agenten hilft, wieder in die Arbeit einzusteigen. Der thinking-Trigger ist anders: Er ist für den separaten synthetischen Reader/CMP-Synthesizer reserviert, der chronologische Trainingsblöcke aus dem zugrunde liegenden Graphen rekonstruiert. Reservierte Blöcke sind für gewöhnliche Lese-, Schreib-, Codier- und allgemeine Workflows verborgen und unveränderlich; nur TOOL_MODE=synthetic_reader kann auf sie zugreifen. Der vollständige, bewusst gewählte Satz von 18 Triggertypen ist im understanding-graph paper (Abschnitt 3.1) dokumentiert; es ist ein sich entwickelndes Design und kein beanspruchtes formales Minimum.

Kanten (Verbindungen)

Dokumente

Strukturierte Prosa, Quellmaterial und graph-nativer Code teilen sich denselben adressierbaren Dokumentbaum. Ein Blatt kann eine Passage, Funktion, Klasse, ein Typ oder ein Test sein, mit eigenem aufgezeichnetem Zweck, Ursprungs-Commit, Revisionen und typisierten Links zu den Fragen, Entscheidungen, Belegen oder Spannungen, die es geprägt haben. Dies ermöglicht einem späteren Reader zu fragen, warum genau diese Einheit existiert – nicht nur, warum die Datei existiert – durch Aufruf von doc_read({ nodeId, showProvenance: true, showRevisions: true }).

implements zeigt von einer abstrakten Verpflichtung auf ihre konkrete Einheit; expresses und inspired_by zeigen von einer Artefakt-Einheit auf das, was sie darstellt oder was ihr Autor als einflussreich berichtet; learned_from zeigt von einer kognitiven Aktualisierung auf die Quelle oder Artefakt-Begegnung, die sie veranlasst hat. Dies sind überprüfbare verfasste Behauptungen, keine verifizierten Ursachen. Code-Wurzeln erzeugen ausführbare Dateien; Einheiten können vor der Regenerierung aufgeteilt, zusammengeführt, verschoben und neu angeordnet werden.

Projekte

Isolierte Graphen für verschiedene Kontexte. Jedes Projekt hat seine eigene SQLite-Datenbank.

Werkzeugübersicht

Batch-Operationen

Konzept- & Knotenverwaltung (Batch-Operationen, sofern nicht vom gewählten Modus aufgeführt)

Verbindungsverwaltung (Batch-Operationen, sofern nicht vom gewählten Modus aufgeführt)

Lesen & Analyse

Synthese & Erkundung

Dokumentoperationen (Verfügbarkeit variiert je nach Workflow-Modus)

Quellen-Lesen

Projektverwaltung

Projektübergreifend

Multi-Agent-Koordination (Solver)

Multi-Agent mit Claude Code Agent Teams

Understanding Graph ist als gemeinsames persistentes Medium für Claude Code Agent Teams konzipiert. Nach der Ausführung von npx -y understanding-graph@0.1.30 init erstellt der Lead einen benannten Graphen oder wählt einen aus; jeder Teammitglied, das in diesem Projektstamm arbeitet, kann ihn dann gemeinsam nutzen – Stigmergie ohne gebündelte Daten.

So funktioniert es

You: "Create an agent team to research and implement auth for this app"

Claude (Team Lead):
  ├── Researcher teammate   ─── reads/writes shared graph ───┐
  ├── Backend teammate       ─── reads/writes shared graph ───┤  Same Understanding Graph
  ├── Security teammate      ─── reads/writes shared graph ───┤  (via MCP)
  └── synthesizes findings from graph_history()               ┘

1. init installiert dasselbe flüssige Protokoll für jedes Teammitglied – Jeder Agent behandelt den Graphen als kanonisches Medium und kann direkt arbeiten oder graph_suggest_next um konkrete Möglichkeiten an natürlichen Entscheidungspunkten bitten.

2. Commit-Nachrichten sind die Koordinationsebene – Jede graph_batch erfordert eine commit_message. Wenn das Security-Teammitglied „Security Agent: JWT im localStorage gefunden – Spannung zwischen Komfort und XSS-Risiko" schreibt, sieht das Backend-Teammitglied dies über graph_history() und handelt entsprechend.

3. Trigger klassifizieren Beiträge – Teammitglieder taggen ihre Knoten (tension, question, decision, surprise), sodass leicht zu finden ist, was wichtig ist: „Zeig mir alle ungelösten Spannungen" oder „Welche Fragen sind noch offen?"

4. Persistente Übergaben ohne verpflichtende Direktnachrichten – Teammitglieder können über den Graphen selbst koordinieren. Der Forscher hinterlässt question-Knoten; der Backend-Agent findet sie über graph_find_by_trigger und erstellt answers-Kanten.

Erste Schritte mit einem Schwarm

cd your-project
npx -y understanding-graph@0.1.30 init     # one-time setup

Dann in Claude Code:

Create an agent team with 3 teammates to [your task].
Each teammate should work through the shared Understanding Graph,
preserve material understanding as it emerges, and use graph_batch
with descriptive commit messages so the team can coordinate.

Langfristige Koordination (Solver-System)

Für Aufgaben, die mehrere Sitzungen umfassen oder eine asynchrone Übergabe über ein einzelnes Team hinaus benötigen:

Das Solver-System wird in der SQLite-Datenbank persistiert, sodass Aufgaben Sitzungen überdauern. Ein Team kann Arbeit delegieren, die ein zukünftiges Team aufnimmt.

Architektur

packages/
  core/          # Graph logic, SQLite storage, embeddings
  mcp-server/    # MCP server (41 default / 69 full tools + batch operations)
  web-server/    # REST API + serves frontend
  frontend/      # 3D visualization (React + Three.js)

Stack:

• SQLite + better-sqlite3 – Persistente Speicherung

• Graphology – In-Memory-Graphoperationen

• MCP-Protokoll – Agentenintegration

• Transformers.js – Lokale Embeddings für semantische Suche

Entwicklung

git clone https://github.com/emergent-wisdom/understanding-graph.git
cd understanding-graph
npm install
npm run build
npm run start:web    # Web UI at http://localhost:3000

Entwicklermodus

# Terminal 1: Web server with hot reload
npm run dev:web

# Terminal 2: Frontend dev server
cd packages/frontend && npm run dev

Umgebungsvariablen

Arbeitsprinzipien

1. Den Graphen als Medium nutzen – Solange der Understanding-Modus aktiv ist, die vermittelbare Erkenntnis und adressierbaren Artefakteinheiten bewahren, die für die Arbeit wichtig sind, nicht nur deren endgültige Antwort.

2. Die Handlungsfähigkeit beim Modell belassen – graph_suggest_next bietet gewichtete, konkrete Provokationen, wenn die optionale Hilfe nützlich ist. Das Modell kann direkt arbeiten oder sie entsprechend der Aufgabe des Benutzers auswählen, kombinieren, modifizieren, ablehnen, ersetzen oder überspringen.

3. Wiedereintreten, wenn es die Arbeit verändern kann – Den angesammelten Graphen an echten Entscheidungspunkten, Überraschungen, Widerständen oder Unsicherheiten erneut aufsuchen – nicht nach festem Zeitplan und nicht als Zeremoniell.

4. Synthetisieren statt transkribieren – Bewahren, was eine Begegnung verändert hat, einschließlich ungelöster Implikationen und Spannungen, statt die Eingabe zu kopieren. PURE ist als optionale Stabilisierungsprüfung nach offener Erkundung verfügbar; es ist kein Kontingent und kein Tor für Emergenz.

5. Herkunft bewahren – Deskriptive Commits, dedizierte Revisions- und Supersessions-Operationen, Belege aus dem realen Artefakt und explizite Eigentümerschaft oder Übergaben verwenden, wenn Zusammenarbeit dies tatsächlich erfordert.

Verwendung mit sema

Understanding Graph gibt Ihren Agenten ein gemeinsames episodisches Gedächtnis – den aufgezeichneten interpretativen Pfad hinter einer Entscheidung. Sema gibt ihnen ein gemeinsames semantisches Gedächtnis – ein inhaltsadressiertes Vokabular kognitiver Muster. Sie ergänzen sich:

# Add both to Claude Code
claude mcp add ug   -- npx -y understanding-graph@0.1.30 mcp
claude mcp add sema -- uvx --from semahash sema mcp

Mit beiden installiert kann ein Agent:

1. Eine sema-Muster-URI (z. B. sema://StateLock#7859) im understanding- oder why-Text eines Knotens referenzieren, um die Bedeutung eines Koordinationsprimitivs festzulegen.

2. graph_semantic_search verwenden, um Knoten zu finden, die ein Muster im aktuellen Projekt referenzieren. Bei projektübergreifender Suche explizit Projekte wechseln oder die projektübergreifenden Referenzwerkzeuge verwenden.

3. sema_handshake aufrufen, um zu verifizieren, dass zwei Agenten dieselbe Definition eines Musters teilen, bevor sie im Graphen auf dem Denken des jeweils anderen aufbauen – der fail-closed-Handshake verhindert stilles semantisches Abdriften.

Vollständige Anleitung: Using Understanding Graph with sema

Codieren im Graphen

Code befindet sich in Dokumentwurzeln des Graphen und deren geordneten Kindknoten. Ausführbare Dateien mit doc_generate oder doc_generate_all erzeugen, den echten Build und Tests ausführen, dann die Quellknoten überarbeiten oder neu anordnen und neu generieren – niemals die generierte Projektion direkt patchen.

Siehe coding-inside-the-graph für den vollständigen Workflow.

Zitieren

@misc{westerberg2026understanding,
  title        = {Understanding Graph: A Recursive Medium for Persistent Understanding},
  author       = {Westerberg, Henrik},
  year         = {2026},
  month        = aug,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19462658},
  url          = {https://doi.org/10.5281/zenodo.19462658}
}

Siehe CITATION.cff für die maschinenlesbare Version (GitHub rendert daraus einen „Cite this repository"-Button).

Lizenz

MIT – LICENSE

GitHub: emergent-wisdom/understanding-graph npm: understanding-graph MCP-Protokoll: modelcontextprotocol.io