talon-agent 3.7.0 → 3.8.1

package/src/core/agent-runtime/capabilities.ts

@@ -35,54 +35,16 @@ import type {
 
 // ── Run parameters ──────────────────────────────────────────────────────────
 
-/**
- * Provenance trust level of a retrieved memory item, per the memory-poisoning
- * threat model (#373). Only the first three levels are ever eligible for
- * automatic injection; `user_claim` and `group_chat` content must stay
- * pull-only (explicit search), never auto-injected.
- */
-export type RetrievedMemoryTrustLevel =
-  | "dylan_direct" // stated by the operator in a verified DM
-  | "bot_inferred" // inferred by the bot from code/docs/verified primary source
-  | "heartbeat_synthesis" // synthesized in a background run, no external input
-  | "user_claim" // claimed by a non-operator user, unverified
-  | "group_chat"; // sourced from group chat content
-
-/** One retrieved memory fragment with its provenance. */
-export interface RetrievedMemoryItem {
-  /** Palace wing (top-level category), e.g. "technical". */
-  wing: string;
-  /** Palace room within the wing, when known. */
-  room?: string;
-  /** Source file locator, when known (e.g. "memory-phase-b.md"). */
-  sourceFile?: string;
-  /** The retrieved text fragment. */
-  text: string;
-  /** Retrieval relevance score, when the retriever provides one. */
-  score?: number;
-  /** Provenance trust level; absent means unknown (treat as untrusted). */
-  trustLevel?: RetrievedMemoryTrustLevel;
-}
-
-/**
- * A bounded, sanitized slice of long-term memory retrieved for one turn.
- * This is DYNAMIC turn context: it is injected into the live user prompt by
- * the backend prompt formatter and must never enter `prepareSystemPrompt()`
- * output, frozen prompt snapshots, plugin prompt additions, or backend
- * `system` fields — that would break the prompt-cache contract.
- */
-export interface RetrievedMemory {
-  source: "mempalace";
-  /** The (possibly trimmed) query the retriever ran. */
-  query: string;
-  items: RetrievedMemoryItem[];
-}
-
 /**
  * Parameters for a chat turn. `model` is a resolved `ModelRef`,
  * carrying everything the backend needs to identify the model and
  * render the resulting reply. Streaming callbacks aren't part of
  * this shape — backends emit `AgentEvent`s.
+ *
+ * Long-term memory is deliberately NOT part of this shape. `memory.md` is
+ * loaded once into the cached system prompt (`core/prompt/assemble.ts`);
+ * anything deeper the model searches for itself with the MemPalace tools.
+ * Nothing is auto-injected into a turn.
  */
 export interface ChatRunParams {
   chatId: string;
@@ -92,12 +54,6 @@ export interface ChatRunParams {
   isGroup?: boolean;
   /** Provider message ID. Telegram is numeric; Discord snowflakes are strings. */
   messageId?: number | string;
-  /**
-   * Optional pre-retrieved memory slice for this turn. Backends fold it into
-   * the live user prompt (after the cached system prompt), never into
-   * `system` — see `formatPromptWithRetrievedMemory`.
-   */
-  retrievedMemory?: RetrievedMemory;
 }
 
 // ── Catalog types ───────────────────────────────────────────────────────────

package/src/core/background/dream.ts

@@ -19,10 +19,11 @@ import { importLegacyJson } from "../../storage/legacy-import.js";
 import { readPromptAsset } from "#prompt-assets";
 import { log, logError, logWarn } from "../../util/log.js";
 import { getDefaultModel } from "../models/catalog.js";
-import type { OneShotAgentParams } from "../types.js";
+import type { OneShotAgentParams, ReasoningEffortLevel } from "../types.js";
 import type { Backend } from "../agent-runtime/capabilities.js";
 import { getSoul } from "../soul/service.js";
 import { taskTable } from "../tasks/index.js";
+import { resolveBackgroundEffort } from "./effort.js";
 import { FailureBackoff } from "./failure-backoff.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
@@ -65,6 +66,8 @@ export const dreamFailureBackoff = new FailureBackoff();
 let configRef: {
   model?: string;
   dreamModel?: string;
+  /** Reasoning effort for dream runs. Undefined = backend/model default. */
+  dreamEffort?: ReasoningEffortLevel;
   workspace?: string;
   /** When false, `maybeStartDream` never fires (config `dream: false`). */
   enabled?: boolean;
@@ -86,6 +89,12 @@ export function initDream(cfg: {
   model?: string;
   /** Override model for dream consolidation (e.g. a cheaper model). Falls back to main model. */
   dreamModel?: string;
+  /**
+   * Reasoning effort for dream consolidation (config `dreamEffort`). Unset
+   * leaves the backend/model default in place. Ignored by backends with no
+   * reasoning knob (Kilo, OpenCode).
+   */
+  dreamEffort?: ReasoningEffortLevel;
   workspace?: string;
   /** Gate for automatic dream runs — config `dream` flag. Defaults to enabled. */
   enabled?: boolean;
@@ -242,13 +251,28 @@ If commands fail, log the error and continue — this stage is optional.`
     );
   }
 
+  // Resolved against the dream backend's catalog — an effort level the model
+  // doesn't offer is dropped with a reason instead of reaching the SDK.
+  const effort = await resolveBackgroundEffort({
+    requested: configRef.dreamEffort,
+    model,
+    backend,
+  });
+  if (effort.dropped) {
+    logWarn("dream", effort.dropped);
+  }
+
   // Set up dream log file
   const dreamLogFile = createDreamLogFile();
   appendDreamLog(dreamLogFile, `# Dream Run — ${new Date().toISOString()}\n`);
   appendDreamLog(
     dreamLogFile,
-    `**Trigger:** last_run=${lastRunIso}, model=${model}\n`,
+    `**Trigger:** last_run=${lastRunIso}, model=${model}` +
+      `${effort.effort ? `, effort=${effort.effort}` : ""}\n`,
   );
+  if (effort.dropped) {
+    appendDreamLog(dreamLogFile, `**Effort:** ${effort.dropped}\n`);
+  }
   appendDreamLog(
     dreamLogFile,
     `**Prompt:**\n\`\`\`\n${prompt}\n\`\`\`\n\n---\n`,
@@ -272,6 +296,7 @@ If commands fail, log the error and continue — this stage is optional.`
     systemPrompt,
     workspace,
     model,
+    ...(effort.effort ? { reasoningEffort: effort.effort } : {}),
     contextLabel: "dream",
     abortController,
     // appendDreamLog is sync (writeFileSync) — wrap to satisfy the async

package/src/core/background/effort.ts

@@ -0,0 +1,80 @@
+/**
+ * Reasoning-effort resolution for background runs (heartbeat, dream).
+ *
+ * Both background agents take an effort level from config
+ * (`heartbeatEffort` / `dreamEffort`). Two separate questions hide behind
+ * "apply that level", and they belong to different layers:
+ *
+ *   1. *Is the level available on this model?* — a model-capability
+ *      question. Every backend catalog already answers it through the
+ *      `models.getRawModelInfo` capability (`supportedReasoningLevels`),
+ *      which is the same channel the frontends' effort pickers read. So it
+ *      is answered here, once, against the `Backend` abstraction.
+ *
+ *   2. *How is the level expressed to the provider?* — Claude thinking
+ *      options, Codex `modelReasoningEffort`, nothing at all for
+ *      Kilo/OpenCode. That is adapter work and stays inside each backend's
+ *      one-shot runner.
+ *
+ * Keeping (1) here is what stops four one-shot runners from each growing
+ * their own copy of the same catalog lookup.
+ */
+
+import type { Backend } from "../agent-runtime/capabilities.js";
+import type { ReasoningEffortLevel } from "../types.js";
+import {
+  normalizeReasoningLevels,
+  supportsReasoningLevel,
+} from "../models/reasoning-levels.js";
+
+export type BackgroundEffortResolution = {
+  /** The level to pass to the backend, or undefined to use its default. */
+  effort?: ReasoningEffortLevel;
+  /**
+   * Set when a configured level was discarded — a log-ready explanation of
+   * what was asked for and why the run proceeds without it. A dropped level
+   * never fails the run: a stale effort setting shouldn't cost an operator
+   * their hourly heartbeat.
+   */
+  dropped?: string;
+};
+
+/**
+ * Resolve the effort level a background run should ask for.
+ *
+ * Unset config → `{}` (backend/model default, i.e. what background runs did
+ * before the knob existed). A backend with no catalog capability, an
+ * unreachable catalog, or a model that reports no level metadata all pass
+ * the level through untouched: absent metadata is not evidence that the
+ * level is unsupported, and the adapter still has the final say.
+ */
+export async function resolveBackgroundEffort(params: {
+  requested: ReasoningEffortLevel | undefined;
+  model: string;
+  backend: Backend | null;
+}): Promise<BackgroundEffortResolution> {
+  const { requested, model, backend } = params;
+  if (!requested) return {};
+
+  const catalog = backend?.models;
+  if (!catalog) return { effort: requested };
+
+  let info;
+  try {
+    info = await catalog.getRawModelInfo(model);
+  } catch {
+    return { effort: requested }; // catalog unavailable — don't second-guess
+  }
+
+  const levels = normalizeReasoningLevels(info?.supportedReasoningLevels);
+  if (levels.length === 0) return { effort: requested };
+
+  if (!supportsReasoningLevel(requested, levels)) {
+    return {
+      dropped:
+        `configured effort "${requested}" is not available on "${model}" ` +
+        `(supports: ${levels.join(", ")}) — running the model default`,
+    };
+  }
+  return { effort: requested };
+}

package/src/core/background/heartbeat/agent.ts

@@ -14,6 +14,7 @@ import { loadSystemTemplate } from "../../prompt/templates.js";
 import { formatGoal, getOpenGoals } from "../../../storage/goal-store.js";
 import { taskTable } from "../../tasks/index.js";
 import type { OneShotAgentParams } from "../../types.js";
+import { resolveBackgroundEffort } from "../effort.js";
 import { hb } from "./state.js";
 
 const DEFAULT_HEARTBEAT_TIMEOUT_MS = 10 * 60 * 1000; // 10-minute soft cap
@@ -164,6 +165,18 @@ export async function runHeartbeatAgent(
     );
   }
 
+  // Effort is resolved against the heartbeat backend's catalog, not just
+  // copied from config — a level the model doesn't offer is dropped with a
+  // reason rather than handed to the SDK.
+  const effort = await resolveBackgroundEffort({
+    requested: config.heartbeatEffort,
+    model,
+    backend,
+  });
+  if (effort.dropped) {
+    logWarn("heartbeat", effort.dropped);
+  }
+
   // Set up heartbeat log file
   const heartbeatLogFile = await createHeartbeatLogFile();
   await appendHeartbeatLog(
@@ -172,8 +185,15 @@ export async function runHeartbeatAgent(
   );
   await appendHeartbeatLog(
     heartbeatLogFile,
-    `**Trigger:** ${lastRunIso === "never" ? "first run" : `last_run=${lastRunIso}`}, model=${model}\n`,
+    `**Trigger:** ${lastRunIso === "never" ? "first run" : `last_run=${lastRunIso}`}, model=${model}` +
+      `${effort.effort ? `, effort=${effort.effort}` : ""}\n`,
   );
+  if (effort.dropped) {
+    await appendHeartbeatLog(
+      heartbeatLogFile,
+      `**Effort:** ${effort.dropped}\n`,
+    );
+  }
   await appendHeartbeatLog(
     heartbeatLogFile,
     `**Prompt:**\n\`\`\`\n${prompt}\n\`\`\`\n\n---\n`,
@@ -197,6 +217,7 @@ export async function runHeartbeatAgent(
     systemPrompt: buildHeartbeatSystemPrompt(),
     workspace,
     model,
+    ...(effort.effort ? { reasoningEffort: effort.effort } : {}),
     contextLabel: "heartbeat",
     abortController,
     appendLog: (text) => appendHeartbeatLog(heartbeatLogFile, text),

package/src/core/background/heartbeat/state.ts

@@ -10,6 +10,7 @@ import { files as pathFiles } from "../../../util/paths.js";
 import { kvGet, kvSet } from "../../../storage/kv.js";
 import { importLegacyJson } from "../../../storage/legacy-import.js";
 import type { Backend } from "../../agent-runtime/capabilities.js";
+import type { ReasoningEffortLevel } from "../../types.js";
 import { FailureBackoff } from "../failure-backoff.js";
 
 export type HeartbeatState = {
@@ -28,6 +29,12 @@ export type HeartbeatState = {
 export type HeartbeatConfig = {
   model?: string;
   heartbeatModel?: string;
+  /**
+   * Reasoning effort for heartbeat runs (config `heartbeatEffort`).
+   * Undefined = backend/model default. Passed straight through to the
+   * one-shot params; backends without a reasoning knob ignore it.
+   */
+  heartbeatEffort?: ReasoningEffortLevel;
   workspace?: string;
   /**
    * Accessor for the active backend — invoked each time a heartbeat fires so

package/src/core/engine/model-audit.ts

@@ -20,14 +20,20 @@
 
 import type { Backend } from "../agent-runtime/capabilities.js";
 import type { TalonConfig } from "../../util/config.js";
+import type { ReasoningEffortLevel } from "../types.js";
+import {
+  normalizeReasoningLevels,
+  supportsReasoningLevel,
+} from "../models/reasoning-levels.js";
 
 export type ModelAuditRole = "chat" | "heartbeat" | "dream";
 
 export type ModelAuditFinding = {
   role: ModelAuditRole;
   backendId: string;
+  /** The config value the finding is about — a model id, or an effort level for `unsupported-effort`. */
   configured: string;
-  kind: "missing" | "ambiguous";
+  kind: "missing" | "ambiguous" | "unsupported-effort";
   /** Human-readable, log-ready description with the fix. */
   message: string;
 };
@@ -39,6 +45,15 @@ const CONFIG_KEY: Record<ModelAuditRole, string> = {
   dream: "dreamModel",
 };
 
+/**
+ * Effort config keys, for the roles that have one. Chat effort is a
+ * per-chat setting (`/settings`), not config, so it isn't audited here.
+ */
+const EFFORT_KEY: Partial<Record<ModelAuditRole, string>> = {
+  heartbeat: "heartbeatEffort",
+  dream: "dreamEffort",
+};
+
 /**
  * Audit each role's configured model against its backend's catalog.
  *
@@ -55,22 +70,25 @@ export async function auditConfiguredModels(
     role: ModelAuditRole;
     model: string | undefined;
     backendId: string;
+    effort?: ReasoningEffortLevel;
   }> = [
     { role: "chat", model: config.model, backendId: config.backend },
     {
       role: "heartbeat",
       model: config.heartbeatModel,
       backendId: config.heartbeatBackend ?? config.backend,
+      effort: config.heartbeatEffort,
     },
     {
       role: "dream",
       model: config.dreamModel,
       backendId: config.dreamBackend ?? config.backend,
+      effort: config.dreamEffort,
     },
   ];
 
   const findings: ModelAuditFinding[] = [];
-  for (const { role, model, backendId } of targets) {
+  for (const { role, model, backendId, effort } of targets) {
     if (!model || model === "default") continue;
 
     let backend: Backend | undefined;
@@ -115,7 +133,56 @@ export async function auditConfiguredModels(
           `"${backendId}" (matches: ${names}) — pin an exact id in ` +
           `"${CONFIG_KEY[role]}" in config.json.`,
       });
+    } else if (resolution.kind === "exact") {
+      const finding = auditEffort(
+        role,
+        backendId,
+        effort,
+        resolution.model.supportedReasoningLevels,
+      );
+      if (finding) findings.push(finding);
     }
   }
   return findings;
 }
+
+/**
+ * Check a role's configured effort level against what the resolved model
+ * advertises.
+ *
+ * Same "silently runs something else" failure mode as a withdrawn model:
+ * an effort the model doesn't offer is dropped at run time, and without
+ * this the operator only learns that from a heartbeat log up to an hour
+ * later (up to twelve, for dream).
+ *
+ * Returns undefined — no finding — whenever the answer isn't knowable:
+ * no effort configured, no role-level effort key, or a model that reports
+ * no level metadata at all (absent metadata is not evidence of absence).
+ * Note this only runs for roles with a PINNED model; an effort set against
+ * an unpinned model can't be checked because there's no id to resolve.
+ */
+function auditEffort(
+  role: ModelAuditRole,
+  backendId: string,
+  effort: ReasoningEffortLevel | undefined,
+  advertised: readonly ReasoningEffortLevel[] | undefined,
+): ModelAuditFinding | undefined {
+  const key = EFFORT_KEY[role];
+  if (!effort || !key) return undefined;
+
+  const levels = normalizeReasoningLevels(advertised);
+  if (levels.length === 0) return undefined;
+  if (supportsReasoningLevel(effort, levels)) return undefined;
+
+  return {
+    role,
+    backendId,
+    configured: effort,
+    kind: "unsupported-effort",
+    message:
+      `${role}: configured effort "${effort}" is NOT available on the ` +
+      `model pinned for this role on backend "${backendId}" ` +
+      `(supports: ${levels.join(", ")}) — runs will use the model default. ` +
+      `Update "${key}" in config.json.`,
+  };
+}

package/src/core/errors.ts

@@ -60,6 +60,68 @@ export class TalonError extends Error {
   }
 }
 
+// ── Transport-failure detection ─────────────────────────────────────────────
+
+/**
+ * Node / undici error codes that mean "the connection failed, try again".
+ *
+ * Codes beat message text: they're stable across Node versions and
+ * locales, and undici in particular throws bare `TypeError: terminated`
+ * / `TypeError: fetch failed` whose message says nothing while the
+ * `code` on the cause chain says everything.
+ *
+ * `ENOTFOUND` is deliberately absent — a DNS name that doesn't resolve
+ * is a config error, not a blip. `EAI_AGAIN` (temporary resolver
+ * failure) IS here, because that one does clear.
+ */
+const RETRYABLE_TRANSPORT_CODES: ReadonlySet<string> = new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ECONNABORTED",
+  "EPIPE",
+  "ETIMEDOUT",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENETDOWN",
+  "EAI_AGAIN",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_SOCKET",
+  "ERR_STREAM_PREMATURE_CLOSE",
+  "ERR_SOCKET_CONNECTION_TIMEOUT",
+]);
+
+/**
+ * Transient transport failures that surface as prose with no usable
+ * `code` — Node's own `socket hang up`, undici's `other side closed` /
+ * `Premature close`, and the named 5xx bodies proxies return as text.
+ *
+ * `timeout`/`timed out` is here but bare `abort` deliberately is NOT: a
+ * user interrupt (`controller.abort()` → "This operation was aborted")
+ * must stay non-retryable, or cancelling a turn would restart it.
+ * `AbortSignal.timeout()` says "aborted due to timeout" and is caught by
+ * the timeout half, which is the distinction we want.
+ */
+const TRANSIENT_TRANSPORT_RE =
+  /socket hang up|other side closed|premature close|connection (?:closed|reset|lost)|timed out|time-?out|bad gateway|service unavailable|gateway time-?out|internal server error|upstream connect error|server disconnected/i;
+
+/**
+ * Walk the `cause` chain collecting `code` / `errno` / `name` values.
+ * undici nests the real fault one or two levels down (`TypeError: fetch
+ * failed` → `cause: Error { code: 'ECONNREFUSED' }`), so a shallow look
+ * at the thrown object misses it entirely.
+ */
+function errorCodes(err: unknown, depth = 0): string[] {
+  if (depth > 5 || err === null || typeof err !== "object") return [];
+  const e = err as { code?: unknown; errno?: unknown; cause?: unknown };
+  const codes: string[] = [];
+  if (typeof e.code === "string") codes.push(e.code);
+  if (typeof e.errno === "string") codes.push(e.errno);
+  codes.push(...errorCodes(e.cause, depth + 1));
+  return codes;
+}
+
 // ── Classify any error ──────────────────────────────────────────────────────
 
 /**
@@ -115,6 +177,27 @@ export function classify(err: unknown): TalonError {
     });
   }
 
+  // Transport failure by CODE, before any prose matching. undici wraps
+  // the real fault ("TypeError: fetch failed" → cause.code) so the
+  // message alone is often empty of signal while the code is decisive.
+  //
+  // `TimeoutError` (what AbortSignal.timeout throws) is a transient
+  // deadline and retries. `AbortError` is NOT handled here on purpose —
+  // it means a user interrupt, and retrying a cancelled turn would
+  // restart work the user just stopped.
+  const errName = err instanceof Error ? err.name : "";
+  const transportCode = errorCodes(err).find((code) =>
+    RETRYABLE_TRANSPORT_CODES.has(code),
+  );
+  if (transportCode !== undefined || errName === "TimeoutError") {
+    return new TalonError(msg, {
+      reason: "network",
+      retryable: true,
+      retryAfterMs: 2_000,
+      cause,
+    });
+  }
+
   // Overloaded / capacity
   if (/overloaded|503|capacity/i.test(msg)) {
     return new TalonError(msg, {
@@ -126,11 +209,19 @@ export function classify(err: unknown): TalonError {
     });
   }
 
-  // Network errors
+  // Network errors — codes echoed into the message text (a stringified
+  // cause, a provider wrapping the errno into prose), plus the
+  // code-less transient shapes in TRANSIENT_TRANSPORT_RE.
+  //
+  // The prose half only applies when NO HTTP status was found. A real
+  // status is the stronger signal and its own branches below own it:
+  // "500 Internal Server Error" must stay `overloaded` carrying
+  // status 500, not become a status-less `network`.
   if (
-    /network|ECONNREFUSED|ECONNRESET|ECONNABORTED|ETIMEDOUT|ENOTFOUND|fetch failed|connection reset/i.test(
+    /network|ECONNREFUSED|ECONNRESET|ECONNABORTED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EPIPE|UND_ERR_|fetch failed|connection reset/i.test(
       msg,
-    )
+    ) ||
+    (status === undefined && TRANSIENT_TRANSPORT_RE.test(msg))
   ) {
     return new TalonError(msg, {
       reason: "network",
@@ -140,6 +231,19 @@ export function classify(err: unknown): TalonError {
     });
   }
 
+  // 408 Request Timeout — a transient deadline like any other, but it
+  // is neither 4xx-terminal nor 5xx, so it used to fall through to
+  // `unknown`/non-retryable and strand the request.
+  if (status === 408) {
+    return new TalonError(msg, {
+      reason: "network",
+      retryable: true,
+      status: 408,
+      retryAfterMs: 2_000,
+      cause,
+    });
+  }
+
   // Session expired
   if (/session.*expired|expired.*session|invalid.*resume/i.test(msg)) {
     return new TalonError(msg, {

package/src/core/models/reasoning-levels.ts

@@ -1,13 +1,24 @@
 import type { ReasoningEffortLevel } from "../types.js";
 
+/**
+ * Ascending ladder, weakest reasoning first. This is the ONLY ordering in
+ * the codebase: `normalizeReasoningLevels` re-sorts a model's advertised
+ * levels through it, so every effort picker (Telegram, Discord, native)
+ * renders in this sequence.
+ *
+ * `xhigh` (Codex's ceiling) sits below `max` (Claude's ceiling) so the row
+ * reads low → medium → high → xhigh → max. A single model advertises one
+ * ceiling or the other, never both, so their relative position only ever
+ * matters for how the ladder reads.
+ */
 export const REASONING_LEVEL_ORDER: ReasoningEffortLevel[] = [
   "off",
   "minimal",
   "low",
   "medium",
   "high",
-  "max",
   "xhigh",
+  "max",
 ];
 
 export const REASONING_LEVEL_LABELS: Record<ReasoningEffortLevel, string> = {
@@ -16,8 +27,8 @@ export const REASONING_LEVEL_LABELS: Record<ReasoningEffortLevel, string> = {
   low: "Low",
   medium: "Med",
   high: "High",
-  max: "Max",
   xhigh: "XHigh",
+  max: "Max",
 };
 
 export const REASONING_LEVEL_DESCRIPTIONS: Record<
@@ -29,8 +40,8 @@ export const REASONING_LEVEL_DESCRIPTIONS: Record<
   low: "short reasoning pass",
   medium: "balanced reasoning",
   high: "deeper reasoning, slower",
-  max: "maximum Claude reasoning budget",
   xhigh: "maximum Codex reasoning budget",
+  max: "maximum Claude reasoning budget",
   adaptive: "use the model/backend default",
 };
 

package/src/core/prompt/assemble.ts

@@ -18,7 +18,7 @@
  *   3. Frontend capabilities                ~/.talon/prompts/<frontend>.md
  *   4. Persistent memory (size-capped)      prompts/system/persistent-memory.md
  *                                           wrapping ~/.talon/workspace/memory/memory.md
- *   5. Workspace / cron / triggers docs     prompts/system/{workspace,cron,triggers}.md
+ *   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,
  *       AFTER plugins, so it is the last thing the model reads.
@@ -207,11 +207,14 @@ export function assembleSystemPrompt(
     loaded.push(truncated ? "memory(capped)" : "memory");
   }
 
-  // 5. Capability docs — workspace layout, cron, triggers, goals,
-  //    skills. Concise by design: per-tool protocols and examples
-  //    live in the MCP tool descriptions, which the model also has
-  //    in context.
+  // 5. Package-owned behavioural and capability docs. The memory policy
+  //    is deliberately package-owned so custom identity/base prompts cannot
+  //    remove recall-before-asking or adaptive persistence behaviour.
+  //    Provider-specific additions follow in step 6 and become canonical
+  //    when their tools are available; otherwise the policy falls back to
+  //    memory.md + daily notes.
   staticParts.push(
+    loadSystemTemplate("memory-recall"),
     loadSystemTemplate("workspace"),
     loadSystemTemplate("cron"),
     loadSystemTemplate("triggers"),