understanding-graph 0.1.4 → 0.1.5

package/README.md

@@ -117,15 +117,24 @@ Without it, the rest of the graph (skeleton, history, batch, supersede, semantic
 
 ## How It Works
 
-Every mutation goes through `graph_batch` with a required `commit_message` -- git for cognition. Nodes are never deleted, only superseded. The commit stream becomes a metacognitive log that other agents can read to understand what happened and why.
+Every mutation goes through `graph_batch` with a required `commit_message` — git for cognition. The batch is wrapped in a SQLite transaction: if any operation fails, the entire batch rolls back as if it never ran. Nodes are never deleted, only superseded. The commit stream becomes a metacognitive log that other agents can read to understand what happened and why — each node's commit message becomes its *Origin Story*, the agent's inner monologue at the moment of creation.
 
 ```
-1. project_switch("my-project")        # Load a project
+1. project_switch("my-project")        # Load (or create) a project
 2. graph_skeleton()                     # Orient yourself (~150 tokens)
-3. graph_semantic_search({ query })     # Find relevant past reasoning
-4. graph_batch({ commit_message, ... }) # Mutate with intent
+3. graph_history()                      # See what other agents did recently
+4. graph_semantic_search({ query })     # Find relevant past reasoning (optional embeddings)
+5. graph_batch({ commit_message, ... }) # Mutate with intent — atomic
 ```
 
+### Atomic commits
+
+`graph_batch` is the only mutation entry point. Inside one batch you can chain `graph_add_concept`, `graph_connect`, `graph_question`, `graph_supersede`, `doc_create`, and others. The pre-validation check accepts both ID and *title* references for `graph_connect`, and computes transitive reachability (so a chain `A → B → existing` is valid even though A doesn't directly touch existing). On any failure mid-batch, the entire transaction rolls back; no half-state.
+
+### Cross-project references
+
+A 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.
+
 ---
 
 ## Core Concepts
@@ -134,6 +143,8 @@ Every mutation goes through `graph_batch` with a required `commit_message` -- gi
 
 Each node captures a moment of comprehension with a **trigger** marking *why* it was created:
 
+Triggers 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:
+
 | Trigger | When to Use |
 |---------|-------------|
 | `foundation` | Core concepts, axioms, starting points |
@@ -141,9 +152,10 @@ Each node captures a moment of comprehension with a **trigger** marking *why* it
 | `tension` | Conflict between ideas, unresolved |
 | `consequence` | Downstream implication |
 | `question` | Open question to explore |
-| `decision` | Choice made between alternatives |
-| `thinking` | Reasoning trace during reading |
-| `prediction` | Forward-looking belief |
+| `decision` | Choice made between alternatives, with rationale |
+| `prediction` | Forward-looking belief that can be validated later |
+
+Less common but available: `hypothesis`, `model`, `evaluation`, `analysis`, `experiment`, `serendipity`, `repetition`, `randomness`, `reference`, `library`. The `thinking` trigger is reserved for the synthesizer agent and rejected for normal use. The full set of 18 trigger types is documented in the [understanding-graph paper](paper/understanding_graph.pdf) (Section 3.1) and described as the *minimum* count for cognitive distinguishability — collapsing them would dissolve the Cognitive Guardrail.
 
 ### Edges (Connections)
 
@@ -392,11 +404,11 @@ cd packages/frontend && npm run dev
 
 ## The Five Laws
 
-1. **Git for Cognition** -- Nodes are never deleted, only superseded. Every `graph_batch` requires a `commit_message`.
-2. **PURE Standard** -- Quality gates: **P**arsimonious, **U**nique, **R**ealizable, **E**xpansive.
-3. **Graph-First Context** -- Always check existing graph before creating new nodes.
-4. **Synthesize, Don't Transcribe** -- Capture implications, not just facts.
-5. **Delegate by Default** -- Break complex tasks into sub-tasks.
+1. **Git for Cognition** — Nodes are never deleted, only superseded. The supersession edge preserves the *epistemic journey*: a future agent reading the chain learns not just the current belief but the path from the wrong belief to the right one. Every `graph_batch` requires a `commit_message` that becomes the node's *Origin Story*.
+2. **PURE Standard** — Quality gates: **P**arsimonious, **U**nique, **R**ealizable, **E**xpansive. Non-compensatory: any RED gate halts.
+3. **Graph-First Context** — Always check existing graph before creating new nodes. Duplicate detection is a forcing function, not a check: it pulls prior cognition into the current moment.
+4. **Synthesize, Don't Transcribe** — Capture *implications* and *tensions*, not raw facts. The graph is for your understanding, not your input.
+5. **Delegate by Default** — Break complex tasks into sub-tasks via the solver system; let specialized agents (Skeptic, Connector, Synthesizer) coordinate stigmergically through the graph.
 
 ---
 

package/node_modules/@understanding-graph/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@understanding-graph/core",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Core business logic for understanding graph",
   "type": "module",
   "main": "dist/index.js",

package/node_modules/@understanding-graph/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@understanding-graph/mcp-server",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "MCP server for building understanding graphs - persistent AI memory that captures comprehension, not just facts",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "understanding-graph",
-  "version": "0.1.4",
+  "version": "0.1.5",
+  "mcpName": "io.github.emergent-wisdom/understanding-graph",
   "description": "Persistent understanding graphs for AI agents - structured memory with MCP support",
   "author": "Henrik Westerberg",
   "license": "MIT",

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@understanding-graph/core",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Core business logic for understanding graph",
   "type": "module",
   "main": "dist/index.js",

package/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@understanding-graph/mcp-server",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "MCP server for building understanding graphs - persistent AI memory that captures comprehension, not just facts",
   "type": "module",
   "main": "dist/index.js",

package/server.json

@@ -1,28 +1,35 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "io.github.emergent-wisdom/understanding-graph",
-  "description": "Persistent reasoning memory for AI agents: tensions, hypotheses, belief revisions, and multi-agent coordination through shared thinking traces.",
-  "status": "active",
+  "description": "Persistent reasoning memory for AI agents via typed cognitive nodes and supersedes edges.",
+  "version": "0.1.5",
   "repository": {
     "url": "https://github.com/emergent-wisdom/understanding-graph",
     "source": "github"
   },
-  "website_url": "https://emergentwisdom.org/entangled-alignment/",
-  "version_detail": {
-    "version": "0.1.4",
-    "release_date": "2026-04-08"
-  },
+  "websiteUrl": "https://emergentwisdom.org/entangled-alignment/",
   "packages": [
     {
-      "registry_name": "npm",
-      "name": "understanding-graph",
-      "version": "0.1.4",
-      "runtime_hint": "npx",
-      "package_arguments": [
-        { "name": "-y" }
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "understanding-graph",
+      "version": "0.1.5",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtimeHint": "npx",
+      "runtimeArguments": [
+        {
+          "type": "positional",
+          "value": "-y"
+        }
       ],
-      "command": "understanding-graph",
-      "subcommand": "mcp"
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "mcp"
+        }
+      ]
     }
   ]
 }