Understanding Graph: A Persistent Medium for Recursive Understanding

A persistent medium for recursive, inspectable understanding.

Understanding Graph is an MCP server that gives AI agents structured, persistent memory. Unlike knowledge bases that store facts, it stores externally useful understanding updates -- tensions, surprises, decisions, evidence, and how beliefs evolved over time. It does not require private chain-of-thought. Multiple agents can coordinate through the graph itself: each agent reads what others have written, builds on it, and leaves inspectable traces for the next -- stigmergy.

Why Understanding Graph?

Core insight: AI agents don't just need to remember facts -- they need the usable before state, pivoting evidence, updated conclusion, and remaining uncertainty. That lets later work test or revise a conclusion without reconstructing hidden deliberation.

Quick Start

Requires Node.js 22 or newer.

Recommended: use your Codex or Claude subscription

Run the initializer in the directory where you want the graph-backed work to live:

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

It creates project-scoped MCP configuration for both Codex and Claude Code, installs the same fluid-understanding contract in AGENTS.md and CLAUDE.md, installs a project-scoped reading-mode skill for both clients, and adds the local projects/ path to ignore rules without installing any starter graph. Open either client, sign in with your normal ChatGPT or Claude subscription, and ask for the actual research, writing, coding, or decision task. The agent creates a descriptively named graph when real work begins. You do not need to say “use the graph.” The model runs in the subscription client; Understanding Graph itself makes no model API calls.

For a fresh chronological reading, give the agent a file path and ask it to turn on reader mode. It stages the source without returning or sampling its body, then encounters only the next ordered passage through source_read and may attach ordinary, passage-grounded understanding before continuing. Codex also exposes $reading-mode; Claude Code exposes /reading-mode. Text pasted directly into chat has already been encountered, so use a file path when a genuinely fresh reading matters.

Codex is available through eligible ChatGPT plans, and Claude Code can use Claude Pro or Max. Their normal plan limits still apply.

Installable plugin (workflow skill + MCP server)

The package ships both .codex-plugin and .claude-plugin manifests. The plugin combines the MCP capabilities with an understanding-work skill. While the mode is active, material, communicable understanding that could matter to the work or a future inquiry develops in the graph. The graph rolls a small state-dependent set of concrete next moves; the model judges their weights against the user task and freely chooses, combines, changes, or rejects them. The initializer above provides the same contract without waiting for a plugin-directory listing.

For Claude Code, the existing marketplace flow is:

# 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 these skills:

The raw MCP server works with any compatible client, but the bundled skill or generated project instructions are the recommended experience. Tool schemas alone do not reliably activate a multi-step understanding workflow.

What the initializer creates

This creates:

• .codex/config.toml -- Codex MCP configuration
• .mcp.json -- Claude Code project MCP configuration
• AGENTS.md and CLAUDE.md -- the same canonical understanding workflow
• .agents/skills/reading-mode/SKILL.md -- explicit Codex reader workflow
• .claude/skills/reading-mode/SKILL.md -- explicit Claude Code reader workflow
• .gitignore entry for projects/ -- keeps graph data local; no starter project is created

Every session opened in the directory shares the same project root. Once a named graph is selected, agents working there share it. Use additional agents only when the work has real independent seams.

Raw MCP configuration (advanced)

If a client cannot install plugins or run the initializer, connect the MCP server directly:

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

MCP initialization still supplies a concise graph-use contract, but client support for server instructions varies. For consistent behavior, also provide the bundled understanding-work skill or its generated project instructions.

Per-client setup guides: 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.31", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects",
        "UG_SOURCE_ROOT": "/path/to/your/source-project"
      }
    }
  }
}

UG_SOURCE_ROOT limits file-based source loading to that directory. The project initializer sets it to the project root automatically.

Cursor / Windsurf

Add to your MCP config:

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

Web UI / 3D visualization

The root npm package includes the built frontend and depends on the web server, so the published package can launch the UI directly:

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

Run independent sidecars by giving each process its own port and project-store root. The roots may be sibling directories on the same volume:

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

Use absolute paths in deployments. Sharing the installed package and its read-only frontend is safe; do not point independent sidecars at the same PROJECT_DIR.

The server binds to loopback by default. To run a worker on another host, explicitly set HOST and a private worker token; non-loopback startup fails closed without both:

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.31 start

The trusted caller must send Authorization: Bearer <UG_WORKER_TOKEN> on every /api or /admin request. Put remote traffic behind TLS or a private authenticated network.

To develop the UI from a checkout instead:

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 can use @huggingface/transformers (a local embedding model, roughly 160 MB once compiled). It is an optional peer dependency so the default install stays small. For an npx-based project, install both packages locally so Node can resolve the peer from the same dependency tree:

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

A separate global @huggingface/transformers install does not reliably satisfy an isolated npx cache install.

Without it, the rest of the graph works normally. graph_understand and graph_semantic_search use deterministic lexical retrieval when embeddings are unavailable; semantic-only analysis tools explain when the optional model is needed.

How It Works

Direct concept and edge mutations go through graph_batch. Relevant workflow modes also expose document helpers at the top level; use a batch when related document, concept, and edge changes must land together. Every batch requires a commit_message and runs in a SQLite transaction: if any operation fails, the entire batch rolls back as if it never ran. Workflow tools such as source_read manage their own atomic updates. Ordinary work revises, archives, or supersedes nodes while preserving their history; irreversible purge is a separate, explicitly selected administrative action. The commit stream becomes an inspectable update log—each node's commit message becomes its Origin Story.

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

The optional chooser is an aid for surfacing graph-specific pointers that may deepen or diversify understanding, recover neglected material, test the current view, or expose a useful connection. Suggestions are sampled server-side from graph- and workflow-weighted pressures, include concrete nodes or regions when possible, and temporarily down-weight recently suggested action kinds. The model remains responsible for task fit and may always work directly, do something else, or stop rather than manufacture work. Set UG_GUIDANCE_MODE to direct to remove ambient suggestion prompts; graph_suggest_next remains available on demand. Pass creativity: false to an individual roll when ordinary guidance is useful but grounded random comparison, bisociation, ANI, disruption, and temporary forcing are not. This changes the roll only; the optional creativity tools remain available for direct use.

Retrieval has two orthogonal axes: workflow identifies the domain and its native evidence, while stance weights the epistemic pressure—such as deepening, resistance, connection, disruption, revisiting, or testing. Neither axis limits what the model may do.

Atomic commits

graph_batch is the entry point for concept and edge mutations, and for atomic multi-step document changes. 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 cognitive node captures an authored understanding update 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. These ordinary cognitive nodes may preserve rich, provisional, unresolved testimony—not only settled conclusions—when it will help a future agent re-enter the work. The thinking trigger is different: it is reserved for the separate synthetic Reader/CMP synthesizer, which reconstructs chronological training blocks from the underlying graph. Reserved blocks are hidden from and immutable to ordinary reading, writing, coding, and general workflows; only TOOL_MODE=synthetic_reader can access them. The full, deliberately chosen set of 18 trigger types is documented in the understanding-graph paper (Section 3.1); it is an evolving design rather than a claimed formal minimum.

Edges (Connections)

Documents

Structured prose, source material, and graph-native code share the same addressable document tree. A leaf can be a passage, function, class, type, or test with its own recorded purpose, origin commit, revisions, and typed links to the questions, decisions, evidence, or tensions that shaped it. This allows a later Reader to ask why one exact unit exists—not merely why the file exists—by calling doc_read({ nodeId, showProvenance: true, showRevisions: true }).

implements points from an abstract commitment to its concrete unit; expresses and inspired_by point from an artifact unit to what it renders or what its author reports as influential; learned_from points from a cognitive update to the source or artifact encounter that occasioned it. These are inspectable authored claims, not verified causes. Code roots generate runnable files; units can be split, merged, moved, and reordered before regeneration.

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 a shared persistent medium for Claude Code Agent Teams. After running npx -y understanding-graph@0.1.31 init, the lead creates or selects a named graph; every teammate working in that project root can then share it -- stigmergy without bundled data.

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 installs the same fluid protocol for every teammate -- Each agent treats the graph as the canonical medium and may work directly or ask graph_suggest_next for concrete possibilities at natural choice points.
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. Persistent handoffs without mandatory direct messaging -- Teammates can 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 -y understanding-graph@0.1.31 init     # one-time setup

Then 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.

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 (46 default / 70 full tools + batch 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

Working principles

1. Use the graph as the medium — While Understanding mode is active, preserve the communicable understanding and addressable artifact units that matter to the work, not merely its final answer.
2. Keep agency with the model — graph_suggest_next offers weighted, concrete provocations when the optional aid is useful. The model may work directly or choose, combine, modify, reject, replace, or skip them according to the user's task.
3. Re-enter when it can change the work — Revisit the accumulated graph at genuine choice points, surprises, resistance, or uncertainty—not on a fixed timer and not as ceremony.
4. Synthesize rather than transcribe — Preserve what an encounter changed, including unresolved implications and tensions, rather than copying the input. PURE is available as an optional stabilization check after open exploration; it is not a quota or a gate on emergence.
5. Preserve provenance — Use descriptive commits, dedicated revision and supersession operations, evidence from the real artifact, and explicit ownership or handoffs when collaboration actually requires them.

Using with sema

Understanding Graph gives your agents shared episodic memory — the recorded interpretive 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@0.1.31 mcp
claude mcp add sema -- uvx --from semahash sema mcp

With both installed, an agent can:

1. Reference a sema pattern URI (for example, sema://StateLock#7859) inside a node's understanding or why text to pin the meaning of a coordination primitive.
2. Use graph_semantic_search to find nodes that reference a pattern in the current project. Switch projects explicitly, or use cross-project reference tools, when the search spans graphs.
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: using Understanding Graph with sema

Coding inside the graph

Code lives in graph document roots and their ordered child nodes. Generate runnable files with doc_generate or doc_generate_all, run the real build and tests, then revise or rearrange the source nodes and regenerate—never patch the generated projection directly.

See coding-inside-the-graph for the full workflow.

Citing

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

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