Understanding Graph: A Reasoning-Capture Architecture for AI Memory

Persistent memory for AI agents. Shared cognition through stigmergy.

Understanding Graph is an MCP server that gives AI agents structured, persistent memory. Unlike knowledge bases that store facts, it stores the reasoning process -- tensions, surprises, decisions, and how beliefs evolved over time. Multiple agents coordinate through the graph itself: each agent reads what others have written, builds on it, and leaves traces for the next -- stigmergy.

Why Understanding Graph?

Core insight: AI agents don't just need to remember facts -- they need to remember how they arrived at conclusions so they can build on previous reasoning. When multiple agents share a graph, they coordinate without direct communication.

Quick Start

Claude Code (zero-install)

Add understanding-graph to Claude Code with one command -- no global install, nothing to clone:

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

npx -y downloads, caches, and runs the package on first invocation. After this, ug is available as an MCP server in every Claude Code session.

Claude Code with agent teams (one-command project setup)

For projects where you want agent teams to share the graph automatically, run the init flow inside the project directory:

cd your-project
npx -y understanding-graph init

This creates:

• .claude/settings.local.json -- MCP server config (with agent teams enabled)
• CLAUDE.md -- Instructions that all agents and teammates follow automatically
• projects/default/ -- Graph storage directory

Now open Claude Code. Every session (and every agent team teammate) shares the same graph.

Per-client setup guides: integrations/claude-code.md · integrations/claude-desktop.md · integrations/cursor.md · integrations/mcporter.md

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", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP config:

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

Web UI / 3D visualization (build from source)

The npm package ships only what the MCP server needs (~1.5 MB) so npx -y understanding-graph mcp stays fast. The web UI and 3D visualization require the frontend bundle (~160 MB of three.js + react + onnxruntime), which is not in the published tarball for v0.1.0. To run the UI, clone the repo:

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: enable embedding-based search

graph_semantic_search, graph_similar, graph_semantic_gaps, and graph_backfill_embeddings all rely on @xenova/transformers (a local embedding model, ~160 MB once compiled). It is declared as an optional peer dependency so the default install stays small. If you need those tools:

npm install -g @xenova/transformers

Without it, the rest of the graph (skeleton, history, batch, supersede, semantic_search via metadata, find_by_trigger, etc.) works fine — the embedding tools will return a clear error if you call them without installing the peer.

How It Works

Every mutation goes through graph_batch with a required commit_message — git for cognition. The batch is wrapped in a SQLite transaction: if any operation fails, the entire batch rolls back as if it never ran. Nodes are never deleted, only superseded. The commit stream becomes a metacognitive log that other agents can read to understand what happened and why — each node's commit message becomes its Origin Story, the agent's inner monologue at the moment of creation.

1. project_switch("my-project")        # Load (or create) a project
2. graph_skeleton()                     # Orient yourself (~150 tokens)
3. graph_history()                      # See what other agents did recently
4. graph_semantic_search({ query })     # Find relevant past reasoning (optional embeddings)
5. graph_batch({ commit_message, ... }) # Mutate with intent — atomic

Atomic commits

graph_batch is the only mutation entry point. Inside one batch you can chain graph_add_concept, graph_connect, graph_question, graph_supersede, doc_create, and others. The pre-validation check accepts both ID and title references for graph_connect, and computes transitive reachability (so a chain A → B → existing is valid even though A doesn't directly touch existing). On any failure mid-batch, the entire transaction rolls back; no half-state.

Cross-project references

A graph node in one project can reference a node in another project via graph_add_reference({ refProject, refNodeId }). Other projects can then read it without switching via graph_lookup_external or find it by ID alone via graph_global_lookup. This is the substrate for the Hierarchical Understanding Graph used by the entangled-alignment chronological annotation pipeline, where eras and documents draw cross-references.

Core Concepts

Nodes (Understanding Units)

Each node captures a moment of comprehension with a trigger marking why it was created:

Triggers are cognitive acts, not categories — they capture why the agent created the node at this exact moment, not what kind of thing it is. The seven you'll use most often:

Less common but available: hypothesis, model, evaluation, analysis, experiment, serendipity, repetition, randomness, reference, library. The thinking trigger is reserved for the synthesizer agent and rejected for normal use. The full set of 18 trigger types is documented in the understanding-graph paper (Section 3.1) and described as the minimum count for cognitive distinguishability — collapsing them would dissolve the Cognitive Guardrail.

Edges (Connections)

Documents

Structured content (notes, papers, code) with thinking nodes interleaved -- capturing comprehension as it happens.

Projects

Isolated graphs for different contexts. Each project has its own SQLite database.

Tools Overview

Multi-Agent with Claude Code Agent Teams

Understanding Graph is designed as the shared memory layer for Claude Code Agent Teams. After running npx understanding-graph init, every teammate in an agent team automatically shares the same graph -- stigmergy out of the box.

How it works

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 creates the CLAUDE.md -- Every teammate loads it automatically, so all agents know to use graph_skeleton() to orient, graph_batch for mutations, and graph_history() to read the metacognitive trail.
2. Commit messages are the coordination layer -- Each graph_batch requires a commit_message. When the Security teammate writes "Security Agent: found JWT stored in localStorage -- tension between convenience and XSS risk", the Backend teammate sees it via graph_history() and acts on it.
3. Triggers classify contributions -- Teammates tag their nodes (tension, question, decision, surprise), making it easy to find what matters: "show me all unresolved tensions" or "what questions are still open?"
4. No direct messaging needed -- Teammates coordinate through the graph itself. The researcher leaves question nodes; the backend agent finds them via graph_find_by_trigger and creates answers edges.

Getting started with a swarm

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

Then in Claude Code:

Create an agent team with 3 teammates to [your task].
Each teammate should read graph_skeleton() first to orient,
then use graph_batch with descriptive commit messages so
the team can coordinate through the shared understanding graph.

Long-running coordination (solver system)

For tasks that span multiple sessions or need async handoff beyond a single team:

The solver system persists in the SQLite database, so tasks survive across sessions. One team can delegate work that a future team picks up.

Architecture

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

Stack:

• SQLite + better-sqlite3 -- Persistent storage
• Graphology -- In-memory graph operations
• MCP Protocol -- Agent integration
• Transformers.js -- Local embeddings for semantic search

Development

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

Dev mode

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

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

Environment Variables

The Five Laws

1. Git for Cognition — Nodes are never deleted, only superseded. The supersession edge preserves the epistemic journey: a future agent reading the chain learns not just the current belief but the path from the wrong belief to the right one. Every graph_batch requires a commit_message that becomes the node's Origin Story.
2. PURE Standard — Quality gates: Parsimonious, Unique, Realizable, Expansive. Non-compensatory: any RED gate halts.
3. Graph-First Context — Always check existing graph before creating new nodes. Duplicate detection is a forcing function, not a check: it pulls prior cognition into the current moment.
4. Synthesize, Don't Transcribe — Capture implications and tensions, not raw facts. The graph is for your understanding, not your input.
5. Delegate by Default — Break complex tasks into sub-tasks via the solver system; let specialized agents (Skeptic, Connector, Synthesizer) coordinate stigmergically through the graph.

Using with sema

Understanding Graph gives your agents shared episodic memory — the reasoning trail behind a decision. Sema gives them shared semantic memory — a content-addressed vocabulary of cognitive patterns. They compose:

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

With both installed, an agent can:

1. Reference a sema pattern hash (e.g. StateLock#7859) inside an understanding-graph node's mechanism field to pin the meaning of a coordination primitive.
2. Use graph_semantic_search to find all graph nodes that reference a given sema pattern, across projects and agent teams.
3. Call sema_handshake to verify that two agents share the same definition of a pattern before building on each other's thinking in the graph — the fail-closed handshake prevents silent semantic drift.

Full walkthrough: docs/using-with-sema.md

Coding inside the graph

A concrete end-to-end example: build a Bloom filter entirely as graph nodes — design as foundation + decision concepts grounded in sema Check#1544, implementation as a .py doc tree, empirical verification as an evaluation node — then doc_generate it to a runnable file whose self-test prints AcceptSpec#70dd: PASS.

See docs/coding-inside-the-graph.md.

License

MIT -- LICENSE

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