talon-agent 4.4.0 → 4.5.0

package/package.json

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

package/src/cli/index.ts

@@ -157,7 +157,7 @@ export async function runCli(): Promise<void> {
         `    ${pc.cyan("skill")}      Manage skills (install/enable/disable)`,
       );
       console.log(
-        `    ${pc.cyan("memory")}     Read/edit the memory store (list/search/remember)`,
+        `    ${pc.cyan("memory")}     Read/edit the memory store (list/search/import/render)`,
       );
       console.log(`    ${pc.cyan("config")}     View/edit configuration`);
       console.log(`    ${pc.cyan("logs")}       Tail log file`);

package/src/cli/memory.ts

@@ -8,6 +8,11 @@
  */
 
 import pc from "picocolors";
+import { importAll } from "../core/memory/import.js";
+import {
+  renderMemoryMarkdown,
+  writeRenderedMemory,
+} from "../core/memory/render.js";
 import {
   assertMemory,
   dropMemory,
@@ -33,6 +38,8 @@ const USAGE = [
   `    ${pc.cyan("remember <kind> <subject> <text>")} Record an operator claim`,
   `    ${pc.cyan("forget <id> [reason]")}           Drop a row to the graveyard`,
   `    ${pc.cyan("state <key> <text>")}             Replace the row for a state key`,
+  `    ${pc.cyan("import")}                         Fold memory.md + daily notes into the store`,
+  `    ${pc.cyan("render [--write]")}               Render the store as memory.md`,
   "",
   `  Kinds: ${MEMORY_KINDS.join(", ")}`,
   "",
@@ -134,6 +141,24 @@ function cmdState(args: readonly string[]): void {
   console.log(`  ${pc.green("●")} ${key} is now #${id}\n`);
 }
 
+function cmdImport(): void {
+  const { inserted, superseded, skipped } = importAll();
+  console.log(
+    `  ${pc.green("●")} Imported: ${inserted} new, ${superseded} updated, ${skipped} unchanged\n`,
+  );
+}
+
+function cmdRender(args: readonly string[]): void {
+  if (!args.includes("--write")) {
+    console.log(renderMemoryMarkdown());
+    return;
+  }
+  const { path, bytes, backup } = writeRenderedMemory();
+  console.log(`  ${pc.green("●")} Wrote ${bytes} chars to ${path}`);
+  if (backup) console.log(`  ${pc.dim(`Previous file archived to ${backup}`)}`);
+  console.log();
+}
+
 /** Route a `talon memory <command>` invocation. */
 export function runMemoryCommand(args: readonly string[]): void {
   try {
@@ -157,6 +182,12 @@ export function runMemoryCommand(args: readonly string[]): void {
       case "state":
         cmdState(args.slice(1));
         break;
+      case "import":
+        cmdImport();
+        break;
+      case "render":
+        cmdRender(args.slice(1));
+        break;
       default:
         console.log(USAGE);
     }

package/src/core/memory/import.ts

@@ -0,0 +1,380 @@
+/**
+ * `memory.md` and the daily notes → typed memory rows.
+ *
+ * The store (storage/memory.ts) becomes the source of truth in PR 8, but
+ * the markdown files hold years of the operator's own writing and stay
+ * hand-editable afterwards. This module is the bridge: it seeds the store
+ * from the files, and — because it is idempotent by content hash — it is
+ * also how a hand-edit to the rendered `memory.md` folds back in
+ * (plan §3.1, rollout PR 5).
+ *
+ * Three rules make re-running it safe:
+ *
+ *   - **The parser is PR 1's.** Sections, families and tiers come from
+ *     prompt/memory-view.ts, so what the prompt considers one status
+ *     family is what the store considers one keyed state row. Nothing is
+ *     classified twice, two different ways.
+ *   - **Content hash decides.** A live import-owned row with the same
+ *     kind + subject + key and the same hash is left alone; a different
+ *     hash is a hand-edit, and supersedes the row so the old text stays
+ *     in the audit trail. Only a subject never seen before inserts.
+ *   - **The files are never written.** Import reads; render writes. A
+ *     failed or partial import loses nothing.
+ *
+ * Kind follows the heading's tier, because the tier already encodes the
+ * lifecycle: directives are intent, status snapshots are keyed state,
+ * historical sections are episodes, people sections are relationships,
+ * everything else is a durable fact.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import {
+  MAX_SUBJECT_LENGTH,
+  MAX_TEXT_LENGTH,
+  assertMemory,
+  listMemories,
+  memoryContentHash,
+  replaceStateKey,
+  supersedeMemory,
+  type MemoryKind,
+  type MemoryRow,
+  type MemorySource,
+} from "../../storage/memory.js";
+import { dirs, files } from "../../util/paths.js";
+import {
+  TIER_ORDER,
+  classify,
+  collapseFamilies,
+  familyKey,
+  parseSections,
+  type Section,
+  type Tier,
+} from "../prompt/memory-view.js";
+
+// ── Tunables ────────────────────────────────────────────────────────────────
+
+/** `source.actor` on every row this module writes — the ownership marker. */
+const IMPORT_ACTOR = "import";
+
+/** Recorded on the supersede that a changed section causes. */
+const RE_IMPORT_REASON = "re-import: file changed";
+
+/** Daily notes only: `YYYY-MM-DD.md`, which excludes `diary-*.md`. */
+const DAILY_NOTE = /^(\d{4}-\d{2}-\d{2})\.md$/;
+
+/**
+ * A heading that is just a date is a day's episode — which is how the
+ * render emits an imported daily note, so reading one back produces the
+ * episode it came from rather than a fresh fact.
+ */
+const DATE_HEADING = /^\d{4}-\d{2}-\d{2}$/;
+
+/** How many same-subject rows are scanned for the import-owned one. */
+const LOOKUP_LIMIT = 200;
+
+/** Room left for a ` (n/N)` chunk or ` #n` duplicate suffix on a subject. */
+const SUBJECT_SUFFIX_ROOM = 16;
+
+/** Cap on a generated state key, inside the store's own 100-char limit. */
+const MAX_SLUG_LENGTH = 90;
+
+/**
+ * The lifecycle each heading tier maps to. `active` and `general` are
+ * durable knowledge with no special lifecycle, so both land as facts.
+ */
+const KIND_BY_TIER: Readonly<Record<Tier, MemoryKind>> = {
+  directive: "directive",
+  people: "relationship",
+  active: "fact",
+  general: "fact",
+  status: "state",
+  historical: "episode",
+};
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/** What one import run did, per row. */
+export type ImportCounts = {
+  inserted: number;
+  superseded: number;
+  skipped: number;
+};
+
+/** One row an import wants to land — the unit of the idempotency check. */
+type Claim = {
+  kind: MemoryKind;
+  subject: string;
+  key?: string;
+  text: string;
+  source: MemorySource;
+};
+
+const emptyCounts = (): ImportCounts => ({
+  inserted: 0,
+  superseded: 0,
+  skipped: 0,
+});
+
+function addCounts(into: ImportCounts, from: ImportCounts): ImportCounts {
+  return {
+    inserted: into.inserted + from.inserted,
+    superseded: into.superseded + from.superseded,
+    skipped: into.skipped + from.skipped,
+  };
+}
+
+// ── Text shaping ────────────────────────────────────────────────────────────
+
+/**
+ * A state key from a family key: `Inbox / CI Watch` → `inbox.ci-watch`.
+ * The slash is the family separator the operator already writes, so it
+ * becomes the key's dot; everything else collapses to a dash.
+ */
+function slugKey(family: string): string {
+  const slug = family
+    .toLowerCase()
+    .replace(/\s*\/\s*/g, ".")
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9_.-]/g, "")
+    .replace(/-{2,}/g, "-")
+    .replace(/\.{2,}/g, ".")
+    .replace(/^[-._]+|[-._]+$/g, "");
+  return slug.slice(0, MAX_SLUG_LENGTH) || "section";
+}
+
+/**
+ * Demote `## ` headings inside a claim's body to `### `.
+ *
+ * A daily note is a whole document and routinely carries its own `## `
+ * headings. Stored verbatim, the render would emit them at the top level
+ * and the next import would read one row back as several sections — and
+ * an embedded `## Active Investigations` would collide with the real
+ * section of that name and supersede it. A claim's body therefore never
+ * holds a top-level heading. Running this twice changes nothing, which is
+ * what keeps the round trip a fixed point.
+ */
+function demoteHeadings(body: string): string {
+  return body.replace(/^##(?=\s)/gm, "###");
+}
+
+/** Blank-line-separated paragraphs, trimmed and normalized. */
+function paragraphsOf(text: string): string[] {
+  return demoteHeadings(text)
+    .split(/\n\s*\n/)
+    .map((para) => para.trim())
+    .filter(Boolean);
+}
+
+/** A single paragraph bigger than the cap — the one place text is lost. */
+function hardCut(para: string): string {
+  return `${para.slice(0, MAX_TEXT_LENGTH - 1).trimEnd()}…`;
+}
+
+/**
+ * Pack paragraphs into chunks of at most `MAX_TEXT_LENGTH`. Splitting on
+ * paragraph boundaries keeps every chunk readable on its own — a claim
+ * cut mid-sentence is worse than no claim. Rejoining the chunks with a
+ * blank line reproduces the input exactly, which is what makes
+ * import → render → import a fixed point.
+ */
+function chunkParagraphs(paras: readonly string[]): string[] {
+  const chunks: string[] = [];
+  let current = "";
+  for (const para of paras) {
+    const piece = para.length > MAX_TEXT_LENGTH ? hardCut(para) : para;
+    const joined = current ? `${current}\n\n${piece}` : piece;
+    if (joined.length <= MAX_TEXT_LENGTH) {
+      current = joined;
+      continue;
+    }
+    if (current) chunks.push(current);
+    current = piece;
+  }
+  if (current) chunks.push(current);
+  return chunks;
+}
+
+// ── Claims ──────────────────────────────────────────────────────────────────
+
+/** Clamp a subject, leaving room for the suffixes appended below. */
+function clampSubject(subject: string): string {
+  return subject.slice(0, MAX_SUBJECT_LENGTH - SUBJECT_SUFFIX_ROOM).trim();
+}
+
+/**
+ * Two sections can share a heading. Without a disambiguator the second
+ * would supersede the first on every run and vice versa, so occurrence
+ * `n > 1` gets a ` #n` marker — deliberately not a parenthetical, which
+ * `familyKey` would strip straight back off on the next import.
+ */
+function disambiguate(
+  seen: Map<string, number>,
+  kind: MemoryKind,
+  subject: string,
+): string {
+  const slot = `${kind}|${subject}`;
+  const occurrence = (seen.get(slot) ?? 0) + 1;
+  seen.set(slot, occurrence);
+  return occurrence === 1 ? subject : `${subject} #${occurrence}`;
+}
+
+/** Spread one section's text across as many rows as the cap needs. */
+function claimsFrom(
+  base: { kind: MemoryKind; subject: string; key?: string },
+  paras: readonly string[],
+  source: MemorySource,
+): Claim[] {
+  const chunks = chunkParagraphs(paras);
+  const many = chunks.length > 1;
+  return chunks.map((text, index) => {
+    const nth = index + 1;
+    const subject = many
+      ? `${base.subject} (${nth}/${chunks.length})`
+      : base.subject;
+    const key =
+      base.key !== undefined && many && nth > 1
+        ? `${base.key}.${nth}`
+        : base.key;
+    return {
+      kind: base.kind,
+      subject,
+      text,
+      source,
+      ...(key !== undefined ? { key } : {}),
+    };
+  });
+}
+
+/**
+ * One `## ` section → its rows. A `state` section's subject is its key:
+ * the render emits keyed rows under their key, so anchoring both on the
+ * slug is what keeps import → render → import a no-op.
+ */
+function sectionClaims(
+  section: Section,
+  source: MemorySource,
+  seen: Map<string, number>,
+): Claim[] {
+  const dated = DATE_HEADING.test(section.title);
+  const tier = TIER_ORDER[classify(section.title)] ?? "general";
+  const kind = dated ? "episode" : KIND_BY_TIER[tier];
+  const family = familyKey(section.title) || section.title;
+  // People sections are per-person and a dated section is one day, so the
+  // heading itself is the subject; everything else is keyed on the family
+  // so a family's snapshots line up on one row.
+  const named = dated || tier === "people" ? section.title : family;
+  const key = kind === "state" ? slugKey(family) : undefined;
+  const subject = disambiguate(
+    seen,
+    kind,
+    clampSubject(key ?? named) || "untitled",
+  );
+  const newline = section.body.indexOf("\n");
+  const paras = paragraphsOf(
+    newline === -1 ? "" : section.body.slice(newline + 1),
+  );
+  if (paras.length === 0) return [];
+  const anchor = key === undefined ? { kind, subject } : { kind, subject, key };
+  return claimsFrom(anchor, paras, source);
+}
+
+// ── Landing ─────────────────────────────────────────────────────────────────
+
+/** The live row this claim owns, if it has landed before. */
+function liveImportRow(claim: Claim): MemoryRow | undefined {
+  return listMemories({
+    kind: claim.kind,
+    subject: claim.subject,
+    limit: LOOKUP_LIMIT,
+  }).find((row) => row.source.actor === IMPORT_ACTOR && row.key === claim.key);
+}
+
+/**
+ * Land one claim: skip an unchanged row, supersede a changed one, insert
+ * a new one. Keyed state goes in through `replaceStateKey`, so the newest
+ * snapshot of a family is the single live row for its key.
+ */
+function landClaim(claim: Claim): keyof ImportCounts {
+  const hash = memoryContentHash(
+    claim.kind,
+    claim.subject,
+    claim.key,
+    claim.text,
+  );
+  const existing = liveImportRow(claim);
+  if (existing?.contentHash === hash) return "skipped";
+  if (existing) {
+    supersedeMemory(existing.id, claim.text, RE_IMPORT_REASON);
+    return "superseded";
+  }
+  if (claim.kind === "state" && claim.key !== undefined) {
+    replaceStateKey(claim.key, claim.text, claim.source, {
+      subject: claim.subject,
+      trust: "operator",
+    });
+  } else {
+    assertMemory({
+      kind: claim.kind,
+      subject: claim.subject,
+      text: claim.text,
+      source: claim.source,
+      trust: "operator",
+    });
+  }
+  return "inserted";
+}
+
+function landAll(claims: Iterable<Claim>): ImportCounts {
+  const counts = emptyCounts();
+  for (const claim of claims) counts[landClaim(claim)] += 1;
+  return counts;
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Import `memory.md`: one row per `## ` section, families collapsed
+ * first so only a status family's newest snapshot becomes its live state
+ * row. A missing file is not an error — a fresh install has none.
+ */
+export function importMemoryFile(path: string = files.memory): ImportCounts {
+  if (!existsSync(path)) return emptyCounts();
+  const content = readFileSync(path, "utf8");
+  const source: MemorySource = { actor: IMPORT_ACTOR, chat: basename(path) };
+  const { kept } = collapseFamilies(parseSections(content).sections);
+  const seen = new Map<string, number>();
+  return landAll(
+    kept.flatMap((section) => sectionClaims(section, source, seen)),
+  );
+}
+
+/**
+ * Import the daily notes: one `episode` per `YYYY-MM-DD.md`, subject the
+ * date. `diary-*.md` is the soul's first-person writing — a reflection,
+ * never a fact source (plan §3.1) — so the filename pattern excludes it.
+ */
+export function importDailyNotes(dir: string = dirs.dailyMemory): ImportCounts {
+  if (!existsSync(dir)) return emptyCounts();
+  let counts = emptyCounts();
+  for (const name of readdirSync(dir).sort()) {
+    const date = DAILY_NOTE.exec(name)?.[1];
+    if (!date) continue;
+    const paras = paragraphsOf(readFileSync(join(dir, name), "utf8"));
+    if (paras.length === 0) continue;
+    const source: MemorySource = { actor: IMPORT_ACTOR, chat: name };
+    const claims = claimsFrom(
+      { kind: "episode", subject: date },
+      paras,
+      source,
+    );
+    counts = addCounts(counts, landAll(claims));
+  }
+  return counts;
+}
+
+/** Both sources, one set of counts — what `talon memory import` runs. */
+export function importAll(): ImportCounts {
+  return addCounts(importMemoryFile(), importDailyNotes());
+}

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/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.

package/src/frontend/native/routes/host.ts

@@ -12,12 +12,14 @@ import type {
   DeviceLocation,
   LogEntry,
   LogLevel,
+  MemoryWhyWire,
   ModelOption,
   PluginItem,
   SearchResult,
   SkillItem,
   ToggleResult,
 } from "../protocol.js";
+import type { MemoryListQuery, MemoryListResult } from "../memory.js";
 import type { ConfigSnapshot } from "../settings.js";
 
 /** Optional attachment references carried alongside a sent message. */
@@ -48,6 +50,13 @@ export type BridgeServerHandlers = {
   ): ClientMessage[];
   /** Full-text search across chats (or one chat when `chatId` is given). */
   search(query: string, chatId?: string): SearchResult[];
+  /**
+   * Live memory rows — a full-text search when `q` is given, else the
+   * ranked listing. Read-only: the bridge exposes no memory writes.
+   */
+  listMemory(query: MemoryListQuery): MemoryListResult;
+  /** One memory row plus its audit trail, or null when no such id. */
+  memoryWhy(id: number): MemoryWhyWire | null;
   /** Fire-and-forget: streams its results back through `broadcast`. */
   send(id: string, text: string, opts?: SendOptions): void;
   /**

package/src/frontend/native/routes/index.ts

@@ -7,6 +7,7 @@ import type { RouteHost } from "./host.js";
 import type { BridgeRoutes } from "./table.js";
 import { preAuthRoutes } from "./pre-auth.js";
 import { chatRoutes } from "./chats.js";
+import { memoryRoutes } from "./memory.js";
 import { modelRoutes } from "./models.js";
 import { daemonRoutes } from "./daemon.js";
 import { meshRoutes } from "./mesh.js";
@@ -15,6 +16,7 @@ export function buildRoutes(host: RouteHost): BridgeRoutes {
   return {
     ...preAuthRoutes(host),
     ...chatRoutes(host),
+    ...memoryRoutes(host),
     ...modelRoutes(host),
     ...daemonRoutes(host),
     ...meshRoutes(host),

package/src/frontend/native/routes/memory.ts

@@ -0,0 +1,34 @@
+import type { RouteHost } from "./host.js";
+import type { BridgeRoutes } from "./table.js";
+import { asPositiveInt } from "./params.js";
+
+export function memoryRoutes(
+  host: RouteHost,
+): Pick<BridgeRoutes, "GET /memory" | "GET /memory/why"> {
+  const { json, handlers: h } = host;
+  return {
+    // ── Memory (read-only) ─────────────────────────────────────────────
+
+    // `q` turns the listing into a search; `kind` narrows either. A bad
+    // kind is a 400 naming the valid ones, not an empty list — a typo
+    // must not look like an empty memory.
+    "GET /memory": ({ res, url }) => {
+      const result = h.listMemory({
+        q: url.searchParams.get("q") ?? undefined,
+        kind: url.searchParams.get("kind") ?? undefined,
+        limit: asPositiveInt(url.searchParams.get("limit")),
+      });
+      return result.ok
+        ? json(res, 200, { rows: result.rows })
+        : json(res, 400, { ok: false, error: result.error });
+    },
+    "GET /memory/why": ({ res, url }) => {
+      const raw = url.searchParams.get("id") ?? "";
+      const id = asPositiveInt(raw);
+      const why = id === undefined ? null : h.memoryWhy(id);
+      return why
+        ? json(res, 200, why)
+        : json(res, 404, { ok: false, error: `No memory with id ${raw}` });
+    },
+  };
+}

package/src/frontend/native/routes/table.ts

@@ -47,6 +47,13 @@ export const BRIDGE_ROUTE_AUTH = {
   "POST /queue": "bearer",
   "GET /history": "bearer",
   "GET /search": "bearer",
+
+  // Memory — read-only. The typed memory store is readable over the
+  // bridge but never writable from it: asserting and dropping stay with
+  // the daemon's own write path.
+  "GET /memory": "bearer",
+  "GET /memory/why": "bearer",
+
   "POST /send": "bearer",
   "POST /upload": "bearer",
   "GET /media": "bearer",

package/src/frontend/telegram/commands/definitions.ts

@@ -44,6 +44,10 @@ export const TELEGRAM_COMMANDS: ReadonlyArray<{
     description: "Environment and native-module health",
   },
   { command: "dream", description: "Force memory consolidation" },
+  {
+    command: "memory",
+    description: "What Talon remembers — list, search, why <id>",
+  },
   { command: "plugins", description: "List loaded plugins" },
   { command: "help", description: "All commands and features" },
 ];

package/src/frontend/telegram/commands/index.ts

@@ -5,6 +5,7 @@
  *   - `definitions` — the TELEGRAM_COMMANDS menu (single source of truth)
  *   - `state`       — shared admin-id holder + admin guard
  *   - `info`        — /start /help /ping /plugins
+ *   - `memory`      — /memory (read-only view of the typed memory store)
  *   - `session`     — /reset /status
  *   - `settings`    — /model /effort /pulse /settings
  *   - `admin`       — /admin /metrics /doctor /dream /soul /restart /update
@@ -19,6 +20,7 @@ import type { Bot } from "grammy";
 import type { TalonConfig } from "../../../core/config/index.js";
 import type { Backend } from "../../../core/agent-runtime/capabilities.js";
 import { registerInfoCommands } from "./info.js";
+import { registerMemoryCommand } from "./memory.js";
 import { registerSessionCommands } from "./session.js";
 import { registerSettingsCommands } from "./settings.js";
 import { registerAdminCommands } from "./admin.js";
@@ -35,6 +37,7 @@ export function registerCommands(
 ): void {
   const deps = { config, gateway };
   registerInfoCommands(bot);
+  registerMemoryCommand(bot);
   registerSessionCommands(bot, deps);
   registerSettingsCommands(bot, deps);
   registerWhatsAppPairingCommand(bot);

package/src/frontend/telegram/commands/info.ts

@@ -50,6 +50,9 @@ export function registerInfoCommands(bot: Bot): void {
         "  /metrics -- aggregate performance metrics (admin)",
         "  /doctor -- environment and native-module health (admin)",
         "  /dream -- force memory consolidation now",
+        // Entity-escaped: this whole message is sent with parse_mode HTML,
+        // so a literal <id> would be read as a tag and 400 the reply.
+        "  /memory -- what Talon remembers; /memory why &lt;id&gt; for provenance",
         "  /ping -- health check with latency",
         "  /mesh -- ping and list companion mesh devices",
         "  /reset -- clear session and start fresh",

package/src/frontend/telegram/commands/memory.ts

@@ -0,0 +1,112 @@
+/**
+ * `/memory` — a read-only window on the typed memory store.
+ *
+ * Four shapes, all reads: the ranked listing, a full-text search, one
+ * row's provenance (`why <id>`) and a per-kind listing. Nothing here
+ * writes: asserting, superseding and dropping are the write path's job
+ * (rollout PR 6), so the operator can always ask what Talon remembers
+ * without the answer being able to change it.
+ *
+ * Gated exactly like `/status` — not at all. The store holds the
+ * operator's own memory, and a read of it is the least privileged thing
+ * a chat can do.
+ *
+ * Every line is model- or user-authored text reaching an HTML-parsed
+ * send, so it goes through `escapeHtml` before it is joined; the reply
+ * is chunked because a listing of 15 rows can outgrow Telegram's
+ * 4096-char cap on its own.
+ */
+
+import type { Bot, Context } from "grammy";
+import { escapeHtml } from "../formatting.js";
+import { replyHtmlChunked } from "../admin/chunked-reply.js";
+import {
+  formatMemory,
+  getMemory,
+  isMemoryKind,
+  listMemories,
+  memoryHistory,
+  searchMemories,
+  MEMORY_KINDS,
+  type MemoryRow,
+} from "../../../storage/memory.js";
+
+/** Rows per reply — a chat listing is a glance, not an export. */
+const LIST_LIMIT = 15;
+
+export function registerMemoryCommand(bot: Bot): void {
+  bot.command("memory", async (ctx: Context) => {
+    const arg = (ctx.match ?? "").toString().trim();
+    await replyHtmlChunked(ctx, renderMemory(arg));
+  });
+}
+
+/** Route the argument to one of the four reads. Returns ready HTML. */
+function renderMemory(arg: string): string {
+  const why = /^why\b\s*(.*)$/is.exec(arg);
+  if (why) return renderWhy(why[1]!.trim());
+  const kind = /^kind\b\s*(.*)$/is.exec(arg);
+  if (kind) return renderKind(kind[1]!.trim());
+  if (!arg)
+    return renderRows(
+      listMemories({ limit: LIST_LIMIT }),
+      "Nothing remembered yet.",
+    );
+  return renderRows(
+    searchMemories(arg, { limit: LIST_LIMIT }),
+    `No memories matching "${arg}".`,
+  );
+}
+
+/** One escaped line per row, or the (escaped) empty-case sentence. */
+function renderRows(rows: MemoryRow[], empty: string): string {
+  if (rows.length === 0) return escapeHtml(empty);
+  return rows.map((row) => escapeHtml(formatMemory(row))).join("\n");
+}
+
+function renderKind(kind: string): string {
+  if (!isMemoryKind(kind))
+    return escapeHtml(
+      `No such kind "${kind}". Valid kinds: ${MEMORY_KINDS.join(", ")}.`,
+    );
+  return renderRows(
+    listMemories({ kind, limit: LIST_LIMIT }),
+    `Nothing remembered under ${kind}.`,
+  );
+}
+
+/**
+ * Provenance for one row: the row itself, the numbers that decide where
+ * it ranks, and its audit trail. Reads by id rather than by the live
+ * listing, so a superseded or dropped row still explains itself.
+ */
+function renderWhy(raw: string): string {
+  const id = Number(raw);
+  if (!raw || !Number.isInteger(id))
+    return escapeHtml(`No memory with id ${raw || "(none given)"}.`);
+  const row = getMemory(id);
+  if (!row) return escapeHtml(`No memory with id ${id}.`);
+  const lines = [
+    escapeHtml(formatMemory(row)),
+    "",
+    escapeHtml(
+      `trust ${row.trust} · confidence ${row.confidence} · hits ${row.hitCount} · salience ${row.salience}`,
+    ),
+    escapeHtml(
+      `created ${isoTime(row.createdAt)} · last seen ${isoTime(row.lastSeenAt)}`,
+    ),
+  ];
+  const history = memoryHistory(row.id);
+  if (history.length > 0) {
+    lines.push("", "<b>History</b>");
+    for (const entry of history) {
+      const reason = entry.reason ? ` — ${entry.reason}` : "";
+      lines.push(escapeHtml(`${isoTime(entry.at)} ${entry.op}${reason}`));
+    }
+  }
+  return lines.join("\n");
+}
+
+function isoTime(ms: number): string {
+  return new Date(ms).toISOString();
+}

package/src/storage/memory.ts

@@ -440,6 +440,14 @@ export function touchMemory(id: number): void {
 
 // ── Reads ───────────────────────────────────────────────────────────────────
 
+/**
+ * The idempotency key a re-import compares against: sha256 of
+ * `kind|subject|key|text`. Re-exported from the repository so
+ * core/memory/import.ts can decide skip-vs-supersede without reaching
+ * past the store (plan §3.1).
+ */
+export const memoryContentHash = repo.contentHash;
+
 /** Any row by id — including superseded and dropped ones. */
 export function getMemory(id: number): MemoryRow | undefined {
   return repo.get(id);