talon-agent 4.4.0 → 4.6.0

package/src/core/memory/render.ts

@@ -0,0 +1,243 @@
+/**
+ * Typed memory rows → a `memory.md`-shaped document.
+ *
+ * The inverse of import.ts, and the second half of "markdown becomes a
+ * view" (plan §3.1): the store holds the claims, the file is a rendered
+ * projection of them — still human-readable, still `Read`-able, still
+ * editable, but no longer authoritative.
+ *
+ * Two properties matter more than prettiness:
+ *
+ *   - **Deterministic.** The same rows render to the same bytes, every
+ *     time. A file that churns on every render is a file nobody can diff
+ *     and a prompt prefix that never caches.
+ *   - **A fixed point with import.** Chunked rows are regrouped under
+ *     their base subject and keyed state renders under its key, so
+ *     importing this document back produces exactly the rows it came
+ *     from and reports zero inserts. That round trip is what lets a
+ *     hand-edit be folded back instead of duplicated.
+ *
+ * Truncation is selection, not slicing: sections are dropped whole, from
+ * the bottom of the ranking, and the tail is named so the reader knows
+ * to ask the store for the rest.
+ */
+
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+
+import {
+  listMemories,
+  type MemoryKind,
+  type MemoryRow,
+} from "../../storage/memory.js";
+import { dirs, files } from "../../util/paths.js";
+import { toYMD } from "../../util/time.js";
+import {
+  MEMORY_INJECT_MAX_CHARS,
+  headingTitle,
+} from "../prompt/memory-view.js";
+
+// ── Tunables ────────────────────────────────────────────────────────────────
+
+/**
+ * Kind order in the document, most durable first. `reflection` is absent
+ * on purpose: the diary is the persona layer and never a fact source, so
+ * it is not part of the memory projection (plan §3.1).
+ */
+const KIND_ORDER: readonly MemoryKind[] = [
+  "directive",
+  "relationship",
+  "fact",
+  "state",
+  "episode",
+];
+
+/** How many rows per kind the default render pulls from the store. */
+const KIND_ROW_LIMIT = 500;
+
+/** The preamble. Import ignores everything above the first `## `. */
+const HEADER =
+  "# Memory\n\n" +
+  "_Rendered from the typed memory store. Edit freely — " +
+  "`talon memory import` folds changes back._\n";
+
+/** The ` (n/N)` marker import appends when a section outgrew the text cap. */
+const CHUNK_SUFFIX = /^(.*) \((\d+)\/(\d+)\)$/;
+
+// ── Ordering ────────────────────────────────────────────────────────────────
+
+/** One row placed under its section heading. */
+type Piece = { label: string; index: number; row: MemoryRow };
+
+/**
+ * A keyed row renders under its key, which is the more specific label and
+ * the one import reads back. Chunk `n > 1` carries a `.n` key suffix so
+ * each chunk owns a distinct key; the heading drops it again.
+ */
+function stateLabel(row: MemoryRow, index: number): string {
+  const key = row.key ?? row.subject;
+  const suffix = `.${index}`;
+  return index > 1 && key.endsWith(suffix) ? key.slice(0, -suffix.length) : key;
+}
+
+function pieceOf(row: MemoryRow): Piece {
+  const chunk = CHUNK_SUFFIX.exec(row.subject);
+  const index = chunk ? Number(chunk[2]) : 1;
+  const base = chunk?.[1] ?? row.subject;
+  return {
+    label: row.kind === "state" ? stateLabel(row, index) : base,
+    index,
+    row,
+  };
+}
+
+/** Pinned first, then kind, then salience, then recency; id breaks ties. */
+function compareRows(a: MemoryRow, b: MemoryRow): number {
+  return (
+    Number(b.pinned) - Number(a.pinned) ||
+    KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind) ||
+    b.salience - a.salience ||
+    b.lastSeenAt - a.lastSeenAt ||
+    a.id - b.id
+  );
+}
+
+// ── Rendering ───────────────────────────────────────────────────────────────
+
+/** One heading plus its rows, blank-line separated, chunks back in order. */
+function renderSection(label: string, pieces: readonly Piece[]): string {
+  const body = [...pieces]
+    .sort((a, b) => a.index - b.index)
+    .map((piece) => piece.row.text)
+    .join("\n\n");
+  return `## ${headingTitle(label)}\n\n${body}\n`;
+}
+
+/**
+ * Group ranked rows into sections. A section takes the position of its
+ * best-ranked row, so the ranking survives the grouping.
+ */
+function sectionsFrom(rows: readonly MemoryRow[]): string[] {
+  const groups = new Map<string, Piece[]>();
+  const ranked = rows
+    .filter((row) => KIND_ORDER.includes(row.kind))
+    .sort(compareRows);
+  for (const row of ranked) {
+    const piece = pieceOf(row);
+    const held = groups.get(piece.label);
+    if (held) held.push(piece);
+    else groups.set(piece.label, [piece]);
+  }
+  return [...groups].map(([label, pieces]) => renderSection(label, pieces));
+}
+
+/** The pointer that replaces whatever the budget could not carry. */
+function moreLine(omitted: number): string {
+  const plural = omitted === 1 ? "section" : "sections";
+  return `_… ${omitted} more ${plural} in the store — \`talon memory list\`_\n`;
+}
+
+/**
+ * Take whole sections until the budget is spent, then give back sections
+ * until the "N more" pointer fits too — the document as a whole stays
+ * inside the budget, and every cut lands on a section boundary. The
+ * header plus that pointer is the floor: a budget smaller than those two
+ * still gets them, because a document that cannot say what it dropped is
+ * worse than one slightly over budget.
+ */
+function selectSections(
+  sections: readonly string[],
+  budget: number,
+): { taken: readonly string[]; omitted: number } {
+  let spent = HEADER.length;
+  let take = 0;
+  for (const section of sections) {
+    if (spent + section.length + 1 > budget) break;
+    spent += section.length + 1;
+    take += 1;
+  }
+  let omitted = sections.length - take;
+  while (
+    take > 0 &&
+    omitted > 0 &&
+    spent + moreLine(omitted).length + 1 > budget
+  ) {
+    take -= 1;
+    spent -= sections[take]!.length + 1;
+    omitted += 1;
+  }
+  return { taken: sections.slice(0, take), omitted };
+}
+
+/** Options shared by the render and the file write. */
+export type RenderOptions = {
+  /** Char budget for the whole document. Defaults to the inject cap. */
+  budget?: number;
+  /**
+   * Rows to render instead of the live store — the seam the tests and
+   * (from PR 9) the pre-ranked core view use.
+   */
+  rows?: readonly MemoryRow[];
+};
+
+function liveRows(): MemoryRow[] {
+  return KIND_ORDER.flatMap((kind) =>
+    listMemories({ kind, limit: KIND_ROW_LIMIT }),
+  );
+}
+
+/**
+ * Render the live store as a `memory.md` document. Same rows in, same
+ * bytes out.
+ */
+export function renderMemoryMarkdown(opts: RenderOptions = {}): string {
+  const sections = sectionsFrom(opts.rows ?? liveRows());
+  const { taken, omitted } = selectSections(
+    sections,
+    opts.budget ?? MEMORY_INJECT_MAX_CHARS,
+  );
+  const parts = [HEADER, ...taken];
+  if (omitted > 0) parts.push(moreLine(omitted));
+  return parts.join("\n");
+}
+
+// ── Writing ─────────────────────────────────────────────────────────────────
+
+/** Where a render went, and what it displaced. */
+export type RenderWrite = {
+  path: string;
+  bytes: number;
+  /** The archived copy of the previous file, when one was taken. */
+  backup?: string;
+};
+
+/**
+ * Copy the file aside before it is replaced — once per day, so a render
+ * loop can't bury the archive, and never overwriting an existing backup,
+ * so the first render of the day keeps the hand-written original.
+ */
+function backUp(path: string, archiveDir: string): string | undefined {
+  if (!existsSync(path)) return undefined;
+  const dest = join(archiveDir, `memory-before-render-${toYMD(new Date())}.md`);
+  if (existsSync(dest)) return undefined;
+  mkdirSync(archiveDir, { recursive: true });
+  copyFileSync(path, dest);
+  return dest;
+}
+
+/** Render the store over `memory.md`, keeping a dated copy of what was there. */
+export function writeRenderedMemory(
+  path: string = files.memory,
+  opts: RenderOptions & { archiveDir?: string } = {},
+): RenderWrite {
+  const markdown = renderMemoryMarkdown(opts);
+  const backup = backUp(path, opts.archiveDir ?? dirs.memoryArchive);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileAtomic.sync(path, markdown);
+  return {
+    path,
+    bytes: markdown.length,
+    ...(backup !== undefined ? { backup } : {}),
+  };
+}

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/core/prompt/memory-view.ts

@@ -60,7 +60,7 @@ const MAX_OMITTED_NAMED = 8;
  * dropped and most cheaply re-derived. `historical` is last for the mirror
  * reason: it will never change again, so it is the least urgent to carry.
  */
-const TIER_ORDER = [
+export const TIER_ORDER = [
   "directive",
   "people",
   "active",
@@ -69,7 +69,7 @@ const TIER_ORDER = [
   "historical",
 ] as const;
 
-type Tier = (typeof TIER_ORDER)[number];
+export type Tier = (typeof TIER_ORDER)[number];
 
 const tier = (name: Tier): number => TIER_ORDER.indexOf(name);
 
@@ -107,7 +107,7 @@ const MATCHERS: readonly { readonly tier: Tier; readonly match: RegExp }[] = [
 const STATUS_TIER = tier("status");
 const GENERAL_TIER = tier("general");
 
-function classify(title: string): number {
+export function classify(title: string): number {
   for (const m of MATCHERS) {
     if (m.match.test(title)) return tier(m.tier);
   }
@@ -116,7 +116,7 @@ function classify(title: string): number {
 
 // ── Parsing ─────────────────────────────────────────────────────────────────
 
-type Section = {
+export type Section = {
   /** Heading with markup and trailing qualifiers stripped — the display name. */
   readonly title: string;
   /** Whole section including its heading and any `###` children. */
@@ -131,7 +131,7 @@ type Section = {
 };
 
 /** Strip `## ` markup and bold markers from a heading line. */
-function headingTitle(heading: string): string {
+export function headingTitle(heading: string): string {
   return heading
     .replace(/^#+\s*/, "")
     .replace(/\*\*/g, "")
@@ -144,7 +144,7 @@ function headingTitle(heading: string): string {
  * parenthetical is exactly what makes each snapshot look unique while the
  * underlying topic repeats, so removing it is what lets a family collapse.
  */
-function familyKey(title: string): string {
+export function familyKey(title: string): string {
   return title
     .replace(/\s*\([^)]*\)\s*$/, "")
     .replace(/\s*[—–-]\s*(?:as of|run #).*$/i, "")
@@ -172,7 +172,7 @@ function recencyKey(heading: string): string {
  * the first `## `) plus one entry per `## ` section. The split is on `## `
  * only, so an `h3` travels with the section it belongs to.
  */
-function parseSections(content: string): {
+export function parseSections(content: string): {
   preamble: string;
   sections: Section[];
 } {
@@ -201,7 +201,7 @@ function parseSections(content: string): {
  * the one that appeared first. Only the `status` tier collapses — two
  * sections about people are two different people, not two snapshots of one.
  */
-function collapseFamilies(sections: readonly Section[]): {
+export function collapseFamilies(sections: readonly Section[]): {
   kept: Section[];
   dropped: Section[];
 } {

package/src/frontend/native/handlers.ts

@@ -18,6 +18,7 @@ import {
 } from "./extensions.js";
 import { historyPage, searchHistory } from "./history.js";
 import { readLogEntries } from "./logs.js";
+import { listMemory, memoryWhy } from "./memory.js";
 import {
   describeAttachment,
   MAX_UPLOAD_BYTES,
@@ -98,6 +99,10 @@ export function buildBridgeHandlers(
     deleteChat: (id) => deleteChat(runtime, id),
     history: (id, opts) => historyPage(runtime, id, opts),
     search: (query, chatId) => searchHistory(runtime, query, chatId),
+    // Memory is daemon-wide state in SQLite, not per-runtime — these are
+    // straight delegations to the read-only half of the store.
+    listMemory,
+    memoryWhy,
     send: (id, text, opts) => {
       const entry = chats.get(id) ?? chats.ensure(id);
       // Resolve the client's references into the records this daemon minted

package/src/frontend/native/memory.ts

@@ -0,0 +1,112 @@
+/**
+ * Memory reads for the client bridge — the read-only half of the typed
+ * memory store (`storage/memory.ts`), projected onto the wire shapes in
+ * protocol.ts.
+ *
+ * Read-only on purpose: a bridge client can ask what Talon remembers and
+ * why, and nothing more. Asserting, superseding and dropping stay with
+ * the write path (rollout PR 6), so a paired phone can never quietly
+ * rewrite the operator's memory.
+ *
+ * The one piece of policy here is the limit cap: whatever a client asks
+ * for, a single response carries at most `MAX_LIMIT` rows, so a stray
+ * `?limit=1000000` cannot turn a listing into a full-table dump.
+ */
+
+import {
+  getMemory,
+  isMemoryKind,
+  listMemories,
+  memoryHistory,
+  searchMemories,
+  MEMORY_KINDS,
+  type MemoryHistoryRow,
+  type MemoryKind,
+  type MemoryRow,
+} from "../../storage/memory.js";
+import type {
+  MemoryHistoryWire,
+  MemoryRowWire,
+  MemoryWhyWire,
+} from "./protocol.js";
+
+/** Hard ceiling on one listing, whatever the client asks for. */
+const MAX_LIMIT = 100;
+
+/** What `GET /memory` accepts, already coerced from the query string. */
+export type MemoryListQuery = {
+  /** Full-text query; when present the listing becomes a search. */
+  q?: string;
+  kind?: string;
+  limit?: number;
+};
+
+/** An ok listing, or the reason the request was rejected (a 400). */
+export type MemoryListResult =
+  { ok: true; rows: MemoryRowWire[] } | { ok: false; error: string };
+
+/** Project a stored row onto the wire — internals stay daemon-side. */
+function toWire(row: MemoryRow): MemoryRowWire {
+  return {
+    id: row.id,
+    kind: row.kind,
+    subject: row.subject,
+    ...(row.key !== undefined ? { key: row.key } : {}),
+    text: row.text,
+    trust: row.trust,
+    confidence: row.confidence,
+    pinned: row.pinned,
+    hitCount: row.hitCount,
+    salience: row.salience,
+    createdAt: row.createdAt,
+    lastSeenAt: row.lastSeenAt,
+  };
+}
+
+/**
+ * Live rows: a bm25 search when `q` is given, otherwise the ranked
+ * listing (pinned, then salience, then recency). An unknown `kind` is
+ * a client error rather than an empty result — silently returning
+ * nothing for a typo is how a client ends up "showing" an empty memory.
+ */
+export function listMemory(query: MemoryListQuery = {}): MemoryListResult {
+  const raw = query.kind?.trim();
+  let kind: MemoryKind | undefined;
+  if (raw) {
+    if (!isMemoryKind(raw))
+      return {
+        ok: false,
+        error: `Unknown kind "${raw}" (expected one of ${MEMORY_KINDS.join(", ")})`,
+      };
+    kind = raw;
+  }
+  const limit = Math.min(query.limit ?? MAX_LIMIT, MAX_LIMIT);
+  const q = query.q?.trim();
+  const rows = q
+    ? searchMemories(q, { ...(kind ? { kind } : {}), limit })
+    : listMemories({ ...(kind ? { kind } : {}), limit });
+  return { ok: true, rows: rows.map(toWire) };
+}
+
+/**
+ * One row plus its audit trail, or null when no such id. Reads by id
+ * rather than from the live listing, so a superseded or dropped row
+ * still explains itself — that is the whole point of "why".
+ */
+export function memoryWhy(id: number): MemoryWhyWire | null {
+  const row = getMemory(id);
+  if (!row) return null;
+  return {
+    row: toWire(row),
+    history: memoryHistory(row.id).map(toHistoryWire),
+  };
+}
+
+/** One audit entry on the wire — before/after text stays daemon-side. */
+function toHistoryWire(entry: MemoryHistoryRow): MemoryHistoryWire {
+  return {
+    op: entry.op,
+    at: entry.at,
+    ...(entry.reason !== undefined ? { reason: entry.reason } : {}),
+  };
+}

package/src/frontend/native/protocol.ts

@@ -263,6 +263,51 @@ export type SkillItem = {
  */
 export type ToggleResult = { ok: boolean; error?: string };
 
+/**
+ * One row of the typed memory store, as `GET /memory` lists it.
+ *
+ * A projection, not the stored row: the internal `source`, `contentHash`
+ * and supersede/drop pointers stay daemon-side, and the numbers that
+ * decide where a row ranks (trust, confidence, hits, salience) come
+ * along so a client can show WHY something is remembered, not just
+ * what. `kind` and `trust` are the store's vocabularies as plain
+ * strings — a client renders what it gets rather than refusing an
+ * unknown one.
+ */
+export type MemoryRowWire = {
+  id: number;
+  kind: string;
+  subject: string;
+  /** Present only on keyed `state` rows. */
+  key?: string;
+  text: string;
+  trust: string;
+  /** 0..1. */
+  confidence: number;
+  pinned: boolean;
+  hitCount: number;
+  salience: number;
+  /** Epoch milliseconds. */
+  createdAt: number;
+  /** Epoch milliseconds. */
+  lastSeenAt: number;
+};
+
+/** One audit entry from a row's trail, oldest first in `MemoryWhyWire`. */
+export type MemoryHistoryWire = {
+  /** assert | supersede | drop | merge | pin | unpin | replace_state. */
+  op: string;
+  /** Epoch milliseconds. */
+  at: number;
+  reason?: string;
+};
+
+/** `GET /memory/why?id=` — one row plus everything that happened to it. */
+export type MemoryWhyWire = {
+  row: MemoryRowWire;
+  history: MemoryHistoryWire[];
+};
+
 // Mesh device shapes are canonical in core (the mesh is daemon-wide state,
 // readable from every frontend); re-exported here so bridge clients keep
 // depending on the protocol module alone.