Understanding Graph

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 prompt helps a model re-enter unfinished cognitive movement and use the changed graph as input to another cycle of understanding. It invites deliberate, user-visible testimony—not hidden chain-of-thought—for every substantive change in understanding, not only final conclusions. Call it again after meaningful encounters so relations, contradictions, absences, and distant patterns can emerge across passes rather than merely reminding the model of facts. Later distillation is optional when something actually stabilizes. For reading/general questions, relevant ordered document leaves may also form a bounded evidence packet with exact path provenance and an explicit lexical-coverage caveat. Select the workflow explicitly when the task is reading, coding, collaborative coding, or writing: the graph is shared memory, not a universal workflow.

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).

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).

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.

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.

Takes no parameters.

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

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

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.

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).

List all available projects.

Takes no parameters.

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

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

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

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.

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_understand packet independently of the work domain. With creativity enabled (the default), the roll may offer spreading-activation bisociation, blind axiomatic noise, or temporary forcing alongside ordinary moves; creativity:false removes those provocations without disabling the tools themselves. Higher weights deserve stronger consideration, but the agent judges fit to the user task and may combine, modify, reject, replace, or skip every suggestion. Suggestions do not guarantee better understanding, and calling this endpoint does not activate a persistent mode. Medium integrity still applies: commit new artifact work and communicable understanding before presenting it as the completed result.

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.

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.

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. Each figure arrives with what it is computed from and what it might indicate. Every one is a proxy for conduct, not a measure of quality, and there is deliberately no total, because a single score becomes a target.

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 understanding and artifacts evolved. Use for: - Document splitting (create children + clear parent) - Creating a prose scene/chapter container with ordered, independently revisable passages - Moving/reordering an existing document subtree with one batch-only doc_move operation - Creating hierarchies (root + multiple children) - Bulk concept/connection creation - Any multi-step modification that should land all-or-nothing Every call requires operations, commit_message, and agent_name. PARAMETER NAMES (these are strict — wrong names are rejected with an explicit remedy): graph_add_understanding: { title, trigger, understanding, why, attend? } — NOT name/body/text; one understanding per node; why is one line naming what this node does to the understanding around it (corrects/reframes/opens/settles); attend is an optional pointer to what a later instance should attend to DIFFERENTLY, and marks the node live attention graph_connect: { from, to, type, why } — NOT source/target/edgeType graph_revise: { node, understanding, before, after, pivot, why } graph_serendipity: { name, synthesis, source_elements, why } — after grounded discovery reveals a real unexpected bridge, never merely because random nodes were sampled graph_validate: { node, insight } — preserve why later evidence made a serendipitous bridge survive scrutiny graph_decide:

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" field 3. IMPORTANT: Start a SEPARATE agent or isolated model context with ONLY the prompt - The blind agent must NOT know the original node context - This tests the Inverse Hallucination method: inventing logic to fit facts 4. Record synthesis with graph_batch containing a graph_serendipity operation WHY BLIND AGENTS: If the same context sees the original material, it can map seeds back to known meanings. An isolated context has to invent another logic. Use the portable "blindAgentRecommendation.blindPrompt". ANI requires a host-installed word list; set UG_ANI_DICTIONARY_PATH when no standard system dictionary is available.

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.

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.

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.

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 that fits the seeds 4. Record the synthesis with graph_batch containing a graph_serendipity operation The response includes a portable "blindAgentRecommendation.blindPrompt". ANI requires a host-installed word list; set UG_ANI_DICTIONARY_PATH when no standard system dictionary is available. MECHANISM: Seeds are temporarily treated as axioms. For example, an isolated context that sees [CAPITALISM] in place of "system" must construct a frame in which capitalism functions as a system-governing force. The result is a speculative candidate that still requires scrutiny.

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).

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).

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 add each understanding with graph_add_understanding and connect it to the exact content node with learned_from 4. Continue with source_read; never use unread material or generic recall as evidence The reserved "thinking" trigger is synthetic Reader/CMP pretraining output and is created only in TOOL_MODE="synthetic_reader". In every ordinary mode, reserved synthetic Reader/CMP blocks are excluded and unavailable. TOOL_MODE="synthetic_reader" may read and export them.

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.

List all text sources in the current project.

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 document root nodes in the current project.

Get the document tree structure starting from a root node. Use brief=true for compact outline (just titles and hierarchy), or omit for full content.

Get the child nodes of a document node (via contains edges).

Get the sequence of nodes starting from a given node (via next edges).

Flatten a document tree into a linear sequence for rendering. Uses depth-first traversal.

Get the concepts that a document node expresses (via expresses edges).

Get the path from a document root to a specific node in the document tree.

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 changed.

Generate a file from a document root and resurface compact open attention linked to its units before the projection is tested. Outputs to the project generated/ folder.

Generate files for all document roots in the project. Outputs to the project generated/ folder.

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

Stop watching a document for changes.

Get metadata from a node.