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