Understanding Graph

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

Upgrading from 0.1.32 to 0.2.1

Version 0.2.1 changes the authoring tool names. Existing graph data, including previously recorded notes, remains usable; this release requires no database schema migration.

• Replace graph_add_concept with graph_add_understanding; its parameters stay the same.
• Replace graph_note with graph_add_understanding and a separate graph_connect operation in the same graph_batch. Map testimony to understanding and about to the connection's to target. Supply explicit title, trigger, and why values; these are required on the new node.
• Set optional attend to the next question or action when the node should remain open attention. Automatic resurfacing requires a learned_from edge to a visible document node; a provenance link alone does not enable it.

For example, pass this to graph_batch, replacing SOURCE_NODE_ID with the existing passage or artifact node that occasioned the understanding:

{

"commit_message": "Record the unresolved retry assumption", "agent_name": "researcher", "operations": [ { "tool": "graph_add_understanding", "params": { "title": "Retries may synchronize clients", "trigger": "hypothesis", "understanding": "A fixed retry delay may align clients after a shared failure.", "why": "Questions whether the proposed recovery policy reduces overload", "attend": "Test fixed delays against jitter before choosing the policy." } }, { "tool": "graph_connect", "params": { "from": "$0.id", "to": "SOURCE_NODE_ID", "type": "learned_from", "why": "The hypothesis arose while reading this recovery design" } } ] }

Run npx -y understanding-graph@0.2.1 init in each initialized project to update managed MCP configuration and generated workflow guidance, then reconnect the MCP client so it loads the new tool catalog. Update custom configuration or instructions that the initializer preserves yourself.

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.2.1 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.2.1", "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.2.1", "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.2.1 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.2.1 start

PORT=3102 PROJECT_DIR=/srv/undergraph/worker-2 npx -y understanding-graph@0.2.1 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.2.1 start

The trusted caller must send Authorization: Bearer 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