@hviana/sema 0.1.6 → 0.1.7

package/dist/example/train_base.js

@@ -1487,9 +1487,22 @@ async function main() {
     const checkpoint = () => mind.save();
     /** Run index maintenance: compact (remove garbage) then repair (fill gaps).
      *  Both are idempotent — running twice produces the same result as once.
-     *  Compaction frees index space first; repair then adds back the bridges
-     *  whose gists were evicted before indexing, completing the coverage that
-     *  incremental bridge promotion alone cannot guarantee.
+     *  Compaction frees index space first; repair then adds back every
+     *  edge/halo-bearing node whose gist was evicted from the pending cache
+     *  before it reached the content index, completing the coverage that
+     *  incremental promotion alone cannot guarantee.
+     *
+     *  repair runs with minParents = 0, NOT the library default of 2.  The
+     *  default repairs only structural BRIDGES (≥2 parents), but this
+     *  trainer's fact deposits also leave answer-side DEPOSIT ROOTS with 0
+     *  structural parents ("The capital of France is Paris." as the dst of a
+     *  Q→A edge is a root of its own tree, contained in nothing).  Those are
+     *  resonance targets recall depends on — a trained store shipped without
+     *  them cannot ground statement-shaped queries against its own answers
+     *  (observed: 33 such roots missing after a full curriculum, including
+     *  high-traffic conversation replies).  minParents = 0 admits every
+     *  edge/halo bearer; the candidate set is still corpus-of-experiences-
+     *  sized, so the pass stays cheap.
      *
      *  Logs the number of entries removed/added so a run that silently degrades
      *  (growing compaction count, or repair never recovering anything) is
@@ -1507,9 +1520,9 @@ async function main() {
             progress.log(`  ${YEL}⚠ index compact failed${R}: ${err instanceof Error ? err.message : String(err)}`);
         }
         try {
-            const added = await mind.repairContentIndex();
+            const added = await mind.repairContentIndex(0);
             if (added > 0) {
-                progress.log(`  ${GRN}index repair: added ${int(added)} missing bridges${R}`);
+                progress.log(`  ${GRN}index repair: added ${int(added)} missing resonance targets${R}`);
             }
         }
         catch (err) {

package/dist/src/geometry.d.ts

@@ -103,8 +103,19 @@ export declare function knownPrefixLength(bytes: Uint8Array, leafAt: (i: number)
 /** Bytes → Sema tree.  `leafAt` and `lookup` are store capabilities for
  *  detecting previously-stored prefixes so the river can split at the
  *  correct boundary.  Pass them through from `perceive`; the geometry
- *  computes the stable prefix internally. */
-export declare function bytesToTree(space: Space, alphabet: Alphabet, bytes: Uint8Array, leafAt?: (i: number) => number | null, lookup?: (leafIds: number[]) => number | null): Sema;
+ *  computes the stable prefix internally.
+ *
+ *  `boundaries` is the CALLER-computed stable-prefix boundary set (§10.3):
+ *  strictly-increasing proper byte offsets, each the length of a prefix that
+ *  is already a stored whole-stream form.  When given, the fold splits into
+ *  the segments between consecutive boundaries — each folded independently,
+ *  exactly as it folded when it was learned — and the segment roots join
+ *  LEFT-NESTED (((s₀·s₁)·s₂)…), so every learnt cumulative-context root
+ *  reappears as an identical subtree (and, by hash-consing, the very same
+ *  node) inside the grown stream.  This is what lets a conversation's next
+ *  turn extend perception instead of refolding it: identical prefixes
+ *  produce identical subtrees regardless of what follows them. */
+export declare function bytesToTree(space: Space, alphabet: Alphabet, bytes: Uint8Array, leafAt?: (i: number) => number | null, lookup?: (leafIds: number[]) => number | null, boundaries?: readonly number[]): Sema;
 /** The PLAIN fold's full level pyramid — every level's item list, bottom
  *  (leaves) to top (root).  Left-grouped folding is RADIX-ALIGNED: the item
  *  at level L, index i, covers exactly bytes [i·mg^L, (i+1)·mg^L) whenever

package/dist/src/geometry.js

@@ -270,14 +270,101 @@ export function knownPrefixLength(bytes, leafAt, lookup) {
 /** Bytes → Sema tree.  `leafAt` and `lookup` are store capabilities for
  *  detecting previously-stored prefixes so the river can split at the
  *  correct boundary.  Pass them through from `perceive`; the geometry
- *  computes the stable prefix internally. */
-export function bytesToTree(space, alphabet, bytes, leafAt, lookup) {
+ *  computes the stable prefix internally.
+ *
+ *  `boundaries` is the CALLER-computed stable-prefix boundary set (§10.3):
+ *  strictly-increasing proper byte offsets, each the length of a prefix that
+ *  is already a stored whole-stream form.  When given, the fold splits into
+ *  the segments between consecutive boundaries — each folded independently,
+ *  exactly as it folded when it was learned — and the segment roots join
+ *  LEFT-NESTED (((s₀·s₁)·s₂)…), so every learnt cumulative-context root
+ *  reappears as an identical subtree (and, by hash-consing, the very same
+ *  node) inside the grown stream.  This is what lets a conversation's next
+ *  turn extend perception instead of refolding it: identical prefixes
+ *  produce identical subtrees regardless of what follows them. */
+export function bytesToTree(space, alphabet, bytes, leafAt, lookup, boundaries) {
     if (bytes.length === 0) {
         return sema(alphabet.vecs[0], new Uint8Array(0), null);
     }
+    if (boundaries !== undefined && boundaries.length > 0) {
+        return stablePrefixFold(space, alphabet, bytes, boundaries);
+    }
     const sb = (leafAt && lookup) ? knownPrefixLength(bytes, leafAt, lookup) : 0;
     return riverFold(space, bytesToLeaves(alphabet, bytes), sb > 0 ? sb : bytes.length).tree;
 }
+/** The stable-prefix segmented fold (§10.3).  Each segment between
+ *  consecutive boundaries folds PLAINLY and independently; segment roots
+ *  join left-nested, and only the final root is normalized (the linear-fold
+ *  contract: one normalize per perception).  A segment's own inner splits
+ *  need no recursion here: a nested learnt prefix is itself an earlier
+ *  boundary, so the left-nested join reproduces every intermediate learnt
+ *  root ((s₀·s₁) IS the root the store learnt for the first two segments'
+ *  bytes, and so on). */
+function stablePrefixFold(space, alphabet, bytes, boundaries) {
+    const cuts = [];
+    let prev = 0;
+    for (const b of boundaries) {
+        if (b > prev && b < bytes.length) {
+            cuts.push(b);
+            prev = b;
+        }
+    }
+    if (cuts.length === 0) {
+        return riverFold(space, bytesToLeaves(alphabet, bytes), bytes.length).tree;
+    }
+    const edges = [0, ...cuts, bytes.length];
+    const segs = [];
+    for (let i = 0; i + 1 < edges.length; i++) {
+        const seg = bytes.subarray(edges[i], edges[i + 1]);
+        segs.push(riverFoldRaw(space, bytesToLeaves(alphabet, seg)));
+    }
+    let cur = segs[0];
+    for (let i = 1; i < segs.length; i++)
+        cur = fold2(space, cur, segs[i]);
+    normalize(cur.tree.v);
+    return cur.tree;
+}
+/** Join two folded items as one 2-kid branch — the top-level join of the
+ *  stable-prefix fold, identical FP ops to foldSlice's seat-bound
+ *  accumulation over a group of two.  Unnormalized (interior). */
+function fold2(space, a, b) {
+    const D = space.D;
+    const gist = new Float32Array(D);
+    const kids = [a.tree, b.tree];
+    for (let k = 0; k < 2; k++) {
+        const seat = space.seats[k].fwd;
+        const v = kids[k].v;
+        for (let d = 0; d < D; d++)
+            gist[d] += v[seat[d]];
+    }
+    return { tree: sema(gist, null, kids), len: a.len + b.len };
+}
+/** Plain river fold WITHOUT the final root normalize — the segment-level
+ *  building block of {@link stablePrefixFold} (interiors must keep their
+ *  byte-proportional magnitude; only the whole perception's root is ever
+ *  normalized). */
+function riverFoldRaw(space, row) {
+    if (row.length === 0) {
+        const z = new Float32Array(space.D);
+        return { tree: sema(z, new Uint8Array(0), null), len: 0 };
+    }
+    if (row.length === 1)
+        return row[0];
+    let level = row;
+    while (level.length > 1) {
+        const next = [];
+        foldSlice(space, level, 0, level.length, next, false);
+        if (next.length === level.length) {
+            const forced = [];
+            foldSlice(space, next, 0, next.length, forced, true);
+            level = forced;
+        }
+        else {
+            level = next;
+        }
+    }
+    return level[0];
+}
 /** Plain bytes→tree (identical to capability-less {@link bytesToTree}) that
  *  also RETURNS its pyramid, reusing `prev` — the pyramid of a PROPER
  *  prefix of `bytes` (caller guarantees content match and

package/dist/src/mind/attention.js

@@ -9,7 +9,7 @@
 import { isChunk } from "../sema.js";
 import { lightestDerivation, } from "../derive/src/index.js";
 import { consensusFloor, dominates, estimatorNoise } from "../geometry.js";
-import { foldTree, gistOf, perceive, read } from "./primitives.js";
+import { foldTree, gistOf, latin1Key, perceive, read } from "./primitives.js";
 import { recognise } from "./recognition.js";
 import { leafIdRun } from "./canonical.js";
 import { corpusN, edgeAncestors } from "./traverse.js";
@@ -27,16 +27,20 @@ export async function climbAttention(ctx, query, k, mode = "inverse") {
  *  attention) and the entire ranked list.  Cached via ctx.climbMemo when
  *  ctx.trace is null. */
 export async function climbAttentionAll(ctx, query, k, mode = "inverse") {
+    // Content-keyed memo — works for both single-turn respond() and multi-turn
+    // respondTurn().  Skipped while tracing.
     if (ctx.climbMemo && !ctx.trace) {
-        const key = `${k}:${mode}`;
-        let byRead = ctx.climbMemo.get(query);
-        if (byRead === undefined)
-            ctx.climbMemo.set(query, byRead = new Map());
-        const hit = byRead.get(key);
+        const contentKey = latin1Key(query);
+        const modeKey = `${k}:${mode}`;
+        let byRead = ctx.climbMemo.get(contentKey);
+        if (byRead === undefined) {
+            ctx.climbMemo.set(contentKey, byRead = new Map());
+        }
+        const hit = byRead.get(modeKey);
         if (hit !== undefined)
             return hit;
         const read = await computeAttention(ctx, query, k, mode);
-        byRead.set(key, read);
+        byRead.set(modeKey, read);
         return read;
     }
     return computeAttention(ctx, query, k, mode);

package/dist/src/mind/mechanisms/recall.js

@@ -100,7 +100,17 @@ export async function recallByResonance(ctx, query, pre) {
     // long answer sharing only scaffolding pass; the query-relative fraction
     // measures exactly what the reach bar means: how much of THE QUERY the
     // store accounts for.
-    const fracOfQuery = (cos, otherLen) => Math.min(1, cos * Math.sqrt(otherLen / Math.max(1, query.length)));
+    // Chance similarity survives the length conversion AMPLIFIED: the same
+    // √(lenG/lenQ) factor that converts an honest shared fraction into a
+    // query-relative one multiplies the estimator/chance floor too, so a long
+    // stored form (√(lenG/lenQ) ≈ 10 at 100×) lifted a noise-level cosine past
+    // the reach bar and grounded pure gibberish (observed).  Only the
+    // ABOVE-CHANCE part of the similarity is evidence of shared content —
+    // subtract the significance bar (3/√D, §8.3) before converting.  Derived
+    // from the existing bars; never tuned.
+    const sig = significanceBar(ctx.store.D);
+    const fracOfQuery = (cos, otherLen) => Math.min(1, Math.max(0, cos - sig) *
+        Math.sqrt(otherLen / Math.max(1, query.length)));
     for (const h of whole) {
         const g = await project(ctx, h.id, queryGist);
         if (g) {
@@ -110,20 +120,25 @@ export async function recallByResonance(ctx, query, pre) {
             }
         }
     }
-    // The refusal/echo decision, in the same query-relative units — the top
-    // hit's magnitude read from the store (contentLen: √bytes IS the linear
-    // fold's gist norm), never from re-reading its bytes.
-    // The magnitude read SATURATES at the decision point: frac reaches the
-    // reach bar exactly when lenH = lenQ·(reach/score)², so the walk never
-    // needs to see past that — a huge conversation root costs a capped read,
-    // and a clamped return decides "pass" identically (frac ≥ reach).
+    // The refusal/echo decision.  The echo returns a stored form's bytes AS
+    // the answer — a near-identity claim about the query — and identity-grade
+    // decisions are never made on an estimated score ("approximate scores may
+    // rank and propose; they may never decide", §6.2): the RaBitQ estimate
+    // overshooting the reach bar echoed a WRONG-entity neighbour ("capital of
+    // Zamunda?" echoed the Armenia fact, observed).  The bytes are read
+    // anyway to be echoed, so the decision uses their EXACT fold: one river
+    // fold of the top hit, measured in the same query-relative,
+    // chance-corrected units as the tier above.
     const reach = reachThreshold(ctx.space.maxGroup);
-    const lenCap = Math.ceil(query.length * (reach / Math.max(top.score, 1e-6)) ** 2) + 1;
-    if (fracOfQuery(top.score, ctx.store.contentLen(top.id, lenCap)) < reach) {
+    const topBytes = read(ctx, top.id);
+    const exact = topBytes.length > 0
+        ? cosine(queryGist, gistOf(ctx, topBytes))
+        : 0;
+    if (fracOfQuery(exact, topBytes.length) < reach) {
         return ground(null, "below reach threshold — nothing in the store relates to this query", [], 0);
     }
     // Honest echo.
-    return ground(read(ctx, top.id), "last resort: the nearest resonant form's own bytes (echo, not grounded)", [], 0, true);
+    return ground(topBytes, "last resort: the nearest resonant form's own bytes (echo, not grounded)", [], 0, true);
 }
 // ── Pipeline mechanism ──────────────────────────────────────────────────────
 export const recallMechanism = {

package/dist/src/mind/mind.d.ts

@@ -1,7 +1,7 @@
 import { Vec } from "../vec.js";
 import { Sema, Space } from "../sema.js";
 import { Alphabet } from "../alphabet.js";
-import { Grid } from "../geometry.js";
+import { type FoldPyramid, Grid } from "../geometry.js";
 import { BoundedMap, type Store } from "../store.js";
 import { type MindConfig } from "../config.js";
 import { GraphSearch, type Leaf, type Site } from "./graph-search.js";
@@ -19,6 +19,27 @@ export interface Response {
      *  no answer. */
     provenance?: import("./pipeline.js").Provenance;
 }
+/** Serializable state of a conversation — can be saved and restored across
+ *  sessions.  The Mind never interprets the bytes; it only tracks their
+ *  cumulative lengths so the caller can reconstruct turn boundaries later
+ *  without inspecting content. */
+export interface ConversationState {
+    /** The accumulated context bytes — raw concatenation of every turn's
+     *  bytes in order.  No separator is inserted; the boundary offsets
+     *  ({@link boundaries}) tell the caller where each turn ends. */
+    context: Uint8Array;
+    /** Cumulative byte length after each completed turn.  Sorted, strictly
+     *  increasing, each {@code < context.length}.  The first turn's length
+     *  is `boundaries[0]`; the second turn starts at that offset, and so
+     *  on.  Empty for a single-turn or new conversation. */
+    boundaries: number[];
+}
+/** An active conversation handle.  Opaque — interact through the Mind's
+ *  conversation methods ({@link Mind.beginConversation},
+ *  {@link Mind.respondTurn}, {@link Mind.endConversation}). */
+export interface Conversation {
+    readonly id: number;
+}
 import type { AttentionRead, MindContext, Recognition } from "./types.js";
 export interface MindOptions {
     seed?: number;
@@ -46,16 +67,17 @@ export declare class Mind implements MindContext {
     readonly mechanisms: import("./pipeline-mechanism.js").PipelineMechanism[];
     /** The live rationale tracer for the inference currently in flight, or null. */
     trace: Rationale | null;
-    /** Per-response memo of the consensus climb.  NOTE: this memo and
-     *  {@link recogniseMemo} are BYPASSED while a rationale trace is attached
-     *  (every mechanism must emit its own steps), so a traced respond re-pays
-     *  up to four consensus climbs plus repeat recognitions — that is where the
-     *  traced-vs-untraced latency multiple comes from, by design. */
-    climbMemo: WeakMap<Uint8Array, Map<string, AttentionRead>> | null;
-    /** Per-response memo of recognise() — see {@link MindContext.recogniseMemo}. */
-    recogniseMemo: WeakMap<Uint8Array, Recognition> | null;
-    /** Per-response memo of perceive() — see {@link MindContext.perceiveMemo}. */
+    /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
+    climbMemo: Map<string, Map<string, AttentionRead>> | null;
+    /** Memo of recognise() — content-keyed.  See {@link MindContext.recogniseMemo}. */
+    recogniseMemo: Map<string, Recognition> | null;
+    /** Memo of perceive() — content-keyed.  See {@link MindContext.perceiveMemo}. */
     perceiveMemo: Map<string, import("../sema.js").Sema> | null;
+    /** Subtree-resolution cache.  See {@link MindContext._resolvedSubtrees}. */
+    _resolvedSubtrees: WeakMap<import("../sema.js").Sema, {
+        id: number;
+        len: number;
+    }> | null;
     /** The perceived gist of the query currently being answered.  Set by `think`
      *  before the graph search runs; `chooseNext` consults it as a gate (a null
      *  guide means no query is in flight, so structural walkers keep plain
@@ -72,9 +94,11 @@ export declare class Mind implements MindContext {
      *  {@link MindContext._gistCache}.  32 MB ≈ 8K gists at D=1024; hub
      *  candidate sets (√N at most) fit comfortably and recur across queries. */
     _gistCache: BoundedMap<number, Vec>;
-    _depositTrees: BoundedMap<string, import("../geometry.js").FoldPyramid>;
+    _depositTrees: BoundedMap<string, FoldPyramid>;
     _depositLens: Set<number>;
     _internIds: WeakMap<Sema, number>;
+    private _nextConvId;
+    private _conversations;
     /** Canonical node id of a byte span.  Required by GraphSearchHost & MindContext. */
     resolve(bytes: Uint8Array): number | null;
     recogniseSpan(bytes: Uint8Array): {
@@ -109,12 +133,52 @@ export declare class Mind implements MindContext {
     /** Close one response's transient state — every per-response field, incl.
      *  the edge guide/choices `think` sets mid-flight. */
     private endResponse;
+    /** Shared response core — the one path from bytes to voiced answer.
+     *  `respond` calls this directly; `respondTurn` has its own path
+     *  with conversation-persistent memos and incremental perception. */
+    private _respondImpl;
     respond(input: Input, inspectRationale?: InspectRationale): Promise<Response>;
     /** Text view of {@link respond}.  NUL bytes (0x00) are stripped before
      *  decoding — they are structural padding in text answers.  LOSSY for a
      *  binary answer that legitimately contains NULs: use {@link respond} and
      *  read `bytes` directly for binary/grid modalities. */
     respondText(input: string, inspectRationale?: InspectRationale): Promise<string>;
+    /** Begin a new conversation, optionally restoring from a previously-saved
+     *  {@link ConversationState}.  The returned handle is required for
+     *  {@link respondTurn} and {@link endConversation}.
+     *
+     *  Conversations are independent — a Mind can manage several concurrently.
+     *  Each tracks the fold pyramid (accumulated internal processing) and
+     *  turn-boundary offsets; the geometry never inspects content to guess
+     *  where one turn ends and the next begins. */
+    beginConversation(state?: ConversationState): Conversation;
+    /** End a conversation, releasing its internal resources (accumulated
+     *  context, boundary offsets, and the fold-pyramid cache).  Idempotent. */
+    endConversation(conv: Conversation): void;
+    /** The current serialisable state of an active conversation.  Save this
+     *  to resume the conversation later via {@link beginConversation}. */
+    conversationState(conv: Conversation): ConversationState | null;
+    /** Process one turn of a conversation.
+     *
+     *  `turn` is the raw input for the latest turn — its bytes are appended
+     *  to the accumulated context directly (raw concatenation).  The Mind
+     *  tracks the byte offset where each turn ends; no separator is ever
+     *  inserted or inspected.
+     *
+     *  Returns the response AND the updated {@link ConversationState} so the
+     *  caller can persist it.  The conversation handle's internal state is
+     *  updated in place — the returned state is a snapshot for storage. */
+    respondTurn(conv: Conversation, turn: Input, inspectRationale?: InspectRationale): Promise<{
+        response: Response;
+        state: ConversationState;
+    }>;
+    /** Text view of {@link respondTurn}.  See {@link respondText} for the
+     *  NUL-stripping caveat.  For binary or grid turns use {@link respondTurn}
+     *  directly — this is a text-only convenience, like {@link respondText}. */
+    respondTurnText(conv: Conversation, turn: string, inspectRationale?: InspectRationale): Promise<{
+        response: string;
+        state: ConversationState;
+    }>;
     embedding(input: Input): Promise<Vec | null>;
     /** Kinship note: the vector arm below is a miniature of recall's tier 3
      *  (resonate → reach gate → read out the nearest form's bytes) — the

package/dist/src/mind/mind.js

@@ -10,15 +10,15 @@
 // Implementation split across src/mind/*.ts — this file assembles the Mind class.
 import { makeKeyring, rng, setVecConfig } from "../vec.js";
 import { Alphabet } from "../alphabet.js";
-import { reachThreshold, } from "../geometry.js";
+import { bytesToTreePyramid, reachThreshold, } from "../geometry.js";
 import { BoundedMap } from "../store.js";
 import { SQliteStore } from "../store-sqlite.js";
 import { resolveConfig } from "../config.js";
-import { bytesEqual } from "../bytes.js";
+import { bytesEqual, concat2 } from "../bytes.js";
 import { GraphSearch, } from "./graph-search.js";
 import { Alu } from "../alu/src/index.js";
 import { decodeText, Rationale, } from "./rationale.js";
-import { gistOf, inputBytes, perceive as perceiveImpl, resolve as resolveImpl, } from "./primitives.js";
+import { gistOf, inputBytes, latin1Key, perceive as perceiveImpl, resolve as resolveImpl, } from "./primitives.js";
 import { chooseNext, edgeAncestors as edgeAncestorsFn } from "./traverse.js";
 import { follow } from "./match.js";
 import { recognise, segment } from "./recognition.js";
@@ -42,16 +42,14 @@ export class Mind {
     mechanisms = [];
     /** The live rationale tracer for the inference currently in flight, or null. */
     trace = null;
-    /** Per-response memo of the consensus climb.  NOTE: this memo and
-     *  {@link recogniseMemo} are BYPASSED while a rationale trace is attached
-     *  (every mechanism must emit its own steps), so a traced respond re-pays
-     *  up to four consensus climbs plus repeat recognitions — that is where the
-     *  traced-vs-untraced latency multiple comes from, by design. */
+    /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
     climbMemo = null;
-    /** Per-response memo of recognise() — see {@link MindContext.recogniseMemo}. */
+    /** Memo of recognise() — content-keyed.  See {@link MindContext.recogniseMemo}. */
     recogniseMemo = null;
-    /** Per-response memo of perceive() — see {@link MindContext.perceiveMemo}. */
+    /** Memo of perceive() — content-keyed.  See {@link MindContext.perceiveMemo}. */
     perceiveMemo = null;
+    /** Subtree-resolution cache.  See {@link MindContext._resolvedSubtrees}. */
+    _resolvedSubtrees = null;
     /** The perceived gist of the query currently being answered.  Set by `think`
      *  before the graph search runs; `chooseNext` consults it as a gate (a null
      *  guide means no query is in flight, so structural walkers keep plain
@@ -75,6 +73,9 @@ export class Mind {
     _depositTrees = new BoundedMap(8);
     _depositLens = new Set();
     _internIds = new WeakMap();
+    // ── Conversation state ──────────────────────────────────────────────────
+    _nextConvId = 1;
+    _conversations = new Map();
     // ── GraphSearchHost implementation ─────────────────────────────────────
     /** Canonical node id of a byte span.  Required by GraphSearchHost & MindContext. */
     resolve(bytes) {
@@ -167,8 +168,8 @@ export class Mind {
      *  created, so adding a memo cannot forget its reset. */
     beginResponse(inspectRationale) {
         this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
-        this.climbMemo = new WeakMap();
-        this.recogniseMemo = new WeakMap();
+        this.climbMemo = new Map();
+        this.recogniseMemo = new Map();
         this.perceiveMemo = new Map();
     }
     /** Close one response's transient state — every per-response field, incl.
@@ -181,19 +182,21 @@ export class Mind {
         this._edgeGuide = null;
         this._edgeChoice.clear();
     }
-    async respond(input, inspectRationale) {
+    /** Shared response core — the one path from bytes to voiced answer.
+     *  `respond` calls this directly; `respondTurn` has its own path
+     *  with conversation-persistent memos and incremental perception. */
+    async _respondImpl(queryBytes, inspectRationale, traceLabel = "respond") {
         this.beginResponse(inspectRationale);
         try {
-            const inBytes = inputBytes(this, input);
-            const top = this.trace?.enter("respond", [
-                rItem(inBytes, "query"),
+            const top = this.trace?.enter(traceLabel, [
+                rItem(queryBytes, "query"),
             ]);
-            const thought = await think(this, inBytes, this.mechanisms);
+            const thought = await think(this, queryBytes, this.mechanisms);
             if (thought === null) {
                 top?.done([], "nothing to perceive or an empty store — no answer");
                 return { v: null, bytes: new Uint8Array(0) };
             }
-            const voiced = await articulate(this, thought.bytes, inBytes);
+            const voiced = await articulate(this, thought.bytes, queryBytes);
             top?.done([rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)], "the answer, re-voiced in the asker's words");
             return {
                 v: gistOf(this, voiced),
@@ -205,6 +208,9 @@ export class Mind {
             this.endResponse();
         }
     }
+    async respond(input, inspectRationale) {
+        return this._respondImpl(inputBytes(this, input), inspectRationale);
+    }
     /** Text view of {@link respond}.  NUL bytes (0x00) are stripped before
      *  decoding — they are structural padding in text answers.  LOSSY for a
      *  binary answer that legitimately contains NULs: use {@link respond} and
@@ -213,6 +219,133 @@ export class Mind {
         const r = await this.respond(input, inspectRationale);
         return decodeText(r.bytes);
     }
+    // ── Conversation API ────────────────────────────────────────────────────
+    /** Begin a new conversation, optionally restoring from a previously-saved
+     *  {@link ConversationState}.  The returned handle is required for
+     *  {@link respondTurn} and {@link endConversation}.
+     *
+     *  Conversations are independent — a Mind can manage several concurrently.
+     *  Each tracks the fold pyramid (accumulated internal processing) and
+     *  turn-boundary offsets; the geometry never inspects content to guess
+     *  where one turn ends and the next begins. */
+    beginConversation(state) {
+        const id = this._nextConvId++;
+        // Build the initial pyramid: from scratch for a new conversation,
+        // or from the saved context bytes when restoring.
+        const initBytes = state?.context ?? new Uint8Array(0);
+        const { pyramid } = bytesToTreePyramid(this.space, this.alphabet, initBytes);
+        this._conversations.set(id, {
+            pyramid,
+            bytes: initBytes,
+            boundaries: state?.boundaries ? [...state.boundaries] : [],
+            perceiveMemo: new Map(),
+            recogniseMemo: new Map(),
+            climbMemo: new Map(),
+            resolvedSubtrees: new WeakMap(),
+        });
+        return { id };
+    }
+    /** End a conversation, releasing its internal resources (accumulated
+     *  context, boundary offsets, and the fold-pyramid cache).  Idempotent. */
+    endConversation(conv) {
+        this._conversations.delete(conv.id);
+    }
+    /** The current serialisable state of an active conversation.  Save this
+     *  to resume the conversation later via {@link beginConversation}. */
+    conversationState(conv) {
+        const data = this._conversations.get(conv.id);
+        if (!data)
+            return null;
+        return {
+            context: data.bytes,
+            boundaries: [...data.boundaries],
+        };
+    }
+    /** Process one turn of a conversation.
+     *
+     *  `turn` is the raw input for the latest turn — its bytes are appended
+     *  to the accumulated context directly (raw concatenation).  The Mind
+     *  tracks the byte offset where each turn ends; no separator is ever
+     *  inserted or inspected.
+     *
+     *  Returns the response AND the updated {@link ConversationState} so the
+     *  caller can persist it.  The conversation handle's internal state is
+     *  updated in place — the returned state is a snapshot for storage. */
+    async respondTurn(conv, turn, inspectRationale) {
+        const data = this._conversations.get(conv.id);
+        if (!data)
+            throw new Error(`Conversation ${conv.id} not found`);
+        const turnBytes = inputBytes(this, turn);
+        const prevLen = data.pyramid.bytes;
+        const prevBytes = data.bytes;
+        const newContext = prevLen > 0 ? concat2(prevBytes, turnBytes) : turnBytes;
+        data.bytes = newContext;
+        if (prevLen > 0)
+            data.boundaries.push(prevLen);
+        // Incremental perception — O(turn) instead of O(context).
+        const { tree, pyramid } = bytesToTreePyramid(this.space, this.alphabet, newContext, data.pyramid);
+        data.pyramid = pyramid;
+        // Swap in the conversation's persistent state so the inference
+        // pipeline does not re-process the prefix from scratch.
+        //   perceiveMemo / recogniseMemo / climbMemo — content-keyed;
+        //     the prefix's results from the previous turn are found by
+        //     the current turn's sub-span calls.
+        //   _resolvedSubtrees — Sema-node-keyed; when the pyramid reuses
+        //     prefix subtrees (identical objects), foldTree returns their
+        //     ids immediately — O(suffix) instead of O(context).
+        this.perceiveMemo = data.perceiveMemo;
+        this.recogniseMemo = data.recogniseMemo;
+        this.climbMemo = data.climbMemo;
+        this._resolvedSubtrees = data.resolvedSubtrees;
+        this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
+        try {
+            this.perceiveMemo.set(latin1Key(newContext), tree);
+            const top = this.trace?.enter("respondTurn", [
+                rItem(newContext, "query"),
+            ]);
+            const thought = await think(this, newContext, this.mechanisms);
+            if (thought === null) {
+                top?.done([], "nothing to perceive or an empty store — no answer");
+                return {
+                    response: { v: null, bytes: new Uint8Array(0) },
+                    state: this.conversationState(conv),
+                };
+            }
+            const voiced = await articulate(this, thought.bytes, newContext);
+            top?.done([rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)], "the answer, re-voiced in the asker's words");
+            return {
+                response: {
+                    v: gistOf(this, voiced),
+                    bytes: voiced,
+                    provenance: thought.provenance,
+                },
+                state: this.conversationState(conv),
+            };
+        }
+        finally {
+            // Save back to the conversation for the next turn.
+            data.perceiveMemo = this.perceiveMemo;
+            data.recogniseMemo = this.recogniseMemo;
+            data.climbMemo = this.climbMemo;
+            data.resolvedSubtrees = this._resolvedSubtrees;
+            // Clear Mind references — non-conversation respond() calls get
+            // fresh per-response memos.
+            this.trace = null;
+            this.perceiveMemo = null;
+            this.recogniseMemo = null;
+            this.climbMemo = null;
+            this._resolvedSubtrees = null;
+            this._edgeGuide = null;
+            this._edgeChoice.clear();
+        }
+    }
+    /** Text view of {@link respondTurn}.  See {@link respondText} for the
+     *  NUL-stripping caveat.  For binary or grid turns use {@link respondTurn}
+     *  directly — this is a text-only convenience, like {@link respondText}. */
+    async respondTurnText(conv, turn, inspectRationale) {
+        const { response, state } = await this.respondTurn(conv, turn, inspectRationale);
+        return { response: decodeText(response.bytes), state };
+    }
     async embedding(input) {
         return (await this.respond(input)).v;
     }

package/dist/src/mind/primitives.d.ts

@@ -1,9 +1,20 @@
 import { Vec } from "../vec.js";
 import { Sema } from "../sema.js";
 import type { Input, MindContext } from "./types.js";
+/** The content key of a byte span — one latin1 char per byte, an exact,
+ *  collision-free encoding.  Spans on the perception path are query-scale
+ *  (windows, regions, candidate spans), so key construction is far cheaper
+ *  than the river fold it deduplicates. */
+export declare function latin1Key(bytes: Uint8Array): string;
 /** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree. */
-export declare function perceive(ctx: MindContext, input: Input, leafAt?: (i: number) => number | null, lookup?: (ids: number[]) => number | null): Sema;
+ *  Deterministic — identical bytes always produce an identical tree.
+ *
+ *  `boundaries` is an optional sorted list of proper byte offsets where the
+ *  fold must split so that each prefix segment folds identically to how it
+ *  folded when it was learned (§10.3 stable-prefix contract).  Only the
+ *  CALLER — who assembled the multi-turn context — knows where those
+ *  boundaries are; the geometry never guesses them from the bytes. */
+export declare function perceive(ctx: MindContext, input: Input, leafAt?: (i: number) => number | null, lookup?: (ids: number[]) => number | null, boundaries?: readonly number[]): Sema;
 /** The DEPOSIT-shaped perceive: the PLAIN fold (bit-identical to inference
  *  perception — that structural train/inference agreement is load-bearing
  *  for exact recall), computed INCREMENTALLY via the fold's level pyramid