understanding-graph

# Understanding Graph: A Recursive Medium for Persistent Understanding

**A recursive medium for persistent, inspectable understanding.**

[![Paper](https://img.shields.io/badge/Paper-PDF-red)](https://github.com/emergent-wisdom/understanding-graph/blob/main/paper/understanding_graph.pdf)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19462658.svg)](https://doi.org/10.5281/zenodo.19462658)
[![npm version](https://img.shields.io/npm/v/understanding-graph.svg)](https://www.npmjs.com/package/understanding-graph)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/servers/io.github.emergent-wisdom/understanding-graph)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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?

| Traditional Memory | Understanding Graph |
|-------------------|---------------------|
| Stores facts | Stores authored understanding updates |
| "User prefers dark mode" | "User switched to dark mode after eye strain -- tension between aesthetics and comfort resolved toward comfort" |
| Flat retrieval | Typed, revisable interpretation |
| Loses the interpretive middle | Preserves recorded rationale and revision |
| Single agent | Multi-agent coordination through shared 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

### Recommended: use your Codex or Claude subscription

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

```bash
cd your-project
npx -y understanding-graph@0.1.29 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`, 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.

[Codex is available through eligible ChatGPT plans](https://help.openai.com/en/articles/11369540-codex-and-chatgpt-plan-usage-limits), and [Claude Code can use Claude Pro or Max](https://support.anthropic.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan). 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:

```bash
# 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:

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

This gives you the MCP server and these skills:

| Skill | Invoke | What it teaches |
|-------|--------|-----------------|
| understanding-work | *(auto-loaded)* | Fluid graph-mediated understanding with weighted, model-chosen provocations |
| 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)* | Shared graph laws plus task-to-workflow routing |
| code-work | *(auto-loaded)* | Graph-native code nodes, generation, and executable evidence |
| collaborative-code | *(auto-loaded)* | Code-subtree ownership, handoffs, locks, and integration evidence |
| creative-work | *(auto-loaded)* | Books, prose, scripts, and editorial revision |

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
- `.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:

```bash
claude mcp add ug -- npx -y understanding-graph@0.1.29 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](https://github.com/emergent-wisdom/understanding-graph/blob/main/integrations/claude-code.md) · [Claude Desktop](https://github.com/emergent-wisdom/understanding-graph/blob/main/integrations/claude-desktop.md) · [Cursor](https://github.com/emergent-wisdom/understanding-graph/blob/main/integrations/cursor.md) · [mcporter](https://github.com/emergent-wisdom/understanding-graph/blob/main/integrations/mcporter.md)

### Claude Desktop

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "understanding-graph@0.1.29", "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:

```json
{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "understanding-graph@0.1.29", "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:

```bash
PROJECT_DIR=/path/to/your/projects npx -y understanding-graph@0.1.29 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:

```bash
PORT=3101 PROJECT_DIR=/srv/undergraph/worker-1 npx -y understanding-graph@0.1.29 start
PORT=3102 PROJECT_DIR=/srv/undergraph/worker-2 npx -y understanding-graph@0.1.29 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:

```bash
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.29 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:

```bash
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:

```bash
npm install --save-dev understanding-graph@0.1.29 @huggingface/transformers@4.2.0
npx understanding-graph@0.1.29 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