talon-agent 3.6.3 → 3.8.0

package/README.md

@@ -385,6 +385,10 @@ Config file: `~/.talon/config.json`
 | `pulse`                    | `true`       | Periodic group engagement                                                                                               |
 | `heartbeat`                | `false`      | Background maintenance agent                                                                                            |
 | `heartbeatIntervalMinutes` | `60`         | Heartbeat interval                                                                                                      |
+| `heartbeatModel`           | ---          | Model for the heartbeat agent (falls back to `model`)                                                                   |
+| `heartbeatEffort`          | ---          | Reasoning effort for the heartbeat agent: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Unset = the model's own default |
+| `dreamModel`               | ---          | Model for dream / memory consolidation (falls back to `model`)                                                          |
+| `dreamEffort`              | ---          | Reasoning effort for the dream agent — same levels as `heartbeatEffort`                                                 |
 | `braveApiKey`              | ---          | Brave Search API key                                                                                                    |
 | `timezone`                 | ---          | IANA timezone (e.g. `"Europe/London"`)                                                                                  |
 | `plugins`                  | `[]`         | External plugin packages                                                                                                |
@@ -398,6 +402,18 @@ Config file: `~/.talon/config.json`
 | `mempalace`                | ---          | Legacy MemPalace plugin config (prefer `memory`)                                                                        |
 | `playwright`               | ---          | Playwright plugin config (see above)                                                                                    |
 
+### Background reasoning effort
+
+`heartbeatEffort` / `dreamEffort` set how hard the background agents think —
+useful when you want unattended goal work to reason harder than a chat turn,
+or hourly heartbeats to stay cheap. Chat effort stays per-chat (`/settings`).
+
+Which levels a model accepts comes from its catalog entry, so the usable set
+differs per model (`max` is Claude's ceiling, `xhigh` is Codex's). A level the
+model doesn't offer is dropped — the run proceeds on the model default, the
+reason is written to the run log, and the boot-time model audit warns about it.
+Backends with no reasoning knob at all (Kilo, OpenCode) ignore the setting.
+
 ---
 
 ## Terminal Mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.6.3",
+  "version": "3.8.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -105,7 +105,7 @@
     "@openai/agents": "^0.13.0",
     "@openai/codex-sdk": "^0.145.0",
     "@opencode-ai/sdk": "^1.17.4",
-    "@playwright/mcp": "0.0.56",
+    "@playwright/mcp": "0.0.78",
     "@types/cross-spawn": "^6.0.6",
     "big-integer": "^1.6.52",
     "cheerio": "^1.2.0",

package/prompts/README.md

@@ -16,7 +16,7 @@ placed after the cache boundary):
 | 2   | Core behaviour        | `custom.md` (replaces `base.md` when present)                          | static        |
 | 3   | Frontend capabilities | `<frontend>.md` (telegram / discord / teams / terminal / native)       | static        |
 | 4   | Persistent memory     | `system/persistent-memory.md` wrapping `memory/memory.md`, size-capped | static        |
-| 5   | Capability docs       | `system/workspace.md`, `system/cron.md`, `system/triggers.md`          | static        |
+| 5   | Memory + capabilities | `system/memory-recall.md`, workspace, cron, triggers, goals, skills    | static        |
 | 6   | Plugin additions      | each plugin's `systemPrompt()` contribution                            | static        |
 | 7   | **Delivery contract** | `system/contract-*.md`, appended by the **backend** as its suffix      | static (tail) |
 | 8   | Daily-memory pointer  | `system/daily-memory.md` (names today's file)                          | dynamic       |
@@ -42,7 +42,7 @@ when a backend has no native "skills" feature.
 **User-editable prompts** (everything at the top level of this directory:
 `identity.md`, `base.md`, `custom.md`, `telegram.md`, `discord.md`,
 `teams.md`, `terminal.md`, `native.md`, `heartbeat.md`, `dream.md`,
-`mempalace.md`) are
+`mempalace.md`, `mem0.md`) are
 seeded into `~/.talon/prompts/` on first run and read from there.
 Seeding is upgrade-aware (dpkg-conffile semantics, tracked via a
 `.seeded.json` hash manifest next to the seeded files): a file the user
@@ -70,6 +70,14 @@ User-editable prompts are NOT Liquid: their consumers substitute
 `{{var}}` placeholders with plain string replacement, so a user edit
 can never break prompt assembly with a template syntax error.
 
+`system/memory-recall.md` is the provider-neutral continuity policy. It guides
+agents to make a proportionate, thorough attempt across relevant memory,
+workspace, log, and connected sources before asking a user to repeat
+information, and to persist new information. When a memory plugin is enabled,
+its prompt addition follows this section and names the preferred provider and
+exact tools; without one, the policy falls back to `memory/memory.md` plus
+daily notes.
+
 ## The delivery contract (response flow)
 
 How a reply reaches the user is a property of the **backend**, not the

package/prompts/dream.md

@@ -23,7 +23,8 @@ You primarily use filesystem tools (Read, Write, Edit, Bash, Glob, Grep). Do NOT
   - Corrections to previously held beliefs
   - Operational patterns (e.g. who stays up late, who prefers what tools)
   - Project context changes inferred from the conversation (e.g. new repos, shifted priorities)
-- Be selective — only extract genuinely new or updated information
+- Capture every genuinely new or updated piece of information; avoid
+  duplicating facts already represented in memory
 
 ### Stage 3 — Consolidate
 
@@ -38,8 +39,9 @@ You primarily use filesystem tools (Read, Write, Edit, Bash, Glob, Grep). Do NOT
 ### Stage 4 — Prune
 
 - Remove entries that have been explicitly contradicted
-- Remove entries that are clearly stale or irrelevant
-- Do NOT remove entries just because they're old — only remove if wrong or superseded
+- Remove entries that are clearly superseded
+- Do NOT remove entries just because they're old or seem unimportant — only
+  remove information that is wrong or replaced by a newer version
 - Write the updated memory.md back to `{{memoryFile}}`
 
 ### Stage 5 — Mine to MemPalace & Write Diary (optional)

package/prompts/heartbeat.md

@@ -32,7 +32,7 @@ For each goal:
 3. Record every advance with `update_goal(goal_id=..., progress_note=..., chat_id=<the goal's chat>)`. The `chat_id` parameter is REQUIRED in heartbeat mode — use the chat id shown next to the goal. Keep notes short and concrete: what was done, what was learned, what's blocked.
 4. When a goal's objective is achieved, set `status="completed"` and send a short, high-signal message to the goal's chat (explicit `chat_id` required). If a goal has become impossible or moot, set `status="abandoned"` with a note explaining why.
 5. If nothing can be done on a goal right now, skip it silently — do not write filler progress notes.
-6. If MemPalace tools are available: `mempalace_search` for context relevant to a goal before working on it, and store durable learnings afterward (`mempalace_add_drawer` / `mempalace_kg_add`).
+6. If MemPalace tools are available: `mempalace_search` for context relevant to a goal before working on it, and store new information learned while working (`mempalace_add_drawer` / `mempalace_kg_add`).
 
 ## Instructions
 

package/prompts/identity.md

@@ -33,4 +33,4 @@ When a filesystem-capable tool is available, persist the answers to `~/.talon/wo
 
 ## Memory
 
-When you learn something worth keeping — who people are, how they like to work, what they're building, decisions and facts that should outlive this session — persist it to `~/.talon/workspace/memory/memory.md` (when a filesystem-capable tool is available for this backend; otherwise hold it in working memory for the conversation and don't pretend to save). The test is simple: would future-you be glad this was written down? Update memory quietly as conversations happen — no announcements — and keep the file organized, current, and free of trivia.
+When you learn new information — who people are, how they like to work, what they're building, decisions, facts, and surrounding context — follow the Memory and Recall policy in this prompt. Use the configured long-term-memory provider when one is available; otherwise use the workspace memory files.

package/prompts/mem0.md

@@ -2,12 +2,14 @@
 
 You have access to mem0 long-term memory via MCP tools. mem0 extracts durable facts from what you store and retrieves them by semantic search. All memories are filed under the entity id `{{userId}}`.
 
-### Protocol — FOLLOW EVERY SESSION
+mem0 is the preferred durable-memory store while its tools are available. Workspace daily notes can still hold concise chronological context; `memory.md` remains a fallback if the mem0 tools are unavailable.
 
-1. **BEFORE RESPONDING** about any person, project, or past event: call `mem0_search_memory` FIRST. Never guess — verify from memory.
-2. **IF UNSURE** about a fact (name, age, relationship, preference): search memory. Wrong is worse than slow.
-3. **WHEN FACTS CHANGE**: store the new fact with `mem0_add_memory` (mem0 supersedes contradicted memories itself); delete plainly wrong entries with `mem0_delete_memory`.
-4. **AFTER LEARNING** something important: store it with `mem0_add_memory`. Pass natural conversational text — mem0 extracts the durable facts.
+### How to use it well
+
+1. Search with `mem0_search_memory` when prior context about a person, project, or past event could materially improve the answer.
+2. If a fact such as a name, relationship, or preference is uncertain, checking memory is usually better than guessing or asking the user to repeat it.
+3. When a fact changes, store the new version with `mem0_add_memory` (mem0 supersedes contradicted memories itself); use `mem0_delete_memory` for plainly wrong entries.
+4. When you learn new information, pass natural conversational text to `mem0_add_memory` so mem0 can extract and retain the facts.
 
 ### Tools
 

package/prompts/mempalace.md

@@ -2,6 +2,8 @@
 
 You have access to a local memory palace via MCP tools. The palace stores verbatim conversation history and a temporal knowledge graph — all local, zero cloud, zero API calls.
 
+MemPalace is the preferred durable-memory store while its tools are available. Workspace daily notes can still hold concise chronological context; `memory.md` remains a fallback if the MemPalace tools are unavailable.
+
 ### Architecture
 
 - **Wings** = top-level categories (people, projects, topics)
@@ -10,12 +12,12 @@ You have access to a local memory palace via MCP tools. The palace stores verbat
 - **Tunnels** = cross-wing links between related rooms (auto-created in mempalace 3.3.4+ when topics overlap, plus manual)
 - **Knowledge Graph** = entity-relationship facts with temporal validity
 
-### Protocol — FOLLOW EVERY SESSION
+### How to use it well
 
-1. **BEFORE RESPONDING** about any person, project, or past event: call `mempalace_search` or `mempalace_kg_query` FIRST. Never guess — verify from the palace.
-2. **IF UNSURE** about a fact (name, age, relationship, preference): query the palace. Wrong is worse than slow.
-3. **WHEN FACTS CHANGE**: Call `mempalace_kg_invalidate` on the old fact, then `mempalace_kg_add` for the new one.
-4. **AFTER LEARNING** something important: store it. Use `mempalace_add_drawer` for rich context, `mempalace_kg_add` for structured facts.
+1. Search with `mempalace_search` or `mempalace_kg_query` when prior context about a person, project, or past event could materially improve the answer.
+2. If a fact such as a name, relationship, or preference is uncertain, checking the palace is usually better than guessing or asking the user to repeat it.
+3. When a fact changes, keep its history accurate with `mempalace_kg_invalidate` followed by `mempalace_kg_add`.
+4. When you learn new information, use `mempalace_add_drawer` for rich context or `mempalace_kg_add` for a structured fact.
 
 ### Tools
 

package/prompts/system/memory-recall.md

@@ -0,0 +1,49 @@
+## Memory and Recall
+
+### Recall before asking
+
+Protect continuity. If a request relies on information the user reasonably
+expects you to already have, or you are unsure about a prior fact, take that
+as a cue to recover the context before asking them to repeat it. Make a
+proportionate but thorough attempt across the relevant sources available to
+you:
+
+- the current conversation and memory already included in this prompt;
+- enabled long-term-memory providers, including browse/fetch tools when a
+  search hit needs more context;
+- `memory/memory.md`, including the rest when its prompt excerpt is
+  truncated, and relevant recent files in `memory/daily/`;
+- workspace files, interaction logs, and connected sources that the request
+  suggests may contain the answer.
+
+Start with the most likely source, then broaden rather than stopping after one
+empty result. Alternate names, keywords, dates, or scopes can recover memories
+that a first query misses; follow promising results to their full source and
+weigh conflicts by recency and authority. Keep the effort relevant to the
+request—ordinary questions about the current turn do not call for rummaging
+through unrelated history.
+
+If a meaningful search still leaves the answer missing, inaccessible, or
+genuinely ambiguous, ask for the smallest piece of information needed and
+briefly explain the gap.
+
+### Save new information
+
+Proactively persist new information so future conversations can draw on it.
+This includes preferences, relationships, decisions, corrections, project
+context, durable facts, and details that may only become relevant later. Do
+this naturally as you learn it, without interrupting the conversation. Keep
+memory organized, update stale facts, and avoid duplicate copies.
+
+- If a dedicated long-term-memory provider is described elsewhere in this
+  prompt and its tools are available, prefer it as the canonical durable store
+  and use its guidance for searching, adding, updating, and deduplicating
+  memories. Daily notes can still preserve useful chronological context.
+- Otherwise, when filesystem tools are available, keep durable knowledge
+  organized and current in `~/.talon/workspace/memory/memory.md`, and use
+  today's `memory/daily/YYYY-MM-DD.md` for concise dated observations,
+  corrections, and follow-ups.
+- If neither a memory provider nor filesystem tools are available, retain the
+  information only for the current conversation and never claim it was saved.
+
+Memory updates should usually be quiet unless the user asks about them.

package/prompts/system/workspace.md

@@ -2,8 +2,8 @@
 
 You have a workspace directory at `~/.talon/workspace/`. This is your home — organize it however you want.
 
-- `memory/memory.md` — your persistent memory file. Update it (Write tool) when you learn important things.
-- `memory/daily/YYYY-MM-DD.md` — your daily notes: observations, learnings, corrections, follow-ups. Keep entries concise.
+- `memory/memory.md` — your file-based persistent-memory fallback when no dedicated memory provider is available.
+- `memory/daily/YYYY-MM-DD.md` — concise chronological notes: observations, learnings, corrections, and follow-ups.
 - `logs/` — daily interaction logs, written automatically.
 - `uploads/` — files users send you (photos, docs, voice) land here.
 - Everything else is yours to create and organize as you see fit.

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

@@ -15,8 +15,9 @@ import { readdir, readFile } from "node:fs/promises";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
-import { log } from "../../util/log.js";
+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";
 
 const DEFAULT_SUBPROCESS_KILL_GRACE_MS = 5 * 1000;
@@ -59,14 +60,26 @@ export async function runOneShotAgent(
     systemPrompt,
     workspace,
     model,
+    reasoningEffort,
     contextLabel,
     abortController,
     appendLog,
   } = params;
 
+  // Reasoning effort is opt-in for background runs (config `heartbeatEffort`
+  // / `dreamEffort`). Unset → omit the thinking options entirely so the SDK
+  // keeps whatever default the model ships with, which is what these runs
+  // did before the knob existed. The chat path applies an explicit
+  // `{ thinking: { type: "adaptive" } }` fallback instead because a chat has
+  // a persisted per-chat setting to honour; a one-shot has none.
+  const thinkingConfig = reasoningEffort
+    ? EFFORT_MAP[reasoningEffort]
+    : undefined;
+
   const options = {
     model,
     systemPrompt,
+    ...thinkingConfig,
     cwd: workspace,
     permissionMode: "bypassPermissions" as const,
     allowDangerouslySkipPermissions: true,
@@ -81,6 +94,23 @@ export async function runOneShotAgent(
     tools: [...ALLOWED_TOOLS_BACKGROUND],
   };
 
+  if (reasoningEffort && !thinkingConfig) {
+    // `minimal` / `xhigh` are Codex-side vocabulary with no Claude
+    // equivalent in EFFORT_MAP — the run proceeds on the model default
+    // rather than failing, but say so in the log so a configured knob that
+    // does nothing isn't silent.
+    logWarn(
+      "agent",
+      `[${contextLabel}] Claude one-shot: effort "${reasoningEffort}" has no ` +
+        `Claude mapping — using the model default`,
+    );
+  } else if (thinkingConfig) {
+    log(
+      "agent",
+      `[${contextLabel}] Claude one-shot effort: ${reasoningEffort}`,
+    );
+  }
+
   const qi = query({
     prompt,
     options: options as Parameters<typeof query>[0]["options"],

package/src/backend/codex/effort.ts

@@ -0,0 +1,30 @@
+/**
+ * Codex reasoning-effort vocabulary mapping.
+ *
+ * Talon's canonical `ReasoningEffortLevel` is a superset of what Codex's
+ * `modelReasoningEffort` thread option accepts: `off` isn't expressible on a
+ * reasoning model, and `max` is Claude-only. Both simply fall through to the
+ * model's own default.
+ *
+ * This is pure vocabulary translation — the "does this model offer that
+ * level?" question is answered by the caller (per-chat settings for an
+ * interactive turn, `core/background/effort.ts` for heartbeat/dream) against
+ * the model catalog's `supportedReasoningLevels`. Keeping the mapping here
+ * means the chat path and the one-shot path can't drift apart.
+ */
+
+import type { ReasoningEffortLevel } from "../../core/types.js";
+
+/** The levels Codex's `modelReasoningEffort` thread option accepts. */
+export type CodexReasoningEffort = Exclude<ReasoningEffortLevel, "off" | "max">;
+
+/**
+ * Map a canonical level onto Codex's thread option, or undefined when Codex
+ * has no way to express it (`off`, `max`, or nothing requested).
+ */
+export function toCodexReasoningEffort(
+  level: ReasoningEffortLevel | undefined,
+): CodexReasoningEffort | undefined {
+  if (!level || level === "off" || level === "max") return undefined;
+  return level;
+}

package/src/backend/codex/handler/message.ts

@@ -66,6 +66,7 @@ import {
   isCodexOAuthIncompat,
 } from "../models.js";
 import { supportsReasoningLevel } from "../../../core/models/reasoning-levels.js";
+import { toCodexReasoningEffort } from "../effort.js";
 import { markOAuthIncompat } from "../oauth-incompat.js";
 import { readLastRolloutSnapshot } from "../token-usage.js";
 import { activeAborts } from "./state.js";
@@ -283,22 +284,18 @@ export async function handleMessage(
   const supportedReasoningLevels =
     activeModelInfo?.supportedReasoningLevels ?? [];
   const requestedEffort = chatSettings.effort;
+  // Availability check (does this model offer the level?) then vocabulary
+  // translation (can Codex express it?) — the latter is shared with the
+  // one-shot path via `toCodexReasoningEffort` so the two can't drift.
   const modelReasoningEffort =
     requestedEffort &&
-    requestedEffort !== "off" &&
-    requestedEffort !== "max" &&
     supportsReasoningLevel(requestedEffort, supportedReasoningLevels)
-      ? requestedEffort
+      ? toCodexReasoningEffort(requestedEffort)
       : undefined;
   const threadOptions = {
     model: activeModel,
     skipGitRepoCheck: true,
-    ...(modelReasoningEffort
-      ? {
-          modelReasoningEffort: modelReasoningEffort as
-            "minimal" | "low" | "medium" | "high" | "xhigh",
-        }
-      : {}),
+    ...(modelReasoningEffort ? { modelReasoningEffort } : {}),
     ...CODEX_THREAD_PERMISSIONS,
   };
   const thread: Thread = session.sessionId

package/src/backend/codex/one-shot.ts

@@ -29,6 +29,7 @@ import {
 import { isChatGptModelMismatchError } from "./auth.js";
 import { chatGptFallbackFor, isCodexOAuthIncompat } from "./models.js";
 import { markOAuthIncompat } from "./oauth-incompat.js";
+import { toCodexReasoningEffort } from "./effort.js";
 
 /**
  * Resolve the effective model for a one-shot run, applying the same
@@ -74,6 +75,7 @@ export async function runOneShotAgent(
     prompt,
     systemPrompt,
     model: requestedModel,
+    reasoningEffort,
     contextLabel,
     abortController,
     appendLog,
@@ -103,9 +105,27 @@ export async function runOneShotAgent(
   }
   log("agent", `[${contextLabel}] Codex one-shot model: ${activeModel}`);
 
+  // Availability was already checked by the caller against the model
+  // catalog (core/background/effort.ts); all that's left is Codex's own
+  // vocabulary, which can't express `off` / `max`.
+  const modelReasoningEffort = toCodexReasoningEffort(reasoningEffort);
+  if (reasoningEffort && !modelReasoningEffort) {
+    logWarn(
+      "agent",
+      `[${contextLabel}] Codex one-shot: effort "${reasoningEffort}" has no ` +
+        `Codex equivalent — using the model default`,
+    );
+  } else if (modelReasoningEffort) {
+    log(
+      "agent",
+      `[${contextLabel}] Codex one-shot effort: ${modelReasoningEffort}`,
+    );
+  }
+
   const thread = codex.startThread({
     model: activeModel,
     skipGitRepoCheck: true,
+    ...(modelReasoningEffort ? { modelReasoningEffort } : {}),
     ...CODEX_THREAD_PERMISSIONS,
   });
 

package/src/backend/remote-server/one-shot.ts

@@ -19,6 +19,12 @@
  * subprocesses to evict — `evictOrphanSubprocesses` is intentionally
  * not implemented for this family.
  *
+ * Note on reasoning effort: `params.reasoningEffort` (config
+ * `heartbeatEffort` / `dreamEffort`) is deliberately unused here. Neither
+ * server's `session.prompt` exposes a reasoning knob — the level is baked
+ * into the provider's model id when it's selectable at all — so the field
+ * is ignored rather than half-honoured.
+ *
  * Note on abort semantics: both SDKs expose `session.abort` but the
  * REST `prompt` endpoint blocks until the underlying provider
  * returns. The heartbeat module's outer abort grace is what actually

package/src/bootstrap.ts

@@ -467,6 +467,7 @@ export async function initBackendAndDispatcher(
   initDream({
     model: config.model,
     dreamModel: config.dreamModel,
+    dreamEffort: config.dreamEffort,
     workspace: config.workspace,
     enabled: config.dream,
     getBackend: () => getBackendForRole("dream"),
@@ -482,6 +483,7 @@ export async function initBackendAndDispatcher(
   initHeartbeat({
     model: config.model,
     heartbeatModel: config.heartbeatModel,
+    heartbeatEffort: config.heartbeatEffort,
     workspace: config.workspace,
     getBackend: () => getBackendForRole("heartbeat"),
     frontends: frontendNames,

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/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"),

package/src/core/prompt/embedded-prompts.ts

@@ -26,13 +26,14 @@ import asset12 from "../../../prompts/system/cron.md" with { type: "file" };
 import asset13 from "../../../prompts/system/daily-memory.md" with { type: "file" };
 import asset14 from "../../../prompts/system/goals.md" with { type: "file" };
 import asset15 from "../../../prompts/system/heartbeat-agent.md" with { type: "file" };
-import asset16 from "../../../prompts/system/persistent-memory.md" with { type: "file" };
-import asset17 from "../../../prompts/system/skills.md" with { type: "file" };
-import asset18 from "../../../prompts/system/triggers.md" with { type: "file" };
-import asset19 from "../../../prompts/system/workspace.md" with { type: "file" };
-import asset20 from "../../../prompts/teams.md" with { type: "file" };
-import asset21 from "../../../prompts/telegram.md" with { type: "file" };
-import asset22 from "../../../prompts/terminal.md" with { type: "file" };
+import asset16 from "../../../prompts/system/memory-recall.md" with { type: "file" };
+import asset17 from "../../../prompts/system/persistent-memory.md" with { type: "file" };
+import asset18 from "../../../prompts/system/skills.md" with { type: "file" };
+import asset19 from "../../../prompts/system/triggers.md" with { type: "file" };
+import asset20 from "../../../prompts/system/workspace.md" with { type: "file" };
+import asset21 from "../../../prompts/teams.md" with { type: "file" };
+import asset22 from "../../../prompts/telegram.md" with { type: "file" };
+import asset23 from "../../../prompts/terminal.md" with { type: "file" };
 
 /** rel path (posix, under prompts/) → embedded file path (/$bunfs/… when compiled). */
 const ASSETS: Record<string, string> = {
@@ -52,13 +53,14 @@ const ASSETS: Record<string, string> = {
   "system/daily-memory.md": asset13,
   "system/goals.md": asset14,
   "system/heartbeat-agent.md": asset15,
-  "system/persistent-memory.md": asset16,
-  "system/skills.md": asset17,
-  "system/triggers.md": asset18,
-  "system/workspace.md": asset19,
-  "teams.md": asset20,
-  "telegram.md": asset21,
-  "terminal.md": asset22,
+  "system/memory-recall.md": asset16,
+  "system/persistent-memory.md": asset17,
+  "system/skills.md": asset18,
+  "system/triggers.md": asset19,
+  "system/workspace.md": asset20,
+  "teams.md": asset21,
+  "telegram.md": asset22,
+  "terminal.md": asset23,
 };
 
 /** Read an embedded prompt by its rel path (e.g. "system/cron.md"). */

package/src/core/types.ts

@@ -141,6 +141,16 @@ export type OneShotAgentParams = {
   workspace: string;
   /** Model id (interpretation is backend-specific). */
   model: string;
+  /**
+   * Reasoning effort for the run (config `heartbeatEffort` / `dreamEffort`).
+   * Undefined = let the backend/model pick its own default, which is what
+   * every background run did before the knob existed.
+   *
+   * Honoured by the backends that expose a reasoning knob (Claude SDK
+   * thinking/effort, Codex `modelReasoningEffort`); ignored by the ones
+   * that don't (Kilo, OpenCode).
+   */
+  reasoningEffort?: ReasoningEffortLevel;
   /**
    * Sentinel chat ID for outbound MCP tool calls (e.g. "heartbeat", "dream").
    * Frontend MCP servers use this to enforce explicit `chat_id` on outbound

package/src/util/config.ts

@@ -5,6 +5,7 @@ import { dirs, files as pathFiles } from "./paths.js";
 import { hardenTalonPermissions } from "./harden.js";
 import { setTimezone } from "./time.js";
 import { BACKEND_IDS } from "../core/agent-runtime/model-ref.js";
+import { REASONING_LEVEL_ORDER } from "../core/models/reasoning-levels.js";
 import {
   assembleSystemPrompt,
   joinSystemPromptParts,
@@ -28,6 +29,20 @@ const BACKEND_ID_ENUM = [...BACKEND_IDS] as [
   ...(typeof BACKEND_IDS)[number][],
 ];
 
+/**
+ * Reasoning-effort literal source for the background-agent knobs
+ * (`heartbeatEffort` / `dreamEffort`). Same trick as `BACKEND_ID_ENUM`:
+ * reuse the single source of truth (`REASONING_LEVEL_ORDER`) so adding a
+ * level to the vocabulary doesn't need a second edit here.
+ *
+ * There is no `"adaptive"` member — leaving the field unset IS adaptive
+ * (the backend/model default), matching how per-chat `effort` behaves.
+ */
+const REASONING_EFFORT_ENUM = [...REASONING_LEVEL_ORDER] as [
+  (typeof REASONING_LEVEL_ORDER)[number],
+  ...(typeof REASONING_LEVEL_ORDER)[number][],
+];
+
 // ── Config schema ───────────────────────────────────────────────────────────
 
 /** Path-based Talon plugin (loaded as a Node module). */
@@ -317,6 +332,15 @@ const configSchema = z.object({
    */
   backendDefaults: z.record(z.string(), z.string()).optional(),
   dreamModel: z.string().optional(), // Model used for background memory consolidation (defaults to main model)
+  /**
+   * Reasoning effort for the dream / memory-consolidation agent. Unset =
+   * the backend/model default. Pair with `dreamModel` when you want a
+   * cheap model that still thinks hard (or an expensive one that doesn't).
+   *
+   * Honoured by backends with a reasoning knob (Claude SDK, Codex);
+   * silently ignored by Kilo / OpenCode, which have none.
+   */
+  dreamEffort: z.enum(REASONING_EFFORT_ENUM).optional(),
   maxMessageLength: z.number().int().min(100).default(4000),
   concurrency: z.number().int().min(1).max(20).default(1),
   apiId: z.number().int().optional(),
@@ -339,6 +363,16 @@ const configSchema = z.object({
   heartbeat: z.boolean().default(true),
   heartbeatIntervalMinutes: z.number().int().min(5).default(60),
   heartbeatModel: z.string().optional(), // Model for heartbeat agent (defaults to main model)
+  /**
+   * Reasoning effort for the heartbeat agent. Unset = the backend/model
+   * default. Pair with `heartbeatModel` — e.g. `"high"` so unattended
+   * goal work reasons harder than a chat turn, or `"low"` to keep hourly
+   * runs cheap.
+   *
+   * Honoured by backends with a reasoning knob (Claude SDK, Codex);
+   * silently ignored by Kilo / OpenCode, which have none.
+   */
+  heartbeatEffort: z.enum(REASONING_EFFORT_ENUM).optional(),
   braveApiKey: z.string().optional(),
   /**
    * Codex-specific OpenAI API key. Prefer this, CODEX_API_KEY, or