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?

Traditional Memory	Understanding Graph
Stores facts	Stores comprehension
"User prefers dark mode"	"User switched to dark mode after eye strain -- tension between aesthetics and comfort resolved toward comfort"
Flat retrieval	Reasoning trails
Forgets context	Preserves the why
Single agent	Multi-agent coordination through shared 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 plugin (MCP server + skills)

The npm package also ships as a Claude Code plugin — the MCP server plus skills that teach the agent how to use the graph effectively:

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

# Install the plugin
claude plugin install understanding-graph

For local development:

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

This gives you the MCP server and 7 skills:

Skill	Invoke	What it teaches
orient	/understanding-graph:orient	Read graph state at conversation start
quality-check	/understanding-graph:quality-check	Score, analyze, thermostat
reading-mode	/understanding-graph:reading-mode	Deep source reading with source_read
serendipity	/understanding-graph:serendipity	Inject novelty via grounded/pure serendipity
web-ui	/understanding-graph:web-ui	Launch 3D visualization at :3030
graph-workflow	(auto-loaded)	Five laws, batches, edges, triggers, API reference
creative-work	(auto-loaded)	Two surfaces: concepts + doc trees

The MCP server works with any client. The skills are a Claude Code bonus — use whichever fits your setup.

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:

Trigger	When to Use
foundation	Core concepts, axioms, starting points
surprise	Unexpected findings, contradicts prior belief
tension	Conflict between ideas, unresolved
consequence	Downstream implication
question	Open question to explore
decision	Choice made between alternatives, with rationale
prediction	Forward-looking belief that can be validated later

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)

Edge Type	Meaning
supersedes	New understanding replaces old
contradicts	Ideas in conflict
refines	Adds precision to existing understanding
learned_from	Attribution of insight
answers / questions	Resolves or raises questions
contains	Parent-child hierarchy
next	Sequential ordering

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

50+ top-level tools listed via tools/list, plus additional batch-only operations callable through graph_batch (click to expand)

Batch Operations

Tool	Purpose
graph_batch	Execute multiple operations as an atomic commit with a required commit_message. Wrapped in a SQLite transaction: if any operation fails, the entire batch is rolled back. The commit_message is preserved as the node's Origin Story — future agents reading those nodes see not just the content but the intent that created it.

Concept & Node Management

Tool	Purpose
graph_add_concept	Add new concept with duplicate detection
graph_question	Create question node for exploration
graph_revise	Update concept understanding
graph_supersede	Replace outdated concept
graph_add_reference	Add external/cross-project references
graph_rename	Rename node (updates soft references)
graph_archive	Soft-delete preserving history
node_set_metadata	Set arbitrary metadata on nodes
node_get_metadata	Retrieve node metadata
node_set_trigger	Change node classification
node_get_revisions	Get understanding evolution history

Connection Management

Tool	Purpose
graph_connect	Create edges between concepts
graph_answer	Record answer to a question node
graph_disconnect	Remove/archive edges
edge_update	Update edge type or explanation
edge_get_revisions	Get relationship history

Reading & Analysis

Tool	Purpose
graph_skeleton	Structural overview (~150 tokens)
graph_context	Surrounding context for a concept
graph_context_region	Context for multiple related nodes
graph_semantic_search	Find nodes by meaning
graph_similar	Find conceptually similar nodes
graph_find_by_trigger	Find nodes by type
graph_analyze	Concept and pattern frequencies
graph_semantic_gaps	Find disconnected concepts
graph_score	Graph health metrics
graph_path	Reasoning path between concepts
graph_centrality	Most influential concepts
graph_thermostat	Regulate graph density
graph_history	Commit history and changes

Synthesis & Exploration

Tool	Purpose
graph_discover	Serendipity pipeline with chaos injection
graph_random	Random insights from graph
graph_serendipity	Record synthesized connection
graph_validate	Validate proposed connections
graph_chaos	Inject controlled randomness
graph_decide	Evaluate competing concepts
graph_evaluate_variations	Compare alternative ideas

Document Operations

Tool	Purpose
doc_create	Create document with content
doc_revise	Modify document text
doc_insert_thinking	Insert thinking node in document
doc_append_thinking	Append thinking at end

Source Reading

Tool	Purpose
source_load	Load text for staged reading
source_read	Read next portion, auto-create nodes
source_position	Get reading progress
source_list	List loaded sources
source_export	Export with thinking interleaved
source_commit	Record thinking during reading

Project Management

Tool	Purpose
project_switch	Switch active project
project_list	List available projects

Cross-Project

Tool	Purpose
graph_lookup_external	Look up node in another project
graph_list_external	List accessible external projects
graph_find_by_reference	Find nodes referencing a concept
graph_resolve_references	Verify cross-project references
graph_global_lookup	Search across all projects

Thematic System

Tool	Purpose
theme_create	Define theme with activation zones
theme_activate	Enter activation zone
theme_landing	Mark pause point
theme_get_active	Get active themes
theme_check_alignment	Validate prose alignment
theme_deactivate	Leave activation zone

Multi-Agent Coordination (Solver)

Tool	Purpose
solver_spawn	Register specialized solver agent
solver_delegate	Post task to solver queue
solver_claim_task	Claim pending task (worker mode)
solver_complete_task	Submit task results
solver_list	List registered solvers
solver_queue_status	Task queue statistics

---

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:

Tool	Purpose
solver_spawn	Register a specialist (e.g., "SecurityReviewer", "ArchiveKeep")
solver_delegate	Post a task to the queue
solver_claim_task	Pick up pending work (worker mode)
solver_complete_task	Submit results
solver_lock / solver_unlock	Prevent conflicts on shared nodes

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

Variable	Default	Description
PROJECT_DIR	./projects	Where to store project data
PORT	3000	Web server port
ANTHROPIC_API_KEY	--	For autonomous workers (optional)
TOOL_MODE	full	Tool exposure: reading, research, or full
DEFAULT_PROJECT	default	Project loaded on startup

---

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.

---

Citing

@misc{westerberg2026understanding,
  title        = {Understanding Graph: Persisting the Invisible Thinking},
  author       = {Westerberg, Henrik},
  year         = {2026},
  month        = apr,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19462908},
  url          = {https://doi.org/10.5281/zenodo.19462908}
}

See CITATION.cff for the machine-readable version (GitHub renders a "Cite this repository" button from it).

License

MIT -- LICENSE

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