talon-agent 4.6.0 → 5.0.0

package/src/core/memory/taps.ts

@@ -0,0 +1,199 @@
+/**
+ * Message taps — the memory store's mechanical input stream.
+ *
+ * This is the one part of the soul kernel that was worth keeping
+ * (docs/memory-persona-plan.md §2): a pair of high-precision regex sets
+ * that recognise, without a model call, the two message shapes that carry
+ * durable intent — a *directive* ("from now on, …") and a *correction*
+ * ("no, that's wrong"). The kernel that consumed them is gone; the rows
+ * now land in the typed memory store, where the core view and the
+ * retriever already know how to read them.
+ *
+ * Three rules govern what gets written, and none of them live in the
+ * store:
+ *
+ *   - **Trust comes from the chat.** A DM (or a local terminal/native
+ *     session) is the operator typing, so the row is `operator` trust —
+ *     stronger than `remember`'s `agent`, because a tap records what a
+ *     human literally wrote rather than what the model concluded. A
+ *     group — or a chat-id grammar that cannot tell, which fails closed —
+ *     is `group_chat`, and a **directive is not recorded there at all**:
+ *     durable standing intent only comes from a direct conversation with
+ *     the operator. Same rule as the `remember` action.
+ *   - **A repeated phrase is not a second memory.** The FTS near-dupe
+ *     probe runs before every write, so saying "always use ripgrep" twice
+ *     leaves one row, not two.
+ *   - **It fails closed and it is never on the prompt-cache path.** Any
+ *     store error is one warning and nothing else; the turn proceeds. This
+ *     module must not import `core/prompt/invalidation.js` — a tap that
+ *     invalidated every live session's prompt snapshot would turn a
+ *     ~50-token claim into a 60–90 k cache write (plan §3.6).
+ */
+
+import {
+  assertMemory,
+  findSimilarMemories,
+  type MemoryKind,
+  type MemorySource,
+  type MemoryTrust,
+} from "../../storage/memory.js";
+import { chatScope } from "../../util/chat-id.js";
+import { log, logWarn } from "../../util/log.js";
+
+/**
+ * High-precision cues that a message is a *correction* of Talon's behavior. Kept
+ * tight on purpose: a false positive stores a claim about how to behave, so we
+ * would rather miss a soft correction than mislabel ordinary chat.
+ */
+const CORRECTION_PATTERNS: readonly RegExp[] = [
+  /^\s*(no|nope|nah)\b[\s,.!:-]/i,
+  /\bthat'?s (wrong|incorrect|not (right|correct)|false)\b/i,
+  /\b(you'?re|you are) wrong\b/i,
+  /\bnot what i (asked|meant|wanted|said)\b/i,
+  /\bnever (do|say) that( again)?\b/i,
+  /\b(stop|quit) (doing|saying) that\b/i,
+  /\bwrong[\s,.!]/i,
+  /\byou (messed|screwed|fucked) (that|this|it)? ?up\b/i,
+];
+
+/**
+ * High-precision cues that a message is a *directive* about how to be — a
+ * standing instruction rather than a one-off request. These are stored verbatim
+ * as evidence, so again we favor precision over recall.
+ */
+const DIRECTIVE_PATTERNS: readonly RegExp[] = [
+  /\bfrom now on\b/i,
+  /\bgoing forward\b/i,
+  /\bin (the )?future\b/i,
+  /\byou should (always|never)\b/i,
+  /\b(always|never) (do|say|reply|respond|answer|use|be|call|check)\b/i,
+  /\bi (want|need|'?d like) you to\b/i,
+  /\bmake sure (you|to|that)\b/i,
+  /\bremember to\b/i,
+];
+
+export type MessageClass = "directive" | "correction" | null;
+
+/** `source.actor` on every row this path writes — the ownership marker. */
+const TAP_ACTOR = "tap";
+
+/** The subject a tapped directive is filed under: standing operator intent. */
+const DIRECTIVE_SUBJECT = "operator";
+
+/** The subject a tapped correction is filed under. */
+const CORRECTION_SUBJECT = "correction";
+
+/**
+ * Classify a single inbound message. Returns "correction" or "directive" when a
+ * cue matches, else null. Corrections are checked first because a correction is
+ * the more specific (and more consequential) signal. Very long messages are
+ * skipped — standing instructions and corrections are terse.
+ */
+export function classifyMessage(text: string): MessageClass {
+  const t = text.trim();
+  if (t.length === 0 || t.length > 500) return null;
+  if (CORRECTION_PATTERNS.some((re) => re.test(t))) return "correction";
+  if (DIRECTIVE_PATTERNS.some((re) => re.test(t))) return "directive";
+  return null;
+}
+
+/**
+ * The trust tier for something the human typed in this chat. A DM is the
+ * operator speaking for themselves; anything multi-party — or a grammar that
+ * cannot tell, which fails closed — is `group_chat`.
+ */
+function trustForChat(chatKey: string): MemoryTrust {
+  return chatScope(chatKey) === "dm" ? "operator" : "group_chat";
+}
+
+/**
+ * How much of two claims' wording must coincide before the tap calls the
+ * second one a restatement of the first. Jaccard over the word sets, so
+ * word order and punctuation don't matter.
+ *
+ * A threshold is needed because the tap files every directive under the
+ * *same* subject, and the store's FTS probe ORs a claim's terms: "from now
+ * on, always use ripgrep" and "from now on, never use emoji" both match it
+ * on `from`/`now`/`use`. Without this, the first directive Talon ever heard
+ * would swallow every later one. Set high on purpose — the case this
+ * exists for is the same sentence typed twice.
+ */
+const DUPLICATE_OVERLAP = 0.8;
+
+/** The word set of a claim, lowercased, punctuation dropped. */
+function wordSet(text: string): Set<string> {
+  return new Set(
+    text
+      .toLowerCase()
+      .split(/[^\p{L}\p{N}]+/u)
+      .filter(Boolean),
+  );
+}
+
+/** Jaccard similarity of two claims' word sets, 0..1. */
+function overlap(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 || b.size === 0) return 0;
+  let shared = 0;
+  for (const w of a) if (b.has(w)) shared += 1;
+  return shared / (a.size + b.size - shared);
+}
+
+/**
+ * Write one tapped claim, unless the store already holds a restatement of it
+ * under the same kind and subject. Returns true when a row was inserted.
+ *
+ * The store's FTS probe is the cheap prefilter — live rows only, right kind
+ * and subject, best textual match first — and `DUPLICATE_OVERLAP` is the
+ * decision.
+ */
+function storeClaim(
+  kind: MemoryKind,
+  subject: string,
+  text: string,
+  trust: MemoryTrust,
+  source: MemorySource,
+  speaker: string,
+): boolean {
+  const words = wordSet(text);
+  const restated = findSimilarMemories(kind, subject, text).some(
+    (row) => overlap(words, wordSet(row.text)) >= DUPLICATE_OVERLAP,
+  );
+  if (restated) return false;
+  const { id } = assertMemory({ kind, subject, text, trust, source });
+  log("memory", `tap: [${kind}] ${subject} from ${speaker} #${id}`);
+  return true;
+}
+
+/**
+ * Feed one inbound message to the memory store if it reads as a directive or a
+ * correction. Returns the class recognised, whether or not a row was written —
+ * a group-chat directive is classified and deliberately dropped.
+ *
+ * Never throws: the tap runs beside a turn, not inside it, so a store failure
+ * costs one warning and nothing else.
+ */
+export function recordMessageSignal(opts: {
+  readonly text: string;
+  readonly chatKey: string;
+  readonly actor?: string;
+}): MessageClass {
+  const cls = classifyMessage(opts.text);
+  if (cls === null) return null;
+  const text = opts.text.trim();
+  const trust = trustForChat(opts.chatKey);
+  const source: MemorySource = { chat: opts.chatKey, actor: TAP_ACTOR };
+  const speaker = opts.actor ?? "user";
+  try {
+    if (cls === "directive") {
+      // A standing instruction only counts when the operator gave it
+      // directly — anyone in a group could otherwise plant one.
+      if (trust !== "operator") return cls;
+      storeClaim("directive", DIRECTIVE_SUBJECT, text, trust, source, speaker);
+    } else {
+      storeClaim("episode", CORRECTION_SUBJECT, text, trust, source, speaker);
+    }
+  } catch (err) {
+    logWarn("memory", `tap failed to record ${cls}: ${String(err)}`);
+  }
+  return cls;
+}

package/src/core/memory/turn-retrieval.ts

@@ -0,0 +1,222 @@
+/**
+ * **Turn retrieval** — the per-turn tier of docs/memory-persona-plan.md
+ * §3.4, behind `TALON_MEMORY_STORE`.
+ *
+ * Retrieval has two tiers and the boundary between them is a
+ * prompt-cache invariant (plan §3.6):
+ *
+ *   - **Core view** (`core-view.ts`) — computed once per session build,
+ *     lives in `staticText`, frozen for the session.
+ *   - **Turn retrieval** (this module) — keyed to the *incoming
+ *     message*, resolved once per turn by the Weaver and injected into
+ *     the **user turn** by `formatUserPrompt`. It never enters
+ *     `prepareSystemPrompt()` and nothing here may ever call
+ *     `notifyPromptInputsChanged()` — a per-turn invalidation would
+ *     force a full-prompt cache write on every live session, every
+ *     turn, which is the single most expensive mistake in the plan.
+ *
+ * This is the seam #639 deleted, rebuilt without the divergence that
+ * justified deleting it. The old `retrievedMemory` field was read by
+ * two backends out of six and silently dropped by the rest; now there
+ * is exactly ONE consumer — `backend/runtime/prompt/prompt-format.ts` — that
+ * every backend already calls, so a backend cannot forget to inject it
+ * without also losing its time tag and `msg_id` framing.
+ *
+ * **Trust policy (plan §5, #373).** Only `operator` and `agent` rows
+ * are ever auto-injected. `user_claim` and `group_chat` rows are
+ * reachable only through the explicit `recall` tool: an auto-injected
+ * low-trust row is a permanent prompt injection that anyone in a group
+ * chat can plant. `reflection` rows are excluded too — the diary is the
+ * persona layer and is structurally never a fact source (plan §3.5).
+ *
+ * **Fail closed.** A broken store must never block chat delivery: any
+ * error logs once per process and the turn runs with no injected
+ * memory, exactly as if the flag were off.
+ */
+
+import {
+  formatMemory,
+  searchMemories,
+  touchMemory,
+  type MemoryRow,
+  type MemoryTrust,
+} from "../../storage/memory.js";
+import { logDebug, logWarn } from "../../util/log.js";
+import { memoryStoreEnabled } from "./flag.js";
+
+// ── Tunables ────────────────────────────────────────────────────────────────
+
+/**
+ * Hard cap on the injected block, header excluded. Whole rows only —
+ * a truncated memory is a misquoted memory, and a half-line is worse
+ * than a missing one. Paid on *every* turn (unlike the core view,
+ * which is paid once per session and then cached), so it stays small.
+ */
+export const TURN_MEMORY_MAX_CHARS = 3_000;
+
+/**
+ * Candidates pulled from FTS before re-ranking. The trust filter runs
+ * *after* this cut, so a query whose twenty best matches are all
+ * low-trust injects nothing — which is the conservative direction: an
+ * untrusted row must never be promoted into the prompt just because
+ * nothing trusted matched.
+ */
+const CANDIDATE_LIMIT = 20;
+
+/**
+ * Trust tiers eligible for automatic injection (plan §5). Everything
+ * else stays pull-only, through the explicit `recall` tool.
+ */
+const AUTO_INJECT_TRUST: ReadonlySet<MemoryTrust> = new Set([
+  "operator",
+  "agent",
+]);
+
+/** `hitCount` at which the affinity term saturates. */
+const HIT_SATURATION = 20;
+
+/** Age at which the recency term reaches zero. */
+const RECENCY_HORIZON_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * Re-ranking weights. bm25 order (as the store returned it) is the
+ * strongest signal — it is the only one that knows what was *asked* —
+ * and the three store-side signals refine it rather than overturn it:
+ * salience is the curator's judgement, `hitCount` is the feedback loop
+ * this module itself feeds, and recency breaks ties towards the live
+ * world. They sum to 1 so a score reads as a 0..1 fraction.
+ */
+const W_RELEVANCE = 0.4;
+const W_SALIENCE = 0.3;
+const W_AFFINITY = 0.2;
+const W_RECENCY = 0.1;
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/** What one turn's retrieval produced. `undefined` means "inject nothing". */
+export type TurnMemory = {
+  /** The rendered block, one row per line. Never truncated mid-row. */
+  text: string;
+  /** How many rows it carries. */
+  rows: number;
+  /** `text.length` — the per-turn cost, recorded as `turn.memory_chars`. */
+  chars: number;
+};
+
+/** One turn's retrieval context: the raw inbound message and its chat. */
+export type TurnRetrievalInput = {
+  chatId: string;
+  /** The user's text, as the Weaver received it (no prompt framing yet). */
+  text: string;
+  isGroup: boolean;
+};
+
+// ── Ranking ─────────────────────────────────────────────────────────────────
+
+/** Eligible for auto-injection: trusted tier, and not the diary. */
+function injectable(row: MemoryRow): boolean {
+  return AUTO_INJECT_TRUST.has(row.trust) && row.kind !== "reflection";
+}
+
+/**
+ * Blend the store's bm25 order with the row's own standing. `index` is
+ * the row's position in the bm25 result, best first.
+ */
+function score(row: MemoryRow, index: number, total: number, now: number) {
+  const relevance = total > 1 ? 1 - index / (total - 1) : 1;
+  const affinity = Math.min(
+    1,
+    Math.log1p(row.hitCount) / Math.log1p(HIT_SATURATION),
+  );
+  const age = Math.max(0, now - row.lastSeenAt);
+  const recency = Math.max(0, 1 - age / RECENCY_HORIZON_MS);
+  return (
+    W_RELEVANCE * relevance +
+    W_SALIENCE * row.salience +
+    W_AFFINITY * affinity +
+    W_RECENCY * recency
+  );
+}
+
+/** Trust-filtered candidates, best first. */
+function rank(hits: MemoryRow[], now: number): MemoryRow[] {
+  const scored = hits
+    .map((row, index) => ({ row, index }))
+    .filter(({ row }) => injectable(row))
+    .map(({ row, index }) => ({
+      row,
+      score: score(row, index, hits.length, now),
+    }));
+  scored.sort((a, b) => b.score - a.score || a.row.id - b.row.id);
+  return scored.map((s) => s.row);
+}
+
+/** Fill the budget with whole rows, in rank order. */
+function fill(rows: MemoryRow[]): { lines: string[]; taken: MemoryRow[] } {
+  const lines: string[] = [];
+  const taken: MemoryRow[] = [];
+  let used = 0;
+  for (const row of rows) {
+    const line = formatMemory(row);
+    // +1 for the newline that joins this line to the previous one.
+    const cost = line.length + (lines.length > 0 ? 1 : 0);
+    if (used + cost > TURN_MEMORY_MAX_CHARS) break;
+    lines.push(line);
+    taken.push(row);
+    used += cost;
+  }
+  return { lines, taken };
+}
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+/** One warning per process — a broken store must not spam every turn. */
+let warned = false;
+
+function failClosed(err: unknown): undefined {
+  if (!warned) {
+    warned = true;
+    logWarn(
+      "dispatcher",
+      "memory turn retrieval failed (turns run without it): " +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Retrieve the memory block for one chat turn, or `undefined` when
+ * there is nothing to inject (flag off, no match, or any failure).
+ *
+ * Injected rows are `touch`ed — that is the ranking feedback loop:
+ * a row that keeps getting recalled climbs, one that never matches
+ * stays where it is.
+ */
+export function retrieveForTurn(
+  input: TurnRetrievalInput,
+): TurnMemory | undefined {
+  if (!memoryStoreEnabled()) return undefined;
+  try {
+    // `match: "any"` — the query is a sentence the user wrote as a
+    // message, not as a search; AND-ing its every word would match
+    // nothing. bm25 over the OR-ed terms does the ranking.
+    const hits = searchMemories(input.text, {
+      limit: CANDIDATE_LIMIT,
+      match: "any",
+    });
+    if (hits.length === 0) return undefined;
+    const { lines, taken } = fill(rank(hits, Date.now()));
+    if (taken.length === 0) return undefined;
+    for (const row of taken) touchMemory(row.id);
+    const text = lines.join("\n");
+    logDebug(
+      "dispatcher",
+      `memory turn retrieval chat=${input.chatId}${input.isGroup ? " (group)" : ""}: ` +
+        `${taken.length}/${hits.length} row(s), ${text.length} chars`,
+    );
+    return { text, rows: taken.length, chars: text.length };
+  } catch (err) {
+    return failClosed(err);
+  }
+}

package/src/core/prompt/assemble.ts

@@ -30,7 +30,7 @@
  *   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.
- *       See backend/shared/delivery-contract.ts.)
+ *       See backend/runtime/prompt/delivery-contract.ts.)
  *
  *   DYNAMIC
  *   1. Daily-memory pointer                 prompts/system/daily-memory.md
@@ -52,7 +52,7 @@
  * ## Deliberate omissions
  *
  * No "Current Date & Time" section: every user message already
- * carries a `[YYYY-MM-DD HH:MM:SS]` tag (see shared/prompt-format),
+ * carries a `[YYYY-MM-DD HH:MM:SS]` tag (see backend/runtime/prompt/prompt-format),
  * the daily-memory pointer names today's file, and the `check_time`
  * tool covers timezone queries. A minute-precision timestamp here was
  * the single biggest cache-buster — it guaranteed every rebuild
@@ -72,7 +72,6 @@ import { renderStickerLibraryPrompt } from "../../storage/stickers.js";
 import { recordHistogram } from "../../storage/metrics.js";
 import { renderCoreView } from "../memory/core-view.js";
 import { memoryStoreEnabled } from "../memory/flag.js";
-import { getSoul } from "../soul/service.js";
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
@@ -213,15 +212,6 @@ export function assembleSystemPrompt(
     loaded.push("identity");
   }
 
-  // 1.5. Soul — the compiled identity surface, when the soul is enabled.
-  //      Off by default (TALON_SOUL_ENABLED); inert deployments add nothing.
-  //      Selection-based and verbatim, so it never injects invented self-text.
-  const soulSection = getSoul().renderPromptSection();
-  if (soulSection) {
-    staticParts.push(soulSection);
-    loaded.push("soul");
-  }
-
   // 2. Core behaviour — custom.md replaces base.md wholesale when present.
   const custom = readOptionalFile(resolve(promptDir, "custom.md"));
   const basePrompt = readOptionalFile(resolve(promptDir, "base.md"));

package/src/core/prompt/index.ts

@@ -8,9 +8,9 @@
  *   - `workspace-listing` — lazy workspace tree for the dynamic tail
  *
  * The per-session freezing/caching of assembled prompts lives in
- * `backend/shared/system-prompt.ts` (it is a backend concern); the
+ * `backend/runtime/prompt/system-prompt.ts` (it is a backend concern); the
  * delivery-contract suffix builders live in
- * `backend/shared/delivery-contract.ts`.
+ * `backend/runtime/prompt/delivery-contract.ts`.
  */
 
 export { loadSystemTemplate } from "./templates.js";

package/src/core/prompt/invalidation.ts

@@ -4,7 +4,7 @@
  * skill toggle).
  *
  * Whoever caches assembled prompts registers a hook here (today: the
- * per-session snapshot store in backend/shared/system-prompt.ts, at its
+ * per-session snapshot store in backend/runtime/prompt/system-prompt.ts, at its
  * module load). Core and frontends call `notifyPromptInputsChanged()`
  * and never import the cache — the dependency points backend → core,
  * as the layer rule requires.

package/src/core/tasks/index.ts

@@ -2,7 +2,7 @@
  * Task table — public surface.
  *
  * See table.ts for the registry and types.ts for the vocabulary. Wiring
- * points: weaver (turns), heartbeat/agent, dream, background/job-oneshot
+ * points: weaver (turns), heartbeat/agent, dream, background/cron/job-oneshot
  * (isolated cron/trigger jobs); read surfaces: gateway `GET /tasks` +
  * `POST /tasks/kill`, CLI `talon ps` / `talon kill`.
  */

package/src/core/tools/index.ts

@@ -16,6 +16,7 @@ import { stickerTools } from "./stickers.js";
 import { schedulingTools } from "./scheduling.js";
 import { triggerTools } from "./triggers.js";
 import { goalTools } from "./goals.js";
+import { memoryTools } from "./memory.js";
 import { scriptTools } from "./scripts.js";
 import { skillTools } from "./skills.js";
 import { webTools } from "./web.js";
@@ -38,6 +39,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...schedulingTools,
   ...triggerTools,
   ...goalTools,
+  ...memoryTools,
   ...scriptTools,
   ...skillTools,
   ...webTools,

package/src/core/tools/memory.ts

@@ -0,0 +1,128 @@
+/**
+ * Memory tools — one typed claim at a time, in band.
+ *
+ * `remember` / `recall` / `forget` are the write path of
+ * docs/memory-persona-plan.md §3.2: a claim costs ~50 tokens and a
+ * transaction instead of a 23 KB file rewrite mid-conversation, and a
+ * restatement is offered back as a supersede candidate rather than
+ * silently becoming a second row.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+import type { MemoryKind } from "../../storage/memory.js";
+
+/**
+ * The store's kinds, spelled out here rather than imported.
+ * `core/tools/` holds pure definitions; importing `storage/memory.js`
+ * for one constant would pull SQLite (and `db.ts`'s top-level await)
+ * into every backend that imports the tool registry. The `MemoryKind`
+ * annotation is the compile-time link, and `memory-actions.test.ts`
+ * asserts this list still equals `MEMORY_KINDS` exactly.
+ */
+const MEMORY_KIND_NAMES: readonly [MemoryKind, ...MemoryKind[]] = [
+  "directive",
+  "fact",
+  "state",
+  "episode",
+  "relationship",
+  "reflection",
+];
+
+const kindSchema = z
+  .enum(MEMORY_KIND_NAMES)
+  .describe(
+    "directive = standing instruction; fact = durable and supersedable; state = keyed, replaced on write; episode = dated, decays; relationship = how a person works; reflection = your own diary, never a fact source",
+  );
+
+export const memoryTools: ToolDefinition[] = [
+  {
+    name: "remember",
+    description: `Store one durable claim in long-term memory. Cheap — prefer it to editing memory files.
+
+One claim per call, written as a standalone sentence that will still parse months from now.
+If a near-duplicate already exists the call is REFUSED and lists the matching rows: re-issue with replace_id=<that id> to fold your wording into it (the old row stays readable), or force=true only when the new claim genuinely stands beside the old one.
+subject is who/what the claim is about; it defaults to this chat for episode and relationship. state also needs a key (e.g. "release.status") and replaces that key's live row.`,
+    schema: {
+      kind: kindSchema,
+      text: z
+        .string()
+        .describe(
+          "The claim itself, self-contained and specific (max 4000 chars)",
+        ),
+      subject: z
+        .string()
+        .optional()
+        .describe(
+          "Who or what this is about — a person, a project, a topic. Required except for episode/relationship, which default to this chat.",
+        ),
+      key: z
+        .string()
+        .optional()
+        .describe(
+          'Required for kind="state": lowercase dotted namespace (e.g. "heartbeat.health"). Writing a key replaces its live row.',
+        ),
+      confidence: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("How sure you are, 0–1 (default 1)"),
+      replace_id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(
+          "Supersede this existing memory with the new text instead of adding a row — the answer to a near-duplicate refusal",
+        ),
+      force: z
+        .boolean()
+        .optional()
+        .describe(
+          "Store anyway despite a near-duplicate. Only when the claims really are distinct.",
+        ),
+    },
+    execute: (params, bridge) => bridge("remember", params),
+    tag: "memory",
+  },
+
+  {
+    name: "recall",
+    description: `Search long-term memory for stored claims — full-text, best match first.
+
+Use it when you need more than the memory already in this prompt, before asking the user to repeat something. Returns lines prefixed with an id you can pass to remember(replace_id) or forget.`,
+    schema: {
+      query: z
+        .string()
+        .describe("Words to search for — names, topics, distinctive phrases"),
+      kind: kindSchema.optional().describe("Restrict to one kind"),
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Max rows to return (default and max 20)"),
+    },
+    execute: (params, bridge) => bridge("recall", params),
+    tag: "memory",
+  },
+
+  {
+    name: "forget",
+    description: `Retire a stored memory by id. It goes to the graveyard — readable and revertible, not erased.
+
+The reason is required and is kept with the row. Use this for claims that are wrong or that the user asked you to drop; to correct a claim that is merely out of date, use remember with replace_id so the correction supersedes it.
+A claim can only be retired from a context at least as trusted as the one that recorded it: operator memories are never droppable this way, and a group chat cannot drop what was learned in a DM.`,
+    schema: {
+      id: z.number().int().positive().describe("Memory id, as shown by recall"),
+      reason: z
+        .string()
+        .describe(
+          "Why it is being dropped — required, stored in the audit log",
+        ),
+    },
+    execute: (params, bridge) => bridge("forget", params),
+    tag: "memory",
+  },
+];

package/src/core/tools/types.ts

@@ -22,6 +22,7 @@ export type ToolTag =
   | "scheduling"
   | "triggers"
   | "goals"
+  | "memory"
   | "scripts"
   | "skills"
   | "web"

package/src/core/weaver/turn-cpu.ts

@@ -0,0 +1,32 @@
+/**
+ * Per-turn CPU accounting — how much of a turn the daemon itself spends
+ * on a CPU, as opposed to waiting on a model or a chat platform.
+ *
+ * This is the number Phase 0's kill criterion is written against
+ * (docs/ts-migration-plan.md): the TS control plane's share of turn
+ * latency is `turn.cpu_ms / response_latency_ms`, and if that share is
+ * small then a port buys latency nothing. `turn.stream_ms` is the wall
+ * clock over the identical bracket, so the two divide cleanly.
+ *
+ * `process.cpuUsage()` is process-wide, not per-turn: with concurrent
+ * turns each one's delta includes the others' work. That is the honest
+ * upper bound for "what the daemon costs while a turn is in flight", and
+ * it is the direction that matters — a small number stays small.
+ */
+
+import { recordHistogram } from "../../storage/metrics.js";
+
+/**
+ * Bracket a turn's backend stream. Returns the stop function; calling it
+ * records `turn.cpu_ms` (user + system, milliseconds).
+ */
+export function startTurnCpu(): () => void {
+  const startedAt = process.cpuUsage();
+  return () => {
+    const used = process.cpuUsage(startedAt);
+    recordHistogram(
+      "turn.cpu_ms",
+      Math.round((used.user + used.system) / 1000),
+    );
+  };
+}