Understanding Graph

Link a document node to a concept it expresses. Creates an "expresses" edge.

List all document root nodes in the current project.

Atomically merge consecutive leaf document siblings under one parent. The node IDs must be distinct and supplied in their current reading order. The first node survives in place with combined content; the remaining nodes and their structural edges are archived. The parent receives one rebuilt contains/next topology, and each external non-structural relationship is preserved at most once on the survivor. This narrow operation rejects document roots, nodes with child subtrees, different parents, gaps/reversed order, and malformed document structure rather than inventing a hierarchy. Use doc_mo…

BATCH-ONLY: Move one non-root document node, preserving its complete subtree, content, and revision history. Use only as an operation inside graph_batch so contains/next rewiring is atomic and the batch commit records its origin. parentId defaults to the current parent. afterId is the previous sibling under the destination parent; omit afterId to move the node to the first position. The destination may be another valid document parent, including a parent under another document root. In code, this is how a function, class, test, or other responsibility moves to the module that should own it; …

Get navigation context for a document node: where you are (path to root), what's around you (siblings), and what's below (children). Use this to orient yourself within a document before reading or editing.

Read exact document content starting from any node. Pass a document root to read the whole document, or an exact passage/function/test node to inspect that unit. A root read without pagination is unbounded and intended only for small documents. For a bounded end-to-end reread, pass offset and limit, then continue with pagination.nextOffset until hasMore is false. Returns content, structure, and compact open attention. Add showRevisions: true for edit history and showProvenance: true for the recorded purpose, origin commit, and typed rationale relations that answer why this unit exists or chang…

Update content when the whole leaf remains one coherent unit. If only one of several independently revisable functions, beats, images, or exchanges is changing, split or create addressable children and revise the exact unit instead of repeatedly replacing the whole leaf. The required why records this local edit in revision history. If a discovered insight, question, or tension should influence other passages or future work, make doc_revise and graph_note about this exact passage sibling operations inside graph_batch; if it is purely local, revision history is enough. WARNING: use "nodeId" (NOT…

SYNTHETIC_READER MODE ONLY: Sign a synthetic Reader/CMP pretraining thinking block, optionally adding a role-specific review. Within synthetic Reader/CMP production, configured reviewers can sign reconstructed blocks before the producer advances. Signing records that the block is faithful to its typed evidence and chronological source boundary; it is not an ordinary reading action or a request for private chain-of-thought. Each agent can add their unique contribution: - Connector: patterns found, long-range connections - Skeptic: caveats, tensions, questions raised - Synthesizer: integration…

Batch-only: split a leaf into ordered, independently addressable units when one responsibility or creative center has become several. This is a semantic restructuring action, never a size or node quota. Split by headers or zero-based line boundaries and optionally choose the child level. The original remains an empty container, prior content stays in revision history, and graph_batch supplies atomic rollback plus an origin commit.

Convert a document node to an ordinary concept node. Clears content, level, isDocRoot and optionally moves content to understanding. Reserved synthetic Reader/CMP thinking blocks must instead use the dedicated tools in TOOL_MODE="synthetic_reader".

Start watching a document for changes. The file will auto-update when document nodes change.

Stop watching a document for changes.

Create one local prose unit whose actual creative source includes specific graph material, preserving that influence with typed provenance. Choose targets returned by graph_understand, graph_semantic_search, or focused context because an image, tension, question, promise, or distant association genuinely changes the passage. The graph should provoke rather than prescribe. If no graph material catches, use doc_create and do not force a connection. Provide a concise why for how each chosen target shaped the prose. doc_weave records each document-unit → graph-material connection as inspired_by:…

Get the revision history for an edge. Shows how the relationship between concepts evolved.

Update an edge's type or explanation. Use to change edge types (e.g., relates→contains) or update descriptions.

Add a new concept node to the understanding graph. AUTOMATIC DUPLICATE DETECTION: This tool automatically checks for similar existing concepts before creating: - >80% similarity: BLOCKS creation - extend existing concept instead - 60-80% similarity: WARNS but creates - consider linking - <60% similarity: Creates normally If blocked, you'll receive the existing concept ID and suggestions for how to extend it instead. WHEN TO USE: - An encounter changes what is understood or what becomes salient: a surprise, hesitation, attraction, alternative, question, hypothesis, prediction, consequenc…

Add a reference to an existing node. Can be an external URL OR a cross-project reference to a node in another project.

Analyze graph structure to find gaps, cycles, bridges, and open questions.

Answer a previously asked question. Creates a new concept with the answer and connects it to the question.

Archive (soft-delete) a node. The node is hidden from default context but preserved in history. Use for orphan nodes, outdated concepts, or cleanup.

Generate embeddings for all nodes that don't have them. Run this to enable semantic search on existing nodes.

Execute multiple graph operations as an ATOMIC COMMIT. The entire batch is wrapped in a SQLite transaction. If any operation fails, the entire batch is rolled back as if it never ran — there is no half-state to clean up. This is the system's "Atomic Commit" primitive from the paper: it lets you branch and revert cognitive states cleanly. The required commit_message becomes the Origin Story attached to every node and edge created in the batch. Future agents reading those nodes see the intent that created them, not just the content. The commit stream is the provenance trail of how externalized…

Optional Bisociation Engine: use spreading activation and information-gain signals to surface concrete concept pairs that may support an unexpected connection. Supply seed_nodes to spread from the current focus, or omit them for graph-wide mixed sampling. The candidates are provocations for model judgment, not claims that a connection exists.

Find and replace text across all nodes in the graph. Useful for renaming characters, locations, or concepts. Supports single replacement or batch replacements. Use preview mode first to see what will change.

Get advanced centrality measures: PageRank (importance via link structure), Betweenness (bridges between clusters), Degree (connection count). Use to find the most important concepts.

ANI (Axiomatic Noise Injection): Corrupt text with chaos seeds to force a divergent reinterpretation. WHAT IT DOES: 1. Takes your text (or random node content) 2. Replaces words independently at a configurable probability (25% by default) 3. Returns corrupted text + "Physics What-If" prompt WORKFLOW: 1. graph_chaos({ text: "Your concept description" }) 2. Read the "prompt" field from result 3. CRITICAL: Start a BLIND agent or isolated model context using ONLY the prompt - Agent must NOT see original text - This tests the Inverse Hallucination method by asking the model to invent logic …

Create edge between nodes. COGNITIVE PURPOSE: Edges are thinking scaffolds, not metadata. Only create an edge if it helps future agents reason better. Ask: "When thinking about X, should I also consider Y?" If yes, explain WHY in the why field. Good edges: "this tension led to that insight", "this question was answered here", "this pattern repeats there" Bad edges: "both about topic X" (too vague), "for completeness" (doesn't aid thinking) WARNING: edge type param is "type" (NOT "edgeType" - graph_disconnect uses edgeType).

Get the current understanding graph as XML context. For large graphs (50+ nodes), returns a compact view with overview of important concepts and region summaries. Use graph_context_region to drill into specific regions.

Get full details for a specific region/cluster of concepts. Use after graph_context to drill into regions of interest.

BATCH-ONLY: Create a durable decision node that captures a choice, connects to every option with valid typed edges, and records what was chosen and why. Use as a graph_batch operation so the node, option edges, and commit land atomically.

Remove/archive edge between nodes. WARNING: edge type param is "edgeType" (NOT "type" - graph_connect uses type). Edges are soft-deleted (active=0).

HIGH-DIVERGENCE, UNGROUNDED ANI (Axiomatic Noise Injection). Use when the live work genuinely benefits from high-divergence exploration, whether chosen directly or offered by a creativity-enabled suggestion roll. For ordinary connection-finding, prefer graph_discover_grounded: it first asks for a defensible bridge and allows "no connection" as an answer. WHAT IT DOES: 1. Selects random nodes from graph 2. Corrupts their synthesis with chaos seeds (dictionary words) 3. Returns a prompt for sense-making WORKFLOW: 1. Call graph_discover({ nodes: 2, cold: true }) 2. Read the returned "prompt" f…

DEFAULT serendipity workflow: 1) Pick random nodes and optional edges whose endpoints are among them, 2) Find a defensible connection or explicitly report none, 3) optionally perturb the grounded bridge, 4) integrate only what survives scrutiny. Prefer this over ungrounded graph_discover for understanding work.

Phase 3 of grounded serendipity: Takes the genuine bridge you found and injects chaos to push it into unexplored territory. Call this AFTER graph_discover_grounded once you have articulated the real connection. Requires a host-installed newline-delimited dictionary; set UG_ANI_DICTIONARY_PATH when no standard system word list exists.

Get statistics about embedding coverage in the graph.

Experimentally rank candidate texts by a Novelty Score: the harmonic mean of semantic divergence from the supplied original context and caller-assessed coherence. Returns candidates best-to-worst with per-candidate scores; it does not measure truth or validate the winner. Originally designed as the selection phase of the ANI serendipity pipeline (see graph_chaos / graph_discover).

Find nodes that reference a specific URL or external resource. Useful for finding all nodes that cite a paper or website.

Find all nodes with a specific trigger type. Useful for finding all questions, tensions, serendipities, etc. Use unresolvedOnly=true to find open predictions (no validates/invalidates) or unanswered questions (no answers edge).

Find a node by ID across ALL projects. Searches every project database to locate the node. Use when you have a node ID but do not know which project it belongs to.

Read the recent activity and commit feeds for the current project: who created/revised which nodes and edges, with commit messages and agent attribution in chronological order. Returns one XML packet so structure is preserved when other agents quote from it. Use it when recent collaboration or activity could affect the current task; it is not a required session-opening ritual.

List nodes from a different project without switching. Use this to browse available references in other projects.

Look up a node from a different project without switching. Use this to resolve cross-project references.

Capture each substantive, user-visible change in understanding while working with an artifact, source, or prior graph material. This is the low-friction, batch-only path for new interpretations, questions, tensions, alternatives, predictions, surprises, and evaluations that record corrections that change attention or action before they become polished conclusions. It creates an ordinary typed concept and a learned_from edge to the exact visible graph node that occasioned it. Use it inside the same graph_batch as nearby work so the note is prospective or contemporaneous, not a rationale filed …

Find the shortest path between two concepts. Shows how they connect through the graph.

Report how this graph has been WORKED, as distinct from how it is shaped: whether it is re-entered or only written to, whether artifact units carry links to the understanding that shaped them, whether practices present early have since decayed, whether existing predictions were later scored, and whether anything has been overturned. Absent node types are omitted rather than presented as missing work. graph_analyze and graph_score answer whether a graph is well formed and cannot answer whether it is doing anything — a graph nobody re-enters scores exactly like one that changes someone's mind. E…

ADMIN: Permanently delete nodes/edges (not just archive). Use for test data cleanup only. Two-step: preview first, then confirm.

Create a question node representing something you want to explore or understand better.

Sample concrete graph elements for divergent exploration. Use the returned nodes as provocations: judge how, or whether, they matter to the live task. No defensible connection is valid. force:true enables the stronger local Physics What-If experiment; ordinary work should normally keep force:false.

Rename a node (update its text/name). Use this to change character names, place names, concept names, etc. Documents using soft references ({{char:id}}) will automatically resolve to the new name on regeneration.

Resolve all cross-project references in a node. Given a node ID, fetches the full content of any referenced nodes from other projects.

Update concept understanding with EPISTEMIC JOURNEY tracking. This tool captures HOW your understanding developed, not just WHAT changed. The before/after/pivot fields create a learning trail for future agents. EPISTEMIC JOURNEY (recommended for significant revisions): - before: What you believed before ("I thought X because...") - after: What you now believe ("Now I see Y because...") - pivot: The key insight that caused the shift ("The realization was...") These fields are stored in revision history, making understanding evolution visible. WARNING: use "node" (NOT "nodeId"). Updates "und…

Calculate a structural diagnostic for ordinary graph state: chronological references, supersession, question resolution, edge specificity, connectivity, and explanations. Reserved Reader/CMP artifacts are excluded. This score is a proxy, not evidence of semantic quality.

Search nodes by metadata field values. Metadata is flexible JSON stored on nodes for module-specific data.

Find potential missing connections - node pairs that are semantically similar but not connected. Uses embeddings when available, falls back to keyword matching.

Search nodes by semantic similarity to a query. Uses embeddings to find conceptually related nodes even if they don't share keywords. Returns region_id for each result to enable efficient context loading via graph_context_region.

BATCH-ONLY: Record a serendipitous synthesis, anchor it to every source element with typed learned_from edges, and get a Novelty Score verdict. Use as a graph_batch operation so the node, edges, and commit land atomically. WHEN TO USE: After graph_discover or graph_chaos produces an insight worth keeping. WHAT IT DOES: 1. Creates a serendipity node with your synthesis 2. Calculates Novelty Score (S_N) = Harmonic Mean of Divergence × Coherence 3. Returns an advisory label: ACCEPT (S_N ≥ 0.35) | RETRY (regenerate) | UNSCORED (no embeddings) The score does not validate the synthesis and never …

Find nodes structurally similar to a given node (share neighbors). Use this to discover related concepts you might want to connect.

Ultra-minimal graph overview (~150 tokens) of the CURRENTLY ACTIVE project. Shows regions with sizes, hub nodes, and recent activity. Use for initial orientation before drilling into regions. To inspect a different project, call project_switch first — graph_skeleton always reports on whatever project is active at call time.

OPTIONAL UNDERSTANDING AID. Call when a substantive graph-backed task reaches a choice point where graph-specific pointers could deepen or diversify understanding, recover neglected material, test the current view, or make a useful connection newly visible. Direct use of graph_understand, graph_batch, and other graph tools is equally valid and loses no capability. This endpoint rolls several graph-state-, task-, and workflow-weighted concrete possibilities. Every option carries an epistemic stance—balanced, deepen, resist, connect, disrupt, revisit, or test—that can shape the next graph_unders…

Replace a wrong or incomplete concept with a fundamentally better understanding. Creates a supersession edge to preserve evolution history.

Optional entropy-style graph-state pulse. Use it when deciding whether the current graph would benefit from convergence, ordinary continuation, or a more divergent creativity tool. It is advisory, not a governor; graph_suggest_next can turn the broad pressure into concrete weighted options.

CONTEXTUAL RE-ENTRY TOOL. Usually enter Understanding mode through this tool directly. In ordinary modes, a separately advertised graph_suggest_next is an optional aid when a choice point would benefit from concrete provocations. Call this when a route or fresh encounter could be changed by prior graph state. It composes a read-only, graph-conditioned prompt for the concrete task instead of leaving continuation only in transient chat or a final artifact. Unlike ordinary retrieval, this surfaces a relevant prior, graph material that resists it, evidence links, and exact typed relations. The pro…

Get graph changes (nodes, edges, errors) since a specific timestamp. Use this to maintain state without reloading the full context. Returns new nodes, edges, and YOUR recent actions (success/failure).

BATCH-ONLY: Record an authored validation judgment after a serendipity has survived scrutiny or testing. This stores status and rationale; it does not independently prove the claim. Use as a graph_batch operation so the revision and commit land atomically.

Get metadata from a node.

Get the revision history for a node. Shows how understanding evolved over time, who changed what, and why.

Set arbitrary metadata on a node. Merges with existing metadata. Use for module-specific data (e.g., narrative-engine coordinates, thought_fluid translations). Creates a commit if commit_message is provided.

Change a node's trigger type. Use to reclassify nodes (e.g., foundation→analysis, foundation→tension).

List all available projects.

Switch to a different project, creating it if it does not exist yet. The project becomes the active target for all subsequent graph mutations and queries. Pass the project you want to use; the matching directory + SQLite database are loaded (or created) on demand. Set goal to describe the project purpose (shown in the UI).

Check what resources are currently locked.

Worker Mode: Check the queue for pending tasks. If found, returns the Agent Persona + Task. Reclaimed parent tasks include exact terminal child handoffs so the integration owner can inspect and acknowledge their evidence.

Submit the results of a task and mark it as complete or failed.

Post a task to the queue for a specific Solver. The task will be picked up by a worker calling solver_claim_task. Supports recursive decomposition via parent_task_id.

Post-exploration PURE stabilization check for a candidate intended to become reusable analysis, a decision, or a generalized synthesis. Apply it after open exploration, not as a gate on raw surprises, questions, or hypotheses. For each gate, you MUST argue both sides (steelman success AND failure) before deciding. Returns Traffic Light (RED/YELLOW/GREEN). Decision Rule: stabilize for reuse only when no gate is RED - GREEN: Gate convincingly satisfied; eligible for stabilization - YELLOW: Plausible but under-specified; targeted rework is needed before stabilization - RED: Gate fails materially…

Send feedback to a solver about a rejected task. Enables learning from rejection. The solver receives this feedback in future tasks.

List all registered Solvers in the Parliament.

Cooperative subtree-partition lock for parallel cognition. Records "agent X is working on resource R (or the subtree rooted at R) until time T" in a shared table. The intended use is to PARTITION the graph among cooperating agents — Agent A locks the "Economics" subtree, Agent B locks the "Ethics" subtree, and they refactor in parallel without colliding. Use scope="subtree" to atomically lock the root plus every node reachable through active "contains" edges; semantic edges do not expand the lease. Cooperating agents query solver_check_locks before mutating to honor each other's claims. Honest…

Get the status of the task queue: pending, processing, completed counts.

Register a new specialized Solver (agent) in the Parliament. The manifest defines the agent persona and strict behavior rules.

Release advisory locks you hold on resources. See solver_lock for the cooperative-vs-mutex caveat.

Verify a result against an AcceptSpec. Returns pass/fail with detailed breakdown.

Delete a text source (does not delete committed graph nodes).

Export a completed source reading. In an ordinary mode, the export is the exact source with reserved synthetic Reader/CMP blocks excluded and unavailable. TOOL_MODE="synthetic_reader" may include those blocks in chronological position. Preserves original source content and does not request private chain-of-thought.

List all text sources in the current project.

Stage a text source for chronological reading when sequence matters: books, papers, articles, transcripts, or similar texts. The source body is stored in SQLite but NOT returned by this call; encounter it portion by portion with source_read. For a filePath, do not inspect or sample the file first. This is not the graph-native coding workflow: code belongs in ordered document nodes, with generated files used only as executable projections. Accepts content directly or a filePath within UG_SOURCE_ROOT (the server working directory by default).

Get the current reading progress for a text source. Hidden cursor IDs are never returned. In every ordinary mode, reserved synthetic Reader/CMP blocks are excluded and unavailable. TOOL_MODE="synthetic_reader" may read and export them.

Read the next portion of a text source and AUTO-CREATE a content node. The content is automatically committed to the graph as a document node - perfect replication from source, no manual copying needed. ORDINARY READING WORKFLOW: 1. source_read → exact encountered content is appended to the source chain 2. Stop at a natural, self-selected boundary when something will help later continuation 3. If warranted, use graph_batch to preserve rich non-"thinking" typed testimony and connect it to the exact content node with learned_from 4. Continue with source_read; never use unread material or gener…

Submit the final result of your task. Call this when done.

Mark a theme as entering its activation zone. Call when narrative reaches the startId. Returns density check and active theme list.

Validate if prose aligns with active themes. Call after generating significant prose to ensure ideas are being transmitted.

Create a theme node defining an idea to transmit through the narrative. Themes have scope (story/arc/scene/moment), activation zones (where they become active), and landing points (pause moments where ideas land).

Mark a theme as leaving its activation zone. Call at endId or when theme is complete.

Get all currently active themes and their intensities. Use before generating prose to know what ideas should be expressed.

Mark a pause point where an idea lands. Call at peakId. This signals the narrative should slow down to let the idea sink in.

SYNTHETIC_READER MODE ONLY: Translate a synthetic Reader/CMP pretraining thinking block by expanding its concept references into fluid prose. TRANSLATOR-ONLY TOOL: This is the ONLY tool the translator should use to mark thinking as translated. It enforces that only THINKING nodes (trigger="thinking") can be marked as translated. WORKFLOW: 1. Find untranslated thinking: graph_find_by_trigger({ trigger: "thinking", missingMetadata: "translated" }) 2. Read the thinking node's prose 3. Look up each referenced concept (n_xxx) to get its full understanding 4. Write the expanded thought_fluid (all …