@sema-ai/core 1.275.1

package/dist/core/memory.js

@@ -0,0 +1,881 @@
+import { Type } from "typebox";
+import { uuidv7 } from "../internal/harness.js";
+import { defineTool } from "./tools.js";
+import { parseScopeKey } from "./memory-engine/scope-contract.js";
+import { sanitizeUntrustedText } from "./untrusted-text.js";
+/**
+ * True when a store implements the full id-addressable trio required for memory consolidation
+ * (design/41): {@link MemoryStore.searchScored}/{@link MemoryStore.update}/{@link MemoryStore.delete}.
+ * When false, the Runner skips consolidation entirely (graceful no-op).
+ */
+export function supportsConsolidation(store) {
+    return (typeof store.searchScored === "function" &&
+        typeof store.update === "function" &&
+        typeof store.delete === "function");
+}
+/**
+ * True when a store implements the design/84 Seam B cursor PAIR
+ * ({@link MemoryStore.getConsolidationCursor}/{@link MemoryStore.setConsolidationCursor}). Periodic/incremental
+ * consolidation ({@link import("./consolidate-scope.js").consolidateScope}) GATES on this: a store missing
+ * either method makes a periodic pass a safe **NO-OP** (never a silent full re-consolidation of the whole
+ * scope, which would re-merge already-consolidated notes forever). Both-or-neither — a store implementing
+ * only one is treated as unsupported. Independent of {@link supportsConsolidation} (the id-addressable trio),
+ * which a periodic pass ALSO needs to actually mutate.
+ */
+export function supportsPeriodicConsolidation(store) {
+    return (typeof store.getConsolidationCursor === "function" &&
+        typeof store.setConsolidationCursor === "function");
+}
+// ============================================================================
+// design/77 §2 — Gate 2: promotable-write utilityVerdict chokepoint
+// ============================================================================
+//
+// A STORE-BOUNDARY, fail-closed gate. A "promotable" memory write (a self-evolution artifact — a
+// skill/playbook/outcome-stats blob, classified by NOTE STRUCTURE, *not* a caller flag) REQUIRES a
+// present-and-positive `utilityVerdict`, else fail-closed — regardless of which tool emitted it. This
+// prevents ungated self-evolution writes: a deployment that forgets the profile promotion gate still
+// cannot silently durably-write a promotable artifact (the chokepoint sits at the store, downstream of
+// every inlet — the `remember` tool AND consolidation ADD).
+//
+// CONSTITUTIONAL SPLIT (design/76 §0 ①②): core enforces the gate's *presence* (a promotable write with
+// no verdict throws); the *threshold/taxonomy* stays in the PROFILE — `utilityVerdict`/`outcomeStats`
+// are opaque `unknown` here, and the definition of "positive" is a profile-injected `utilityGate`. With
+// the gate UNWIRED, a promotable note still fails closed (absent gate NEVER auto-passes).
+/** The closed set of caller-authored note types (design/65 {@link MemoryNoteType}, memory.ts). A note
+ *  whose `type` is in this set is caller-authored; a `type` *outside* it (e.g. `"skill"`) is promotable.
+ *  Exported so a caller-authored inlet (e.g. consolidation ADD) can NORMALIZE a model-suggested type to
+ *  the closed set before the store boundary — a legitimate caller_authored write must never trip the
+ *  promotable gate just because the model invented a non-standard `type` slug (MINOR-3). */
+export const CALLER_AUTHORED_TYPES = new Set(["user", "feedback", "project", "reference"]);
+/** The default caller-authored note type (matches {@link StructuredNoteInput.type}'s documented default). */
+export const DEFAULT_CALLER_AUTHORED_TYPE = "project";
+/** Typed, fail-closed error thrown when a promotable artifact write reaches the store boundary without a
+ *  present-and-positive `utilityVerdict` (design/77 §2). The `code` is stable for callers to switch on;
+ *  the write NEVER reaches the backend. */
+export class MemoryGateError extends Error {
+    code;
+    constructor(code, detail) {
+        // Prefix the stable code into the message so it survives `String(err.message)` sinks (e.g. the
+        // consolidation `onWarn` channel, which logs the message, not the typed `.code`).
+        super(detail ? `${code}: ${detail}` : code);
+        this.name = "MemoryGateError";
+        this.code = code;
+    }
+}
+/** True when `note` carries a structural self-evolution marker (skill/playbook/outcome-stats) — design/77
+ *  §2. This is what lets the marker WIN over a caller-authored `type` (e.g. `type:"reference"` WITH an
+ *  `outcomeStats` blob is promotable). Kept taxonomy-free: core only checks PRESENCE, never shape. */
+function hasPromotableMarker(note) {
+    return note.outcomeStats !== undefined;
+}
+/**
+ * Conservative high-confidence credential patterns (CC-parity P0-2). Each is provider-prefixed or a
+ * structurally unmistakable PEM header, so a match is almost certainly a real secret — chosen to MINIMIZE
+ * false-positives (a wrongly-rejected normal note is the head risk). No generic `key=value` /
+ * `password: …` rule (those flood on ordinary prose). Word-boundary-anchored where a prefix could appear
+ * mid-word. NOT exported as values (a consumer could regex-DoS or fingerprint the list); the public
+ * surface is {@link detectSecret} only.
+ */
+const SECRET_PATTERNS = [
+    // AWS access key id — literal "AKIA" + 16 uppercase-alnum. (Also covers ABIA/ACCA/ASIA variants is NOT
+    // done on purpose: AKIA is the long-lived-key prefix and the highest-confidence, lowest-FP shape.)
+    { label: "aws_access_key_id", re: /\bAKIA[0-9A-Z]{16}\b/ },
+    // GitHub personal-access / fine-grained / OAuth / app / refresh tokens — all share the `gh*_`/`github_pat_`
+    // prefix followed by a long base62 body. The prefixes are GitHub-reserved, so FP risk is ~nil.
+    { label: "github_token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/ },
+    { label: "github_fine_grained_pat", re: /\bgithub_pat_[A-Za-z0-9_]{60,}\b/ },
+    // OpenAI / Anthropic-style `sk-…` keys. The key body is a LONG CONTINUOUS base62 run (no hyphen) — the
+    // `sk-`/`sk-proj-`/`sk-ant-`/`sk-ant-api03-` prefixes are matched explicitly, then ≥20 alnum/underscore
+    // chars. Hyphen is DELIBERATELY excluded from the body: it let a dash-joined word slug
+    // (`task-sk-orchestrator-helper-utility`, `prod-sk-compute-cluster-east-1a`) match mid-string and flood
+    // fail-closed rejections on ordinary prose — the head FP risk. Real keys have no hyphen in the body.
+    { label: "openai_api_key", re: /\bsk-(?:ant-(?:api03-)?|proj-)?[A-Za-z0-9_]{20,}\b/ },
+    // Stripe secret / restricted keys — `sk_live_`/`sk_test_`/`rk_live_`/`rk_test_` then a LONG base62 body.
+    // These use an UNDERSCORE (not the OpenAI hyphen), and the `live`/`test` ENV QUALIFIER is what makes the
+    // prefix Stripe-distinctive + low-FP: requiring the literal `live_`/`test_` qualifier means an ordinary
+    // identifier like `sk_compute`/`sk_handler` (no env qualifier, short body) does NOT match — so the head
+    // FP risk (a word slug mid-string) is avoided while real Stripe keys (≥24-char body) are caught.
+    { label: "stripe_secret_key", re: /\b[sr]k_(?:live|test)_[A-Za-z0-9]{24,}\b/ },
+    // Slack tokens — `xox[baprs]-` prefix then 1-3 short dash-separated id fields and a LONG (≥16-char)
+    // alnum secret body as the final field. Requiring the long terminal run rejects dash-joined word slugs
+    // (`xoxb-archive-channel-for-old-stuff`, `xoxr-style-guide-v2`) that the old free `[A-Za-z0-9-]{10,}`
+    // body flagged as the head FP risk, while still matching real bot/user/app tokens.
+    { label: "slack_token", re: /\bxox[baprs]-(?:[A-Za-z0-9]+-){1,3}[A-Za-z0-9]{16,}\b/ },
+    // Google API key — `AIza` + 35 url-safe chars (Google-reserved prefix).
+    { label: "google_api_key", re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    // PEM private-key header — RSA/EC/DSA/OPENSSH/PGP/plain. The "-----BEGIN … PRIVATE KEY[ BLOCK]-----" banner
+    // is unmistakable and never legitimately appears in a durable declarative fact. The optional " BLOCK" suffix
+    // covers PGP's "-----BEGIN PGP PRIVATE KEY BLOCK-----" form (effect-test 1a caught this as a real MISS —
+    // private key could otherwise bypass the write-gate into durable memory).
+    { label: "private_key", re: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/ },
+];
+/**
+ * Scan `text` for a high-confidence credential (CC-parity P0-2). Returns the matched pattern's stable
+ * `label` (NEVER the matched secret value — labels are safe to log/surface), or `null` when clean.
+ * Deliberately CONSERVATIVE: only provider-prefixed keys + PEM private-key headers match, so ordinary
+ * prose that merely mentions tokens/keys/passwords passes through untouched (false-positives are the head
+ * risk — a wrongly-rejected normal note silently breaks legitimate memory).
+ */
+export function detectSecret(text) {
+    if (!text)
+        return null;
+    for (const p of SECRET_PATTERNS) {
+        if (p.re.test(text))
+            return p.label;
+    }
+    return null;
+}
+/**
+ * Store-boundary secret-scan invariant (CC-parity P0-2). Fail-closed: if `body` carries a high-confidence
+ * credential, throw {@link MemoryGateError}`("memory.secret_detected")` — the write NEVER reaches the
+ * backend. The error detail names the pattern LABEL (e.g. `aws_access_key_id`), never the matched value,
+ * so the secret is not re-leaked into a log/error sink. A clean body is a no-op. Applied by
+ * {@link guardedMemoryStore} on EVERY durable write inlet (`append`, `appendStructured`, the
+ * `appendPromotable` door) so both the `remember` tool and consolidation ADD are covered at one chokepoint.
+ */
+export function enforceSecretWriteGate(body) {
+    const label = detectSecret(body);
+    if (label !== null) {
+        throw new MemoryGateError("memory.secret_detected", `memory write blocked: detected ${label}`);
+    }
+}
+/**
+ * Structured-note secret-scan invariant (CC-parity P0-2). Scans EVERY text field of a {@link StructuredNoteInput}
+ * that becomes DURABLE and/or enters the manifest — not just `body`. The body alone is insufficient: `name`
+ * (rendered as `[[name]]` cross-references) and `description` (rendered into the recall manifest + injected
+ * into the side-query sub-prompt) are ALSO persisted and surfaced, so a secret hidden there
+ * (`appendStructured({ body: "safe", description: "sk_live_…" })`) would otherwise be durably stored and
+ * leaked into every later same-scope manifest — a real bypass of the body-only scan. `links` slugs are NOT
+ * scanned: they are short `[[name]]`-style reference tokens (no credential body shape clears the
+ * conservative detector), and scanning them adds FP surface for no realistic gain. Fail-closed: the first
+ * field that carries a high-confidence credential throws {@link MemoryGateError}`("memory.secret_detected")`.
+ */
+export function enforceStructuredNoteSecretGate(note) {
+    // Scan EVERY field that lands in the durable store AND/OR the rendered manifest: body, name,
+    // description, AND type (a free-form string when unknown — re-review residual-bypass fix). `links` are
+    // deliberately NOT scanned: short `[[name]]` ref tokens with no credential-body shape; the conservative
+    // detector never fires on them and scanning only adds false-positive surface for no gain.
+    enforceSecretWriteGate(note.body);
+    if (note.name !== undefined)
+        enforceSecretWriteGate(note.name);
+    if (note.description !== undefined)
+        enforceSecretWriteGate(note.description);
+    if (note.type !== undefined)
+        enforceSecretWriteGate(note.type);
+}
+/**
+ * Classify a structured-note write as `caller_authored` (normal memory — ungated) or `promotable` (a
+ * self-evolution artifact — gated) — design/77 §2. PURE, taxonomy-free CORE logic.
+ *
+ * `promotable` iff the note's `type` is defined AND outside the caller-authored closed set, OR the note
+ * carries a structural promotable marker. **The structural marker WINS over the closed-set type** — a
+ * `type:"reference"` note WITH an `outcomeStats` marker classifies `promotable`.
+ */
+export function classifyPromotable(note) {
+    if (hasPromotableMarker(note))
+        return "promotable"; // structural marker wins over closed-set type
+    if (note.type !== undefined && !CALLER_AUTHORED_TYPES.has(note.type))
+        return "promotable";
+    return "caller_authored";
+}
+/**
+ * The store-boundary Gate-2 check (design/77 §2). For a `promotable` note, require a present-and-positive
+ * `utilityVerdict`; otherwise throw {@link MemoryGateError}`("memory.promotable_ungated")` fail-closed —
+ * the write NEVER reaches the backend. A `caller_authored` note is unchanged (no verdict needed).
+ *
+ * **Gate-presence invariant (CRITICAL):** "positive" is decided by the profile `utilityGate`. When the
+ * gate is UNWIRED, a promotable note STILL fails closed (an absent gate never auto-passes). When wired,
+ * the verdict must be present (`!== undefined`) and the gate must accept its `outcomeStats`.
+ */
+export function enforcePromotableWriteGate(note, utilityVerdict, utilityGate) {
+    if (classifyPromotable(note) === "caller_authored")
+        return; // normal memory: unchanged, ungated
+    // Promotable artifact: a verdict MUST be present AND judged positive by the (profile) gate.
+    if (utilityVerdict === undefined) {
+        throw new MemoryGateError("memory.promotable_ungated", "promotable memory write requires a utilityVerdict");
+    }
+    if (utilityGate === undefined) {
+        // Gate-presence invariant: with the profile gate unwired, a present verdict cannot be judged →
+        // fail-closed (the gate is ABSENT, never an implicit pass).
+        throw new MemoryGateError("memory.promotable_ungated", "promotable memory write but profile utilityGate is unwired");
+    }
+    if (!utilityGate(note.outcomeStats)) {
+        throw new MemoryGateError("memory.promotable_ungated", "promotable memory write failed the profile utilityGate");
+    }
+}
+/** Return a copy of `note` with any caller-supplied `consolidationGenerated` removed (design/84 Seam B
+ *  boundary defense, council DESIGN-4). The public `appendStructured` inlet uses this so an EXTERNAL caller
+ *  can never mark a note "consolidation-generated" (which would silently exile it from periodic
+ *  consolidation forever). When the field is absent the original object is returned unchanged (no churn). */
+function stripConsolidationGenerated(note) {
+    if (note.consolidationGenerated === undefined)
+        return note;
+    const { consolidationGenerated: _drop, ...rest } = note;
+    return rest;
+}
+/**
+ * Wrap a {@link MemoryStore} so EVERY durable write path runs the Gate-2 chokepoint (design/77 §2). One
+ * wrapper at the store boundary covers BOTH inlets (the `remember` tool and consolidation ADD) — no
+ * per-inlet edits. It intercepts BOTH write methods (§2 polish):
+ *  - `appendStructured` — classify the structured note; a `promotable` one needs a present+positive verdict.
+ *    Since `appendStructured` carries NO verdict, a promotable structured write is ALWAYS rejected here;
+ *    the legitimate way to land one is {@link MemoryStore.appendPromotable} (which carries the verdict).
+ *  - `append` — the legacy/typeless fallback CANNOT carry structure, so any append-path write is
+ *    classified `caller_authored` and passes through unchanged (documents the chokepoint's exhaustiveness
+ *    across store methods — a promotable artifact structurally cannot flow out of this path).
+ *
+ * `appendPromotable` is the gated legitimate door: it runs the gate WITH the supplied verdict, then (on
+ * pass) writes via the inner store's `appendStructured` (or `append` fallback). The id-addressed `update`
+ * (consolidation's UPDATE op) replaces a note's text with new model-generated content, so it is ALSO
+ * secret-scanned (a promotable artifact structurally cannot flow out of it — only existing-note text is
+ * rewritten). `delete` and the read/search/manifest surface are straight pass-throughs (they carry no new
+ * content and never WRITE a promotable artifact).
+ */
+export function guardedMemoryStore(inner, utilityGate) {
+    const guarded = {
+        // ---- reads & lifecycle: straight pass-through ----
+        get vectorMode() {
+            return inner.vectorMode; // forward the Slice-5 rung observable (design/81)
+        },
+        read: (scope) => inner.read(scope),
+        clear: (scope) => inner.clear(scope),
+        // ---- legacy/typeless append: structurally caller-authored, but still secret-scanned (P0-2) ----
+        append: (scope, note) => {
+            enforceSecretWriteGate(note); // CC-parity P0-2: fail-closed on a high-confidence credential
+            return inner.append(scope, note);
+        },
+        // ---- the chokepoint: a structured write with NO verdict ----
+        appendStructured: inner.appendStructured
+            ? (scope, note) => {
+                // CC-parity P0-2: scan ALL durable+manifest fields (body, name, description), not just the body —
+                // a secret in `description`/`name` would otherwise persist + leak into every later manifest.
+                enforceStructuredNoteSecretGate(note);
+                // No verdict travels with appendStructured → a caller_authored note passes, a promotable one
+                // (free-form type or outcomeStats marker) fails closed before reaching the backend.
+                enforcePromotableWriteGate(note, undefined, utilityGate);
+                // design/84 Seam B boundary defense (council DESIGN-4): the public appendStructured is the EXTERNAL
+                // inlet (the `remember` tool, a caller). It must NEVER honor a caller-supplied
+                // `consolidationGenerated` — that flag silently EXILES a note from periodic consolidation forever, so
+                // a misconfigured/hostile caller setting it would permanently break consolidation for that note.
+                // STRIP it here; the ONLY legitimate inlet is `appendConsolidationGenerated` below (consolidation-only).
+                return inner.appendStructured(scope, stripConsolidationGenerated(note));
+            }
+            : undefined,
+        // ---- INTERNAL consolidation-only door: the ONE inlet allowed to SET the Seam B marker ----
+        appendConsolidationGenerated: inner.appendStructured
+            ? (scope, note) => {
+                // Same write-boundary hygiene as appendStructured (secret-scan + promotable gate) — consolidation
+                // ADDs are caller_authored by construction (memory-consolidation.ts normalizes a non-closed-set
+                // type), so the promotable gate passes; the secret scan still applies.
+                enforceStructuredNoteSecretGate(note);
+                enforcePromotableWriteGate(note, undefined, utilityGate);
+                // FORCE the marker on (this is the legitimate consolidation-generated inlet, the counterpart to the
+                // strip above). Ignore whatever the note carried and set it true.
+                const withMarker = { ...note, consolidationGenerated: true };
+                // DOUBLE-WRAP marker transit (codex BLOCKER): when `inner` is ITSELF a guarded store (e.g.
+                // FileStorageBackend already wraps its FileMemoryStore in guardedMemoryStore, then the Runner wraps
+                // THAT again), routing the marker through the inner's PUBLIC `appendStructured` would hit its
+                // boundary-defense `stripConsolidationGenerated` and DROP the marker before it reaches the backing
+                // store → the note is never excluded from future passes → infinite re-merge. So PREFER the inner's
+                // INTERNAL consolidation door (`appendConsolidationGenerated`) when present: that is the counterpart
+                // that FORCES the marker on, so the marker survives every guard layer down to the backing store.
+                // Fall back to the inner's `appendStructured` (with the marker set) ONLY for a RAW (un-guarded)
+                // inner store, which honors the marker directly (no strip). DESIGN-4 is preserved: this internal
+                // door is never reachable by an external caller — the `remember` tool / a caller go through the
+                // PUBLIC `appendStructured`, whose strip is untouched; only `runMemoryConsolidation` calls this.
+                if (inner.appendConsolidationGenerated)
+                    return inner.appendConsolidationGenerated(scope, withMarker);
+                return inner.appendStructured(scope, withMarker);
+            }
+            : undefined,
+        // ---- the legitimate door: promotable write WITH a verdict ----
+        appendPromotable: (scope, note, utilityVerdict) => {
+            // CC-parity P0-2: even a verdict-bearing artifact may not carry a secret — and the scan covers
+            // name/description too (they enter the durable store + manifest), not just the body.
+            enforceStructuredNoteSecretGate(note);
+            enforcePromotableWriteGate(note, utilityVerdict, utilityGate); // gate WITH the supplied verdict
+            // On pass, persist as a structured note (verdict/outcomeStats are profile-side; core stores the body).
+            if (inner.appendPromotable)
+                return inner.appendPromotable(scope, note, utilityVerdict);
+            if (inner.appendStructured)
+                return inner.appendStructured(scope, note);
+            return inner.append(scope, note.body);
+        },
+    };
+    // Forward the optional consolidation/recall surface so a wrapped store stays a drop-in (these are reads
+    // or id-addressed mutations of EXISTING notes — none can introduce a new promotable artifact).
+    if (inner.search)
+        guarded.search = (scope, query, limit) => inner.search(scope, query, limit);
+    if (inner.searchScored)
+        guarded.searchScored = (scope, query, limit) => inner.searchScored(scope, query, limit);
+    if (inner.update)
+        guarded.update = (scope, id, text) => {
+            // CC-parity P0-2: UPDATE replaces a note's stored text with NEW content (consolidation's UPDATE op
+            // writes MODEL-GENERATED text), so it is a durable write path and MUST be scanned — otherwise a
+            // secret could be laundered past the gate by phrasing it as an edit of an existing note.
+            enforceSecretWriteGate(text);
+            return inner.update(scope, id, text);
+        };
+    // `delete` carries no new content (id-addressed removal) → no scan needed.
+    if (inner.delete)
+        guarded.delete = (scope, id) => inner.delete(scope, id);
+    if (inner.listStructuredNotes)
+        guarded.listStructuredNotes = (scope) => inner.listStructuredNotes(scope);
+    if (inner.getByIds)
+        guarded.getByIds = (scope, ids) => inner.getByIds(scope, ids);
+    // design/84 Seam B cursor pair: opaque ordering markers carry no new content (no promotable artifact, no
+    // secret to scan) → straight pass-throughs. Forwarding them keeps `supportsPeriodicConsolidation` true on
+    // a wrapped store (else wrapping would silently disable periodic consolidation).
+    if (inner.getConsolidationCursor)
+        guarded.getConsolidationCursor = (scope) => inner.getConsolidationCursor(scope);
+    if (inner.setConsolidationCursor)
+        guarded.setConsolidationCursor = (scope, cursor) => inner.setConsolidationCursor(scope, cursor);
+    return guarded;
+}
+/** Render a stored entry as the timestamped bullet used in `read`/`search` output. */
+function renderBullet(e) {
+    return `- (${e.ts} UTC) ${e.text}`;
+}
+/** Lower-cased alphanumeric term set of a string (for the lexical distance stand-in). */
+function termSet(s) {
+    return new Set(s
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean));
+}
+/**
+ * Default in-memory MemoryStore (lost on restart). Use a durable backend in production.
+ *
+ * Id-addressable (design/41): each note gets a UUID stable across `update` and never reused after
+ * `delete`, so {@link searchScored}/{@link update}/{@link delete} work and memory consolidation can run.
+ * It has no embeddings, so `searchScored` returns a **lexical** (Jaccard) distance as a stand-in for a
+ * real cosine distance — fine for dev/tests, but a production store should back this with vectors.
+ */
+export class InMemoryMemoryStore {
+    byScope = new Map();
+    /** design/84 Seam B: per-scope periodic-consolidation cursor (lost on restart, like the rest of this store). */
+    cursorByScope = new Map();
+    /** design/81 Slice 5: the in-memory store has no embedder — always the lexical floor. */
+    vectorMode = "lexical";
+    read(scope) {
+        const entries = this.byScope.get(scope);
+        if (!entries || entries.length === 0) {
+            return null;
+        }
+        return entries.map(renderBullet).join("\n");
+    }
+    append(scope, note) {
+        const text = note.trim().replace(/^#+\s*/, ""); // strip a leading "# " quick-add marker
+        if (!text) {
+            return;
+        }
+        const ts = new Date().toISOString().replace("T", " ").slice(0, 16);
+        const entry = { id: uuidv7(), text, ts };
+        const arr = this.byScope.get(scope) ?? [];
+        arr.push(entry);
+        this.byScope.set(scope, arr);
+        return entry.id;
+    }
+    appendStructured(scope, note) {
+        const body = note.body.trim().replace(/^#+\s*/, "");
+        if (!body)
+            return ""; // nothing to store; caller treats "" like a no-op (mirrors append's empty guard)
+        const ts = new Date().toISOString().replace("T", " ").slice(0, 16);
+        const entry = {
+            id: uuidv7(),
+            text: body,
+            ts,
+            name: note.name,
+            type: note.type ?? "project", // default type (design/65 §2.1)
+            description: note.description?.trim() || firstSentence(body), // derived at write time (§8#6)
+            links: note.links,
+            ...(note.consolidationGenerated ? { consolidationGenerated: true } : {}), // design/84 Seam B marker
+        };
+        const arr = this.byScope.get(scope) ?? [];
+        arr.push(entry);
+        this.byScope.set(scope, arr);
+        return entry.id;
+    }
+    clear(scope) {
+        this.byScope.delete(scope);
+        this.cursorByScope.delete(scope); // design/84 Seam B: a cleared scope is logically fresh — reset its cursor
+    }
+    /**
+     * Keyword search backing the `recall` tool. design/81 Slice 2b — uses the SHARED synonym/stem-aware
+     * {@link lexicalSearchMatch} (the SAME matcher as {@link import("../stores/file/memory-store.js").FileMemoryStore.search}),
+     * so the `recall` tool returns IDENTICAL results across the InMemory and File backends. With no synonym/stem
+     * hit it degrades to the plain substring filter (byte-identical to the pre-Slice-2b behavior).
+     */
+    search(scope, query, limit = 10) {
+        const entries = this.byScope.get(scope);
+        if (!entries || entries.length === 0) {
+            return [];
+        }
+        return entries
+            .map(renderBullet)
+            .filter((b) => lexicalSearchMatch(query, b))
+            .slice(-limit);
+    }
+    /**
+     * Lexical-distance retrieval (consolidation candidate source). Distance = `1 - Jaccard(terms)` so it
+     * lives in [0, 1] ⊂ the [0, 2] cosine-distance contract (0 = identical term set). Returns the top
+     * `limit` nearest entries (excludes zero-overlap ones). Deterministic — handy for tests.
+     */
+    searchScored(scope, query, limit = 20) {
+        const entries = this.byScope.get(scope);
+        if (!entries || entries.length === 0) {
+            return [];
+        }
+        const q = termSet(query);
+        if (q.size === 0) {
+            return [];
+        }
+        const scored = [];
+        for (const e of entries) {
+            const t = termSet(e.text);
+            let inter = 0;
+            for (const term of q) {
+                if (t.has(term))
+                    inter++;
+            }
+            const union = q.size + t.size - inter;
+            const jaccard = union === 0 ? 0 : inter / union;
+            if (jaccard === 0)
+                continue; // no lexical overlap → not a candidate
+            scored.push({ id: e.id, text: e.text, score: 1 - jaccard, ...(e.consolidationGenerated ? { consolidationGenerated: true } : {}) });
+        }
+        scored.sort((a, b) => a.score - b.score);
+        return scored.slice(0, limit);
+    }
+    update(scope, id, text) {
+        const clean = text.trim();
+        if (!clean) {
+            return;
+        }
+        const entry = this.byScope.get(scope)?.find((e) => e.id === id);
+        if (!entry) {
+            return; // unknown id → no-op (the caller already guards ids; this is defensive)
+        }
+        const newBody = clean.replace(/^#+\s*/, "");
+        // design/65 [79]: if the description was AUTO-DERIVED at write time (== first sentence of the OLD body),
+        // re-derive it from the new body so the manifest description doesn't drift away from the content after
+        // consolidation rewrites it (the side-query selects on the description). An EXPLICIT caller-supplied
+        // description (!= the old first sentence) is preserved.
+        if (entry.description !== undefined && entry.description === firstSentence(entry.text)) {
+            entry.description = firstSentence(newBody);
+        }
+        entry.text = newBody;
+        entry.ts = new Date().toISOString().replace("T", " ").slice(0, 16); // a fresh write refreshes recency
+    }
+    delete(scope, id) {
+        const arr = this.byScope.get(scope);
+        if (!arr) {
+            return;
+        }
+        const i = arr.findIndex((e) => e.id === id);
+        if (i !== -1) {
+            arr.splice(i, 1);
+        }
+    }
+    /** Manifest (design/65 §2.2): a header per note, body excluded. description = the note's first sentence
+     *  (legacy flat notes have no frontmatter; this is the council #10 P1 fallback). */
+    listStructuredNotes(scope) {
+        const entries = this.byScope.get(scope) ?? [];
+        // Structured notes surface their name/type/description; legacy flat notes fall back to the first
+        // sentence (no name/type) so a mixed store still produces one manifest (design/65 §8#14 / TC-65P2.5).
+        return entries.map((e) => ({
+            id: e.id,
+            description: e.description ?? firstSentence(e.text),
+            mtimeMs: mtimeMsOf(e.ts),
+            ...(e.name ? { name: e.name } : {}),
+            ...(e.type ? { type: e.type } : {}),
+            ...(e.consolidationGenerated ? { consolidationGenerated: true } : {}),
+        }));
+    }
+    /** design/84 Seam B: read the periodic-consolidation cursor (opaque note-id high-water mark). */
+    getConsolidationCursor(scope) {
+        return this.cursorByScope.get(scope);
+    }
+    /** design/84 Seam B: persist the periodic-consolidation cursor. */
+    setConsolidationCursor(scope, cursor) {
+        this.cursorByScope.set(scope, cursor);
+    }
+    getByIds(scope, ids) {
+        const entries = this.byScope.get(scope);
+        if (!entries)
+            return [];
+        const want = new Set(ids);
+        return entries
+            .filter((e) => want.has(e.id))
+            .map((e) => ({
+            id: e.id,
+            text: e.text,
+            description: e.description ?? firstSentence(e.text),
+            mtimeMs: mtimeMsOf(e.ts),
+            ...(e.name ? { name: e.name } : {}),
+            ...(e.type ? { type: e.type } : {}),
+            ...(e.consolidationGenerated ? { consolidationGenerated: true } : {}),
+        }));
+    }
+}
+/**
+ * design/81 Slice 2b — a ZERO-MODEL lexical term expander closing the only real lexical recall weakness the
+ * red-team raised (the `recall`-tool `search` misses paraphrases like "auth token" vs "credentials/bearer").
+ * Pure TS, NO embedder/native/model dep — same posture as the Jaccard stand-in. For a lower-cased query
+ * term it returns that term PLUS:
+ *  - its members of a small bidirectional **synonym set** (auth↔credentials↔bearer, token↔key↔secret, …),
+ *    looked up for BOTH the original term AND its plural stem (so an inflected query like "tokens" — whose
+ *    singular "token" is the synonym-group member — still expands to {bearer, apikey, secret, key}), and
+ *  - a light **plural** stem (`-ies→-y`, `-es`, `-s`, with a ≥3-char guard) so "tokens" reaches "token".
+ *    (The `-ing`/`-ed` rules were removed — they over-truncated and produced wrong stems.)
+ * Always includes the original term, so a non-expandable term degrades to the existing substring match
+ * (byte-identical to the prior behavior when no synonym/stem applies). The caller (`lexicalSearchMatch`)
+ * treats the returned variants as an OR within one query term (still AND across terms).
+ */
+export function expandLexicalTerms(term) {
+    const t = term.toLowerCase();
+    const out = new Set([t]);
+    // Light, conservative PLURAL stemming (additive — keep the original too). Only strip to a ≥3-char stem.
+    const stem = lightStem(t);
+    const stemOk = stem !== t && stem.length >= 3;
+    if (stemOk)
+        out.add(stem);
+    // Bidirectional synonym groups — any member expands to all members of its group(s). Look up BOTH the
+    // original term AND its plural stem, because the groups are mostly singular: a plural/inflected query
+    // (e.g. "tokens") would otherwise never reach its group (the singular "token" IS the member).
+    for (const group of LEXICAL_SYNONYM_GROUPS) {
+        if (group.has(t) || (stemOk && group.has(stem)))
+            for (const w of group)
+                out.add(w);
+    }
+    return [...out];
+}
+/**
+ * Shared SYNONYM/STEM-aware lexical match (design/81 Slice 2b) — the ONE matcher used by BOTH
+ * {@link InMemoryMemoryStore.search} and {@link import("../stores/file/memory-store.js").FileMemoryStore.search},
+ * so the `recall` tool returns IDENTICAL results across backends (the "byte-identical to InMemory" contract).
+ * It is a recall-QUALITY behavior, correct to apply everywhere. (Pg's `search` is a separate SQL path —
+ * a known follow-on, unchanged in this pass.)
+ *
+ * Matching rule: tokenize `text` on word boundaries, then for each whitespace-separated `query` term the
+ * text must match AT LEAST ONE of that term's {@link expandLexicalTerms} variants (OR within a term), and
+ * EVERY query term must match (AND across terms). The ORIGINAL query term keeps its pre-Slice-2b SUBSTRING
+ * semantics (back-compat); the EXPANDED synonym/stem variants are matched on WORD BOUNDARIES (set membership
+ * over the text's token set) so a short injected synonym like "key"/"db" cannot substring-match an unrelated
+ * word ("keyboard"/"double"). An empty/whitespace-only query never matches.
+ */
+export function lexicalSearchMatch(query, text) {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0)
+        return false;
+    const lower = text.toLowerCase();
+    const tokens = termSet(text); // word-boundary token set of the note text (alphanumeric runs)
+    return terms.every((t) => {
+        const variants = expandLexicalTerms(t);
+        return variants.some((v) => 
+        // The original term keeps SUBSTRING semantics (back-compat); expanded variants must hit a whole token.
+        v === t ? lower.includes(v) : tokens.has(v));
+    });
+}
+/** Small bidirectional synonym groups for {@link expandLexicalTerms} (lexical only, no model). Each set is a
+ *  mutual-synonym cluster: matching ANY member expands the query term to ALL members. */
+const LEXICAL_SYNONYM_GROUPS = [
+    new Set(["auth", "authentication", "authorization", "credentials", "credential", "login", "signin"]),
+    new Set(["token", "bearer", "apikey", "secret", "key"]),
+    new Set(["password", "passwd", "passphrase", "pwd"]),
+    new Set(["delete", "remove", "drop", "erase"]),
+    new Set(["config", "configuration", "settings", "setting"]),
+    new Set(["error", "failure", "exception", "fault"]),
+    new Set(["db", "database"]),
+];
+/**
+ * Conservative trailing-PLURAL stem (plural inflections ONLY), returns the input if nothing applies.
+ * The `-ing`/`-ed` rules were REMOVED: they over-truncated and produced wrong stems ("string"→"str",
+ * "logging"→"logg" — NOT "log"), surfacing unrelated words. Plural stemming is the only safe rule, and a
+ * ≥3-char guard keeps the stem a real word fragment (so "is"→"is", not "i").
+ */
+function lightStem(t) {
+    if (t.length > 4 && t.endsWith("ies"))
+        return `${t.slice(0, -3)}y`; // policies → policy
+    if (t.length > 3 && t.endsWith("es"))
+        return t.slice(0, -2); // boxes → box
+    if (t.length > 3 && t.endsWith("s") && !t.endsWith("ss"))
+        return t.slice(0, -1); // tokens → token
+    return t;
+}
+/** First sentence (or ~120-char head) of a note — the manifest description fallback for untyped notes. */
+export function firstSentence(text) {
+    const t = text.trim().replace(/\s+/g, " ");
+    const dot = t.search(/[.!?](\s|$)/);
+    const cut = dot >= 0 && dot < 160 ? dot + 1 : Math.min(t.length, 120);
+    return t.slice(0, cut).trim();
+}
+/** Parse a "YYYY-MM-DD HH:MM" (UTC) timestamp to ms; 0 if unparseable (treated as oldest/least-fresh). */
+function mtimeMsOf(ts) {
+    const ms = Date.parse(`${ts.replace(" ", "T")}:00Z`);
+    return Number.isFinite(ms) ? ms : 0;
+}
+/**
+ * Normalize the backward-compatible {@link import("./types.js").TaskSpec.memory} union into ONE canonical
+ * {@link NormalizedMemorySpec} (design/84 Seam A decision 1). The consumer side reads ONLY this result — no
+ * narrowing of the union anywhere downstream:
+ *  - `scopes` wins over `scope` when both are present; otherwise `scope` → `[scope]`.
+ *  - blank/whitespace scopes are dropped and duplicates collapsed (FIRST occurrence wins — keeps the
+ *    caller's stable→volatile order); list order is the inject order (stable prefix first, volatile tail last).
+ *  - `writeScope` defaults to the LAST scope (the highest-priority layer); an EXPLICIT `null` means read-only
+ *    (no `remember` tool, no consolidation); an explicit non-null string is taken as-is (it need NOT be one
+ *    of `scopes` — a deployment may write a layer it does not inject, though normally it is the last scope).
+ *    ⚠️ Layered READ seeding (service [646]①, 142-S4): when `scopes` comes from a registry's defaultScopes
+ *    (shared read layers), ALWAYS pin `writeScope` explicitly — the last-scope default would land every
+ *    harvest in whichever shared layer happens to be listed last (a cross-tenant write surface).
+ *  - returns `undefined` when there are no usable scopes (the caller treats it like "no memory configured").
+ *
+ * Backward compatibility: `{ scope: "user:42" }` → `{ scopes: ["user:42"], writeScope: "user:42", enabled: true }`,
+ * so every single-scope path is byte-identical to the pre-design/84 behavior.
+ */
+export function normalizeMemorySpec(input) {
+    if (!input)
+        return undefined;
+    const raw = input.scopes && input.scopes.length > 0 ? input.scopes : input.scope !== undefined ? [input.scope] : [];
+    const scopes = [];
+    const seen = new Set();
+    for (const s of raw) {
+        const t = typeof s === "string" ? s.trim() : "";
+        if (!t || seen.has(t))
+            continue;
+        seen.add(t);
+        scopes.push(t);
+    }
+    if (scopes.length === 0)
+        return undefined;
+    // writeScope: explicit `null` = read-only; explicit string = as-is; omitted = the last (highest-priority) scope.
+    let writeScope;
+    if (input.writeScope === null) {
+        writeScope = null;
+    }
+    else if (typeof input.writeScope === "string" && input.writeScope.trim()) {
+        writeScope = input.writeScope.trim();
+    }
+    else {
+        writeScope = scopes[scopes.length - 1];
+    }
+    // design/142 §1.2 — v2 opt-in: validate every key (writeScope included) against the contract syntax.
+    // parseScopeKey is fail-loud ONLY for keys carrying a reserved prefix; unprefixed keys parse as
+    // legacy and keep today's opaque behavior. Without the opt-in this block never runs (no sniffing).
+    if (input.scopeContract === "v2") {
+        for (const key of writeScope !== null ? [...scopes, writeScope] : scopes)
+            parseScopeKey(key);
+        return { scopes, writeScope, enabled: input.enabled !== false, scopeContract: "v2" };
+    }
+    return { scopes, writeScope, enabled: input.enabled !== false };
+}
+/** Max bytes of memory injected into the prompt; larger is truncated with a marker. (CodeWhale: 100 KiB)
+ *  Exported so the inject-all de-dup seeding (prepare-task.ts) can detect truncation and NOT seed dropped
+ *  (truncated-out) note ids as "already surfaced" — see the MINOR-1 audit fix there. */
+export const MAX_MEMORY_BYTES = 100 * 1024;
+/** The wrapper-tag family the memory injection fences neutralize (`<system-reminder>` is ALWAYS
+ *  included by {@link sanitizeUntrustedText} itself). Single source (design/138 S2-C, C-F10/O-F11):
+ *  the memory write-time scan (`memory-engine/scan.ts`) detects break-out markup by diffing
+ *  `sanitizeUntrustedText(text, MEMORY_WRAPPER_TAGS)` against the raw text, so the scan rules and
+ *  the ACTUAL injection boundary (this file's compose* fences) can never drift apart. */
+export const MEMORY_WRAPPER_TAGS = ["user_memory"];
+/**
+ * Wrap memory content in a `<user_memory>` block. This is the **variable tail** of the system prompt
+ * (per-user, scoped, timestamped) — the default prompt provider places it LAST so the stable base
+ * prompt before it stays a cacheable prefix (see `defaultPromptProvider`).
+ * Truncates over-cap content with a `<truncated bytes=N>` marker (mirrors CodeWhale `as_system_block`).
+ * Returns undefined for empty content.
+ */
+export function composeMemoryBlock(content, scope) {
+    const trimmed = (content ?? "").trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    let payload = trimmed;
+    const bytes = Buffer.byteLength(trimmed, "utf8");
+    if (bytes > MAX_MEMORY_BYTES) {
+        // keep a head slice that fits, then mark the omission
+        const buf = Buffer.from(trimmed, "utf8");
+        let cut = MAX_MEMORY_BYTES;
+        // back up to a valid UTF-8 boundary
+        while (cut > 0 && (buf[cut] & 0xc0) === 0x80) {
+            cut--;
+        }
+        const head = buf.subarray(0, cut).toString("utf8");
+        payload = `${head}\n<truncated bytes=${bytes - cut}>`;
+    }
+    // A-7 (round-2 audit): memory content is persisted across sessions and injected into the SYSTEM prompt,
+    // so a note containing `</user_memory>` or `<system-reminder>` (remembered by a steered model, or added
+    // by a consolidation LLM swayed by candidate text) would escape its fence and forge system authority in
+    // every later same-scope session. Neutralize the wrapper + system-reminder tags before injecting.
+    return `<user_memory scope="${scope}">\n${sanitizeUntrustedText(payload, [...MEMORY_WRAPPER_TAGS])}\n</user_memory>`;
+}
+/**
+ * Compose the LAYERED inject-all memory block for multiple scopes (design/84 Seam A decision 2). One
+ * `<user_memory>` block with a `<scope name="…">` subsection per scope, **in the given list order** — the
+ * caller passes stable layers FIRST (cacheable prefix) and volatile layers LAST (re-computed tail), and the
+ * highest-priority layer is therefore at the END of the block (closest to the model's attention, matching the
+ * single-scope tail placement). Empty layers are omitted. Each layer's content is byte-capped + fence-sanitized
+ * exactly like {@link composeMemoryBlock} (the same A-7 escape class). Returns `undefined` when every layer is
+ * empty (no block to inject).
+ *
+ * **Cache-stability guarantee (§5):** the subsection order is EXACTLY the caller's list order — never sorted
+ * or reordered here — and the per-scope wrapper/format is fixed, so a stable layer at the front renders
+ * byte-identically across turns (the 90/98% prefix-cache hit measured in §5.1/§5.2 depends on this). The
+ * VOLATILE layers the caller places last are the only part that changes, so only the tail re-computes.
+ */
+export function composeLayeredMemoryBlock(layers) {
+    const sections = [];
+    for (const layer of layers) {
+        const trimmed = (layer.content ?? "").trim();
+        if (!trimmed)
+            continue; // omit an empty layer entirely (keeps the block tight + the prefix stable)
+        let payload = trimmed;
+        const bytes = Buffer.byteLength(trimmed, "utf8");
+        if (bytes > MAX_MEMORY_BYTES) {
+            const buf = Buffer.from(trimmed, "utf8");
+            let cut = MAX_MEMORY_BYTES;
+            while (cut > 0 && (buf[cut] & 0xc0) === 0x80)
+                cut--;
+            payload = `${buf.subarray(0, cut).toString("utf8")}\n<truncated bytes=${bytes - cut}>`;
+        }
+        // A-7: per-scope content is persisted, model-influenced — neutralize wrapper/system-reminder tags so a
+        // note in one layer can't escape its fence and forge system authority. The scope ATTRIBUTE is sanitized
+        // too (scopes are caller/profile-derived today, but defensive: a scope string never carries markup).
+        sections.push(`<scope name="${sanitizeUntrustedText(layer.scope, [...MEMORY_WRAPPER_TAGS])}">\n` +
+            `${sanitizeUntrustedText(payload, [...MEMORY_WRAPPER_TAGS])}\n` +
+            `</scope>`);
+    }
+    if (sections.length === 0)
+        return undefined;
+    return `<user_memory>\n${sections.join("\n")}\n</user_memory>`;
+}
+const REMEMBER_DESCRIPTION = "Append a durable note to long-term memory so it survives across sessions. Use this when you " +
+    "notice a stable preference, convention, or fact worth keeping (e.g. 'User prefers concise " +
+    "answers', 'The orders table is read-only'). Phrase it as a declarative fact, NOT an instruction " +
+    "to your future self, and NOT transient task state. Single, durable sentences only. Optionally tag " +
+    "it with a `type` (user | feedback | project | reference) so it can be recalled more precisely. " +
+    "For feedback/project notes, include WHY (the reason is what makes the note applicable later).";
+/** Build a `recall` tool that searches long-term memory on demand (just-in-time L3 retrieval).
+ *  @deprecated design/138 S4 — the Runner no longer mounts this (legacy memoryStore path retired;
+ *  new model-facing `Recall` calls get the TOMBSTONED_TOOLS migration text). Kept exported one major
+ *  for deployments that mount it as an explicit custom tool; removal is the next major. */
+export function createRecallTool(store, scope) {
+    return defineTool({
+        name: "Recall", // design/119: PascalCase like the rest of the roster (sema-own tool; old name in OLD_TO_NEW)
+        aliases: ["recall"], // model-call compatibility (old transcripts/habits), same posture as the CC-deprecated names
+        description: "Search your long-term memory for durable facts/preferences relevant to a query. Use this " +
+            "to retrieve a specific remembered detail on demand (in addition to what is already in your " +
+            "system prompt). Returns matching notes, or nothing if none match. Pass \"*\" (or an empty " +
+            "query) to LIST the most recent memories instead of keyword-matching.",
+        effect: "read", // design/108: recall only searches memory (no mutation) — declare it so plan mode doesn't over-block it
+        parameters: Type.Object({
+            query: Type.String({ description: "Keywords to search remembered notes for, or \"*\" to list recent memories." }),
+        }),
+        execute: async (args) => {
+            const query = String(args.query ?? "").trim();
+            // A wildcard/empty query means "show me what you remember" — keyword-matching a literal "*"
+            // can never hit (the lexical matcher does substring/token matching), which made the tool
+            // falsely report an EMPTY memory to a model probing its own recall (design/119 review). List
+            // the most recent notes instead, bounded.
+            if (query === "" || query === "*" || query.toLowerCase() === "all") {
+                const full = await store.read(scope);
+                // Split on BULLET boundaries, not raw newlines — a multi-line note (remember doesn't collapse
+                // the body) must stay one entry, or the count inflates and the tail-slice can split a note
+                // (workflow review). Non-bulleted stores degrade to line-splitting.
+                const text = (full ?? "").trim();
+                const entries = text
+                    ? (/^- /m.test(text) ? text.split(/\n(?=- )/) : text.split("\n")).map((l) => l.trim()).filter(Boolean)
+                    : [];
+                if (entries.length === 0) {
+                    return { content: "No memories stored yet.", details: { type: "memory-recall", count: 0 } };
+                }
+                const recent = entries.slice(-20);
+                const header = entries.length > recent.length ? `[showing the ${recent.length} most recent of ${entries.length} memories]\n` : "";
+                return { content: header + sanitizeUntrustedText(recent.join("\n")), details: { type: "memory-recall", count: recent.length } };
+            }
+            if (!store.search) {
+                return { content: "No memory matches.", details: { type: "memory-recall", count: 0 } };
+            }
+            const matches = await store.search(scope, query);
+            // Same A-7 class as the system-prompt injection (composeMemoryBlock): recalled notes are
+            // persisted, model-influenced content — a note carrying `<system-reminder>` must not surface
+            // it raw in a tool result either (self-review 2026-06-11: the recall TOOL path was the one
+            // memory injection point without the fence).
+            return {
+                content: matches.length ? sanitizeUntrustedText(matches.join("\n")) : "No memory matches.",
+                // 18-tool toolUseResult 尾批: `type` = wire discriminant (sema 形状 — CC 2.1.201 has no Recall
+                // Output type; the shell renders a "Recalled N memory" dim line — COUNT ONLY on the wire
+                // (codex MED-1: raw persisted memory content must not ride structured un-fenced; the fenced
+                // text stays in model-facing content, the consumer redact contract untouched).
+                details: { type: "memory-recall", count: matches.length },
+            };
+        },
+    });
+}
+/**
+ * Build the `remember` tool bound to a store + scope. Auto-applies (writes are scoped to memory).
+ *
+ * `onRemembered` (optional) is called after each successful append with the new note's `text` and its
+ * store id (when the store returned one) — the Runner used it to collect this task's notes for
+ * end-of-task consolidation (design/41) without re-reading the store.
+ *
+ * @deprecated design/138 S4 — the Runner no longer mounts this (legacy memoryStore path retired; new
+ * model-facing `Remember` calls get the TOMBSTONED_TOOLS migration text). Kept exported one major for
+ * deployments that mount it as an explicit custom tool; removal is the next major.
+ */
+export function createRememberTool(store, scope, onRemembered) {
+    return defineTool({
+        name: "Remember", // design/119: PascalCase like the rest of the roster (sema-own tool; old name in OLD_TO_NEW)
+        aliases: ["remember"], // model-call compatibility, same posture as the CC-deprecated names
+        // design/108: write — remember persists to durable memory (a real side effect); make it explicit so plan mode
+        // correctly rejects it (was accidentally correct via the unknown→"write" default, now intentional).
+        effect: "write",
+        description: REMEMBER_DESCRIPTION,
+        parameters: Type.Object({
+            note: Type.String({ description: "A single durable, declarative fact or preference to remember." }),
+            type: Type.Optional(Type.String({ description: "Optional category: user | feedback | project | reference (default project)." })),
+            description: Type.Optional(Type.String({ description: "Optional one-line summary for the memory index (default: the note's first sentence)." })),
+        }),
+        execute: async (args) => {
+            const a = args;
+            const note = String(a.note ?? "").trim();
+            if (!note) {
+                return { content: "Nothing remembered (empty note).", details: { ok: false } };
+            }
+            // The model authors these directly → inlet hygiene, mirroring the consolidation ADD path: collapse
+            // whitespace (a newline would forge manifest lines) + cap (type 32 = the standard values' scale;
+            // description 300 = "one-line summary"). The manifest renderer enforces the same single-line
+            // guarantee as a backstop for stores written by other inlets.
+            const oneLine = (v, cap) => {
+                if (typeof v !== "string")
+                    return undefined;
+                const t = v.replace(/\s+/g, " ").trim();
+                return t ? t.slice(0, cap) : undefined;
+            };
+            const type = oneLine(a.type, 32);
+            const description = oneLine(a.description, 300);
+            // design/65 §2.1: a structured-capable store always stores a typed note (defaulting type="project" +
+            // first-sentence description), so even an old caller passing only `note` gets a [type] tag for recall.
+            // A legacy store (no appendStructured) keeps the plain append path — full back-compat either way.
+            let id;
+            if (store.appendStructured) {
+                id = await store.appendStructured(scope, { body: note, type, description });
+            }
+            else {
+                id = await store.append(scope, note);
+            }
+            onRemembered?.({ id: typeof id === "string" ? id : undefined, text: note });
+            // design/119 + [378]: carry the note + tags under the discriminant `type:"memory-saved"` so the
+            // tool_end.structured allowlist passes it (CC automemory shows a "Saved memory" card). The memory
+            // CATEGORY (user/feedback/project/reference) rides as `memoryType` — `type` is the card discriminant.
+            // `id` = the store's entry id when the backend reports one (MemoryStore has no file-path concept;
+            // a basename-style writtenPaths needs a store-interface extension — deferred, non-blocking per [378]).
+            return {
+                content: `Remembered: ${note}`,
+                details: { type: "memory-saved", ok: true, note, memoryType: type, description, ...(typeof id === "string" ? { id } : {}) },
+            };
+        },
+    });
+}
+//# sourceMappingURL=memory.js.map