talon-agent 4.5.0 → 4.6.0

package/package.json

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

package/prompts/system/memory-core-view.md

@@ -0,0 +1,7 @@
+## Persistent Memory
+
+The following is your memory store's core view — the durable claims that matter most: pinned items, standing directives, who you are talking to, your highest-salience facts, and current status. It is selected and budgeted, not a whole file, so anything not here is not gone. The rest of the store is one query away (`talon memory list`, or `/memory` in chat), and the full rendered projection is at ~/.talon/workspace/memory/memory.md.
+
+Durable facts, not live status. Reference it naturally; the Memory and Recall policy in this prompt governs how you add to it and keep it current.
+
+{{content}}

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

@@ -0,0 +1,158 @@
+/**
+ * The **core view** — the store's contribution to the static system
+ * prompt (docs/memory-persona-plan.md §3.4).
+ *
+ * Retrieval has two tiers, and the boundary between them is a
+ * prompt-cache invariant:
+ *
+ *   - **Core view** (this module) — pinned directives, the relationship
+ *     layer and the top durable facts plus fresh `state`, computed
+ *     **once per session build** and living in `staticText`. Budgeted,
+ *     never truncated mid-section.
+ *   - **Turn retrieval** (PR 8) — keyed to the incoming message and
+ *     injected into the *user turn*, never into `prepareSystemPrompt()`.
+ *
+ * Because `prepareSystemPrompt` freezes the assembled prompt per
+ * `(chatId, sessionEpoch)`, a fact learned at turn 3 cannot appear in
+ * that session's core view. That is the design, not a bug: reaching for
+ * `notifyPromptInputsChanged()` to "fix" it would force a full-prompt
+ * cache write across every live session on every learned fact (plan
+ * §3.6). Nothing here may ever invalidate a snapshot.
+ *
+ * The store is consulted exactly once per build — one `listMemories`
+ * call, ranked and filtered in memory — so the cost of the core view is
+ * one query per session, not one per kind and not one per turn.
+ */
+
+import { listMemories, type MemoryRow } from "../../storage/memory.js";
+import { renderMemoryMarkdown } from "./render.js";
+
+// ── Tunables ────────────────────────────────────────────────────────────────
+
+/**
+ * Char budget for the whole core view (~2 k tokens). Deliberately well
+ * under the 12 k file-injection cap: this block is paid for by every
+ * session on every frontend, and the rest of the store is a `talon
+ * memory list` away.
+ */
+export const CORE_VIEW_MAX_CHARS = 8_000;
+
+/**
+ * A `state` row older than this is stale and left out — a status
+ * snapshot nobody has touched in a week is noise in a prompt, and the
+ * heartbeat rewrites the live ones far more often than that. Pinning
+ * overrides it, which is what pinning is for.
+ */
+const STATE_FRESH_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Rows pulled from the store before ranking. Generous: the budget, not
+ * this number, is what decides how much reaches the prompt.
+ */
+const CORE_VIEW_ROW_LIMIT = 500;
+
+/**
+ * Kinds eligible for the core view, most durable first. `episode` and
+ * `reflection` are absent on purpose (plan §3.1): episodes decay fast
+ * and are a retrieval-only source, and the diary is the persona layer
+ * and never a fact source. Neither enters the core view — not even
+ * pinned, since a pin must not promote a kind past the tier boundary.
+ */
+const CORE_KINDS: readonly MemoryRow["kind"][] = [
+  "directive",
+  "relationship",
+  "fact",
+];
+
+// ── Selection ───────────────────────────────────────────────────────────────
+
+/** Salience first, then recency; id breaks the tie so the order is stable. */
+function byRank(a: MemoryRow, b: MemoryRow): number {
+  return b.salience - a.salience || b.lastSeenAt - a.lastSeenAt || a.id - b.id;
+}
+
+function eligible(row: MemoryRow, now: number): boolean {
+  if (row.kind === "state")
+    return row.pinned || now - row.lastSeenAt <= STATE_FRESH_MS;
+  return CORE_KINDS.includes(row.kind);
+}
+
+/**
+ * Take rows until the budget is spent. A coarse pre-cut on row text
+ * only: the render does the exact accounting and cuts on section
+ * boundaries, so this exists to keep a 500-row store from being ranked
+ * into a document that can hold a fraction of it.
+ */
+function withinBudget(rows: readonly MemoryRow[], budget: number): MemoryRow[] {
+  const taken: MemoryRow[] = [];
+  let spent = 0;
+  for (const row of rows) {
+    if (spent > budget) break;
+    spent += row.text.length;
+    taken.push(row);
+  }
+  return taken;
+}
+
+/** Options shared by the selection and the render. */
+export type CoreViewOptions = {
+  /** Char budget for the rendered view. Defaults to `CORE_VIEW_MAX_CHARS`. */
+  budget?: number;
+  /** Clock for the `state` freshness window (tests pin it). */
+  now?: number;
+};
+
+/**
+ * The ordered rows behind the core view: pinned first (any eligible
+ * kind), then directives, then the relationship layer, then facts by
+ * salience, then fresh `state`.
+ *
+ * The render re-sorts with the same ranking (`render.ts` `compareRows`),
+ * so this order is what reaches the prompt rather than merely what is
+ * handed over — but the selection is asserted here, where the tiers are
+ * decided, and not through the rendered bytes.
+ */
+export function selectCoreRows(opts: CoreViewOptions = {}): MemoryRow[] {
+  const now = opts.now ?? Date.now();
+  const live = listMemories({ limit: CORE_VIEW_ROW_LIMIT }).filter((row) =>
+    eligible(row, now),
+  );
+  const tiers: MemoryRow[][] = [
+    live.filter((row) => row.pinned).sort(byRank),
+    ...CORE_KINDS.map((kind) =>
+      live.filter((row) => !row.pinned && row.kind === kind).sort(byRank),
+    ),
+    live.filter((row) => !row.pinned && row.kind === "state").sort(byRank),
+  ];
+  const seen = new Set<number>();
+  const ordered = tiers.flat().filter((row) => {
+    if (seen.has(row.id)) return false;
+    seen.add(row.id);
+    return true;
+  });
+  return withinBudget(ordered, opts.budget ?? CORE_VIEW_MAX_CHARS);
+}
+
+// ── Rendering ───────────────────────────────────────────────────────────────
+
+/** A rendered core view, with what it cost to carry. */
+export type CoreView = {
+  text: string;
+  /** Rows selected into the view (0 means the store had nothing to say). */
+  rows: number;
+  /** Rendered size — the number recorded as `prompt.memory_chars`. */
+  chars: number;
+};
+
+/**
+ * Render the core view as a `memory.md`-shaped document, reusing the
+ * projection renderer so the store reads identically in the prompt and
+ * in the file. Budgeted, not truncated: sections are dropped whole from
+ * the bottom of the ranking and the tail is named.
+ */
+export function renderCoreView(opts: CoreViewOptions = {}): CoreView {
+  const budget = opts.budget ?? CORE_VIEW_MAX_CHARS;
+  const rows = selectCoreRows({ ...opts, budget });
+  const text = renderMemoryMarkdown({ rows, budget });
+  return { text, rows: rows.length, chars: text.length };
+}

package/src/core/memory/flag.ts

@@ -0,0 +1,16 @@
+/**
+ * The one flag that gates the typed memory store's read path
+ * (docs/memory-persona-rollout.md, "One flag gates the whole new path").
+ *
+ * Kept in its own module because `core/prompt/assemble.ts` asks the
+ * question but must not reach into `storage/` to answer it: the prompt
+ * layer sees the flag and the core view, nothing else.
+ *
+ * Read per call, never cached: tests flip it between builds, and the
+ * cost is an env lookup on a path that already reads files from disk.
+ */
+
+/** True when `TALON_MEMORY_STORE=1`. Off by default until PR 9 is measured. */
+export function memoryStoreEnabled(): boolean {
+  return process.env.TALON_MEMORY_STORE === "1";
+}

package/src/core/prompt/assemble.ts

@@ -19,6 +19,10 @@
  *   4. Persistent memory (ranked, capped)   prompts/system/persistent-memory.md
  *                                           wrapping ~/.talon/workspace/memory/memory.md
  *                                           via memory-view.ts
+ *                                           — or, with TALON_MEMORY_STORE=1 and a
+ *                                           non-empty store, the typed store's core
+ *                                           view (memory/core-view.ts) wrapped in
+ *                                           prompts/system/memory-core-view.md
  *   4.5 Live state (capped)                 prompts/system/live-state.md
  *                                           wrapping ~/.talon/workspace/memory/state.md
  *                                           (heartbeat-owned, rewritten whole)
@@ -65,6 +69,9 @@ import { renderMemoryView } from "./memory-view.js";
 import { renderWorkspaceListing } from "./workspace-listing.js";
 import { renderSkillsPrompt } from "../../storage/skills.js";
 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 ───────────────────────────────────────────────────────────────────
@@ -109,6 +116,14 @@ export function joinSystemPromptParts(parts: SystemPromptParts): string {
  */
 export const STATE_INJECT_MAX_CHARS = 2_000;
 
+/**
+ * Size of the injected memory block, recorded on every build from both
+ * tiers. The whole point of the flag being default-off is that these two
+ * populations can be compared before the store becomes the default path
+ * (rollout Decision 4).
+ */
+const MEMORY_CHARS_METRIC = "prompt.memory_chars";
+
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
 function readOptionalFile(path: string): string {
@@ -122,6 +137,50 @@ function readOptionalFile(path: string): string {
 
 let lastLoggedPromptKey = "";
 
+/** A memory block ready for the static prompt, with the label it logs under. */
+type MemorySection = { section: string; label: string };
+
+/**
+ * The store's core view, when `TALON_MEMORY_STORE` is on and the store
+ * has something to say. Budgeted (not truncated) and computed once per
+ * build — this is the session-frozen tier of plan §3.4, so it belongs in
+ * `staticText` and nowhere else.
+ *
+ * An empty store falls through to the file, which is what makes the flag
+ * safe to turn on before the import has ever run.
+ */
+function coreViewSection(): MemorySection | undefined {
+  if (!memoryStoreEnabled()) return undefined;
+  const view = renderCoreView();
+  if (view.rows === 0) return undefined;
+  recordHistogram(MEMORY_CHARS_METRIC, view.chars);
+  return {
+    section: loadSystemTemplate("memory-core-view", { content: view.text }),
+    label: "memory(store)",
+  };
+}
+
+/**
+ * The rendered `memory.md` file, ranked and capped. The path every
+ * deployment is on until the flag flips: over the cap the view ranks
+ * sections rather than head-slicing, so durable knowledge isn't evicted
+ * by whatever happens to sit at the top of the file (memory-view.ts).
+ */
+function memoryFileSection(): MemorySection | undefined {
+  const memory = readOptionalFile(pathFiles.memory);
+  if (!memory) return undefined;
+  const { text, truncated, omitted } = renderMemoryView(memory);
+  recordHistogram(MEMORY_CHARS_METRIC, text.length);
+  return {
+    section: loadSystemTemplate("persistent-memory", {
+      content: text,
+      truncated: truncated ? "yes" : undefined,
+      omitted: omitted || undefined,
+    }),
+    label: truncated ? "memory(ranked)" : "memory",
+  };
+}
+
 // ── Assembly ────────────────────────────────────────────────────────────────
 
 /** Inputs for `assembleSystemPrompt`. */
@@ -182,22 +241,16 @@ export function assembleSystemPrompt(
     loaded.push(frontendFile.replace(".md", ""));
   }
 
-  // 4. Persistent memory — size-capped so a memory file that has grown
-  //    for months can't bloat every session from turn 0. Over the cap the
-  //    view ranks sections rather than head-slicing, so durable knowledge
-  //    isn't evicted by whatever happens to sit at the top of the file
-  //    (see prompt/memory-view.ts).
-  const memory = readOptionalFile(pathFiles.memory);
-  if (memory) {
-    const { text, truncated, omitted } = renderMemoryView(memory);
-    staticParts.push(
-      loadSystemTemplate("persistent-memory", {
-        content: text,
-        truncated: truncated ? "yes" : undefined,
-        omitted: omitted || undefined,
-      }),
-    );
-    loaded.push(truncated ? "memory(ranked)" : "memory");
+  // 4. Persistent memory — the store's core view when the flag is on and
+  //    the store has rows, else the ranked, size-capped `memory.md` file,
+  //    so a memory file that has grown for months can't bloat every
+  //    session from turn 0. Static either way: both tiers are frozen for
+  //    the session's lifetime (plan §3.4/§3.6). Anything learned
+  //    mid-session reaches the model through turn retrieval instead.
+  const memorySection = coreViewSection() ?? memoryFileSection();
+  if (memorySection) {
+    staticParts.push(memorySection.section);
+    loaded.push(memorySection.label);
   }
 
   // 4.5. Live state — the heartbeat's rewritten-whole status snapshot, kept

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

@@ -27,15 +27,16 @@ 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/live-state.md" with { type: "file" };
-import asset17 from "../../../prompts/system/memory-recall.md" with { type: "file" };
-import asset18 from "../../../prompts/system/persistent-memory.md" with { type: "file" };
-import asset19 from "../../../prompts/system/skills.md" with { type: "file" };
-import asset20 from "../../../prompts/system/triggers.md" with { type: "file" };
-import asset21 from "../../../prompts/system/workspace.md" with { type: "file" };
-import asset22 from "../../../prompts/teams.md" with { type: "file" };
-import asset23 from "../../../prompts/telegram.md" with { type: "file" };
-import asset24 from "../../../prompts/terminal.md" with { type: "file" };
-import asset25 from "../../../prompts/whatsapp.md" with { type: "file" };
+import asset17 from "../../../prompts/system/memory-core-view.md" with { type: "file" };
+import asset18 from "../../../prompts/system/memory-recall.md" with { type: "file" };
+import asset19 from "../../../prompts/system/persistent-memory.md" with { type: "file" };
+import asset20 from "../../../prompts/system/skills.md" with { type: "file" };
+import asset21 from "../../../prompts/system/triggers.md" with { type: "file" };
+import asset22 from "../../../prompts/system/workspace.md" with { type: "file" };
+import asset23 from "../../../prompts/teams.md" with { type: "file" };
+import asset24 from "../../../prompts/telegram.md" with { type: "file" };
+import asset25 from "../../../prompts/terminal.md" with { type: "file" };
+import asset26 from "../../../prompts/whatsapp.md" with { type: "file" };
 
 /** rel path (posix, under prompts/) → embedded file path (/$bunfs/… when compiled). */
 const ASSETS: Record<string, string> = {
@@ -56,15 +57,16 @@ const ASSETS: Record<string, string> = {
   "system/goals.md": asset14,
   "system/heartbeat-agent.md": asset15,
   "system/live-state.md": asset16,
-  "system/memory-recall.md": asset17,
-  "system/persistent-memory.md": asset18,
-  "system/skills.md": asset19,
-  "system/triggers.md": asset20,
-  "system/workspace.md": asset21,
-  "teams.md": asset22,
-  "telegram.md": asset23,
-  "terminal.md": asset24,
-  "whatsapp.md": asset25,
+  "system/memory-core-view.md": asset17,
+  "system/memory-recall.md": asset18,
+  "system/persistent-memory.md": asset19,
+  "system/skills.md": asset20,
+  "system/triggers.md": asset21,
+  "system/workspace.md": asset22,
+  "teams.md": asset23,
+  "telegram.md": asset24,
+  "terminal.md": asset25,
+  "whatsapp.md": asset26,
 };
 
 /** Read an embedded prompt by its rel path (e.g. "system/cron.md"). */

package/src/storage/metrics.ts

@@ -22,6 +22,14 @@ const PHASE_HISTOGRAM: Record<TurnPhase, string> = {
 
 const legacyCounters = new Map<string, number>();
 
+/**
+ * Process-lifetime distributions for values that are not chat-turn
+ * latencies and so have nowhere to live on a session record — currently
+ * `prompt.memory_chars`, the size of the injected memory block, which is
+ * what the `TALON_MEMORY_STORE` before/after comparison reads.
+ */
+const processHistograms = new Map<string, MetricsLatencyAgg>();
+
 export type MetricsSnapshot = {
   counters: Record<string, number>;
   histograms: Record<
@@ -34,6 +42,18 @@ export function incrementCounter(name: string, amount = 1): void {
   legacyCounters.set(name, (legacyCounters.get(name) ?? 0) + amount);
 }
 
+/**
+ * Record one observation of a non-turn distribution. Lifetime-scoped and
+ * in-process, like the legacy counters: it surfaces in `getMetrics()`
+ * (count / avg / min / max), not in the daily rollup.
+ */
+export function recordHistogram(name: string, value: number): void {
+  if (!Number.isFinite(value)) return;
+  const agg = processHistograms.get(name) ?? emptyAgg();
+  mergeAgg(agg, { count: 1, sumMs: value, minMs: value, maxMs: value });
+  processHistograms.set(name, agg);
+}
+
 function addCounter(
   counters: Record<string, number>,
   name: string,
@@ -158,10 +178,14 @@ function buildSnapshot(
 export function getMetrics(): MetricsSnapshot {
   const counters: Record<string, number> = {};
   for (const [key, value] of legacyCounters) addCounter(counters, key, value);
-  return buildSnapshot(
+  const snapshot = buildSnapshot(
     getAllSessions().map(({ info }) => info.metrics.lifetime),
     counters,
   );
+  for (const [name, agg] of processHistograms) {
+    if (agg.count) snapshot.histograms[name] = snapshotAgg(agg);
+  }
+  return snapshot;
 }
 
 /** Today's (UTC) fleet snapshot, aggregated from the sessions' daily
@@ -177,5 +201,6 @@ export function getTodayMetrics(): MetricsSnapshot {
 
 export function resetMetrics(): void {
   legacyCounters.clear();
+  processHistograms.clear();
   resetAllSessionMetrics();
 }