Grounded navigation

Grounded navigation is Synapse's answer path for questions that should be resolved from project evidence. An LLM is allowed to choose useful navigation moves and propose a cited chain of claims; deterministic code owns the substrate, epistemic status, budgets, verification, and the final answer-or-abstain verdict.

That division is the point:

The model reasons freely. The engine decides what is grounded.

The public entry point is the zettelkasten server's existing dispatcher:

synapse(
  action="navigate",
  question="What changed in the backtest after May?",
)

The result is JSON. An accepted answer includes a versioned answer_surface. An answer or grounded abstention may also include a versioned trace_surface; operational failures withhold it. Every abstention or failure includes answer_surface: null.

The trust loop

flowchart LR
    M["Memory<br/>decisions · experiments"]:::memory
    Z["Zettelkasten<br/>claims · quotes"]:::zettel
    C["Codebase<br/>files · symbols · git"]:::code
    D["Data + experiments<br/>runs · hashes"]:::data

    A["1 · bounded substrate<br/>assembly"]:::synapse
    E["2 · deterministic<br/>epistemics"]:::synapse
    R["3 · MemDSL render"]:::synapse
    L["4 · bounded LLM<br/>navigation"]:::synapse
    G["5 · grounding router"]:::synapse
    S["6 · answer + trace surface<br/>or abstention"]:::synapse

    M --> A
    Z --> A
    C --> A
    D --> A
    A --> E --> R --> L --> G --> S

    classDef memory fill:#eff6ff,stroke:#2563eb,color:#1e3a8a
    classDef zettel fill:#fff1f2,stroke:#e11d48,color:#9f1239
    classDef code fill:#ecfdf5,stroke:#0f766e,color:#115e59
    classDef data fill:#fffbeb,stroke:#d97706,color:#92400e
    classDef synapse fill:#eef2ff,stroke:#4f46e5,color:#3730a3

1. Assemble a bounded substrate

Source adapters retrieve addressable nodes from the requested scope. The current production assembly composes memory and the selected local or federated zettelkasten projects; the substrate and MemDSL contracts also support code and data/experiment nodes, which are exercised by the deterministic benchmark.

Every node has a canonical address, body, provenance, and machine-checkable tethers. Assembly de-duplicates nodes, expands optional hops breadth-first, keeps only edges whose endpoints were admitted, and obeys node/source/hop ceilings. One failing adapter does not sink the whole turn.

2. Derive epistemic status

The epistemics engine verifies tethers through injected, deterministic resolvers:

• a git path@sha pin can support grounded;
• a content hash or reproducible run can support measured;
• a resolving citation or applicable predicate can support grounded;
• material without a verifiable tether remains inferred.

The model cannot set these values. Status propagation applies the weakest-link cap, then carries taints and inference-form downgrades through the claim graph.

3. Render MemDSL

The neighborhood becomes a versioned @memdsl/1 envelope. It gives each node a short local reference, frames untrusted body lines, emits engine-owned status and provenance, represents missing information as explicit GapTokens, and advertises only valid navigation affordances.

4. Navigate within hard bounds

The model receives the question and envelope. It may request:

• expand — reveal a node's neighborhood;
• join — traverse a typed bridge between nodes or stores;
• ground — fetch a full body or run a named verifier;
• prune — remove a low-value node from the turn.

It must then return exactly one terminal: a cited @answer ReasoningDAG with exact OUTPUT v2 prose bindings, or an @abstain. Actions run in deterministic order. A parse failure receives a bounded repair attempt; a verifier refutation or low-coverage result can trigger one bounded re-navigation. Token and hop caps always terminate the loop.

A fully rendered grounded/measured node needs no redundant ground action. In particular, a quote verifier request without an explicit quote is unverifiable and cannot strengthen an already verified node.

The engine also annotates the prompt with a bounded set of focus handles and remaining-budget hints. These are advisory: the model still chooses every action, and the executor still owns all hard limits.

5. Adjudicate, do not trust

The grounding router ignores any claim of certainty from the model and re-derives each claim's status from its cited nodes and premises. It also:

• normalizes store-native verifier results;
• requires restatements to match cited atomic claim content rather than merely sharing vocabulary;
• checks numeric literals and their order within the licensed clause;
• rejects unsupported prose and missing citation coverage;
• keeps verified (grounded or measured) and inferred conclusions distinct.

The verifier registry is extensible, but every verifier maps to the same ok / failed / unverifiable contract before it can influence the verdict.

6. Project a public answer—or fail closed

For OUTPUT v2, the answer projector copies only router-approved prose whose exact assertion spans are bound to claims in the conclusion closure. Legacy OUTPUT v1 falls back to the router-approved conclusion text. The projector resolves citations through the final envelope and copies status only from the router decision. It does not ask another model to rewrite the answer and does not copy source bodies into the public result.

If the decision, ReasoningDAG, claim verdicts, citation map, prose bindings, or outdated flags disagree, projection raises an integrity error and the public wrapper converts the turn to a labeled abstention. Partial answer text never escapes.

Status, taint, and disclosure

Synapse exposes three wire statuses:

• grounded — supported by verified source or git/citation/predicate tethers.
• measured — supported by reproducible data or computation.
• inferred — synthesized, assumed, contested, or not mechanically verifiable at a stronger tier.

stale, unresolved, and contested are orthogonal taints. Any of them floors the public wire status to inferred; they never increase certainty.

outdated is different. A git-pinned body may still be exactly retrievable and fully grounded even though the file at HEAD has since changed. Such a result keeps its verified status but must carry the canonical disclosure:

grounded as of the pinned sha; the current committed file (HEAD) has since changed

The flag and disclosure travel together on the router decision, answer surface, and dashboard card. A consumer cannot present an outdated answer as fresh.

Why Synapse abstains

Canonical v1 grounding reasons are ordered from specific to general:

• missing-hop — a required relation or evidence hop is absent.
• stale — a tether cannot verify the bytes or object the answer relies on.
• false-premise — a verifier definitively refuted a claimed ground.
• low-coverage — the conclusion is not fully licensed by verified cited material.

Operational guardrails can also stop a turn with halted_reason values such as budget, hops, parse-fail, validation, or answer-surface-invalid. These explain how the run stopped; they do not grant an answer.

An abstention is not a generic error or a confidence score. It is a calibrated statement that the available, checked substrate does not license the requested answer.

Navigation budgets

The MCP action accepts five public navigation knobs. Negative values mean “use the current default” unless noted otherwise.

• max_nodes — -1 uses the substrate default; 0 removes the caller-specified count cap for in-loop growth while retaining a deterministic token-derived pre-assembly safety ceiling; a positive value is an explicit hard cap.
• hops — pre-loop breadth-first expansion depth. 0 keeps the retrieved seeds only.
• token_budget — the hard per-run token guardrail. The executor checks the estimated cost before each model call.
• render_max_body_chars — maximum body characters shown per node. A positive value emits an elided gap and ground affordance; 0 disables elision. This controls body depth, not neighborhood width.
• trace_floor — compatibility dial for the prose traceability seam. The shipped full-content gate is binary rather than a similarity score.

The public validator also enforces safe numeric domains before any store or model work begins.

Advisory VOI

Navigation keeps its existing minimal VOI policy as the production default. An injectable resolvability_cost policy is available for controlled sweeps:

clamp(relevance, 0, 1) × router_status_gap ÷ clamp(token_cost, 1, 100000)

Relevance is deterministic, derived from adapter seed priority and stable retrieval rank—not model judgment. Verified clean nodes have a zero status gap. Increasing deterministic relevance or decreasing bounded cost cannot lower a non-zero score.

Only the top bounded positive-scoring handles enter the prompt, alongside tokens and hops remaining. VOI cannot ground a node, execute an action, alter router evidence, prune the graph, or bypass a budget. The sweep harness compares VOI policy, maximum hops, and trace floor under the same canonical safety gate and strict-dominance rule. No default is promoted without perfect canonical safety plus non-regressive live reliability and project evaluation.

Public JSON

The outer verdict includes run telemetry and a serialized envelope for audit. The nested answer surface is the stable display contract:

{
  "verdict": "answer",
  "status": "grounded",
  "reasons": [],
  "halted_reason": "answer",
  "conclusion": "c2",
  "outdated": false,
  "detail": "answer licensed by verified cited claims",
  "answer_surface": {
    "version": 1,
    "text": "Transaction costs increased from 5 bps to 8 bps.",
    "conclusion_claim_id": "c2",
    "inference_form": "deduction",
    "status": "grounded",
    "premise_claim_ids": ["c1"],
    "citations": [
      {
        "address": "mem:tree:cost-model",
        "claim_ids": ["c1", "c2"],
        "status": "grounded",
        "outdated": false
      }
    ],
    "outdated": false,
    "disclosure": null
  },
  "trace_surface": {
    "version": 1,
    "verdict": "answer",
    "status": "grounded",
    "conclusion_claim_id": "c2",
    "claims": [
      {
        "id": "c1",
        "text": "Transaction costs increased from 5 bps to 8 bps.",
        "inference_form": "restatement",
        "premise_claim_ids": [],
        "status": "grounded",
        "flags": {
          "stale": false,
          "unresolved": false,
          "extrapolation": false,
          "contested": false,
          "outdated": false
        },
        "citation_addresses": ["mem:tree:cost-model"]
      },
      {
        "id": "c2",
        "text": "Transaction costs increased from 5 bps to 8 bps.",
        "inference_form": "deduction",
        "premise_claim_ids": ["c1"],
        "status": "grounded",
        "flags": {
          "stale": false,
          "unresolved": false,
          "extrapolation": false,
          "contested": false,
          "outdated": false
        },
        "citation_addresses": []
      }
    ],
    "citations": [
      {
        "address": "mem:tree:cost-model",
        "claim_ids": ["c1"],
        "status": "grounded",
        "flags": {
          "stale": false,
          "unresolved": false,
          "extrapolation": false,
          "contested": false,
          "outdated": false
        }
      }
    ],
    "assertions": [
      {
        "text": "Transaction costs increased from 5 bps to 8 bps.",
        "claim_id": "c2"
      }
    ],
    "disclosures": [],
    "abstention": null,
    "telemetry": {
      "hops": 1,
      "renavigations": 0,
      "parse_repairs": 0,
      "tokens_spent": 2740,
      "loop_break": ""
    }
  },
  "envelope": "@memdsl/1\n...",
  "hops": 1,
  "renavigations": 0,
  "tokens_spent": 2740,
  "loop_break": ""
}

The answer surface deliberately excludes source bodies, titles, provenance prose, and model-authored rewrites. Citation rows use canonical MemDSL addresses and group the claim IDs that rely on each address.

The trace surface is a separate deterministic projection of the parsed claim DAG and router verdicts. It contains claim edges, inference forms, exact assertion bindings, canonical citation addresses, router-owned status flags, disclosures, safe abstention details, and bounded telemetry. It never contains source-node bodies, raw model output, filesystem paths, or unredacted verifier payloads. If trace projection or validation disagrees with the trusted structures, Synapse withholds only the trace; it does not weaken or rewrite the independently adjudicated answer/abstention.

Dashboard trace UX and trust

Grounded answer cards remain collapsed by default. “Show reasoning” reveals the redacted claim DAG, evidence addresses, per-claim epistemic flags, disclosures, and telemetry. Trusted abstentions receive their own card with canonical reasons and safe halt detail. Assistant commentary remains visible beneath either card.

Local and federated zk: citation addresses use the existing note-navigation callback. Other store addresses remain selectable text. Cards render only from authenticated grounded_navigation tool-completion metadata; assistant-authored JSON or lookalike prose cannot create an answer, abstention, or trace card.

Isolation and side effects

navigate runs in a fresh subprocess because the Cursor model bridge needs ordinary stdio and cold embedding indexes may enter native code. The parent enforces a timeout, maps a signal-killed child to a structured NativeCrash, and passes through labeled abstentions unchanged.

The action does not write .memory/, .zettelkasten/, .synapse/, code, datasets, or experiment outputs. Cold retrieval may build disposable derived indexes under .angelo/, just as search and frame do.

Validation outside the MCP contract

The public action stays small. Product validation lives in dev/synapse_bench/ and is intentionally separate:

• a canonical deterministic corpus exercises truth, fabrication, disclosure, schema, and failure cases;
• live smoke and repeated reliability runs measure model parse/safety behavior;
• project evaluation supports a committed redacted corpus plus opt-in local cases without publishing private answers;
• safety-constrained sweeps compare navigation configurations and recommend only safety-eligible, utility-improving candidates.

These harnesses validate the implementation; they are not extra fields or actions in the public MCP contract.

Where to go next

• Synapse — product overview and the practice ↔ canon capability.
• MemDSL — the versioned internal protocol used by the navigation loop.
• MCP tool reference — generated from the live synapse signature and docstring.

Design notes

The decisions behind this, drawn as a slice of the memory tree.

ListTree

• P Phase: MemDSL grounded navigation capabilityactive
  Build the v1 read engine: a callable, domain-agnostic angelo capability that navigates an n-type substrate and answers with calibrated honesty (grounded where covered, hedged where extrapolated, abstaining where coverage…
• P Grounded Navigation Productizationactive
  Implement six gated milestones without weakening epistemic honesty: (1) deterministic versioned answer surface, (2) MCP/CLI/dashboard exposure plus model provenance and max_nodes=0 semantics, (3) deterministic and live C…
• C Grounded Navigation Productization complete
  Completed all six milestones without changing the plan file or canonical corpus_v1 oracle: deterministic answer_surface v1; trusted MCP/CLI/dashboard exposure with transport-authenticated tool provenance, honest model me…
• C MemDSL Navigation Truth Benchmark implemented and deterministic baseline locked
  The 48 deterministic + 5 live MemDSL Navigation Truth Benchmark is implemented, hardened, and baselined.
• P Synapse documentation expansionactive
  Publish the native-resolution Synapse animation, reframe the Synapse explanation as a product hub, add dedicated grounded-navigation and MemDSL v1 pages, wire navigation/cross-links, and verify the strict docs build.
• P Synapse Coverage, Trace, and Adaptive VOIactive
  Implement three connected improvements without weakening epistemic honesty: (1) backward-compatible MemDSL OUTPUT v2 with exact prose-to-claim quote bindings and production traceability; (2) a deterministic redacted trac…

• R Angelo
  • P synapse — cross-store grounded reasoning layeractive
    • P Phase: MemDSL grounded navigation capabilityactive
      • A Anti-fabrication gotcha: restatement licensing must use verifier-matched SOURCE span, never caller-supplied payload text
      • E Live navigate reaches GROUNDED tier end-to-end; bottleneck is pin-drift staleness starving coverageactive
      • E Live navigate after outdated reframe + git-resolver hardening: grounded+outdated tier solid; the two remaining barriers to a GROUNDED ANSWER are token-budget and MemDSL OUTPUT parse-failactive
      • N Fixed test-pollution: epistemics leaked ZETTEL_SKIP_EMBEDDINGS, starving federated_ann (6 fails -> 0)
      • P Navigation truth benchmark: 48 deterministic + 5 live casesactive
        • D MemDSL benchmark observes internals without changing public navigation contractsactive
          • C MemDSL Navigation Truth Benchmark implemented and deterministic baseline locked
      • P Grounded Navigation Productizationactive
        • C Grounded Navigation Productization complete
      • P Synapse documentation expansionactive
        • C Synapse documentation expansion complete
      • P Synapse Coverage, Trace, and Adaptive VOIactive
        • A Run Synapse benchmark from dev package root
        • E Synapse OUTPUT v2, trace, and VOI acceptance gatesactive
        • C Release v1.7.21: Synapse coverage, trace, and adaptive VOI

Related

Semantically related entries from the memory graph.

• D Moved zettelkasten storage to committed .zettelkasten/ (mirrors .memory/)
• D Committing code auto-writes to memory (git-commit/push triggers memory record + flush)
• D Source-first ingestion for the zettelkasten agent (ingest_source + content-hash + full-text cache)