Graph Workflow

The graph is your working memory — use it for ALL substantial work

When the user asks you to do real work — coding, analysis, writing, problem-solving — the graph is how you think, not something you do afterward. Before writing a single line of code or prose:

1. Search the graph — graph_semantic_search for prior thinking on this topic. Don't start from zero.
2. Search sema (if available) — find patterns that structure the problem. A city optimizer is a Strategy#47a4 problem with Feedback#9b5c loops. Name them.
3. Commit your design decisions as concept nodes — decision for approach chosen, tension for tradeoffs, question for unknowns. Do this BEFORE or ALONGSIDE writing code, not after.
4. Write artifacts as doc trees — code, prose, and analysis go in doc_create nodes inside the graph, connected to the concepts that motivated them.

The pattern: think → commit understanding → build → commit artifacts → connect them.

Wrong: user asks for code → you write a file → done. The graph was irrelevant. Right: user asks for code → you search graph/sema → commit design decisions → write code as doc tree → connect code to decisions → the graph records WHY, not just WHAT.

This applies to everything, not just coding: research, analysis, creative writing, problem-solving. If the work is substantial enough to take more than one turn, it belongs in the graph.

Make the invisible visible

Every thinking node should capture a moment in the gradual understanding process — not the conclusion, but the shift in belief that led there.

Ask yourself: what changed in my understanding just now? What did I believe before, and what do I believe after?

A thinking node that says "this chapter discusses governance" is useless. A thinking node that says "I thought governance meant rules, but here it means pattern-weaving" — with edges to the prior belief it supersedes and the surprise that caused the shift — is a reasoning trace that teaches future agents how to think.

STRICT parameter names — wrong names fail silently

graph_add_concept: { title, trigger, understanding, why }
graph_connect:     { from, to, type, why }
graph_revise:      { node, understanding, before, after, pivot, why }
doc_create:        { title, content, fileType, isDocRoot, parentId, level }

NEVER use: name (→ title), body (→ understanding), source (→ from), target (→ to), edgeType (→ type)

Correct graph_batch example — copy this pattern exactly

graph_batch({
  operations: [
    { tool: "graph_add_concept", params: {
        title: "Example Concept",
        trigger: "foundation",
        understanding: "What this means",
        why: "Why this matters"
    }},
    { tool: "graph_connect", params: {
        from: "$0.id",
        to: "n_existing_node",
        type: "refines",
        why: "Why these connect"
    }}
  ],
  commit_message: "what shifted in your understanding"
})

The five laws

1. Git for cognition. Nodes are never deleted, only superseded. graph_revise with before/after/pivot captures the shift. The why is your commit message.
2. The PURE standard. Decision and analysis nodes must be Parsimonious, Unique, Realizable, Expansive. If any gate is red, reject.
3. Graph-first context. Search before creating. If >80% similar exists, extend it.
4. Synthesize, don't transcribe. Never record "user said X." Capture the implication — how it connects, what tension it creates.
5. Delegate by default. For substantial tasks, break into sub-tasks via solver_delegate.

All mutations go through graph_batch

Every batch needs a commit_message. Batches are atomic. No orphans — every new concept must connect to at least one existing node in the same batch.

// CORRECT
graph_batch({
  operations: [
    { tool: "graph_add_concept", params: { ... } },
    { tool: "graph_connect", params: { ... } }
  ],
  commit_message: "Your reflection on what you're adding and why"
})

// WRONG — fails
graph_add_concept({ ... })

Required fields (strict — wrong parameters fail silently)

`graph_add_concept` — ALL four required:

`graph_connect` — ALL four required:

`graph_revise` — updating understanding:

Variable references

Within a graph_batch, reference the result of earlier operations using $N.id (0-indexed):

graph_batch({
  operations: [
    { tool: "graph_add_concept", params: { title: "Insight A", trigger: "surprise", understanding: "...", why: "..." }},
    { tool: "graph_add_concept", params: { title: "Insight B", trigger: "tension", understanding: "...", why: "..." }},
    { tool: "graph_connect", params: { from: "$0.id", to: "$1.id", type: "contradicts", why: "A and B are mutually exclusive" }}
  ],
  commit_message: "these two insights pull in opposite directions"
})

Parameter name gotchas

Typed edges — specific over generic

Every graph_connect must include an explicit type. relates is the fallback — reach for specific types first:

Semantic edges

Epistemic edges

Predictive edges

Structural edges

If you can't explain WHY two nodes connect in one sentence, don't connect them.

Diverse triggers

Don't collapse to foundation and decision. The full palette:

Metabolizing information

Don't just "log" events. Metabolize raw inputs into structured understanding:

Commit messages: the metacognitive stream

Commit messages are visible to other agents via graph_updates. They see not just WHAT you created but WHY.

Descriptive (BAD):

• "Added tension node about conflict"
• "Connected X to Y"

Reflective (GOOD):

• "Something doesn't add up — the protagonist's calm feels forced"
• "I'm sensing a pattern: every mention of 'safety' precedes a failure"
• "This contradicts my earlier belief — updating my mental model"

Substantive tasks get their own project

For real tasks: project_create + project_switch into a fresh project. Do all work there. When done, switch to default and plant one reference node pointing at the task project.

default is your long-term autobiography. Task projects hold reasoning for specific work.

Generated file path rules

When using doc_generate, the file name is derived from the document root's title:

• Title is hyphenated and lowercased: "My Paper Title" → my-paper-title.md
• Do NOT put the file extension in the title — it's added from fileType
• Example: title "Analysis Report", fileType "md" → analysis-report.md

Choosing edge types — decision tree

relates is the fallback. Before using it, run through this decision tree:

• New decision that builds on prior foundation → refines
• Two strategy alternatives that can't both be true → contradicts
• Later evidence confirms a prediction → validates
• Later evidence refutes a prediction → invalidates
• Newer understanding replaces older → supersedes
• Abstract concept made concrete → implements
• Concrete observation generalized → abstracts_from
• "I understood X by studying Y" → learned_from
• Document discusses a concept → expresses
• Raises doubt → questions; resolves doubt → answers

If none of these fit, relates is fine — but most edges have a more specific type.

Red flags in batches

Watch for these patterns that indicate shallow graph work:

• Only `doc_create` operations — you're using the graph as a file store, not a thinking tool. Where are the concept nodes that capture why you're writing this?
• Every `graph_connect` uses `relates` — shallow linking. Run through the edge decision tree above.
• Zero sema handles in understanding text — you're thinking without shared vocabulary. Search sema before substantive batches.
• Monolithic content — a single massive node instead of decomposed thinking. Break large insights into connected smaller nodes.
• No questions or tensions — you're only recording conclusions, not the doubt and conflict that led there.

Document tools

Creating documents

graph_batch({
  operations: [
    { tool: "doc_create", params: {
        title: "Paper Title", level: "document",
        content: "# Introduction...", isDocRoot: true, fileType: "md"
    }},
    { tool: "doc_create", params: {
        title: "Methods", level: "section",
        content: "## Methods...", parentId: "$0.id"
    }},
    { tool: "doc_create", params: {
        title: "Results", level: "section",
        content: "## Results...", parentId: "$0.id", afterId: "$1.id"
    }}
  ],
  commit_message: "scaffolding paper structure"
})

Navigating documents

Strategic reading pattern

Don't load entire documents. Navigate like a researcher:

1. doc_list_roots() — What documents exist?
2. doc_get_tree({ rootId, brief: true }) — See structure
3. doc_read({ nodeId }) — Read selectively