{
  "markdown": "# Understanding Graph: A Persistent Medium for Recursive Understanding\n\n**A persistent medium for recursive, inspectable understanding.**\n\n[![Paper](https://img.shields.io/badge/Paper-PDF-red)](https://github.com/emergent-wisdom/understanding-graph/blob/main/paper/understanding_graph.pdf)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19462658.svg)](https://doi.org/10.5281/zenodo.19462658)\n[![npm version](https://img.shields.io/npm/v/understanding-graph.svg)](https://www.npmjs.com/package/understanding-graph)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/?q=io.github.emergent-wisdom%2Funderstanding-graph)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nUnderstanding 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.\n\n## Why Understanding Graph?\n\n| Traditional Memory | Understanding Graph |\n|-------------------|---------------------|\n| Stores facts | Stores authored understanding updates |\n| \"User prefers dark mode\" | \"User switched to dark mode after eye strain -- tension between aesthetics and comfort resolved toward comfort\" |\n| Flat retrieval | Typed, revisable interpretation |\n| Loses the interpretive middle | Preserves recorded rationale and revision |\n| Single agent | Multi-agent coordination through shared graph |\n\n**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.\n\n---\n\n## Quick Start\n\nRequires [Node.js](https://nodejs.org/) 22 or newer.\n\n### Recommended: use your Codex or Claude subscription\n\nRun the initializer in the directory where you want the graph-backed work to\nlive:\n\n```bash\ncd your-project\nnpx -y understanding-graph@0.1.31 init\n```\n\nIt creates project-scoped MCP configuration for both Codex and Claude Code,\ninstalls the same fluid-understanding contract in `AGENTS.md` and\n`CLAUDE.md`, installs a project-scoped `reading-mode` skill for both clients,\nand adds the local `projects/` path to ignore rules without installing any\nstarter graph. Open either client, sign in with your normal ChatGPT or Claude\nsubscription, and ask for the actual research, writing, coding, or decision\ntask. The agent creates a descriptively named graph when real work begins. You\ndo not need to say “use the graph.” The model runs in the subscription client;\nUnderstanding Graph itself makes no model API calls.\n\nFor a fresh chronological reading, give the agent a file path and ask it to\nturn on reader mode. It stages the source without returning or sampling its\nbody, then encounters only the next ordered passage through `source_read` and\nmay attach ordinary, passage-grounded understanding before continuing. Codex\nalso exposes `$reading-mode`; Claude Code exposes `/reading-mode`. Text pasted\ndirectly into chat has already been encountered, so use a file path when a\ngenuinely fresh reading matters.\n\n[Codex is available through eligible ChatGPT plans](https://learn.chatgpt.com/docs/pricing), and [Claude Code can use Claude Pro or Max](https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan). Their normal plan limits still apply.\n\n### Installable plugin (workflow skill + MCP server)\n\nThe package ships both `.codex-plugin` and `.claude-plugin` manifests. The\nplugin combines the MCP capabilities with an `understanding-work` skill. While\nthe mode is active, material, communicable understanding that could matter to\nthe work or a future inquiry develops in the graph.\nThe graph rolls a small state-dependent set of concrete next moves; the model\njudges their weights against the user task and freely chooses, combines, changes,\nor rejects them. The initializer above provides the same contract without\nwaiting for a plugin-directory listing.\n\nFor Claude Code, the existing marketplace flow is:\n\n```bash\n# One-time: add the Emergent Wisdom marketplace\nclaude plugin marketplace add emergent-wisdom/marketplace\n\n# Install the plugin\nclaude plugin install understanding-graph\n```\n\nFor local development:\n\n```bash\nclaude --plugin-dir /path/to/understanding-graph\n```\n\nThis gives you the MCP server and these skills:\n\n| Skill | Invoke | What it teaches |\n|-------|--------|-----------------|\n| understanding-work | *(auto-loaded)* | Fluid graph-mediated understanding with weighted, model-chosen provocations |\n| orient | `/understanding-graph:orient` | Read graph state at conversation start |\n| quality-check | `/understanding-graph:quality-check` | Score, analyze, thermostat |\n| reading-mode | `/understanding-graph:reading-mode` | Deep source reading with source_read |\n| serendipity | `/understanding-graph:serendipity` | Inject novelty via grounded/pure serendipity |\n| web-ui | `/understanding-graph:web-ui` | Launch 3D visualization at :3030 |\n| graph-workflow | *(auto-loaded)* | Shared graph laws plus task-to-workflow routing |\n| code-work | *(auto-loaded)* | Graph-native code nodes, generation, and executable evidence |\n| collaborative-code | *(auto-loaded)* | Code-subtree ownership, handoffs, locks, and integration evidence |\n| creative-work | *(auto-loaded)* | Books, prose, scripts, and editorial revision |\n\nThe raw MCP server works with any compatible client, but the bundled skill or\ngenerated project instructions are the recommended experience. Tool schemas\nalone do not reliably activate a multi-step understanding workflow.\n\n### What the initializer creates\n\nThis creates:\n- `.codex/config.toml` -- Codex MCP configuration\n- `.mcp.json` -- Claude Code project MCP configuration\n- `AGENTS.md` and `CLAUDE.md` -- the same canonical understanding workflow\n- `.agents/skills/reading-mode/SKILL.md` -- explicit Codex reader workflow\n- `.claude/skills/reading-mode/SKILL.md` -- explicit Claude Code reader workflow\n- `.gitignore` entry for `projects/` -- keeps graph data local; no starter\n  project is created\n\nEvery session opened in the directory shares the same project root. Once a\nnamed graph is selected, agents working there share it. Use additional agents\nonly when the work has real independent seams.\n\n### Raw MCP configuration (advanced)\n\nIf a client cannot install plugins or run the initializer, connect the MCP\nserver directly:\n\n```bash\nclaude mcp add ug -- npx -y understanding-graph@0.1.31 mcp\n```\n\nMCP initialization still supplies a concise graph-use contract, but client\nsupport for server instructions varies. For consistent behavior, also provide\nthe bundled `understanding-work` skill or its generated project instructions.\n\nPer-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)\n\n### Claude Desktop\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"understanding-graph\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"understanding-graph@0.1.31\", \"mcp\"],\n      \"env\": {\n        \"PROJECT_DIR\": \"/path/to/your/projects\",\n        \"UG_SOURCE_ROOT\": \"/path/to/your/source-project\"\n      }\n    }\n  }\n}\n```\n\n`UG_SOURCE_ROOT` limits file-based source loading to that directory. The\nproject initializer sets it to the project root automatically.\n\n### Cursor / Windsurf\n\nAdd to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"understanding-graph\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"understanding-graph@0.1.31\", \"mcp\"],\n      \"env\": {\n        \"PROJECT_DIR\": \"/path/to/your/projects\"\n      }\n    }\n  }\n}\n```\n\n### Web UI / 3D visualization\n\nThe root npm package includes the built frontend and depends on the web server,\nso the published package can launch the UI directly:\n\n```bash\nPROJECT_DIR=/path/to/your/projects npx -y understanding-graph@0.1.31 start\n# open http://localhost:3000\n```\n\nRun independent sidecars by giving each process its own port and project-store\nroot. The roots may be sibling directories on the same volume:\n\n```bash\nPORT=3101 PROJECT_DIR=/srv/undergraph/worker-1 npx -y understanding-graph@0.1.31 start\nPORT=3102 PROJECT_DIR=/srv/undergraph/worker-2 npx -y understanding-graph@0.1.31 start\n```\n\nUse absolute paths in deployments. Sharing the installed package and its\nread-only frontend is safe; do not point independent sidecars at the same\n`PROJECT_DIR`.\n\nThe server binds to loopback by default. To run a worker on another host,\nexplicitly set `HOST` and a private worker token; non-loopback startup fails\nclosed without both:\n\n```bash\nHOST=0.0.0.0 PORT=3101 \\\nUG_WORKER_TOKEN=replace-with-a-long-random-secret \\\nPROJECT_DIR=/srv/undergraph/worker-1 \\\nnpx -y understanding-graph@0.1.31 start\n```\n\nThe trusted caller must send `Authorization: Bearer <UG_WORKER_TOKEN>` on every\n`/api` or `/admin` request. Put remote traffic behind TLS or a private\nauthenticated network.\n\nTo develop the UI from a checkout instead:\n\n```bash\ngit clone https://github.com/emergent-wisdom/understanding-graph.git\ncd understanding-graph\nnpm install\nnpm run build\nnpm run start:web\n# open http://localhost:3000\n```\n\n### Optional: enable embedding-based search\n\n`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:\n\n```bash\nnpm install --save-dev understanding-graph@0.1.31 @huggingface/transformers@4.2.0\nnpx understanding-graph@0.1.31 init\n```\n\nA separate global `@huggingface/transformers` install does not reliably satisfy an\nisolated npx cache install.\n\nWithout it, the rest of the graph works normally. `graph_understand` and\n`graph_semantic_search` use deterministic lexical retrieval when embeddings are\nunavailable; semantic-only analysis tools explain when the optional model is\nneeded.\n\n---\n\n## How It Works\n\nDirect concept and edge mutations go through `graph_batch`. Relevant workflow\nmodes also expose document helpers at the top level; use a batch when related\ndocument, concept, and edge changes must land together. Every batch requires a\n`commit_message` and runs in a SQLite transaction: if any operation fails, the\nentire batch rolls back as if it never ran. Workflow tools such as `source_read`\nmanage their own atomic updates. Ordinary work revises, archives, or supersedes\nnodes while preserving their history; irreversible purge is a separate,\nexplicitly selected administrative action. The commit stream becomes an\ninspectable update log—each node's commit message becomes its *Origin Story*.\n\n```\n1. project_switch({ project: \"my-project\" })\n2a. DIRECT: use graph_understand, graph_batch, or another graph tool immediately\n2b. GUIDED: graph_suggest_next({ task, workflow: \"coding\" })\n3. [if guided, judge, modify, reject, skip, or choose a sampled route]\n4. graph_batch({ commit_message, agent_name, ... }) # preserve artifact + understanding\n```\n\nThe optional chooser is an aid for surfacing graph-specific pointers that may\ndeepen or diversify understanding, recover neglected material, test the current\nview, or expose a useful connection. Suggestions are sampled server-side from\ngraph- and workflow-weighted pressures, include concrete nodes or regions when\npossible, and temporarily down-weight recently suggested action kinds. The\nmodel remains responsible for task fit and may always work directly, do\nsomething else, or stop rather than manufacture work. Set `UG_GUIDANCE_MODE` to\n`direct` to remove ambient suggestion prompts; `graph_suggest_next` remains\navailable on demand.\nPass `creativity: false` to an individual roll when ordinary guidance is useful\nbut grounded random comparison, bisociation, ANI, disruption, and temporary\nforcing are not. This changes the roll only; the optional creativity tools\nremain available for direct use.\n\nRetrieval has two orthogonal axes: `workflow` identifies the domain and its\nnative evidence, while `stance` weights the epistemic pressure—such as\ndeepening, resistance, connection, disruption, revisiting, or testing. Neither\naxis limits what the model may do.\n\n### Atomic commits\n\n`graph_batch` is the entry point for concept and edge mutations, and for atomic\nmulti-step document changes. Inside one batch you can chain\n`graph_add_concept`, `graph_connect`, `graph_question`, `graph_supersede`,\n`doc_create`, and others. The pre-validation check accepts both ID and *title*\nreferences for `graph_connect`, and computes transitive reachability (so a chain\n`A → B → existing` is valid even though A doesn't directly touch existing). On\nany failure mid-batch, the entire transaction rolls back; no half-state.\n\n### Cross-project references\n\nA 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](https://github.com/emergent-wisdom/entangled-alignment) chronological annotation pipeline, where eras and documents draw cross-references.\n\n---\n\n## Core Concepts\n\n### Nodes (Understanding Units)\n\nEach cognitive node captures an authored understanding update with a **trigger** marking *why* it was created:\n\nTriggers 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:\n\n| Trigger | When to Use |\n|---------|-------------|\n| `foundation` | Core concepts, axioms, starting points |\n| `surprise` | Unexpected findings, contradicts prior belief |\n| `tension` | Conflict between ideas, unresolved |\n| `consequence` | Downstream implication |\n| `question` | Open question to explore |\n| `decision` | Choice made between alternatives, with rationale |\n| `prediction` | Forward-looking belief that can be validated later |\n\nLess 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](https://github.com/emergent-wisdom/understanding-graph/blob/main/paper/understanding_graph.pdf) (Section 3.1); it is an evolving design rather than a claimed formal minimum.\n\n### Edges (Connections)\n\n| Edge Type | Meaning |\n|-----------|---------|\n| `supersedes` | New understanding replaces old; created through the dedicated `graph_supersede` lifecycle operation |\n| `contradicts` | Ideas in conflict |\n| `refines` | Adds precision to existing understanding |\n| `learned_from` | Attribution of insight |\n| `answers` / `questions` | Resolves or raises questions |\n| `contains` | Parent-child hierarchy |\n| `next` | Sequential ordering |\n\n### Documents\n\nStructured prose, source material, and graph-native code share the same\naddressable document tree. A leaf can be a passage, function, class, type, or\ntest with its own recorded purpose, origin commit, revisions, and typed links to\nthe questions, decisions, evidence, or tensions that shaped it. This allows a\nlater Reader to ask why one exact unit exists—not merely why the file exists—by\ncalling `doc_read({ nodeId, showProvenance: true, showRevisions: true })`.\n\n`implements` points from an abstract commitment to its concrete unit;\n`expresses` and `inspired_by` point from an artifact unit to what it renders or\nwhat its author reports as influential; `learned_from` points from a cognitive\nupdate to the source or artifact encounter that occasioned it. These are\ninspectable authored claims, not verified causes. Code roots generate runnable\nfiles; units can be split, merged, moved, and reordered before regeneration.\n\n### Projects\n\nIsolated graphs for different contexts. Each project has its own SQLite database.\n\n---\n\n## Tools Overview\n\n<details>\n<summary>Selected tools from the 46-tool default <code>general</code> surface and 70-tool explicit <code>full</code> mode, plus batch-only operations callable through <code>graph_batch</code> (click to expand)</summary>\n\n### Batch Operations\n| Tool | Purpose |\n|------|---------|\n| `graph_batch` | Execute multiple operations as an **atomic commit** with a required `commit_message`. Wrapped in a SQLite transaction: if any operation fails, the entire batch is rolled back. The `commit_message` is preserved as the node's *Origin Story* — future agents reading those nodes see not just the content but the intent that created it. |\n\n### Concept & Node Management (batch operations unless listed by the selected mode)\n| Tool | Purpose |\n|------|---------|\n| `graph_add_concept` | Add new concept with duplicate detection |\n| `graph_question` | Create question node for exploration |\n| `graph_revise` | Update concept understanding |\n| `graph_supersede` | Replace outdated concept |\n| `graph_add_reference` | Add external/cross-project references |\n| `graph_rename` | Rename node (updates soft references) |\n| `graph_archive` | Soft-delete preserving history |\n| `node_set_metadata` | Set arbitrary metadata on nodes |\n| `node_get_metadata` | Retrieve node metadata |\n| `node_set_trigger` | Change node classification |\n| `node_get_revisions` | Get understanding evolution history |\n\n### Connection Management (batch operations unless listed by the selected mode)\n| Tool | Purpose |\n|------|---------|\n| `graph_connect` | Create edges between concepts |\n| `graph_answer` | Record answer to a question node |\n| `graph_disconnect` | Remove/archive edges |\n| `edge_update` | Update edge type or explanation |\n| `edge_get_revisions` | Get relationship history |\n\n### Reading & Analysis\n| Tool | Purpose |\n|------|---------|\n| `graph_understand` | Compose a workflow-specific re-entry packet with priors, resistance, evidence, and typed relations |\n| `graph_skeleton` | Structural overview (~150 tokens) |\n| `graph_context` | Full graph XML, optionally focused on one node; auto-compacts above 50 nodes |\n| `graph_context_region` | Full details for one numbered region returned by context, skeleton, or search |\n| `graph_semantic_search` | Find nodes by meaning |\n| `graph_similar` | Find conceptually similar nodes |\n| `graph_find_by_trigger` | Find nodes by type |\n| `graph_analyze` | Find structural gaps, cycles, bridges, open questions, and serendipity nodes |\n| `graph_semantic_gaps` | Find disconnected concepts |\n| `graph_score` | Structural proxy for chronology, revision, resolution, edge specificity, and connectivity—not semantic quality |\n| `graph_path` | Reasoning path between concepts |\n| `graph_centrality` | Most influential concepts |\n| `graph_thermostat` | Advisory entropy-style pulse for convergence, continuation, or divergence |\n| `graph_history` | Commit history and changes |\n\n### Synthesis & Exploration\n\nThe toolkit's median-escape branch---particularly ANI and Axiomatic Forcing---was inspired by [*The Ontology of the Alien*](https://doi.org/10.5281/zenodo.18912179). Its random cues, temporary axioms, and alternative-physics provocations are adapted here as optional agent-facing tools whose outputs remain speculative until scrutinized.\n\n| Tool | Purpose |\n|------|---------|\n| `graph_bisociate` | Surface candidate cross-context pairs with spreading activation and information gain |\n| `graph_discover_grounded` | Default bounded comparison of distant graph material; no connection is valid |\n| `graph_discover_grounded_chaos` | Optional dictionary perturbation after a genuine grounded bridge; requires a host-installed word list |\n| `graph_discover` | Explicitly speculative blind ANI over graph material |\n| `graph_random` | Concrete random provocations, including optional scrutinized Physics What-If forcing |\n| `graph_serendipity` | Batch-only: record a synthesis with source edges |\n| `graph_validate` | Batch-only: record an authored validation judgment for a scrutinized serendipity |\n| `graph_chaos` | Inject words from a machine-local dictionary or graph nodes into text |\n| `graph_decide` | Batch-only: record a typed decision over options |\n| `graph_evaluate_variations` | Rank alternatives with the experimental Novelty Score |\n\n### Document Operations (availability varies by workflow mode)\n| Tool | Purpose |\n|------|---------|\n| `doc_create` | Create document with content |\n| `doc_revise` | Modify document text |\n| `doc_insert_thinking` | `synthetic_reader` only: insert a reconstructed Reader/CMP pretraining block |\n| `doc_append_thinking` | `synthetic_reader` only: append a reconstructed Reader/CMP pretraining block |\n\n### Source Reading\n| Tool | Purpose |\n|------|---------|\n| `source_load` | Load text for staged reading |\n| `source_read` | Read next portion, auto-create nodes |\n| `source_position` | Get reading progress |\n| `source_list` | List loaded sources |\n| `source_export` | Reconstruct exact source text; `synthetic_reader` may additionally export its reserved Reader/CMP blocks |\n\n### Project Management\n| Tool | Purpose |\n|------|---------|\n| `project_switch` | Switch active project |\n| `project_list` | List available projects |\n\n### Cross-Project (`TOOL_MODE=full`)\n\n| Tool | Purpose |\n|------|---------|\n| `graph_lookup_external` | Look up node in another project |\n| `graph_list_external` | List accessible external projects |\n| `graph_find_by_reference` | Find nodes referencing a concept |\n| `graph_resolve_references` | Verify cross-project references |\n| `graph_global_lookup` | Search across all projects |\n\n### Multi-Agent Coordination (Solver)\n\nSolver tools are available in `research`, `collaborative_coding`, and `full`\ntool modes.\n\n| Tool | Purpose |\n|------|---------|\n| `solver_spawn` | Register specialized solver agent |\n| `solver_delegate` | Post task to solver queue |\n| `solver_claim_task` | Claim pending task (worker mode) |\n| `solver_complete_task` | Submit task results |\n| `solver_list` | List registered solvers |\n| `solver_queue_status` | Task queue statistics |\n\n</details>\n\n---\n\n## Multi-Agent with Claude Code Agent Teams\n\nUnderstanding Graph is designed as a shared persistent medium for [Claude Code Agent Teams](https://code.claude.com/docs/en/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.\n\n### How it works\n\n```\nYou: \"Create an agent team to research and implement auth for this app\"\n\nClaude (Team Lead):\n  ├── Researcher teammate   ─── reads/writes shared graph ───┐\n  ├── Backend teammate       ─── reads/writes shared graph ───┤  Same Understanding Graph\n  ├── Security teammate      ─── reads/writes shared graph ───┤  (via MCP)\n  └── synthesizes findings from graph_history()               ┘\n```\n\n1. **`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.\n2. **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.\n3. **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?\"\n4. **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.\n\n### Getting started with a swarm\n\n```bash\ncd your-project\nnpx -y understanding-graph@0.1.31 init     # one-time setup\n```\n\nThen in Claude Code:\n```\nCreate an agent team with 3 teammates to [your task].\nEach teammate should work through the shared Understanding Graph,\npreserve material understanding as it emerges, and use graph_batch\nwith descriptive commit messages so the team can coordinate.\n```\n\n### Long-running coordination (solver system)\n\nFor tasks that span multiple sessions or need async handoff beyond a single team:\n\n| Tool | Purpose |\n|------|---------|\n| `solver_spawn` | Register a specialist (e.g., \"SecurityReviewer\", \"ArchiveKeep\") |\n| `solver_delegate` | Post a task to the queue |\n| `solver_claim_task` | Pick up pending work (worker mode) |\n| `solver_complete_task` | Submit results |\n| `solver_lock` / `solver_unlock` | Prevent conflicts on shared nodes |\n\nThe solver system persists in the SQLite database, so tasks survive across sessions. One team can delegate work that a future team picks up.\n\n---\n\n## Architecture\n\n```\npackages/\n  core/          # Graph logic, SQLite storage, embeddings\n  mcp-server/    # MCP server (46 default / 70 full tools + batch operations)\n  web-server/    # REST API + serves frontend\n  frontend/      # 3D visualization (React + Three.js)\n```\n\n**Stack:**\n- **SQLite** + **better-sqlite3** -- Persistent storage\n- **Graphology** -- In-memory graph operations\n- **MCP Protocol** -- Agent integration\n- **Transformers.js** -- Local embeddings for semantic search\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/emergent-wisdom/understanding-graph.git\ncd understanding-graph\nnpm install\nnpm run build\nnpm run start:web    # Web UI at http://localhost:3000\n```\n\n### Dev mode\n\n```bash\n# Terminal 1: Web server with hot reload\nnpm run dev:web\n\n# Terminal 2: Frontend dev server\ncd packages/frontend && npm run dev\n```\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PROJECT_DIR` | `./projects` | Where to store project data |\n| `UG_SOURCE_ROOT` | current working directory | Directory that `source_load.filePath` may read from; provide `content` directly for files outside it |\n| `PORT` | `3000` | Web server port |\n| `HOST` | `127.0.0.1` | Web bind address; non-loopback requires `UG_WORKER_TOKEN` |\n| `UG_WORKER_TOKEN` | -- | Bearer secret required for remote worker API/admin requests |\n| `ANTHROPIC_API_KEY` | -- | For repository autonomous-worker scripts (optional) |\n| `ANTHROPIC_MODEL` | -- | Explicit model ID for the optional Anthropic autonomous worker |\n| `TOOL_MODE` | `general` | Enforced tool surface: safe cross-domain `general`; focused `reading`, `research`, `coding`, `collaborative_coding`, or `writing`; explicit broad `full`; or the reserved `synthetic_reader` pretraining producer |\n| `UG_GUIDANCE_MODE` | `guided` | Suggestion aid: `guided` adds optional next-move prompts; `direct` suppresses ambient prompts while keeping `graph_suggest_next` callable on demand |\n| `UG_ANI_DICTIONARY_PATH` | system word list | Absolute path to a host-installed newline-delimited word list when `/usr/share/dict/words` or another standard path is unavailable; no dictionary or reduced fallback is bundled |\n| `DEFAULT_PROJECT` | unset | Optional project to load or explicitly create on startup |\n\n---\n\n## Working principles\n\n1. **Use the graph as the medium** — While Understanding mode is active,\n   preserve the communicable understanding and addressable artifact units that\n   matter to the work, not merely its final answer.\n2. **Keep agency with the model** — `graph_suggest_next` offers weighted,\n   concrete provocations when the optional aid is useful. The model may work\n   directly or choose, combine, modify, reject, replace, or skip them according\n   to the user's task.\n3. **Re-enter when it can change the work** — Revisit the accumulated graph at\n   genuine choice points, surprises, resistance, or uncertainty—not on a fixed\n   timer and not as ceremony.\n4. **Synthesize rather than transcribe** — Preserve what an encounter changed,\n   including unresolved implications and tensions, rather than copying the\n   input. PURE is available as an optional stabilization check after open\n   exploration; it is not a quota or a gate on emergence.\n5. **Preserve provenance** — Use descriptive commits, dedicated revision and\n   supersession operations, evidence from the real artifact, and explicit\n   ownership or handoffs when collaboration actually requires them.\n\n---\n\n## Using with sema\n\nUnderstanding Graph gives your agents shared *episodic* memory — the recorded interpretive trail behind a decision. [Sema](https://github.com/emergent-wisdom/sema) gives them shared *semantic* memory — a content-addressed vocabulary of cognitive patterns. They compose:\n\n```bash\n# Add both to Claude Code\nclaude mcp add ug   -- npx -y understanding-graph@0.1.31 mcp\nclaude mcp add sema -- uvx --from semahash sema mcp\n```\n\nWith both installed, an agent can:\n\n1. 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.\n2. 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.\n3. 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.\n\nFull walkthrough: [using Understanding Graph with sema](https://github.com/emergent-wisdom/understanding-graph/blob/main/docs/using-with-sema.md)\n\n### Coding inside the graph\n\nCode lives in graph document roots and their ordered child nodes. Generate\nrunnable files with `doc_generate` or `doc_generate_all`, run the real build and\ntests, then revise or rearrange the source nodes and regenerate—never patch the\ngenerated projection directly.\n\nSee [coding-inside-the-graph](https://github.com/emergent-wisdom/understanding-graph/blob/main/docs/coding-inside-the-graph.md) for the full workflow.\n\n---\n\n## Citing\n\n```bibtex\n@misc{westerberg2026understanding,\n  title        = {Understanding Graph: A Persistent Medium for Recursive Understanding},\n  author       = {Westerberg, Henrik},\n  year         = {2026},\n  month        = aug,\n  publisher    = {Zenodo},\n  doi          = {10.5281/zenodo.19462658},\n  url          = {https://doi.org/10.5281/zenodo.19462658}\n}\n```\n\nSee [`CITATION.cff`](https://github.com/emergent-wisdom/understanding-graph/blob/main/CITATION.cff) for the machine-readable version (GitHub\nrenders a \"Cite this repository\" button from it).\n\n## License\n\nMIT -- [LICENSE](LICENSE)\n\n**GitHub:** [emergent-wisdom/understanding-graph](https://github.com/emergent-wisdom/understanding-graph)\n**npm:** [understanding-graph](https://www.npmjs.com/package/understanding-graph)\n**MCP Protocol:** [modelcontextprotocol.io](https://modelcontextprotocol.io)\n",
  "bytes": 32273,
  "sha": "5358c10f24a9190dbc4ad514e140a532e4573065ae22a9be3584fd92c025628a",
  "repo_slug": "emergent-wisdom/understanding-graph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_emergent_wisdom_understanding__c15bdfab/readme"
}