talon-agent 3.12.5 → 3.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.12.5",
+  "version": "3.13.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/prompts/system/persistent-memory.md

@@ -3,6 +3,8 @@
 The following is your memory file. Reference it naturally. Update it via the Write tool when you learn important new information.
 File: ~/.talon/workspace/memory/memory.md
 
-{{content}}{% if truncated %}
+{{content}}{% if omitted %}
+
+Sections held back to keep session start lean — Read the file above when you need them: {{omitted}}{% elsif truncated %}
 
 …(memory file truncated here to keep session start lean — Read the file above for the rest){% endif %}

package/src/backend/claude-sdk/handler.ts

@@ -64,6 +64,10 @@ import {
   recordTurnMetrics,
   recordFailedTurnAccounting,
   recordFlowViolation,
+  formatTurnCache,
+  exceedsLookbackWindow,
+  estimateTurnBlocks,
+  CACHE_LOOKBACK_BLOCKS,
 } from "../shared/index.js";
 
 // ── Post-result watchdog ────────────────────────────────────────────────────
@@ -577,6 +581,19 @@ export async function* runChatTurn(
 
   state.allResponseText += state.currentBlockText;
 
+  // The aggregate `cache=NN%` can't distinguish a turn that reused the
+  // previous turn's prefix from one that re-wrote it — see
+  // shared/cache-telemetry.ts. Append the cross-turn verdict when the
+  // provider gave us per-request usage to derive it from.
+  if (state.cacheStats && exceedsLookbackWindow(state.toolCalls)) {
+    logWarn(
+      "agent",
+      `[${chatId}] turn emitted ~${estimateTurnBlocks(state.toolCalls)} content ` +
+        `blocks (> ${CACHE_LOOKBACK_BLOCKS} lookback) — the next turn's cache ` +
+        `breakpoint may not find this turn's prefix`,
+    );
+  }
+
   log(
     "agent",
     `[${chatId}] -> (${summarizeUsage(
@@ -586,7 +603,13 @@ export async function* runChatTurn(
         cacheRead: state.sdkCacheRead,
         cacheWrite: state.sdkCacheWrite,
       },
-      { durationMs, toolCalls: state.toolCalls },
+      {
+        durationMs,
+        toolCalls: state.toolCalls,
+        ...(state.cacheStats
+          ? { suffix: formatTurnCache(state.cacheStats) }
+          : {}),
+      },
     )})`,
   );
   traceMessage(chatId, "out", state.allResponseText, {

package/src/backend/claude-sdk/one-shot.ts

@@ -19,6 +19,7 @@ import { log, logWarn } from "../../util/log.js";
 import { ALLOWED_TOOLS_BACKGROUND } from "../../core/constants.js";
 import { EFFORT_MAP } from "./constants.js";
 import { buildMcpServers, buildPluginMcpServers } from "./options.js";
+import { warnIfBelowCacheMinimum } from "../shared/cache-telemetry.js";
 
 const DEFAULT_SUBPROCESS_KILL_GRACE_MS = 5 * 1000;
 
@@ -111,6 +112,11 @@ export async function runOneShotAgent(
     );
   }
 
+  // Background runs are the one path whose prompt can be small enough to
+  // fall under the model's cacheable floor — where nothing is cached and the
+  // API reports no error at all. Chat prompts always clear it.
+  warnIfBelowCacheMinimum(contextLabel, model, `${systemPrompt}\n${prompt}`);
+
   const qi = query({
     prompt,
     options: options as Parameters<typeof query>[0]["options"],

package/src/backend/claude-sdk/options.ts

@@ -26,6 +26,10 @@ import {
   hubPluginServerNames,
 } from "../../core/mcp-hub/index.js";
 import { nonTerminalFrontends, frontendsForChat } from "../shared/frontends.js";
+import {
+  noteToolFingerprint,
+  toolFingerprint,
+} from "../shared/cache-telemetry.js";
 import { log, logError } from "../../util/log.js";
 import { getConfig, getBridgePort } from "./state.js";
 import { ALLOWED_TOOLS_CHAT, EFFORT_MAP } from "./constants.js";
@@ -378,6 +382,24 @@ export function buildSdkOptions(
   const { postToolUseFailureHook, postToolBatchHook } =
     buildTurnTerminatorHooks();
 
+  const builtinTools = config.nativeTools
+    ? ALLOWED_TOOLS_CHAT.filter((t) => !NATIVE_REPLACED_BUILTINS.has(t))
+    : [...ALLOWED_TOOLS_CHAT];
+
+  const mcpServers = {
+    ...buildMcpServers(chatId),
+    ...buildPluginMcpServers(chatId),
+  };
+
+  // Tool definitions render BEFORE the system prompt, so a set that shifts
+  // mid-session invalidates the system prompt and every cached message after
+  // it — the most expensive cache event there is, and one the aggregate
+  // hit-rate can't show. Plugin-provided MCP servers are the mutable part.
+  noteToolFingerprint(
+    chatId,
+    toolFingerprint(builtinTools, Object.keys(mcpServers)),
+  );
+
   const options: Options = {
     model: resolvedActiveModel,
     // Prefer the caller's frozen per-session prompt; fall back to the
@@ -424,16 +446,9 @@ export function buildSdkOptions(
     // teleport onto companion devices), and Agent (sub-agent dispatch) is
     // removed too — the owner prefers the native surface without nested
     // agents. Flip the flag back off to restore the built-ins instantly.
-    tools: config.nativeTools
-      ? ALLOWED_TOOLS_CHAT.filter(
-          (t) => !NATIVE_REPLACED_BUILTINS.has(t as string),
-        )
-      : [...ALLOWED_TOOLS_CHAT],
+    tools: builtinTools,
     ...thinkingConfig,
-    mcpServers: {
-      ...buildMcpServers(chatId),
-      ...buildPluginMcpServers(chatId),
-    },
+    mcpServers,
     hooks: {
       PostToolUseFailure: [{ hooks: [postToolUseFailureHook] }],
       PostToolBatch: [{ hooks: [postToolBatchHook] }],

package/src/backend/claude-sdk/stream.ts

@@ -19,6 +19,10 @@ import type { BetaRawContentBlockDeltaEvent } from "@anthropic-ai/sdk/resources/
 import { STREAM_INTERVAL } from "./constants.js";
 import { log } from "../../util/log.js";
 import { checkModelDrift } from "./model-drift.js";
+import {
+  turnCacheStats,
+  type TurnCacheStats,
+} from "../shared/cache-telemetry.js";
 
 // ── Stream state accumulator ────────────────────────────────────────────────
 
@@ -35,6 +39,14 @@ export type StreamState = {
   sdkOutputTokens: number;
   sdkCacheRead: number;
   sdkCacheWrite: number;
+  /**
+   * Per-turn cache behaviour derived from the result message's per-request
+   * `usage.iterations`. Undefined when the provider reported none — the
+   * aggregate totals above cannot distinguish a turn that read the previous
+   * turn's prefix from one that re-wrote it, and that distinction is the
+   * whole cost signal (see shared/cache-telemetry.ts).
+   */
+  cacheStats: TurnCacheStats | undefined;
   lastStreamUpdate: number;
   /**
    * Trailing text from the most recent assistant message — text after all
@@ -101,6 +113,7 @@ export function createStreamState(): StreamState {
     sdkOutputTokens: 0,
     sdkCacheRead: 0,
     sdkCacheWrite: 0,
+    cacheStats: undefined,
     lastStreamUpdate: 0,
     lastTrailingText: "",
     deliveredTextNorms: [],
@@ -332,6 +345,9 @@ export function processResultMessage(
       (last.input_tokens ?? 0) +
       (last.cache_read_input_tokens ?? 0) +
       (last.cache_creation_input_tokens ?? 0);
+    // The same array answers a question the per-turn totals can't: whether
+    // the FIRST request of this turn read a cache or paid to write one.
+    state.cacheStats = turnCacheStats(usage.iterations);
   }
 
   // Read token counts from the ACTIVE model's usage only.

package/src/backend/shared/cache-telemetry.ts

@@ -0,0 +1,297 @@
+/**
+ * Prompt-cache telemetry — the numbers needed to tell whether Talon's
+ * prompt cache is actually working, and why not when it isn't.
+ *
+ * Motivation (see docs/memory-persona-plan.md §3.6): the obvious lever for a
+ * sparse-traffic chat bot would be a 1-hour cache TTL, but
+ * `@anthropic-ai/claude-agent-sdk` exposes no cache-control surface at all —
+ * it owns `cache_control` placement internally. So the only levers Talon has
+ * are (a) keeping the prompt prefix byte-stable and (b) keeping it small,
+ * and the only way to know which one is costing money is to measure.
+ *
+ * Four things are measured here, each answering a question the aggregate
+ * `cache=NN%` on the accounting line cannot:
+ *
+ *   1. **Cross-turn vs within-turn hits.** An agentic turn makes many model
+ *      requests; every one after the first reads the prefix the first one
+ *      just paid for. So a 97% aggregate hit rate is compatible with *every
+ *      turn* re-writing the whole prefix. The turn's FIRST request is the
+ *      only one that reports whether the previous turn's cache survived —
+ *      that is the number that tracks cost.
+ *   2. **Tool-set churn.** Tool definitions render BEFORE the system prompt,
+ *      so any change to the tool array invalidates the system prompt and the
+ *      whole message history with it. A stable prompt behind an unstable
+ *      tool list buys nothing, and Talon's per-chat MCP servers are exactly
+ *      the shape that can shift mid-session.
+ *   3. **Lookback-window risk.** A cache breakpoint searches back at most
+ *      `CACHE_LOOKBACK_BLOCKS` content blocks for a prior entry. A turn that
+ *      emits more blocks than that can leave the *next* turn's breakpoint
+ *      unable to find anything — a silent miss with no error.
+ *   4. **Sub-minimum prompts.** Below a model-specific token floor nothing
+ *      caches, and the API reports no error. Talon's chat prompts clear every
+ *      floor; its one-shot prompts (dream, heartbeat, cron) may not.
+ *
+ * Everything here is pure except `noteToolFingerprint`, which keeps a small
+ * per-chat map so it can name what changed rather than just that something
+ * did.
+ */
+
+import { logWarn } from "../../util/log.js";
+
+// ── Per-turn cache stats ────────────────────────────────────────────────────
+
+/**
+ * One model request's usage, as the SDK reports it in
+ * `result.usage.iterations`. Fields are optional because a given provider
+ * may omit any of them; absent is treated as zero.
+ */
+export type CacheIteration = {
+  readonly input_tokens?: number;
+  readonly cache_read_input_tokens?: number;
+  readonly cache_creation_input_tokens?: number;
+};
+
+/** Cache behaviour for one user-visible turn. */
+export type TurnCacheStats = {
+  /** Model requests the SDK made inside this turn. */
+  readonly modelRequests: number;
+  /** Cache read on the turn's FIRST request — did the last turn's prefix live? */
+  readonly firstRead: number;
+  /** Cache written by the turn's first request. */
+  readonly firstWrite: number;
+  /** Cache read across every request in the turn. */
+  readonly totalRead: number;
+  /** Cache written across every request in the turn. */
+  readonly totalWrite: number;
+};
+
+/**
+ * What the turn's first request says about the previous turn's cache.
+ *
+ *   - `hit`  — the prefix survived; this turn read it instead of paying for it.
+ *   - `miss` — the prefix was gone and had to be re-written. The expensive case,
+ *              and the one a TTL shorter than the gap between turns produces.
+ *   - `none` — nothing was cached either way: below the model's cacheable
+ *              minimum, or a provider that doesn't cache at all.
+ */
+export type CrossTurnVerdict = "hit" | "miss" | "none";
+
+/**
+ * Fold a turn's per-request usage into cache stats. Returns undefined when
+ * the provider reported no iterations — the caller then logs nothing rather
+ * than inventing a verdict from aggregate totals it can't attribute.
+ */
+export function turnCacheStats(
+  iterations: readonly CacheIteration[] | undefined,
+): TurnCacheStats | undefined {
+  if (!iterations || iterations.length === 0) return undefined;
+  const first = iterations[0]!;
+  let totalRead = 0;
+  let totalWrite = 0;
+  for (const it of iterations) {
+    totalRead += it.cache_read_input_tokens ?? 0;
+    totalWrite += it.cache_creation_input_tokens ?? 0;
+  }
+  return {
+    modelRequests: iterations.length,
+    firstRead: first.cache_read_input_tokens ?? 0,
+    firstWrite: first.cache_creation_input_tokens ?? 0,
+    totalRead,
+    totalWrite,
+  };
+}
+
+/** Classify the turn's first request. See {@link CrossTurnVerdict}. */
+export function crossTurnVerdict(stats: TurnCacheStats): CrossTurnVerdict {
+  if (stats.firstRead > 0) return "hit";
+  if (stats.firstWrite > 0) return "miss";
+  return "none";
+}
+
+/**
+ * Compact suffix for the per-turn accounting line, e.g.
+ * `xturn=miss reqs=11 rw=8.0`. Deliberately terse and space-delimited so a
+ * week of logs can be parsed without a schema:
+ *
+ *   - `xturn` — the cross-turn verdict; the field that tracks cost.
+ *   - `reqs`  — model requests in the turn; explains a high aggregate hit
+ *               rate that isn't saving anything.
+ *   - `rw`    — total read ÷ total write. Above ~1 the turn amortised its
+ *               write; at or below it, the write dominated.
+ */
+export function formatTurnCache(stats: TurnCacheStats): string {
+  const parts = [
+    `xturn=${crossTurnVerdict(stats)}`,
+    `reqs=${stats.modelRequests}`,
+  ];
+  if (stats.totalWrite > 0) {
+    parts.push(`rw=${(stats.totalRead / stats.totalWrite).toFixed(1)}`);
+  }
+  return parts.join(" ");
+}
+
+// ── Lookback window ────────────────────────────────────────────────────────
+
+/**
+ * How far back a cache breakpoint searches for a prior entry, in content
+ * blocks. A turn that emits more than this can prevent the NEXT turn from
+ * finding any cache to read.
+ */
+export const CACHE_LOOKBACK_BLOCKS = 20;
+
+/**
+ * Rough content-block count for a turn from its tool-call count. Each tool
+ * call is a `tool_use` block plus a `tool_result` block, and the assistant
+ * text around them adds at least one more — so `2n + 1` is a floor, not an
+ * estimate. Used only to decide whether to warn, never to report a number.
+ */
+export function estimateTurnBlocks(toolCalls: number): number {
+  return Math.max(0, toolCalls) * 2 + 1;
+}
+
+/** True when a turn plausibly emitted more blocks than a breakpoint looks back. */
+export function exceedsLookbackWindow(toolCalls: number): boolean {
+  return estimateTurnBlocks(toolCalls) > CACHE_LOOKBACK_BLOCKS;
+}
+
+// ── Cacheable minimum ──────────────────────────────────────────────────────
+
+/**
+ * Minimum cacheable prefix, in tokens, by model. Below this nothing is
+ * cached and the API reports no error — `cache_creation_input_tokens` is
+ * simply 0.
+ *
+ * The floor is NOT monotonic across generations (512 on the newest models,
+ * 4096 on Opus 4.6 and Haiku 4.5), so it can't be inferred from a version
+ * number. Longest match wins, so `sonnet-4-6` is checked before `sonnet`.
+ *
+ * Bare aliases resolve only where Talon's catalog leaves no ambiguity:
+ * `haiku` is Haiku 4.5 (and carries the largest floor, making it the most
+ * likely to silently not cache). Ambiguous aliases — `opus`, `sonnet`,
+ * `default` — deliberately return undefined: a warning that fires on the
+ * wrong model teaches people to ignore warnings.
+ */
+const CACHE_MINIMUMS: readonly (readonly [string, number])[] = [
+  ["fable-5", 512],
+  ["mythos-5", 512],
+  ["opus-5", 512],
+  ["opus-4-8", 1024],
+  ["sonnet-5", 1024],
+  ["sonnet-4-6", 1024],
+  ["sonnet-4-5", 1024],
+  ["opus-4-1", 1024],
+  ["opus-4-7", 2048],
+  ["mythos-preview", 2048],
+  ["opus-4-6", 4096],
+  ["opus-4-5", 4096],
+  ["haiku-4-5", 4096],
+  ["haiku", 4096],
+];
+
+/**
+ * The cacheable-prefix floor for a model, or undefined when the model string
+ * doesn't unambiguously identify one.
+ */
+export function cacheMinimumTokens(model: string): number | undefined {
+  const m = model.toLowerCase();
+  let best: { key: string; min: number } | undefined;
+  for (const [key, min] of CACHE_MINIMUMS) {
+    if (!m.includes(key)) continue;
+    if (!best || key.length > best.key.length) best = { key, min };
+  }
+  return best?.min;
+}
+
+/** Cheap tokenizer-free estimate (~4 chars/token), matching soul/projector. */
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Warn when a prompt is too small to be cacheable on its model. No-op when
+ * the model's floor is unknown or the prompt clears it. `label` names the
+ * caller (e.g. `"dream"`) so the warning points somewhere.
+ */
+export function warnIfBelowCacheMinimum(
+  label: string,
+  model: string,
+  prompt: string,
+): void {
+  const min = cacheMinimumTokens(model);
+  if (min === undefined) return;
+  const estimated = estimateTokens(prompt);
+  if (estimated >= min) return;
+  logWarn(
+    "agent",
+    `[${label}] prompt ~${estimated} tokens is below ${model}'s ${min}-token ` +
+      `cacheable minimum — nothing will be cached for this run`,
+  );
+}
+
+// ── Tool-set fingerprint ───────────────────────────────────────────────────
+
+/**
+ * Per-chat fingerprint of the last tool set seen. Bounded so a long-lived
+ * process with many chats can't grow it without limit; eviction is
+ * insertion-ordered, and a false "changed" warning after eviction is
+ * cheaper than unbounded retention.
+ */
+const MAX_TRACKED_CHATS = 256;
+const lastToolSets = new Map<string, readonly string[]>();
+
+/** Stable fingerprint for a tool set: sorted, deduped names. */
+export function toolFingerprint(
+  builtinTools: readonly string[],
+  mcpServerNames: readonly string[],
+): readonly string[] {
+  return [
+    ...new Set([...builtinTools, ...mcpServerNames.map((n) => `mcp:${n}`)]),
+  ].sort();
+}
+
+/**
+ * Record this turn's tool set for a chat and warn when it differs from the
+ * previous turn's. Returns true when a change was detected.
+ *
+ * Tools render before the system prompt, so a mid-session change invalidates
+ * the system prompt and every cached message after it — the most expensive
+ * cache event available, and invisible in aggregate hit-rate numbers.
+ */
+export function noteToolFingerprint(
+  chatId: string,
+  fingerprint: readonly string[],
+): boolean {
+  const previous = lastToolSets.get(chatId);
+
+  if (lastToolSets.size >= MAX_TRACKED_CHATS && !previous) {
+    const oldest = lastToolSets.keys().next().value;
+    if (oldest !== undefined) lastToolSets.delete(oldest);
+  }
+  lastToolSets.set(chatId, fingerprint);
+
+  if (!previous) return false;
+  if (
+    previous.length === fingerprint.length &&
+    previous.every((t, i) => t === fingerprint[i])
+  ) {
+    return false;
+  }
+
+  const before = new Set(previous);
+  const after = new Set(fingerprint);
+  const added = fingerprint.filter((t) => !before.has(t));
+  const removed = previous.filter((t) => !after.has(t));
+  logWarn(
+    "agent",
+    `[${chatId}] tool set changed mid-session — invalidates the whole prompt ` +
+      `cache for this chat` +
+      (added.length ? ` (+${added.join(",")})` : "") +
+      (removed.length ? ` (-${removed.join(",")})` : ""),
+  );
+  return true;
+}
+
+/** Drop all tracked fingerprints (tests / explicit reset). */
+export function resetToolFingerprints(): void {
+  lastToolSets.clear();
+}

package/src/backend/shared/index.ts

@@ -68,6 +68,16 @@ export {
   type TokenUsageSnapshot,
 } from "./usage.js";
 
+// Only what is consumed THROUGH the barrel. Everything else in
+// cache-telemetry.ts is imported from the module directly, matching the
+// barrel discipline the prompt/ barrel was just trimmed to.
+export {
+  formatTurnCache,
+  estimateTurnBlocks,
+  exceedsLookbackWindow,
+  CACHE_LOOKBACK_BLOCKS,
+} from "./cache-telemetry.js";
+
 export {
   prepareSystemPrompt,
   appendBackendSuffix,

package/src/core/prompt/assemble.ts

@@ -16,8 +16,9 @@
  *   2. Core behaviour                       ~/.talon/prompts/custom.md,
  *                                           else base.md, else fallback
  *   3. Frontend capabilities                ~/.talon/prompts/<frontend>.md
- *   4. Persistent memory (size-capped)      prompts/system/persistent-memory.md
+ *   4. Persistent memory (ranked, capped)   prompts/system/persistent-memory.md
  *                                           wrapping ~/.talon/workspace/memory/memory.md
+ *                                           via memory-view.ts
  *   5. Memory recall + capability docs      prompts/system/{memory-recall,workspace,...}.md
  *   6. Plugin additions                     plugin.systemPrompt() contributions
  *   (7. Delivery contract — appended by the backend as its suffix,
@@ -57,6 +58,7 @@ import { dirs, files as pathFiles } from "../../util/paths.js";
 import { todayAndYesterday } from "../../util/time.js";
 import { log } from "../../util/log.js";
 import { loadSystemTemplate } from "./templates.js";
+import { renderMemoryView } from "./memory-view.js";
 import { renderWorkspaceListing } from "./workspace-listing.js";
 import { renderSkillsPrompt } from "../../storage/skill-store.js";
 import { renderStickerLibraryPrompt } from "../../storage/sticker-store.js";
@@ -92,17 +94,6 @@ export function joinSystemPromptParts(parts: SystemPromptParts): string {
   return `${parts.staticText}\n\n---\n\n${parts.dynamicText}`;
 }
 
-// ── Tunables ────────────────────────────────────────────────────────────────
-
-/**
- * Cap on how much of `memory.md` is injected into the static prompt.
- * Memory files grow without bound over months of use; injecting all
- * of it bloats EVERY session from its very first turn. 12k chars is
- * roughly 3k tokens — past that, the model gets the head of the file
- * plus a truncation pointer and can Read the rest on demand.
- */
-export const MEMORY_INJECT_MAX_CHARS = 12_000;
-
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
 function readOptionalFile(path: string): string {
@@ -114,23 +105,6 @@ function readOptionalFile(path: string): string {
   return "";
 }
 
-/**
- * Truncate memory content at the cap, snapping back to the previous
- * newline so the cut never lands mid-sentence. Returns the (possibly
- * shortened) content and whether truncation happened.
- */
-function capMemory(content: string): { text: string; truncated: boolean } {
-  if (content.length <= MEMORY_INJECT_MAX_CHARS) {
-    return { text: content, truncated: false };
-  }
-  const head = content.slice(0, MEMORY_INJECT_MAX_CHARS);
-  const lastNewline = head.lastIndexOf("\n");
-  return {
-    text: (lastNewline > 0 ? head.slice(0, lastNewline) : head).trimEnd(),
-    truncated: true,
-  };
-}
-
 let lastLoggedPromptKey = "";
 
 // ── Assembly ────────────────────────────────────────────────────────────────
@@ -194,17 +168,21 @@ export function assembleSystemPrompt(
   }
 
   // 4. Persistent memory — size-capped so a memory file that has grown
-  //    for months can't bloat every session from turn 0.
+  //    for months can't bloat every session from turn 0. Over the cap the
+  //    view ranks sections rather than head-slicing, so durable knowledge
+  //    isn't evicted by whatever happens to sit at the top of the file
+  //    (see prompt/memory-view.ts).
   const memory = readOptionalFile(pathFiles.memory);
   if (memory) {
-    const { text, truncated } = capMemory(memory);
+    const { text, truncated, omitted } = renderMemoryView(memory);
     staticParts.push(
       loadSystemTemplate("persistent-memory", {
         content: text,
         truncated: truncated ? "yes" : undefined,
+        omitted: omitted || undefined,
       }),
     );
-    loaded.push(truncated ? "memory(capped)" : "memory");
+    loaded.push(truncated ? "memory(ranked)" : "memory");
   }
 
   // 5. Package-owned behavioural and capability docs. The memory policy

package/src/core/prompt/index.ts

@@ -3,6 +3,7 @@
  *
  * One stop for everything system-prompt:
  *   - `assemble`          — section pipeline + static/dynamic split
+ *   - `memory-view`       — ranked selection of `memory.md` under a budget
  *   - `templates`         — package-owned `prompts/system/*.md` loader
  *   - `workspace-listing` — lazy workspace tree for the dynamic tail
  *

package/src/core/prompt/memory-view.ts

@@ -0,0 +1,304 @@
+/**
+ * Persistent-memory view — what the model actually sees of `memory.md`.
+ *
+ * `memory.md` grows without bound and only the first
+ * `MEMORY_INJECT_MAX_CHARS` reach the prompt. Head-slicing that file makes
+ * the cut positional while the content is not priority-ordered, so the
+ * *least* durable material evicts the most durable. Observed on the live
+ * deployment: a 23.6k-char file cut at line 46 of 113, where everything
+ * above the line was one facts block plus three near-duplicate
+ * `## Inbox / CI Watch (as of …, Run #N)` status snapshots, and
+ * `## Active Investigations` — with the root-cause analysis in it — fell
+ * below the cut and was never injected at all.
+ *
+ * So this module makes truncation a *selection* problem:
+ *
+ *   1. Split the file into `## ` sections (an `h3` stays with its parent).
+ *   2. Collapse "state families" — sections whose headings differ only by a
+ *      trailing timestamp / run number — down to the newest member. Three
+ *      CI-watch snapshots describing the same recurring failures are one
+ *      fact, not three.
+ *   3. Order by tier (directives → people → active work → general → status
+ *      → historical), stable within a tier.
+ *   4. Emit whole sections until the budget is spent, and name the ones
+ *      that didn't make it so the model knows to `Read` for them.
+ *
+ * Three deliberate constraints:
+ *
+ *   - **Under the cap, output is byte-identical to the input.** Reordering
+ *     only happens when the alternative is losing content, so deployments
+ *     whose memory still fits see no behaviour change and no prompt-cache
+ *     churn.
+ *   - **Surviving sections are emitted in file order**, not tier order. The
+ *     ranking decides *what* survives, not how it reads — and a
+ *     tier-ordered body would rewrite the prompt prefix every time a
+ *     section's heading changed tier.
+ *   - **If nothing fits, fall back to head-slicing.** A single section
+ *     larger than the whole budget must still give the model something
+ *     rather than an empty memory block.
+ */
+
+// ── Tunables ────────────────────────────────────────────────────────────────
+
+/**
+ * Cap on how much of `memory.md` is injected into the static prompt.
+ * Memory files grow without bound over months of use; injecting all of it
+ * bloats EVERY session from its very first turn. 12k chars is roughly 3k
+ * tokens — past that, the model gets the ranked selection below plus a
+ * pointer, and can Read the file on demand.
+ */
+export const MEMORY_INJECT_MAX_CHARS = 12_000;
+
+/** Cap on how many omitted section titles are named before eliding the rest. */
+const MAX_OMITTED_NAMED = 8;
+
+// ── Tiers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Section priority, most-durable first. `status` sits second-to-last because
+ * a snapshot is true *now* and false later — it is the content most safely
+ * dropped and most cheaply re-derived. `historical` is last for the mirror
+ * reason: it will never change again, so it is the least urgent to carry.
+ */
+const TIER_ORDER = [
+  "directive",
+  "people",
+  "active",
+  "general",
+  "status",
+  "historical",
+] as const;
+
+type Tier = (typeof TIER_ORDER)[number];
+
+const tier = (name: Tier): number => TIER_ORDER.indexOf(name);
+
+/**
+ * Heading classifiers. First match wins, so order is the policy: a heading
+ * reading "Active investigation status" is active work, not a snapshot.
+ * `general` is the unmatched default and ranks above `status` — a section
+ * nobody labelled is more likely durable knowledge than a dated snapshot.
+ */
+const MATCHERS: readonly { readonly tier: Tier; readonly match: RegExp }[] = [
+  {
+    tier: "historical",
+    match:
+      /\b(historical|history|archived?|superseded|resolved|closed|completed|past|old)\b/i,
+  },
+  {
+    tier: "directive",
+    match: /\b(directives?|preferences?|instructions?|rules?)\b/i,
+  },
+  {
+    tier: "active",
+    match:
+      /\b(active|current|investigations?|open|pending|todo|follow.?ups?|blocked|in.progress|priorit(?:y|ies)|goals?)\b/i,
+  },
+  {
+    tier: "people",
+    match: /\b(users?|people|person|contacts?|team|about)\b/i,
+  },
+  {
+    tier: "status",
+    match: /\b(as of|run #|status|health|watch|inbox|snapshot|report)\b/i,
+  },
+];
+
+const STATUS_TIER = tier("status");
+const GENERAL_TIER = tier("general");
+
+function classify(title: string): number {
+  for (const m of MATCHERS) {
+    if (m.match.test(title)) return tier(m.tier);
+  }
+  return GENERAL_TIER;
+}
+
+// ── Parsing ─────────────────────────────────────────────────────────────────
+
+type Section = {
+  /** Heading with markup and trailing qualifiers stripped — the display name. */
+  readonly title: string;
+  /** Whole section including its heading and any `###` children. */
+  readonly body: string;
+  /** Index in the original file, for stable ordering within a tier. */
+  readonly order: number;
+  readonly tier: number;
+  /** Key shared by every member of a state family (see `familyKey`). */
+  readonly family: string;
+  /** Recency score used to pick a family's survivor; higher is newer. */
+  readonly recency: string;
+};
+
+/** Strip `## ` markup and bold markers from a heading line. */
+function headingTitle(heading: string): string {
+  return heading
+    .replace(/^#+\s*/, "")
+    .replace(/\*\*/g, "")
+    .trim();
+}
+
+/**
+ * The family a section belongs to: its title minus temporal qualifiers.
+ * `Inbox / CI Watch (as of 2026-07-03, Run #134)` → `inbox / ci watch`. That
+ * parenthetical is exactly what makes each snapshot look unique while the
+ * underlying topic repeats, so removing it is what lets a family collapse.
+ */
+function familyKey(title: string): string {
+  return title
+    .replace(/\s*\([^)]*\)\s*$/, "")
+    .replace(/\s*[—–-]\s*(?:as of|run #).*$/i, "")
+    .trim()
+    .toLowerCase();
+}
+
+/**
+ * A sortable recency key: `<date>|<run>`, both fixed-width so a plain string
+ * compare orders correctly. Both fields are zero-filled when absent rather
+ * than left empty — an empty field would make the `|` separator the first
+ * character compared, and `|` sorts *above* every digit, which would rank an
+ * undated section as newer than a dated one. A heading with neither field
+ * scores lowest and falls back to file order, where the dream agent puts the
+ * newest section first.
+ */
+function recencyKey(heading: string): string {
+  const date = /(\d{4}-\d{2}-\d{2})/.exec(heading)?.[1] ?? "0000-00-00";
+  const run = /\brun\s*#\s*(\d+)/i.exec(heading)?.[1] ?? "0";
+  return `${date}|${run.padStart(10, "0")}`;
+}
+
+/**
+ * Split content into a leading preamble (the `#` title and anything before
+ * the first `## `) plus one entry per `## ` section. The split is on `## `
+ * only, so an `h3` travels with the section it belongs to.
+ */
+function parseSections(content: string): {
+  preamble: string;
+  sections: Section[];
+} {
+  const parts = content.split(/^(?=## )/m);
+  const first = parts[0] ?? "";
+  const preamble = first.startsWith("## ") ? "" : (parts.shift() ?? "");
+  const sections: Section[] = [];
+  for (const body of parts) {
+    if (!body.trim()) continue;
+    const heading = body.split("\n", 1)[0] ?? "";
+    const title = headingTitle(heading);
+    sections.push({
+      title,
+      body,
+      order: sections.length,
+      tier: classify(title),
+      family: familyKey(title),
+      recency: recencyKey(heading),
+    });
+  }
+  return { preamble, sections };
+}
+
+/**
+ * Keep one section per state family: the newest by `recency`, and on a tie
+ * the one that appeared first. Only the `status` tier collapses — two
+ * sections about people are two different people, not two snapshots of one.
+ */
+function collapseFamilies(sections: readonly Section[]): {
+  kept: Section[];
+  dropped: Section[];
+} {
+  const winners = new Map<string, Section>();
+  for (const s of sections) {
+    if (s.tier !== STATUS_TIER) continue;
+    const held = winners.get(s.family);
+    if (!held || s.recency > held.recency) winners.set(s.family, s);
+  }
+  const kept: Section[] = [];
+  const dropped: Section[] = [];
+  for (const s of sections) {
+    if (s.tier !== STATUS_TIER || winners.get(s.family) === s) kept.push(s);
+    else dropped.push(s);
+  }
+  return { kept, dropped };
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/** The memory block to inject, plus what had to be left out of it. */
+export type MemoryView = {
+  /** Text to render into the persistent-memory prompt section. */
+  text: string;
+  /** True when the file did not fit whole — drives the "Read for more" note. */
+  truncated: boolean;
+  /** Human-readable list of ranked-out sections, or "" when none. */
+  omitted: string;
+};
+
+/** Head-slice at the cap, snapping back to a newline so the cut isn't mid-line. */
+function headSlice(content: string, budget: number): string {
+  const head = content.slice(0, budget);
+  const lastNewline = head.lastIndexOf("\n");
+  return (lastNewline > 0 ? head.slice(0, lastNewline) : head).trimEnd();
+}
+
+/** Render omitted titles as one prose list, eliding a long tail. */
+function formatOmitted(titles: readonly string[]): string {
+  if (titles.length === 0) return "";
+  if (titles.length <= MAX_OMITTED_NAMED) return titles.join("; ");
+  const named = titles.slice(0, MAX_OMITTED_NAMED).join("; ");
+  return `${named}; and ${titles.length - MAX_OMITTED_NAMED} more`;
+}
+
+/**
+ * Render the injectable view of `memory.md`.
+ *
+ * Under the cap this is the identity function — same bytes in, same bytes
+ * out. Over the cap, sections are collapsed and ranked as described in the
+ * module docstring, and anything that didn't fit is named in `omitted`.
+ */
+export function renderMemoryView(
+  content: string,
+  budget: number = MEMORY_INJECT_MAX_CHARS,
+): MemoryView {
+  if (content.length <= budget) {
+    return { text: content, truncated: false, omitted: "" };
+  }
+
+  const { preamble, sections } = parseSections(content);
+  const { kept, dropped } = collapseFamilies(sections);
+
+  // Tier first, then original file order — stable within a tier so the
+  // author's own ordering survives wherever priority doesn't decide.
+  const ranked = [...kept].sort((a, b) => a.tier - b.tier || a.order - b.order);
+
+  const head = preamble.trimEnd();
+  let spent = head.length;
+  const chosen: Section[] = [];
+  const omitted: Section[] = [...dropped];
+  for (const s of ranked) {
+    const cost = s.body.trimEnd().length + 2; // body + section separator
+    if (spent + cost <= budget) {
+      spent += cost;
+      chosen.push(s);
+    } else {
+      omitted.push(s);
+    }
+  }
+
+  // Nothing fit — a single section is bigger than the whole budget. Degrade
+  // to the old behaviour rather than injecting an empty memory block.
+  if (chosen.length === 0) {
+    return { text: headSlice(content, budget), truncated: true, omitted: "" };
+  }
+
+  chosen.sort((a, b) => a.order - b.order);
+  const body = chosen.map((s) => s.body.trimEnd()).join("\n\n");
+
+  return {
+    text: head ? `${head}\n\n${body}` : body,
+    truncated: true,
+    omitted: formatOmitted(
+      omitted
+        .sort((a, b) => a.tier - b.tier || a.order - b.order)
+        .map((s) => s.title),
+    ),
+  };
+}