talon-agent 4.3.3 → 4.5.0

package/src/storage/repositories/memory-repo.ts

@@ -0,0 +1,308 @@
+/**
+ * Memory repository — executes the statements in sql/memory.sql against
+ * the `memory` / `memory_fts` / `memory_history` tables; no SQL text
+ * lives here. The public store (storage/memory.ts) holds the domain API,
+ * validation and the transactional lifecycle rules; this module owns
+ * statement execution, the row↔domain mapping and the content hash.
+ */
+
+import { createHash } from "node:crypto";
+import { getDatabase } from "../db.js";
+import { memorySql } from "../sql/statements.generated.js";
+
+/** Kinds are lifecycles, not labels — see docs/memory-persona-plan.md §3.1. */
+export type MemoryKind =
+  "directive" | "fact" | "state" | "episode" | "relationship" | "reflection";
+
+/** Where a claim came from, and therefore how far it is allowed to rise. */
+export type MemoryTrust = "operator" | "agent" | "user_claim" | "group_chat";
+
+/** The mutation vocabulary recorded in memory_history. */
+export type MemoryOp =
+  "assert" | "supersede" | "drop" | "merge" | "pin" | "unpin" | "replace_state";
+
+/** Provenance of a claim: which frontend, chat, actor and turn asserted it. */
+export type MemorySource = {
+  frontend?: string;
+  chat?: string;
+  actor?: string;
+  turn?: string;
+};
+
+/** One memory row as the domain sees it. */
+export type MemoryRow = {
+  id: number;
+  kind: MemoryKind;
+  subject: string;
+  /** Present only for kind='state' — the key whose single live row this is. */
+  key?: string;
+  text: string;
+  source: MemorySource;
+  trust: MemoryTrust;
+  /** 0..1. */
+  confidence: number;
+  createdAt: number;
+  lastSeenAt: number;
+  hitCount: number;
+  salience: number;
+  pinned: boolean;
+  /** Id of the row that replaced this one; absent while live. */
+  supersededBy?: number;
+  /** When this row was dropped to the graveyard; absent while live. */
+  droppedAt?: number;
+  /** sha256 of kind|subject|key|text — the import idempotency key. */
+  contentHash: string;
+};
+
+/** One audit entry. */
+export type MemoryHistoryRow = {
+  id: number;
+  memoryId: number;
+  op: MemoryOp;
+  beforeText?: string;
+  afterText?: string;
+  reason?: string;
+  at: number;
+};
+
+/** A new claim, as callers supply it (the store fills in the defaults). */
+export type MemoryInput = {
+  kind: MemoryKind;
+  subject: string;
+  key?: string;
+  text: string;
+  source?: MemorySource;
+  trust: MemoryTrust;
+  confidence?: number;
+  salience?: number;
+  pinned?: boolean;
+};
+
+/** The fully-defaulted row the repository inserts. */
+export type MemoryInsert = Omit<MemoryRow, "id" | "supersededBy" | "droppedAt">;
+
+/** Filters for `list`; everything is optional and narrows the result. */
+export type MemoryListFilter = {
+  kind?: MemoryKind;
+  subject?: string;
+  includeSuperseded?: boolean;
+  includeDropped?: boolean;
+  limit?: number;
+};
+
+type Row = {
+  id: number;
+  kind: string;
+  subject: string;
+  key: string | null;
+  text: string;
+  source_frontend: string | null;
+  source_chat: string | null;
+  source_actor: string | null;
+  source_turn: string | null;
+  trust: string;
+  confidence: number;
+  created_at: number;
+  last_seen_at: number;
+  hit_count: number;
+  salience: number;
+  pinned: number;
+  superseded_by: number | null;
+  dropped_at: number | null;
+  content_hash: string;
+};
+
+type HistoryRow = {
+  id: number;
+  memory_id: number;
+  op: string;
+  before_text: string | null;
+  after_text: string | null;
+  reason: string | null;
+  at: number;
+};
+
+function rowToMemory(row: Row): MemoryRow {
+  const source: MemorySource = {
+    ...(row.source_frontend !== null ? { frontend: row.source_frontend } : {}),
+    ...(row.source_chat !== null ? { chat: row.source_chat } : {}),
+    ...(row.source_actor !== null ? { actor: row.source_actor } : {}),
+    ...(row.source_turn !== null ? { turn: row.source_turn } : {}),
+  };
+  return {
+    id: Number(row.id),
+    kind: row.kind as MemoryKind,
+    subject: row.subject,
+    ...(row.key !== null ? { key: row.key } : {}),
+    text: row.text,
+    source,
+    trust: row.trust as MemoryTrust,
+    confidence: row.confidence,
+    createdAt: row.created_at,
+    lastSeenAt: row.last_seen_at,
+    hitCount: row.hit_count,
+    salience: row.salience,
+    pinned: row.pinned !== 0,
+    ...(row.superseded_by !== null
+      ? { supersededBy: Number(row.superseded_by) }
+      : {}),
+    ...(row.dropped_at !== null ? { droppedAt: row.dropped_at } : {}),
+    contentHash: row.content_hash,
+  };
+}
+
+function rowToHistory(row: HistoryRow): MemoryHistoryRow {
+  return {
+    id: Number(row.id),
+    memoryId: Number(row.memory_id),
+    op: row.op as MemoryOp,
+    ...(row.before_text !== null ? { beforeText: row.before_text } : {}),
+    ...(row.after_text !== null ? { afterText: row.after_text } : {}),
+    ...(row.reason !== null ? { reason: row.reason } : {}),
+    at: row.at,
+  };
+}
+
+/**
+ * The idempotency key for PR 5's import: identical claims hash
+ * identically regardless of provenance or ranking, so re-importing the
+ * same `memory.md` produces no new rows.
+ */
+export function contentHash(
+  kind: string,
+  subject: string,
+  key: string | undefined,
+  text: string,
+): string {
+  return createHash("sha256")
+    .update(`${kind}|${subject}|${key ?? ""}|${text}`)
+    .digest("hex");
+}
+
+/** Insert a fully-defaulted row; returns the new id. */
+export function insert(row: MemoryInsert): number {
+  const inserted = getDatabase()
+    .prepare(memorySql.insert)
+    .get(
+      row.kind,
+      row.subject,
+      row.key ?? null,
+      row.text,
+      row.source.frontend ?? null,
+      row.source.chat ?? null,
+      row.source.actor ?? null,
+      row.source.turn ?? null,
+      row.trust,
+      row.confidence,
+      row.createdAt,
+      row.lastSeenAt,
+      row.hitCount,
+      row.salience,
+      row.pinned ? 1 : 0,
+      row.contentHash,
+    ) as { id: number };
+  return Number(inserted.id);
+}
+
+export function get(id: number): MemoryRow | undefined {
+  const row = getDatabase().prepare(memorySql.get).get(id) as Row | undefined;
+  return row ? rowToMemory(row) : undefined;
+}
+
+/** Filtered listing, pinned first then salience then recency. */
+export function list(filter: MemoryListFilter = {}): MemoryRow[] {
+  const kind = filter.kind ?? null;
+  const subject = filter.subject ?? null;
+  const rows = getDatabase()
+    .prepare(memorySql.list)
+    .all(
+      kind,
+      kind,
+      subject,
+      subject,
+      filter.includeSuperseded ? 1 : 0,
+      filter.includeDropped ? 1 : 0,
+      filter.limit ?? 100,
+    ) as Row[];
+  return rows.map(rowToMemory);
+}
+
+/** The single live `state` row for a key, if there is one. */
+export function liveStateByKey(key: string): MemoryRow | undefined {
+  const row = getDatabase().prepare(memorySql.liveStateByKey).get(key) as
+    Row | undefined;
+  return row ? rowToMemory(row) : undefined;
+}
+
+/** FTS5 search over live rows, best match first. `match` must be quoted. */
+export function searchFts(
+  match: string,
+  kind: MemoryKind | undefined,
+  limit: number,
+): MemoryRow[] {
+  const k = kind ?? null;
+  const rows = getDatabase()
+    .prepare(memorySql.searchFts)
+    .all(match, k, k, limit) as Row[];
+  return rows.map(rowToMemory);
+}
+
+/** Near-duplicate candidates for a fresh assert. `match` must be quoted. */
+export function similar(
+  match: string,
+  kind: MemoryKind,
+  subject: string,
+  excludeId: number,
+  limit: number,
+): MemoryRow[] {
+  const rows = getDatabase()
+    .prepare(memorySql.similar)
+    .all(match, kind, subject, excludeId, limit) as Row[];
+  return rows.map(rowToMemory);
+}
+
+export function setSupersededBy(id: number, newId: number): void {
+  getDatabase().prepare(memorySql.setSupersededBy).run(newId, id);
+}
+
+export function setDropped(id: number, at: number): void {
+  getDatabase().prepare(memorySql.setDropped).run(at, id);
+}
+
+export function setPinned(id: number, pinned: boolean): void {
+  getDatabase()
+    .prepare(memorySql.setPinned)
+    .run(pinned ? 1 : 0, id);
+}
+
+export function touch(id: number, at: number): void {
+  getDatabase().prepare(memorySql.touch).run(at, id);
+}
+
+/** Append one audit entry — every mutation writes exactly one. */
+export function insertHistory(entry: {
+  memoryId: number;
+  op: MemoryOp;
+  beforeText?: string;
+  afterText?: string;
+  reason?: string;
+  at: number;
+}): void {
+  getDatabase()
+    .prepare(memorySql.insertHistory)
+    .run(
+      entry.memoryId,
+      entry.op,
+      entry.beforeText ?? null,
+      entry.afterText ?? null,
+      entry.reason ?? null,
+      entry.at,
+    );
+}
+
+export function historyFor(id: number): MemoryHistoryRow[] {
+  const rows = getDatabase()
+    .prepare(memorySql.historyFor)
+    .all(id) as HistoryRow[];
+  return rows.map(rowToHistory);
+}

package/src/storage/sql/memory.sql

@@ -0,0 +1,95 @@
+-- Statements for the memory tables (see repositories/memory-repo.ts for
+-- the parameter order and row↔domain mapping). "Live" everywhere means
+-- superseded_by IS NULL AND dropped_at IS NULL: a row that has been
+-- replaced or dropped stays in the table (stable ids, revertible
+-- history) but is invisible to listings and search.
+--
+-- The optional filters bind the same value twice — `(? IS NULL OR
+-- col = ?)` — so the statement text is constant and nothing is
+-- interpolated into SQL at the call site.
+
+-- name: insert
+-- RETURNING id so the caller gets the new row id without a second
+-- round trip through last_insert_rowid().
+INSERT INTO memory
+  (kind, subject, key, text, source_frontend, source_chat, source_actor,
+   source_turn, trust, confidence, created_at, last_seen_at, hit_count,
+   salience, pinned, superseded_by, dropped_at, content_hash)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?)
+RETURNING id
+
+-- name: get
+SELECT id, kind, subject, key, text, source_frontend, source_chat,
+       source_actor, source_turn, trust, confidence, created_at,
+       last_seen_at, hit_count, salience, pinned, superseded_by,
+       dropped_at, content_hash
+FROM memory WHERE id = ?
+
+-- name: list
+SELECT id, kind, subject, key, text, source_frontend, source_chat,
+       source_actor, source_turn, trust, confidence, created_at,
+       last_seen_at, hit_count, salience, pinned, superseded_by,
+       dropped_at, content_hash
+FROM memory
+WHERE (? IS NULL OR kind = ?)
+  AND (? IS NULL OR subject = ?)
+  AND (? = 1 OR superseded_by IS NULL)
+  AND (? = 1 OR dropped_at IS NULL)
+ORDER BY pinned DESC, salience DESC, last_seen_at DESC, id DESC
+LIMIT ?
+
+-- name: liveStateByKey
+SELECT id, kind, subject, key, text, source_frontend, source_chat,
+       source_actor, source_turn, trust, confidence, created_at,
+       last_seen_at, hit_count, salience, pinned, superseded_by,
+       dropped_at, content_hash
+FROM memory
+WHERE kind = 'state' AND key = ?
+  AND superseded_by IS NULL AND dropped_at IS NULL
+ORDER BY id DESC LIMIT 1
+
+-- name: searchFts
+-- The match param must already be a valid FTS5 expression
+-- (see memory.ts ftsQuery). Live rows only, best match first.
+SELECT m.id, m.kind, m.subject, m.key, m.text, m.source_frontend,
+       m.source_chat, m.source_actor, m.source_turn, m.trust, m.confidence,
+       m.created_at, m.last_seen_at, m.hit_count, m.salience, m.pinned,
+       m.superseded_by, m.dropped_at, m.content_hash
+FROM memory m JOIN memory_fts ON memory_fts.rowid = m.id
+WHERE memory_fts MATCH ?
+  AND m.superseded_by IS NULL AND m.dropped_at IS NULL
+  AND (? IS NULL OR m.kind = ?)
+ORDER BY bm25(memory_fts) LIMIT ?
+
+-- name: similar
+-- Near-duplicate candidates for a fresh assert: live rows of the same
+-- kind + subject that match the new text, the new row itself excluded.
+SELECT m.id, m.kind, m.subject, m.key, m.text, m.source_frontend,
+       m.source_chat, m.source_actor, m.source_turn, m.trust, m.confidence,
+       m.created_at, m.last_seen_at, m.hit_count, m.salience, m.pinned,
+       m.superseded_by, m.dropped_at, m.content_hash
+FROM memory m JOIN memory_fts ON memory_fts.rowid = m.id
+WHERE memory_fts MATCH ?
+  AND m.kind = ? AND m.subject = ? AND m.id <> ?
+  AND m.superseded_by IS NULL AND m.dropped_at IS NULL
+ORDER BY bm25(memory_fts) LIMIT ?
+
+-- name: setSupersededBy
+UPDATE memory SET superseded_by = ? WHERE id = ?
+
+-- name: setDropped
+UPDATE memory SET dropped_at = ? WHERE id = ?
+
+-- name: setPinned
+UPDATE memory SET pinned = ? WHERE id = ?
+
+-- name: touch
+UPDATE memory SET hit_count = hit_count + 1, last_seen_at = ? WHERE id = ?
+
+-- name: insertHistory
+INSERT INTO memory_history (memory_id, op, before_text, after_text, reason, at)
+VALUES (?, ?, ?, ?, ?, ?)
+
+-- name: historyFor
+SELECT id, memory_id, op, before_text, after_text, reason, at
+FROM memory_history WHERE memory_id = ? ORDER BY id

package/src/storage/sql/schema.sql

@@ -52,6 +52,87 @@ CREATE TRIGGER IF NOT EXISTS history_au AFTER UPDATE OF text, sender_name ON his
   VALUES (new.id, new.text, new.sender_name);
 END;
 
+-- Typed memory: one row per claim, with an FTS5 index over subject +
+-- text. Kinds are lifecycles, not labels (docs/memory-persona-plan.md
+-- §3.1): `directive` is durable human intent, `fact` is durable and
+-- supersedable, `state` is keyed (a write replaces the row for that
+-- key), `episode` decays fast, `relationship` and `reflection` are the
+-- persona layer. Rows are never physically deleted — `superseded_by`
+-- points at the replacement and `dropped_at` is the graveyard, so ids
+-- stay stable and every change is revertible.
+CREATE TABLE IF NOT EXISTS memory (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  -- directive | fact | state | episode | relationship | reflection
+  kind            TEXT    NOT NULL,
+  -- Who or what the claim is about; the retrieval scope.
+  subject         TEXT    NOT NULL,
+  -- Required for kind='state' (e.g. 'heartbeat.health'), NULL otherwise.
+  -- One live row per key is enforced by the store's replaceStateKey,
+  -- which supersedes the previous row inside a transaction.
+  key             TEXT,
+  text            TEXT    NOT NULL,
+  -- Provenance: which frontend/chat/actor/turn asserted this.
+  source_frontend TEXT,
+  source_chat     TEXT,
+  source_actor    TEXT,
+  source_turn     TEXT,
+  -- operator | agent | user_claim | group_chat — the trust tier.
+  -- user_claim and group_chat can never be pinned (plan §5).
+  trust           TEXT    NOT NULL,
+  confidence      REAL    NOT NULL DEFAULT 1.0,
+  created_at      INTEGER NOT NULL,
+  last_seen_at    INTEGER NOT NULL,
+  hit_count       INTEGER NOT NULL DEFAULT 0,
+  salience        REAL    NOT NULL DEFAULT 0,
+  pinned          INTEGER NOT NULL DEFAULT 0,
+  -- memory.id of the row that replaced this one; NULL while live.
+  superseded_by   INTEGER,
+  -- Soft delete: the graveyard, not oblivion.
+  dropped_at      INTEGER,
+  -- sha256 of kind|subject|key|text — the idempotency key for import.
+  content_hash    TEXT    NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_memory_kind_subject ON memory(kind, subject);
+CREATE INDEX IF NOT EXISTS idx_memory_key ON memory(key) WHERE key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_memory_salience ON memory(salience);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+  subject,
+  text,
+  content='memory',
+  content_rowid='id'
+);
+CREATE TRIGGER IF NOT EXISTS memory_ai AFTER INSERT ON memory BEGIN
+  INSERT INTO memory_fts(rowid, subject, text)
+  VALUES (new.id, new.subject, new.text);
+END;
+CREATE TRIGGER IF NOT EXISTS memory_ad AFTER DELETE ON memory BEGIN
+  INSERT INTO memory_fts(memory_fts, rowid, subject, text)
+  VALUES ('delete', old.id, old.subject, old.text);
+END;
+CREATE TRIGGER IF NOT EXISTS memory_au AFTER UPDATE OF subject, text ON memory BEGIN
+  INSERT INTO memory_fts(memory_fts, rowid, subject, text)
+  VALUES ('delete', old.id, old.subject, old.text);
+  INSERT INTO memory_fts(rowid, subject, text)
+  VALUES (new.id, new.subject, new.text);
+END;
+
+-- The audit log: one row per mutation, so every change is diffable and
+-- revertible (`/memory diff`, `/memory undo`). Ops are the reconcile
+-- vocabulary of plan §3.3 plus the store's own replace_state. A touch
+-- (hit_count / last_seen_at) changes no content and is not audited.
+CREATE TABLE IF NOT EXISTS memory_history (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  memory_id   INTEGER NOT NULL,
+  -- assert | supersede | drop | merge | pin | unpin | replace_state
+  op          TEXT    NOT NULL,
+  before_text TEXT,
+  after_text  TEXT,
+  reason      TEXT,
+  at          INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_memory_history_memory ON memory_history(memory_id, id);
+
 -- Sessions: real columns rather than a JSON blob. The store's hot
 -- paths (recordUsage, incrementTurns, setSessionId) accumulate into
 -- individual fields per turn, and the usage counters are numeric

package/src/storage/sql/statements.generated.ts

@@ -57,6 +57,87 @@ CREATE TRIGGER IF NOT EXISTS history_au AFTER UPDATE OF text, sender_name ON his
   VALUES (new.id, new.text, new.sender_name);
 END;
 
+-- Typed memory: one row per claim, with an FTS5 index over subject +
+-- text. Kinds are lifecycles, not labels (docs/memory-persona-plan.md
+-- §3.1): \`directive\` is durable human intent, \`fact\` is durable and
+-- supersedable, \`state\` is keyed (a write replaces the row for that
+-- key), \`episode\` decays fast, \`relationship\` and \`reflection\` are the
+-- persona layer. Rows are never physically deleted — \`superseded_by\`
+-- points at the replacement and \`dropped_at\` is the graveyard, so ids
+-- stay stable and every change is revertible.
+CREATE TABLE IF NOT EXISTS memory (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  -- directive | fact | state | episode | relationship | reflection
+  kind            TEXT    NOT NULL,
+  -- Who or what the claim is about; the retrieval scope.
+  subject         TEXT    NOT NULL,
+  -- Required for kind='state' (e.g. 'heartbeat.health'), NULL otherwise.
+  -- One live row per key is enforced by the store's replaceStateKey,
+  -- which supersedes the previous row inside a transaction.
+  key             TEXT,
+  text            TEXT    NOT NULL,
+  -- Provenance: which frontend/chat/actor/turn asserted this.
+  source_frontend TEXT,
+  source_chat     TEXT,
+  source_actor    TEXT,
+  source_turn     TEXT,
+  -- operator | agent | user_claim | group_chat — the trust tier.
+  -- user_claim and group_chat can never be pinned (plan §5).
+  trust           TEXT    NOT NULL,
+  confidence      REAL    NOT NULL DEFAULT 1.0,
+  created_at      INTEGER NOT NULL,
+  last_seen_at    INTEGER NOT NULL,
+  hit_count       INTEGER NOT NULL DEFAULT 0,
+  salience        REAL    NOT NULL DEFAULT 0,
+  pinned          INTEGER NOT NULL DEFAULT 0,
+  -- memory.id of the row that replaced this one; NULL while live.
+  superseded_by   INTEGER,
+  -- Soft delete: the graveyard, not oblivion.
+  dropped_at      INTEGER,
+  -- sha256 of kind|subject|key|text — the idempotency key for import.
+  content_hash    TEXT    NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_memory_kind_subject ON memory(kind, subject);
+CREATE INDEX IF NOT EXISTS idx_memory_key ON memory(key) WHERE key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_memory_salience ON memory(salience);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+  subject,
+  text,
+  content='memory',
+  content_rowid='id'
+);
+CREATE TRIGGER IF NOT EXISTS memory_ai AFTER INSERT ON memory BEGIN
+  INSERT INTO memory_fts(rowid, subject, text)
+  VALUES (new.id, new.subject, new.text);
+END;
+CREATE TRIGGER IF NOT EXISTS memory_ad AFTER DELETE ON memory BEGIN
+  INSERT INTO memory_fts(memory_fts, rowid, subject, text)
+  VALUES ('delete', old.id, old.subject, old.text);
+END;
+CREATE TRIGGER IF NOT EXISTS memory_au AFTER UPDATE OF subject, text ON memory BEGIN
+  INSERT INTO memory_fts(memory_fts, rowid, subject, text)
+  VALUES ('delete', old.id, old.subject, old.text);
+  INSERT INTO memory_fts(rowid, subject, text)
+  VALUES (new.id, new.subject, new.text);
+END;
+
+-- The audit log: one row per mutation, so every change is diffable and
+-- revertible (\`/memory diff\`, \`/memory undo\`). Ops are the reconcile
+-- vocabulary of plan §3.3 plus the store's own replace_state. A touch
+-- (hit_count / last_seen_at) changes no content and is not audited.
+CREATE TABLE IF NOT EXISTS memory_history (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  memory_id   INTEGER NOT NULL,
+  -- assert | supersede | drop | merge | pin | unpin | replace_state
+  op          TEXT    NOT NULL,
+  before_text TEXT,
+  after_text  TEXT,
+  reason      TEXT,
+  at          INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_memory_history_memory ON memory_history(memory_id, id);
+
 -- Sessions: real columns rather than a JSON blob. The store's hot
 -- paths (recordUsage, incrementTurns, setSessionId) accumulate into
 -- individual fields per turn, and the usage counters are numeric
@@ -488,6 +569,71 @@ ORDER BY timestamp ASC, rowid ASC LIMIT 1`,
   countByFilePath: `SELECT COUNT(*) AS n FROM media_index WHERE file_path = ?`,
 } as const;
 
+export const memorySql = {
+  insert: `-- RETURNING id so the caller gets the new row id without a second
+-- round trip through last_insert_rowid().
+INSERT INTO memory
+  (kind, subject, key, text, source_frontend, source_chat, source_actor,
+   source_turn, trust, confidence, created_at, last_seen_at, hit_count,
+   salience, pinned, superseded_by, dropped_at, content_hash)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?)
+RETURNING id`,
+  get: `SELECT id, kind, subject, key, text, source_frontend, source_chat,
+       source_actor, source_turn, trust, confidence, created_at,
+       last_seen_at, hit_count, salience, pinned, superseded_by,
+       dropped_at, content_hash
+FROM memory WHERE id = ?`,
+  list: `SELECT id, kind, subject, key, text, source_frontend, source_chat,
+       source_actor, source_turn, trust, confidence, created_at,
+       last_seen_at, hit_count, salience, pinned, superseded_by,
+       dropped_at, content_hash
+FROM memory
+WHERE (? IS NULL OR kind = ?)
+  AND (? IS NULL OR subject = ?)
+  AND (? = 1 OR superseded_by IS NULL)
+  AND (? = 1 OR dropped_at IS NULL)
+ORDER BY pinned DESC, salience DESC, last_seen_at DESC, id DESC
+LIMIT ?`,
+  liveStateByKey: `SELECT id, kind, subject, key, text, source_frontend, source_chat,
+       source_actor, source_turn, trust, confidence, created_at,
+       last_seen_at, hit_count, salience, pinned, superseded_by,
+       dropped_at, content_hash
+FROM memory
+WHERE kind = 'state' AND key = ?
+  AND superseded_by IS NULL AND dropped_at IS NULL
+ORDER BY id DESC LIMIT 1`,
+  searchFts: `-- The match param must already be a valid FTS5 expression
+-- (see memory.ts ftsQuery). Live rows only, best match first.
+SELECT m.id, m.kind, m.subject, m.key, m.text, m.source_frontend,
+       m.source_chat, m.source_actor, m.source_turn, m.trust, m.confidence,
+       m.created_at, m.last_seen_at, m.hit_count, m.salience, m.pinned,
+       m.superseded_by, m.dropped_at, m.content_hash
+FROM memory m JOIN memory_fts ON memory_fts.rowid = m.id
+WHERE memory_fts MATCH ?
+  AND m.superseded_by IS NULL AND m.dropped_at IS NULL
+  AND (? IS NULL OR m.kind = ?)
+ORDER BY bm25(memory_fts) LIMIT ?`,
+  similar: `-- Near-duplicate candidates for a fresh assert: live rows of the same
+-- kind + subject that match the new text, the new row itself excluded.
+SELECT m.id, m.kind, m.subject, m.key, m.text, m.source_frontend,
+       m.source_chat, m.source_actor, m.source_turn, m.trust, m.confidence,
+       m.created_at, m.last_seen_at, m.hit_count, m.salience, m.pinned,
+       m.superseded_by, m.dropped_at, m.content_hash
+FROM memory m JOIN memory_fts ON memory_fts.rowid = m.id
+WHERE memory_fts MATCH ?
+  AND m.kind = ? AND m.subject = ? AND m.id <> ?
+  AND m.superseded_by IS NULL AND m.dropped_at IS NULL
+ORDER BY bm25(memory_fts) LIMIT ?`,
+  setSupersededBy: `UPDATE memory SET superseded_by = ? WHERE id = ?`,
+  setDropped: `UPDATE memory SET dropped_at = ? WHERE id = ?`,
+  setPinned: `UPDATE memory SET pinned = ? WHERE id = ?`,
+  touch: `UPDATE memory SET hit_count = hit_count + 1, last_seen_at = ? WHERE id = ?`,
+  insertHistory: `INSERT INTO memory_history (memory_id, op, before_text, after_text, reason, at)
+VALUES (?, ?, ?, ?, ?, ?)`,
+  historyFor: `SELECT id, memory_id, op, before_text, after_text, reason, at
+FROM memory_history WHERE memory_id = ? ORDER BY id`,
+} as const;
+
 export const scriptsSql = {
   upsert: `INSERT OR REPLACE INTO scripts
   (id, name, description, language, script_path, created_at,