@remnic/core 9.69.46 → 9.69.48

package/src/standing-memory-block.test.ts

@@ -0,0 +1,262 @@
+/**
+ * standing-memory-block.test.ts — issue #2971 foundation slice.
+ *
+ * Pins the prefix-cache contract:
+ *  - the block is byte-identical across consecutive builds with an unchanged
+ *    store (same entries), regardless of input order and of the evaluation
+ *    instant (the clock classifies bands but never renders);
+ *  - the volatility lint refuses clocks, dates, and counters at build time;
+ *  - three-band layering (pinned full, fresh full, older compressed to a
+ *    recognition hook) with a hook ledger that makes steady-state rebuilds
+ *    free and lets a later model slice pre-seed hooks;
+ *  - the mechanical trim fallback drops compressed lines from the tail and
+ *    never a pinned line;
+ *  - zero-diff: with the feature off (and even on, pre-wiring), the live
+ *    recall output is byte-identical and contains no standing block.
+ */
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import { Orchestrator } from "./orchestrator.js";
+import type { PluginConfig } from "./types.js";
+import {
+  buildStandingMemoryBlock,
+  lintStandingBlockVolatility,
+  parseRecallStandingBlock,
+  parseStandingBlockFreshDays,
+  parseStandingBlockMaxChars,
+  standingHookLedgerKey,
+  StandingBlockBudgetError,
+  StandingBlockVolatilityError,
+  type StandingMemoryEntry,
+} from "./standing-memory-block.js";
+
+const NOW = Date.parse("2026-08-25T12:00:00.000Z");
+
+const PINNED: StandingMemoryEntry = {
+  id: "p-core",
+  description: "Deploys always go through the blue pipeline, never green.",
+  pinned: true,
+};
+const PINNED2: StandingMemoryEntry = {
+  id: "p-two",
+  description: "Every release tag is signed with the release key.",
+  pinned: true,
+};
+const FRESH: StandingMemoryEntry = {
+  id: "f-recent",
+  description: "The auth service owner is Priya.",
+  lastChangedAt: "2026-08-20T09:00:00.000Z",
+};
+const OLD_LONG: StandingMemoryEntry = {
+  id: "o-history",
+  description:
+    "The billing stack migrated off the legacy invoice service after the Q3 review " +
+    "because duplicate charges surfaced twice and the team rebuilt invoicing around " +
+    "the ledger event stream that the finance group already trusted.",
+  lastChangedAt: "2025-11-01T00:00:00.000Z",
+};
+
+test("parseConfig: standing block keys default off with byte-identical behavior", () => {
+  const base = { memoryDir: "/tmp/remnic-standing-config-test" };
+  const parsed = parseConfig(base);
+  assert.equal(parsed.recallStandingBlock, false, "absent → false");
+  assert.equal(parsed.standingBlockFreshDays, 14);
+  assert.equal(parsed.standingBlockMaxChars, 2048);
+  assert.equal(parseConfig({ ...base, recallStandingBlock: false }).recallStandingBlock, false);
+  assert.equal(parseConfig({ ...base, recallStandingBlock: 0 }).recallStandingBlock, false);
+  assert.equal(parseConfig({ ...base, recallStandingBlock: "false" }).recallStandingBlock, false);
+  assert.equal(parseConfig({ ...base, recallStandingBlock: true }).recallStandingBlock, true);
+  assert.equal(parseConfig({ ...base, recallStandingBlock: 1 }).recallStandingBlock, true);
+  assert.equal(parseConfig({ ...base, recallStandingBlock: "true" }).recallStandingBlock, true);
+  assert.equal(parseStandingBlockFreshDays("30"), 30);
+  assert.equal(parseStandingBlockMaxChars(1024), 1024);
+  assert.throws(() => parseStandingBlockFreshDays(-1), /Invalid standingBlockFreshDays/);
+  assert.throws(() => parseStandingBlockMaxChars(0), /Invalid standingBlockMaxChars/);
+});
+
+test("block is byte-identical across consecutive builds with an unchanged store", () => {
+  const entries = [PINNED, FRESH, OLD_LONG];
+  const first = buildStandingMemoryBlock({ entries, nowMs: NOW });
+  const second = buildStandingMemoryBlock({ entries, nowMs: NOW });
+  assert.equal(first.text, second.text);
+  assert.equal(first.text, buildStandingMemoryBlock({ entries: [...entries].reverse(), nowMs: NOW }).text);
+  assert.equal(
+    first.text,
+    buildStandingMemoryBlock({ entries, nowMs: NOW + 3_600_000, ledger: first.ledger }).text,
+    "the evaluation clock must never render into the block",
+  );
+  assert.ok(first.text.startsWith("## Standing Memory (Remnic)"));
+});
+
+test("volatility lint refuses dates, clocks, relative dates, and counters at build time", () => {
+  assert.deepEqual(lintStandingBlockVolatility("shipped 2026-08-01"), [
+    { kind: "iso-date", token: "2026-08-01" },
+  ]);
+  assert.deepEqual(lintStandingBlockVolatility("standup at 10:30 sharp"), [
+    { kind: "clock-time", token: "10:30" },
+  ]);
+  assert.deepEqual(lintStandingBlockVolatility("fixed yesterday"), [
+    { kind: "relative-date", token: "yesterday" },
+  ]);
+  assert.deepEqual(lintStandingBlockVolatility("index has memories: 42 rows"), [
+    { kind: "counter", token: "memories: 42" },
+  ]);
+  assert.deepEqual(lintStandingBlockVolatility("quiet, stable line"), []);
+
+  const refuses = (entry: StandingMemoryEntry, kind: string) => {
+    assert.throws(
+      () => buildStandingMemoryBlock({ entries: [entry], nowMs: NOW }),
+      (err: unknown) => {
+        assert.ok(err instanceof StandingBlockVolatilityError);
+        assert.equal(err.matches[0]?.kind, kind);
+        return true;
+      },
+      `expected refusal for ${kind}`,
+    );
+  };
+  refuses({ id: "d1", description: "Deployed on 2026-08-01 to prod." }, "iso-date");
+  refuses({ id: "d2", description: "The standup moved to 09:15." }, "clock-time");
+  refuses({ id: "d3", description: "The on-call rota changed yesterday." }, "relative-date");
+});
+
+test("three-band layering: pinned full first, fresh full, older compressed to a hook", () => {
+  const built = buildStandingMemoryBlock({ entries: [OLD_LONG, FRESH, PINNED], nowMs: NOW });
+  const body = built.lines.filter((line) => line.startsWith("- "));
+  assert.deepEqual(built.bandCounts, { pinned: 1, fresh: 1, compressed: 1, dropped: 0 });
+  // Band rank, then id order: pinned band has p-core alone.
+  assert.equal(body[0], `- ${PINNED.description}`);
+  assert.equal(body[1], `- ${FRESH.description}`);
+  const hookLine = body[2] ?? "";
+  assert.ok(hookLine.startsWith("- "), "compressed line must render");
+  assert.ok(hookLine.endsWith("..."), "mechanical hook marks truncation");
+  assert.ok(hookLine.length <= 2 + 96 + 3, "hook stays inside the char budget");
+  assert.ok(
+    built.ledger.get(standingHookLedgerKey(OLD_LONG.description, 96))?.endsWith("..."),
+    "generated hook lands in the ledger",
+  );
+});
+
+test("hook ledger: pre-seeded hooks are used verbatim; reuse keeps bytes identical", () => {
+  const seeded = new Map([[standingHookLedgerKey(OLD_LONG.description, 96), "Billing moved to the ledger stream."]]);
+  const built = buildStandingMemoryBlock({ entries: [OLD_LONG], nowMs: NOW, ledger: seeded });
+  assert.ok(built.text.includes("- Billing moved to the ledger stream."));
+  const rebuilt = buildStandingMemoryBlock({ entries: [OLD_LONG], nowMs: NOW, ledger: built.ledger });
+  assert.equal(built.text, rebuilt.text);
+  assert.equal(seeded.size, 1, "input ledger is never mutated");
+});
+
+test("mechanical trim: drops compressed lines from the tail, never pinned lines", () => {
+  const built = buildStandingMemoryBlock({ entries: [OLD_LONG, FRESH, PINNED], nowMs: NOW, maxChars: 220 });
+  assert.equal(built.bandCounts.pinned, 1, "pinned line survives");
+  assert.ok(built.bandCounts.dropped >= 1, "tail lines dropped");
+  assert.ok(built.text.includes("- ...(older lines trimmed)"));
+  assert.ok(!built.text.includes(OLD_LONG.description.slice(0, 40)), "the longest compressed line is gone");
+  assert.throws(
+    () => buildStandingMemoryBlock({ entries: [PINNED, PINNED2], nowMs: NOW, maxChars: 80 }),
+    StandingBlockBudgetError,
+  );
+});
+
+test("no entries render an empty block; bad input is refused loudly", () => {
+  assert.equal(buildStandingMemoryBlock({ entries: [], nowMs: NOW }).text, "");
+  assert.throws(
+    () => buildStandingMemoryBlock({ entries: [{ id: "x", description: "" }], nowMs: NOW }),
+    /requires a non-empty description/,
+  );
+  assert.throws(
+    () =>
+      buildStandingMemoryBlock({
+        entries: [
+          { id: "x", description: "One." },
+          { id: "x", description: "Two." },
+        ],
+        nowMs: NOW,
+      }),
+    /ids must be unique/,
+  );
+  assert.throws(
+    () => buildStandingMemoryBlock({ entries: [{ id: "x", description: "One.", lastChangedAt: "nope" }], nowMs: NOW }),
+    /unparseable lastChangedAt/,
+  );
+});
+
+/**
+ * Zero-diff proof for the foundation slice: nothing on the live recall path
+ * reads the new keys yet, so recall output must stay byte-identical whether
+ * the flag is absent or explicitly true, and must contain no standing block.
+ * When the server wiring slice lands, this test flips to assert the block IS
+ * prepended when on — that flip is the wiring PR's fail-before receipt.
+ */
+async function makeOrchestrator(
+  overrides: Partial<PluginConfig> = {},
+): Promise<{ orchestrator: Orchestrator; memoryDir: string }> {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-standing-zero-diff-"));
+  const config = parseConfig({
+    openaiApiKey: "sk-test",
+    memoryDir,
+    workspaceDir: path.join(memoryDir, "workspace"),
+    qmdEnabled: false,
+    embeddingFallbackEnabled: false,
+    multiGraphMemoryEnabled: false,
+    entityGraphEnabled: false,
+    timeGraphEnabled: false,
+    causalGraphEnabled: false,
+    extractionJudgeEnabled: false,
+    contradictionDetectionEnabled: false,
+    chunkingEnabled: false,
+    extractionMinChars: 0,
+    extractionMinImportanceLevel: "trivial",
+    inlineSourceAttributionEnabled: false,
+    initGateTimeoutMs: 200,
+    ...overrides,
+  });
+  return { orchestrator: new Orchestrator(config), memoryDir };
+}
+
+async function writeFact(memoryDir: string): Promise<void> {
+  const today = new Date().toISOString().slice(0, 10);
+  const factsDir = path.join(memoryDir, "facts", today);
+  await mkdir(factsDir, { recursive: true });
+  const now = new Date().toISOString();
+  const fact = [
+    "---",
+    "id: standing-fact",
+    "category: fact",
+    `created: ${now}`,
+    `updated: ${now}`,
+    "source: extraction",
+    "confidence: 0.8",
+    "confidenceTier: high",
+    "tags: []",
+    "status: active",
+    "---",
+    "",
+    "The blue pipeline is the only deploy path.",
+    "",
+  ];
+  await writeFile(path.join(factsDir, "standing-fact.md"), `${fact.join("\n")}\n`, "utf-8");
+}
+
+test("zero-diff: recall output is byte-identical with the flag off vs on (pre-wiring)", async () => {
+  const off = await makeOrchestrator();
+  const on = await makeOrchestrator({ recallStandingBlock: true });
+  try {
+    await writeFact(off.memoryDir);
+    await writeFact(on.memoryDir);
+    const outOff = await off.orchestrator.recall("how do deploys go out", "sess-standing-off");
+    const outOn = await on.orchestrator.recall("how do deploys go out", "sess-standing-on");
+    assert.equal(outOn, outOff, "recall must not change until the wiring slice lands");
+    assert.ok(!outOn.includes("## Standing Memory (Remnic)"), "no standing block in recall output");
+    assert.ok(outOn.includes("blue pipeline"), "sanity: the fact is recalled");
+  } finally {
+    await off.orchestrator.destroy();
+    await on.orchestrator.destroy();
+    await rm(off.memoryDir, { recursive: true, force: true });
+    await rm(on.memoryDir, { recursive: true, force: true });
+  }
+});

package/src/standing-memory-block.ts

@@ -0,0 +1,331 @@
+/**
+ * Prefix-cache-stable standing memory block (issue #2971, foundation slice).
+ *
+ * A standing block is a compact, byte-stable index over pinned/high-value
+ * memories that a host injects as the FIRST part of the system prompt, so
+ * the LLM prefix cache survives across turns. Measured motivation
+ * (distill-kura, local OpenAI-compatible server): an identical 4k-token
+ * prefix reprices at 0.14 s vs 0.68 s cold, and one changed word at the
+ * front costs the whole cache. So the block contains no clock, no date,
+ * and no counter — and the builder REFUSES, at build time, any block that
+ * carries one instead of discovering slow turns weeks later.
+ *
+ * Determinism rules (byte-identical between rebuilds):
+ *  - line order is band rank, then id codepoint order — never wall clock,
+ *    never insertion order, never locale collation;
+ *  - `nowMs` classifies bands but never renders into the text;
+ *  - the trimmed-tail marker is a constant string (no count of dropped
+ *    lines, which would itself be a counter).
+ *
+ * Host contract for the full feature (later wiring slices):
+ *  - rebuild only when the underlying store changes (store version), not
+ *    per turn and not on a timer — band edges must not drift mid-session;
+ *  - inject the standing block BEFORE per-turn dynamic recall and any
+ *    ticking content (persona with a clock), see docs/config-reference.md;
+ *  - selection of which memories qualify (pinned/high-value) happens
+ *    before this builder — it only layers and renders what it is given;
+ *  - on build failure (volatility, budget) skip injection and log — the
+ *    dynamic recall surface must not go blank.
+ *
+ * Pure: no I/O, inputs never mutated, the returned ledger is a fresh Map.
+ */
+import { coerceBooleanLike, coerceNumber } from "./connectors/coerce.js";
+
+export const DEFAULT_RECALL_STANDING_BLOCK = false;
+export const DEFAULT_STANDING_BLOCK_FRESH_DAYS = 14;
+export const DEFAULT_STANDING_BLOCK_MAX_CHARS = 2048;
+/** ~24-token recognition hook at the repo's 4-chars-per-token Latin headroom. */
+export const DEFAULT_STANDING_BLOCK_HOOK_CHARS = 96;
+
+export const STANDING_BLOCK_HEADER = "## Standing Memory (Remnic)";
+export const STANDING_BLOCK_INSTRUCTION =
+  "Use this standing index for orientation. It changes only when the memory store changes.";
+export const STANDING_BLOCK_TRIMMED_MARKER = "- ...(older lines trimmed)";
+
+export type StandingBand = "pinned" | "fresh" | "compressed";
+
+export interface StandingMemoryEntry {
+  /** Stable document id. Total order within a band is id codepoint order. */
+  id: string;
+  /** The one-line description to stand in the index. */
+  description: string;
+  /** Pinned entries render in full, first band, never trimmed away. */
+  pinned?: boolean;
+  /** ISO timestamp of the last content change; drives the fresh band. */
+  lastChangedAt?: string;
+}
+
+/** Cache of compressed hooks keyed on `${description}\u0000${hookMaxChars}`. */
+export type StandingHookLedger = ReadonlyMap<string, string>;
+
+export function standingHookLedgerKey(description: string, hookMaxChars: number): string {
+  return `${description}\u0000${hookMaxChars}`;
+}
+
+export interface StandingBlockBandCounts {
+  pinned: number;
+  fresh: number;
+  compressed: number;
+  dropped: number;
+}
+
+export interface StandingMemoryBlock {
+  /** Full block text (header + lines + instruction). Empty string for no entries. */
+  text: string;
+  /** Lines without a trailing newline; empty for no entries. */
+  lines: string[];
+  /** Ledger including hooks generated this build. Fresh Map; input never mutated. */
+  ledger: StandingHookLedger;
+  bandCounts: StandingBlockBandCounts;
+}
+
+export type StandingVolatilityKind = "iso-date" | "clock-time" | "relative-date" | "counter";
+
+export interface StandingVolatilityMatch {
+  kind: StandingVolatilityKind;
+  token: string;
+}
+
+const ISO_DATE_RE = /\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2})?/;
+const CLOCK_TIME_RE = /\b\d{1,2}:\d{2}(?::\d{2})?\b/;
+const RELATIVE_DATE_RE =
+  /\b(?:today|tonight|tomorrow|yesterday|this\s+(?:morning|afternoon|evening|week|month|year))\b/i;
+const COUNTER_RE = /\b(?:count|total|entries|memories|items)\s*[:=]\s*\d+\b/i;
+
+/**
+ * Build-time volatility lint. Returns every cache-busting token class found:
+ * ISO dates/datetimes, clock times, relative date words, and index counters.
+ * Refusal is the designed behavior (a memory surface skips the block and
+ * logs) — a silently repricing prefix is the failure this catches.
+ */
+export function lintStandingBlockVolatility(text: string): StandingVolatilityMatch[] {
+  const matches: StandingVolatilityMatch[] = [];
+  for (const [kind, re] of [
+    ["iso-date", ISO_DATE_RE],
+    ["clock-time", CLOCK_TIME_RE],
+    ["relative-date", RELATIVE_DATE_RE],
+    ["counter", COUNTER_RE],
+  ] as const) {
+    const hit = text.match(re);
+    if (hit) matches.push({ kind, token: hit[0] });
+  }
+  return matches;
+}
+
+export class StandingBlockError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StandingBlockError";
+  }
+}
+
+export class StandingBlockVolatilityError extends StandingBlockError {
+  readonly matches: readonly StandingVolatilityMatch[];
+  constructor(matches: readonly StandingVolatilityMatch[]) {
+    super(
+      `standing memory block refused: volatile content busts the prefix cache (${matches
+        .map((m) => `${m.kind}:${JSON.stringify(m.token)}`)
+        .join(", ")})`,
+    );
+    this.name = "StandingBlockVolatilityError";
+    this.matches = matches;
+  }
+}
+
+export class StandingBlockBudgetError extends StandingBlockError {
+  constructor(maxChars: number) {
+    super(
+      `standing memory block does not fit: pinned lines alone exceed maxChars=${maxChars}; raise standingBlockMaxChars or unpin entries`,
+    );
+    this.name = "StandingBlockBudgetError";
+  }
+}
+
+export function parseRecallStandingBlock(raw: unknown): boolean {
+  return coerceBooleanLike(raw, "recallStandingBlock") === true;
+}
+
+export function parseStandingBlockFreshDays(raw: unknown): number {
+  if (raw === undefined || raw === null) return DEFAULT_STANDING_BLOCK_FRESH_DAYS;
+  const n = coerceNumber(raw, "standingBlockFreshDays");
+  if (n === undefined || !Number.isFinite(n) || n < 0) {
+    throw new Error(`Invalid standingBlockFreshDays: expected a number >= 0, got ${JSON.stringify(raw)}`);
+  }
+  return n;
+}
+
+export function parseStandingBlockMaxChars(raw: unknown): number {
+  if (raw === undefined || raw === null) return DEFAULT_STANDING_BLOCK_MAX_CHARS;
+  const n = coerceNumber(raw, "standingBlockMaxChars");
+  if (n === undefined || !Number.isFinite(n) || n < 1) {
+    throw new Error(`Invalid standingBlockMaxChars: expected an integer >= 1, got ${JSON.stringify(raw)}`);
+  }
+  return Math.floor(n);
+}
+
+/**
+ * Mechanical hook: deterministic first-cut of the description to the char
+ * budget at a word boundary. This is also the fallback when no model is
+ * reachable for compression — the standing surface never goes blank because
+ * a model is down. Model-generated hooks arrive pre-seeded in the ledger.
+ */
+function mechanicalHook(description: string, budget: number): string {
+  if (description.length <= budget) return description;
+  const cut = description.slice(0, budget);
+  const lastSpace = cut.lastIndexOf(" ");
+  const base = lastSpace > Math.floor(budget * 0.6) ? cut.slice(0, lastSpace) : cut;
+  return `${base.replace(/[\s,;:]+$/, "")}...`;
+}
+
+interface LayeredEntry {
+  id: string;
+  band: StandingBand;
+  line: string;
+}
+
+const BAND_RANK: Record<StandingBand, number> = { pinned: 0, fresh: 1, compressed: 2 };
+
+function validateEntries(entries: readonly StandingMemoryEntry[]): Map<string, StandingMemoryEntry> {
+  if (!Array.isArray(entries)) {
+    throw new StandingBlockError("standing memory block entries must be an array");
+  }
+  const seen = new Set<string>();
+  const validated = new Map<string, StandingMemoryEntry>();
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null) {
+      throw new StandingBlockError(`standing memory block entry must be an object, got ${JSON.stringify(entry)}`);
+    }
+    const id = typeof entry.id === "string" ? entry.id.trim() : "";
+    const description = typeof entry.description === "string" ? entry.description.trim() : "";
+    if (id.length === 0) {
+      throw new StandingBlockError("standing memory block entry requires a non-empty id");
+    }
+    if (description.length === 0) {
+      throw new StandingBlockError(`standing memory block entry ${id} requires a non-empty description`);
+    }
+    if (seen.has(id)) {
+      throw new StandingBlockError(`standing memory block entry ids must be unique; duplicate: ${id}`);
+    }
+    if (entry.lastChangedAt !== undefined && Number.isNaN(Date.parse(entry.lastChangedAt))) {
+      throw new StandingBlockError(
+        `standing memory block entry ${id} has an unparseable lastChangedAt: ${JSON.stringify(entry.lastChangedAt)}`,
+      );
+    }
+    seen.add(id);
+    validated.set(id, { ...entry, id, description });
+  }
+  return validated;
+}
+
+export interface StandingMemoryBlockInput {
+  entries: readonly StandingMemoryEntry[];
+  /**
+   * Evaluation instant for the fresh band. Hosts must key rebuilds on the
+   * store version, not on this clock, or band edges drift per turn.
+   */
+  nowMs: number;
+  freshDays?: number;
+  maxChars?: number;
+  hookMaxChars?: number;
+  ledger?: StandingHookLedger;
+}
+
+export function buildStandingMemoryBlock(input: StandingMemoryBlockInput): StandingMemoryBlock {
+  const freshDays = input.freshDays ?? DEFAULT_STANDING_BLOCK_FRESH_DAYS;
+  const maxChars = input.maxChars ?? DEFAULT_STANDING_BLOCK_MAX_CHARS;
+  const hookMaxChars = input.hookMaxChars ?? DEFAULT_STANDING_BLOCK_HOOK_CHARS;
+  if (!Number.isFinite(input.nowMs)) {
+    throw new StandingBlockError("standing memory block requires a finite nowMs");
+  }
+  if (!(freshDays >= 0) || !Number.isFinite(freshDays)) {
+    throw new StandingBlockError("standing memory block requires freshDays >= 0");
+  }
+  if (!(maxChars >= 1) || !Number.isFinite(maxChars)) {
+    throw new StandingBlockError("standing memory block requires maxChars >= 1");
+  }
+  if (!(hookMaxChars >= 1) || !Number.isFinite(hookMaxChars)) {
+    throw new StandingBlockError("standing memory block requires hookMaxChars >= 1");
+  }
+
+  const entries = validateEntries(input.entries);
+  const ledger = new Map(input.ledger ?? []);
+  if (entries.size === 0) {
+    return {
+      text: "",
+      lines: [],
+      ledger,
+      bandCounts: { pinned: 0, fresh: 0, compressed: 0, dropped: 0 },
+    };
+  }
+
+  const freshCutoff = input.nowMs - freshDays * 86_400_000;
+  const layered: LayeredEntry[] = [];
+  for (const entry of entries.values()) {
+    let band: StandingBand;
+    if (entry.pinned === true) {
+      band = "pinned";
+    } else if (
+      typeof entry.lastChangedAt === "string" &&
+      Date.parse(entry.lastChangedAt) >= freshCutoff &&
+      Date.parse(entry.lastChangedAt) <= input.nowMs
+    ) {
+      band = "fresh";
+    } else {
+      band = "compressed";
+    }
+    if (band !== "compressed") {
+      layered.push({ id: entry.id, band, line: `- ${entry.description}` });
+      continue;
+    }
+    const key = standingHookLedgerKey(entry.description, hookMaxChars);
+    const cached = ledger.get(key);
+    const hook = cached ?? mechanicalHook(entry.description, hookMaxChars);
+    if (cached === undefined) ledger.set(key, hook);
+    layered.push({ id: entry.id, band, line: `- ${hook}` });
+  }
+
+  // Band rank, then id codepoint order. Never localeCompare: collation is
+  // ICU-dependent and this text must be byte-identical across rebuilds.
+  layered.sort(
+    (a, b) =>
+      BAND_RANK[a.band] - BAND_RANK[b.band] || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+  );
+
+  const render = (keep: number, withMarker: boolean): { text: string; lines: string[] } => {
+    const body = layered.slice(0, keep).map((item) => item.line);
+    if (withMarker) body.push(STANDING_BLOCK_TRIMMED_MARKER);
+    const lines = [STANDING_BLOCK_HEADER, "", ...body, "", STANDING_BLOCK_INSTRUCTION];
+    return { text: lines.join("\n"), lines };
+  };
+
+  const pinnedCount = layered.filter((item) => item.band === "pinned").length;
+  let keep = layered.length;
+  let rendered = render(keep, false);
+  // Mechanical trim: drop from the tail. The sort puts compressed lines
+  // last, so oldest-band hooks go first and pinned lines are never reached.
+  while (rendered.text.length > maxChars && keep > pinnedCount) {
+    keep -= 1;
+    rendered = render(keep, true);
+  }
+  if (rendered.text.length > maxChars) {
+    throw new StandingBlockBudgetError(maxChars);
+  }
+
+  const volatility = lintStandingBlockVolatility(rendered.text);
+  if (volatility.length > 0) {
+    throw new StandingBlockVolatilityError(volatility);
+  }
+
+  const kept = layered.slice(0, keep);
+  return {
+    text: rendered.text,
+    lines: rendered.lines,
+    ledger,
+    bandCounts: {
+      pinned: kept.filter((item) => item.band === "pinned").length,
+      fresh: kept.filter((item) => item.band === "fresh").length,
+      compressed: kept.filter((item) => item.band === "compressed").length,
+      dropped: layered.length - keep,
+    },
+  };
+}

package/src/types.ts

@@ -991,6 +991,12 @@ export interface PluginConfig
   recallDirectAnswerEnabled: boolean;
   /** Recall state views (issue #1952): label current/historical/transition on change-intent queries. Default false. */
   recallStateViews: boolean;
+  /** Standing memory block (issue #2971): byte-stable pinned-memory index injected before per-turn recall; parsed now, injection lands in a later slice. Default false. */
+  recallStandingBlock: boolean;
+  /** Days a memory stays in the standing block's full-text fresh band. Default 14. */
+  standingBlockFreshDays: number;
+  /** Hard character budget for the standing memory block. Default 2048. */
+  standingBlockMaxChars: number;
   /**
    * Disclosure auto-escalation policy (issue #677 PR 4/4).  `"auto"`
    * escalates chunk → section when top-K confidence falls below