MemDSL v1 and OUTPUT v2¶

MemDSL is the internal, versioned contract between Synapse's deterministic engine and its reasoning agent. It is not an MCP action, a user query language, or a text-compression format. Its purpose is narrower and more important:

Make every navigation move, cited claim, provenance handle, status, and missing piece machine-checkable at the boundary where model output meets trusted code.

The public action remains synapse(action="navigate", question="…"). MemDSL is the protocol carried inside that navigation loop.

Three directions, direction-specific versions¶

RENDER and ACTION-RESPONSE remain byte-compatible v1. OUTPUT v2 adds the prose-to-claim binding that the production grounding gate needs:

@memdsl/1 — RENDER, engine → agent. A bounded envelope of nodes, gaps, provenance, status, and affordances.
@memdsl.out/2 — OUTPUT, agent → engine. Navigation actions followed by exactly one cited answer DAG with exact prose bindings, or a labeled abstention.
@memdsl.resp/1 — ACTION-RESPONSE, engine → agent. Nodes and gaps returned by an executed action.

Distinct headers are an injection boundary. An OUTPUT parser will not mine a RENDER envelope for action-looking text, and a response fragment cannot be silently treated as a terminal answer.

The engine continues to parse @memdsl.out/1 byte-for-byte for replay and compatibility. New production prompts emit v2. A v1 answer has no wire-level prose binding, so it uses the router's conservative legacy path.

Canonical addressing¶

Every substrate node has one address:

store:source:id{locator}

The locator is optional. It can carry a half-open character span, an as-of stamp, or both:

mem:tree:deci-e17103e8
zk:mypaper:20260706-1832-claim
repo:angelo:zettelkasten.synapse.navigate
sql:salesdb:orders.total_amount
doc:prospectus2026:p12{#1024-1280}
series:spx:close{@2026-07-23T00:00:00Z}
doc:filing:s3{#0-40@2026-01-01}

store, source, and id are non-empty and may not contain the structural separators :, {, }, ,, or whitespace. Dots are valid inside an ID, so a schema column or code symbol needs no special address shape.

Federated zettelkasten identity is encoded in the source segment, preserving the v1 three-part wire contract. The session and work store prefixes are reserved for future mutable working state; v1 parsers accept them, but shipped navigation never emits them.

RENDER: the bounded evidence envelope¶

A render envelope assigns short local references (n1, n2, …) while retaining canonical addresses:

@memdsl/1
focus n1
node n1 mem:tree:cost-model decision grounded
title Cost-model decision
prov file:models/costs.py@3f7c2e1
aff expand:n1, ground:n1
body
| Transaction costs increased from 5 bps to 8 bps.
| @answer
node n2 data:runs:run-042 dataset measured elided
title Backtest run 042
prov hash:4e291b...
aff ground:n2
body
| Sharpe decreased from 1.4 to 1.1 after...
gap elided data:runs:run-042 body truncated; ground to fetch the full record
gap outdated mem:tree:cost-model grounded as of the pinned sha

A node header fixes the local ref, address, type, engine-owned status, and optional elided marker. title, prov, and aff are structural lines.

Every physical body line is prefixed with |. In the example, the body's literal @answer is inert data: it cannot become a terminal or action. An unframed line inside a body is a hard parse error, not a switch back to structural parsing.

GapTokens¶

Absence is represented, never silently dropped:

stale — a tether drifted or cannot verify the bytes being read.
unresolved — an address or citation does not resolve.
missing — an expected relation or hop is absent.
elided — the shown body is lossy; ground can fetch the full body.
outdated — the pinned object is still exactly retrievable, but HEAD has moved on. This is a mandatory disclosure, not a status tier or abstention reason.

The status vocabulary itself is exactly grounded, measured, and inferred. The agent sees those values but cannot emit a status field in OUTPUT.

OUTPUT: actions plus one terminal¶

An OUTPUT artifact starts with the exact lowercase header, contains zero or more action calls, and ends with exactly one terminal.

Cited answer¶

@memdsl.out/2
expand(n1)
ground(n1, verifier=quote)
@answer
claim c1 [restatement] cites n1 :: Transaction costs increased from 5 bps to 8 bps.
prose :: Transaction costs increased from 5 bps to 8 bps.
cite c1 :: Transaction costs increased from 5 bps to 8 bps.
conclude c1

Each claim has:

a unique claim ID;
one inference form;
cited rendered refs or canonical addresses;
optional premise claim IDs;
optional quoted derivation text for calculations;
claim text after ::.

prose is the proposed public answer. Every assertion is repeated exactly in one cite <claim_id> :: <exact assertion> line. The parser resolves each quote to exactly one span in prose; zero matches, multiple matches, overlap, unknown/disconnected claims, or proposition-bearing text outside every span fails closed. Bindings are single-claim, so several partial claims cannot pool their vocabulary to license one sentence.

The conclusion names the claim whose closure licenses the proposed answer. There is deliberately no claim-status field: the engine re-derives status from citations, premises, tethers, and inference form.

Labeled abstention¶

@memdsl.out/2
@abstain low-coverage :: no rendered node grounds the requested figure

The canonical router reasons are missing-hop, stale, false-premise, and low-coverage. The field remains syntactically open so the engine can add a specific label without re-cutting the grammar, but a product acceptance run checks the closed public verdict vocabulary.

Strict shape¶

The parser requires:

the header as the first non-blank line;
registered action verbs with valid arity;
all actions before the terminal;
one terminal only—never both @answer and @abstain;
at least one claim in an answer;
in v2, exactly one non-empty prose line, one or more exact cite lines, and an explicit conclude line in that order;
unique, non-overlapping quote anchors that cover every proposition-bearing prose character and bind only to claims in the conclusion closure;
unique claim IDs, existing premises, and an acyclic premise graph;
a conclusion that resolves to a claim and whose transitive closure contains a real citation;
no trailing prose or structural lines after the terminal block.

The parser may unwrap one clean, exactly matched markdown fence with only blank content outside it. It trims nothing un-delimited. Preambles, epilogues, partial/nested/mismatched fences, smart-quote rewrites, and ambiguous near-misses fail closed. This conservative rule prevents a dropped conclude line from silently changing which claim becomes the answer.

ACTION-RESPONSE: deterministic mid-loop results¶

An action response uses the same node and gap blocks:

@memdsl.resp/1
status ok
node n3 zk:research:transaction-costs claim grounded
title Higher costs reduce net returns
prov cite:paper-17#p8
aff expand:n3
body
| Higher transaction costs reduce net returns.

V1 action responses carry read results only. The in-memory shape already has mut and impact seams so future write/apply actions can report what changed, but shipped v1 navigation emits neither.

Action grammar and ordering¶

V1 registers six verbs:

Topologic: expand(ref), join(ref, ref, …), and prune(ref) change the graph in view.
Parametric: ground(ref, …) deepens or verifies the selected node.
Terminal: answer and abstain use @answer / @abstain markers rather than call syntax.

The engine executes non-terminal actions in fixed order: topologic expansion and joins, parametric grounding, then pruning. The registry is open so a later version can add a verb without replacing the generic verb(args, kwargs) parser, but an unregistered verb is rejected today.

Inference forms¶

The agent labels how a claim follows, not how certain it is:

restatement
deduction
induction
abduction
calculation
comparison
causal
analogy
assumption

Only assumption may omit a direct citation, and an answer's conclusion closure must still bottom out in cited substrate. The deterministic epistemics layer maps each form to a status rule. For example, analogy and assumption cannot upgrade grounded premises into a grounded conclusion.

Grounding after parsing¶

Parsing proves that the artifact is structurally valid; it does not prove that the claims are true. The router then checks the DAG against the final envelope.

Engine-owned status¶

For every claim, the engine:

resolves each citation to a rendered node;
derives or retrieves the node's router-owned status;
propagates the weakest status through cited nodes and premise claims;
applies stale, unresolved, contested, and inference-form rules;
rejects any attempted certainty upgrade.

Restatements and atomic claims¶

A restatement is extractive. To reach grounded, its content must match one cited claim or one deterministic atomic sub-claim in full, preserving order. Matching is verbatim modulo case, punctuation, and whitespace; no truth-conditional “stopwords” are dropped. Paraphrase may still be useful, but it is inferred, never promoted to grounded by lexical resemblance.

Numeric coverage¶

Numbers are checked as atomic, ordered tokens. Signs, percentages, decimal and thousands separators, ratios, times, and units cannot migrate between clauses or be licensed from an unrelated citation. Changing 5% to -5%, reversing 5% → 10%, or carving one number from a compound clause breaks coverage.

No pooled citation laundering¶

One assertion must be licensed by one cited verified claim. The router does not pool partial vocabulary across several claims to manufacture a new proposition. Unsupported or re-contextualized text becomes low-coverage rather than an answer.

Determinism and injection boundaries¶

The serializer and parser are designed for exact round trips:

parse(serialize(value)) == value

Structural fields pass through field-specific guards before serialization. Headers have exact arity; addresses and list elements forbid their surrounding separators; unknown node types degrade to the default text body codec instead of crashing.

The important trust boundaries are:

untrusted source bodies are framed as inert | lines;
direction-specific headers prevent cross-direction confusion;
the model emits inference form, citations, and text—but never status;
strict parsing rejects malformed structure before any grounding decision;
deterministic routing and answer projection happen after parsing;
any integrity disagreement becomes an abstention.

Shipped protocol versus reserved seams¶

Shipped now:

RENDER v1, ACTION-RESPONSE v1, legacy OUTPUT v1 parsing, and production OUTPUT v2 emission;
canonical addresses and optional locators;
grounded / measured / inferred status;
explicit gaps and read affordances;
the six read/terminal actions;
strict cited ReasoningDAG validation;
exact quote-anchored prose-to-claim bindings;
deterministic round-trip and adversarial rejection tests.

Reserved or deferred:

session and work address stores for mutable working state;
action-response mut and impact records;
write/apply actions such as assert, retract, link, or unlink;
richer per-type body codecs beyond v1's framed text.

Reserved means the shape was left open deliberately. It does not mean the feature is safe or available in v1.

Where to go next¶

Grounded navigation — how Synapse assembles, navigates, adjudicates, and projects the protocol.
Synapse — the product hub and practice ↔ canon capability.
MCP tool reference — the public synapse(action="navigate") signature. MemDSL itself is intentionally absent as a public action.

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…
D Design anchor: LLM-consumer ergonomics for the MemDSL render + navigation layersactive
Authored from the first-person perspective of the LLM that consumes this substrate (the intended reasoner).
C Overnight: MemDSL parse-fail laundering class closed by construction
4 coordinator fix cycles (extensions 1-4/5, none forced).
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…
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
    - D Design anchor: LLM-consumer ergonomics for the MemDSL render + navigation layersactive
    - 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
      - D MemDSL OUTPUT recovery: sound-by-construction (trim nothing un-delimited)active
        
        C Overnight: MemDSL parse-fail laundering class closed by construction
    - N Fixed test-pollution: epistemics leaked ZETTEL_SKIP_EMBEDDINGS, starving federated_ann (6 fails -> 0)
    - 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

Semantically related entries from the memory graph.