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 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 ins

... [View full README on GitHub](https://github.com/emergent-wisdom/understanding-graph#readme)