memhtml 0.1.0

package/guest/corpus.mjs

@@ -0,0 +1,193 @@
+/**
+ * The code-mode helper, as it runs INSIDE the `memhtml exec` sandbox.
+ *
+ * Not TypeScript and not built: this file is read as BYTES by `apps/cli/src/exec.ts` and written into
+ * the guest filesystem verbatim, where `js-exec` loads it under QuickJS. A `.ts` source would have to
+ * survive `tsc`'s emit and land in `dist/` in a shape the guest's loader accepts, which buys nothing
+ * — nothing on the host ever imports this module — and costs the one property that matters: what a
+ * reader sees here is exactly what the guest executes.
+ *
+ * `docs/code-mode.md` is the cookbook whose recipes this serves, and the field set below is that
+ * document's `Memhtml` interface. Its parser is cheerio because its runtime is bun; here the runtime is
+ * QuickJS and the parser is `node-html-parser` (see {@link module:parse}), so the LIBRARY differs
+ * while every selector carries over — the contract is the closed vocabulary, not the library.
+ *
+ * Three facts about this guest, each measured against just-bash 3.2.0 on 2026-08-09 rather than
+ * assumed from Node's semantics:
+ *
+ * 1. **`statSync(...).isDirectory` is a boolean PROPERTY here, not a method.** Node-shaped code
+ *    calling `.isDirectory()` throws "not a function". {@link isDirectory} handles both shapes, so
+ *    this file also runs unchanged under Node — which is what lets a test parse the same corpus twice
+ *    and compare.
+ * 2. **Edge `href`s are root-absolute** (`/areas/x.html`) while a directory walk yields paths under
+ *    the mount. {@link corpus} keys by the href convention for exactly this reason: the spike's first
+ *    traversal reported `0/410 edges resolved`, which reads as a finding about the corpus and was
+ *    entirely a normalization bug on the reading side.
+ * 3. **`atob` does not exist.** QuickJS ships no base64 builtins and `node-html-parser` decodes a
+ *    base64 entity table at load, so the host installs a shim through `javascript.bootstrap` before
+ *    this module is ever imported. Probed: without it the parser fails at load with
+ *    "'atob' is not defined".
+ */
+
+import * as fs from "node:fs"
+import { parse } from "/workspace/lib/nhp.mjs"
+
+/** Where `memhtml exec` mounts the corpus. Matches `CORPUS_MOUNT` in `apps/cli/src/exec.ts`. */
+export const ROOT = "/mnt/memhtml"
+
+/**
+ * True when `path` is a directory, under either `statSync` shape.
+ *
+ * The QuickJS `node:fs` shim returns `isDirectory` as a boolean property while Node returns a method.
+ * Both are handled so this file is one implementation rather than a guest fork of a host helper.
+ */
+const isDirectory = (path) => {
+  const stats = fs.statSync(path)
+  return typeof stats.isDirectory === "function" ? stats.isDirectory() : stats.isDirectory === true
+}
+
+/**
+ * Every `.html` file under `dir`, recursively, in `readdirSync` order.
+ *
+ * `index.html` is skipped because it is GENERATED — `memhtml publish` writes one per directory as a
+ * listing (`packages/store/src/layout.ts`), and counting them as memories inflates every census by
+ * the directory count and pollutes an entity tally with link text. The fixture corpus happens to
+ * contain none, so a test built only on the fixture would not catch a regression here; a real
+ * `$MEMHTML_ROOT` has one per directory.
+ *
+ * `.git` is skipped because the corpus is the HTML tree and git's own storage is not part of it. The
+ * name covers both shapes it takes: a directory when a plain root is mounted, and a FILE when a
+ * pinned worktree is (`git worktree add` writes a `.git` file naming the parent repo). Two reasons,
+ * and the first is correctness: a ref is a file at a path the author chooses, so a branch named
+ * `foo.html` lands at `.git/refs/heads/foo.html` and is counted as a memory whose every field is
+ * empty — a census one higher than any grep of the corpus reports. The second is cost, and it is
+ * paid per entry: every name here is one round-trip across the sandbox's synchronous host bridge, and
+ * 578 of the 305-memory fixture's 935 entries are git's (measured 2026-08-14), so the walk spent 62%
+ * of its calls on files no recipe can read.
+ */
+export const walk = (dir = ROOT, found = []) => {
+  for (const entry of fs.readdirSync(dir)) {
+    if (entry === ".git") continue
+    const path = `${dir}/${entry}`
+    if (isDirectory(path)) walk(path, found)
+    else if (path.endsWith(".html") && entry !== "index.html") found.push(path)
+  }
+  return found
+}
+
+/** The href convention: root-absolute, so a parsed path and an edge target are the same string. */
+const idFor = (path, root) => (path.startsWith(`${root}/`) ? path.slice(root.length) : path)
+
+/** Every `content` of a repeated `meta[name=…]`, blanks dropped. */
+const metaValues = (document, name) =>
+  document
+    .querySelectorAll(`meta[name="${name}"]`)
+    .map((element) => element.getAttribute("content") ?? "")
+    .filter((value) => value !== "")
+
+/**
+ * One memory, read to the planes the closed vocabulary guarantees.
+ *
+ * `claim` uses `article mark`, a DESCENDANT selector. The markup is `<article><p><mark>`
+ * (`docs/code-mode.md`), so `article > mark` matches NOTHING — a helper written from ROADMAP item 7's
+ * prose, which says `article > mark`, silently reports zero claims on every file. Measured on the
+ * 305-file fixture: `article mark` finds 305, `article > mark` finds 0.
+ *
+ * `document` is returned as an escape hatch. Every field here is a projection the cookbook's recipes
+ * needed, and a question none of them covers is answerable with the same parser rather than by
+ * editing this file — which is the whole reason code-mode exists instead of a fixed tool per question.
+ */
+export const memoryAt = (path, root = ROOT) => {
+  const document = parse(fs.readFileSync(path, "utf8"))
+  const facets = {}
+  for (const term of document.querySelectorAll("article dl dt")) {
+    const key = term.text.trim()
+    const definition = term.nextElementSibling
+    if (key !== "" && definition !== null && definition.rawTagName === "dd") {
+      facets[key] = definition.text.trim()
+    }
+  }
+  return {
+    /** Root-absolute, the id an edge `href` names. */
+    path: idFor(path, root),
+    /** Where the file is in the guest, for a re-read that bypasses these fields. */
+    file: path,
+    title: document.querySelector("title")?.text.trim() ?? "",
+    memoryType: metaValues(document, "memhtml-type")[0] ?? "",
+    status: metaValues(document, "memhtml-status")[0] ?? "",
+    claim: document.querySelector("article mark")?.text.trim() ?? "",
+    tags: metaValues(document, "memhtml-tag"),
+    entities: metaValues(document, "memhtml-entity"),
+    links: document.querySelectorAll('link[rel^="memhtml-"]').map((element) => ({
+      rel: element.getAttribute("rel") ?? "",
+      href: element.getAttribute("href") ?? ""
+    })),
+    facets,
+    citations: document.querySelectorAll("article cite").map((element) => element.text.trim()),
+    eventAt: document.querySelector("article time[datetime]")?.getAttribute("datetime") ?? null,
+    document
+  }
+}
+
+/** Every memory under `root`, keyed by the root-absolute path an edge `href` names. */
+export const corpus = (root = ROOT) => {
+  const byPath = new Map()
+  for (const path of walk(root)) {
+    const memory = memoryAt(path, root)
+    byPath.set(memory.path, memory)
+  }
+  return byPath
+}
+
+/** The authored edge set reversed: for each target path, who points at it and with which rel. */
+export const backlinks = (memories) => {
+  const incoming = new Map()
+  for (const memory of memories.values()) {
+    for (const link of memory.links) {
+      const existing = incoming.get(link.href)
+      if (existing === undefined) incoming.set(link.href, [{ from: memory.path, rel: link.rel }])
+      else existing.push({ from: memory.path, rel: link.rel })
+    }
+  }
+  return incoming
+}
+
+/**
+ * Follow one rel from `start` to exhaustion: a supersedence chain, a part-of ancestry.
+ *
+ * The cycle guard is a membership test on the path travelled, not a hop cap: an authored edge set can
+ * be cyclic (nothing in the format forbids `A memhtml-supersedes B memhtml-supersedes A`) and a capped walk
+ * would return a truncated chain that looks like a real one. The returned array always starts at
+ * `start`, including when `start` is absent from `memories` — a caller comparing lengths needs the
+ * one-element case to mean "no chain" rather than "unknown".
+ */
+export const chain = (memories, start, rel) => {
+  const travelled = []
+  let at = start
+  while (at !== undefined && at !== null && !travelled.includes(at)) {
+    travelled.push(at)
+    at = memories.get(at)?.links.find((link) => link.rel === rel)?.href
+  }
+  return travelled
+}
+
+/**
+ * Every edge, split by whether its target is a file in this corpus.
+ *
+ * Present as a helper rather than left to each script because the resolution RATE is the number that
+ * catches a normalization bug: `dangling` counting every edge reads as "the corpus has no valid
+ * edges", which is a plausible-looking finding and was in fact a bug in the reader. A script that
+ * reports `resolved` beside a total it derived independently cannot make that mistake quietly.
+ */
+export const edges = (memories) => {
+  const resolved = []
+  const dangling = []
+  for (const memory of memories.values()) {
+    for (const link of memory.links) {
+      const edge = { from: memory.path, rel: link.rel, href: link.href }
+      if (memories.has(link.href)) resolved.push(edge)
+      else dangling.push(edge)
+    }
+  }
+  return { resolved, dangling }
+}

package/migrations/0001_files.sql

@@ -0,0 +1,111 @@
+-- The memory corpus, one row per file in the git tree. Rebuildable: every column here is
+-- derived from a committed file plus its blob sha, so `rm index.db` costs a rebuild and no data.
+--
+-- `para`, `workspace`, `word_count`, `gist`, `fts_text`, and `disclosure_text` are computed by the
+-- indexer rather than by the database: generated columns are unavailable on this driver.
+--
+-- Every child table declares `ON UPDATE CASCADE` as well as `ON DELETE CASCADE`. `files.path` is the
+-- primary key AND it moves: eviction is a `git mv` into `archive/<YYYY>/`, so a rename is an UPDATE
+-- of a parent key. Foreign keys are immediate on this driver, so without `ON UPDATE CASCADE` that
+-- UPDATE fails outright (probed 2026-08-02), and a rename handled as a delete plus an insert would
+-- cascade the chunk rows away and take their embeddings with them, re-paying Bedrock for text that
+-- did not change.
+
+CREATE TABLE files (
+  path            TEXT PRIMARY KEY,
+  blob_sha        TEXT NOT NULL,
+  content_hash    TEXT NOT NULL,
+  memory_type     TEXT NOT NULL CHECK (memory_type IN (
+                    'episodic','semantic','procedural','agent_insight',
+                    'user_preference','error_pattern','verdict','precedent','arc')),
+  title           TEXT NOT NULL,
+  body_text       TEXT NOT NULL,
+  gist            TEXT NOT NULL DEFAULT '',
+  -- title, gist, and body joined by newlines: the ONE column `files_fts` covers, so that a single
+  -- MATCH finds a term wherever it lives. A multi-column FTS5 table would make `bm25()` weight the
+  -- columns against each other, which is a ranking decision the RRF fusion already owns.
+  fts_text        TEXT NOT NULL DEFAULT '',
+  -- What memory_recall may QUOTE, which is narrower than what it may search: the <mark> claim,
+  -- the <summary> headlines, the <dl> facets, the citations. <details> bodies are excluded (Tier 3,
+  -- memory_read only) and <aside> texts are excluded (a scope caveat quoted as the memory would
+  -- present the exception as the rule). Stored rather than re-derived at read time so the exclusion
+  -- is decided once, by the indexer, where the parsed structure is still in hand.
+  disclosure_text TEXT NOT NULL DEFAULT '',
+  para            TEXT NOT NULL CHECK (para IN ('projects','areas','resources','archive')),
+  workspace       TEXT,
+  confidence      REAL    NOT NULL DEFAULT 1.0 CHECK (confidence BETWEEN 0 AND 1),
+  importance      INTEGER NOT NULL DEFAULT 5 CHECK (importance BETWEEN 1 AND 10),
+  archived        INTEGER NOT NULL DEFAULT 0 CHECK (archived IN (0,1)),
+  origin_path     TEXT,
+  word_count      INTEGER NOT NULL DEFAULT 0,
+  created_at      TEXT NOT NULL,
+  updated_at      TEXT NOT NULL,
+  -- When the remembered fact HAPPENED, from the article's first <time datetime>. World time,
+  -- not write time: the recency arm ranks by coalesce(event_at, updated_at) so a memory about
+  -- last month's incident does not outrank one about today merely by being written later.
+  event_at        TEXT,
+  archived_at     TEXT,
+  valid_from      TEXT,
+  valid_until     TEXT,
+  reprieves       INTEGER NOT NULL DEFAULT 0 CHECK (reprieves >= 0),
+  needs_revision  INTEGER NOT NULL DEFAULT 0 CHECK (needs_revision IN (0,1)),
+  author          TEXT NOT NULL DEFAULT 'agent',
+  session_id      TEXT,
+  prompt_id       TEXT,
+  turn_uuid       TEXT,
+  indexed_at      TEXT NOT NULL
+);
+
+-- Structural dedup. A duplicate active body cannot even be indexed, so the write path's
+-- content-hash lookup and the database agree by construction rather than by discipline.
+CREATE UNIQUE INDEX files_content_hash_active ON files (content_hash) WHERE archived = 0;
+CREATE INDEX files_type_active   ON files (memory_type) WHERE archived = 0;
+CREATE INDEX files_workspace     ON files (workspace)   WHERE archived = 0;
+CREATE INDEX files_para          ON files (para);
+CREATE INDEX files_updated       ON files (updated_at)  WHERE archived = 0;
+CREATE INDEX files_event         ON files (event_at)    WHERE event_at IS NOT NULL;
+CREATE INDEX files_session       ON files (session_id)  WHERE session_id IS NOT NULL;
+CREATE INDEX files_ttl           ON files (valid_until) WHERE valid_until IS NOT NULL AND archived = 0;
+CREATE INDEX files_blob          ON files (blob_sha);
+
+-- Open vocabulary. Tags broaden a scoped search (ANY-of overlap), so a new tag never has to be
+-- registered anywhere before it is usable.
+CREATE TABLE file_tags (
+  path TEXT NOT NULL REFERENCES files (path) ON DELETE CASCADE ON UPDATE CASCADE,
+  tag  TEXT NOT NULL,
+  PRIMARY KEY (path, tag)
+);
+CREATE INDEX file_tags_tag ON file_tags (tag);
+
+-- `type:name` references, split at the first colon. `concept:` rows are promoted by the indexer
+-- from the article's <dfn> terms, so a semantic memory that defines a term is findable by the
+-- term without the author also writing a memhtml-entity meta.
+CREATE TABLE file_entities (
+  path        TEXT NOT NULL REFERENCES files (path) ON DELETE CASCADE ON UPDATE CASCADE,
+  entity_type TEXT NOT NULL,
+  entity_name TEXT NOT NULL,
+  PRIMARY KEY (path, entity_type, entity_name)
+);
+CREATE INDEX file_entities_name ON file_entities (entity_type, entity_name);
+
+-- <dt>/<dd> pairs. `numeric_value` is present only when the <dd> carries a <data value> that
+-- parses as a finite number, and it is UNITLESS: the unit lives in the human phrasing
+-- (<data value="120">about two minutes</data> is seconds because the prose says so), so a
+-- consumer must never infer a unit from the number.
+CREATE TABLE file_facets (
+  path          TEXT NOT NULL REFERENCES files (path) ON DELETE CASCADE ON UPDATE CASCADE,
+  name          TEXT NOT NULL,
+  value         TEXT NOT NULL,
+  numeric_value REAL,
+  PRIMARY KEY (path, name, value)
+);
+CREATE INDEX file_facets_name ON file_facets (name);
+
+-- <cite> and <q cite>. `href` is the quotation's source URI when the file gave one, an
+-- arbitrary URI, not necessarily a memory path, so it is deliberately unconstrained.
+CREATE TABLE file_citations (
+  path TEXT NOT NULL REFERENCES files (path) ON DELETE CASCADE ON UPDATE CASCADE,
+  text TEXT NOT NULL,
+  href TEXT,
+  PRIMARY KEY (path, text)
+);

package/migrations/0002_chunks.sql

@@ -0,0 +1,31 @@
+-- Chunks and their vectors. Both key on `content_hash`, not on `path`: a `git mv`, which is what
+-- eviction and every rename are, reuses the vector with zero Bedrock calls, and two files whose
+-- bodies later diverge never share one.
+
+CREATE TABLE chunks (
+  -- sha256(content_hash || ':' || ordinal). An identical body anywhere in the tree therefore hits
+  -- the same chunk row and the same embedding.
+  chunk_id     TEXT PRIMARY KEY,
+  path         TEXT NOT NULL REFERENCES files (path) ON DELETE CASCADE ON UPDATE CASCADE,
+  content_hash TEXT NOT NULL,
+  -- 0-based position within THIS file's chunk sequence.
+  ordinal      INTEGER NOT NULL CHECK (ordinal >= 0),
+  text         TEXT NOT NULL,
+  char_count   INTEGER NOT NULL
+);
+CREATE INDEX chunks_path ON chunks (path);
+CREATE INDEX chunks_hash ON chunks (content_hash);
+CREATE UNIQUE INDEX chunks_hash_ord ON chunks (content_hash, ordinal);
+
+CREATE TABLE embeddings (
+  chunk_id   TEXT PRIMARY KEY REFERENCES chunks (chunk_id) ON DELETE CASCADE,
+  -- The vector space, as `<model-id>@<dim>`. A model id alone does not identify a space: the same
+  -- id at another output_dimension produces vectors silently incomparable with the stored ones.
+  model      TEXT NOT NULL,
+  dim        INTEGER NOT NULL CHECK (dim > 0),
+  -- float32 little-endian, bound as Buffer.from(Float32Array.buffer). `vector_distance_cos` reads
+  -- it directly; the MMR pass decodes it with Float32Array rather than paying vector_extract.
+  vec        BLOB NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX embeddings_model ON embeddings (model);

package/migrations/0003_fts.sql

@@ -0,0 +1,40 @@
+-- The lexical index: an FTS5 table over `files.fts_text`, plus the triggers that keep it in step.
+--
+-- EXTERNAL CONTENT (`content='files'`) rather than a standalone FTS5 table, so the indexed text is
+-- stored once. `files` already holds `fts_text`; a standalone table would keep a second copy of every
+-- memory's searchable text, doubling the largest column in the schema for nothing. `content_rowid`
+-- names the join back: `files` has a TEXT primary key and therefore an ordinary implicit rowid, which
+-- is what FTS5 addresses rows by.
+--
+-- ONE column, deliberately, and the reason is unchanged: `fts_text` is title + gist + body_text
+-- joined, so a term in any of the three is found by one MATCH. A multi-column FTS5 table would scope
+-- an unqualified MATCH across all columns but make `bm25()` weight them, which is a ranking decision
+-- the RRF fusion already owns.
+--
+-- Ranking is `bm25(files_fts)`, a real relevance score, ascending, most relevant first (FTS5 returns
+-- bm25 as a negative number). The lexical arm's `ROW_NUMBER()` orders by it.
+--
+-- The triggers are the whole maintenance contract. External-content FTS5 does NOT observe its content
+-- table on its own: without them the index silently stops matching rows the corpus has. A delete is
+-- written as the `'delete'` command with the OLD text, because FTS5 needs the previous terms to
+-- unindex them. Passing the new text, or omitting it, corrupts the index rather than failing.
+CREATE VIRTUAL TABLE files_fts USING fts5(
+  fts_text,
+  content='files',
+  content_rowid='rowid'
+);
+
+CREATE TRIGGER files_fts_insert AFTER INSERT ON files BEGIN
+  INSERT INTO files_fts(rowid, fts_text) VALUES (new.rowid, new.fts_text);
+END;
+
+CREATE TRIGGER files_fts_delete AFTER DELETE ON files BEGIN
+  INSERT INTO files_fts(files_fts, rowid, fts_text) VALUES ('delete', old.rowid, old.fts_text);
+END;
+
+-- `OF fts_text` and not a bare `AFTER UPDATE`: every other column is projection metadata the lexical
+-- index does not read, and firing on those would pay an unindex+reindex for an `archived` flip.
+CREATE TRIGGER files_fts_update AFTER UPDATE OF fts_text ON files BEGIN
+  INSERT INTO files_fts(files_fts, rowid, fts_text) VALUES ('delete', old.rowid, old.fts_text);
+  INSERT INTO files_fts(rowid, fts_text) VALUES (new.rowid, new.fts_text);
+END;

package/migrations/0004_edges.sql

@@ -0,0 +1,40 @@
+-- The graph. Authored edges come from the files' <link rel="memhtml-*"> elements; derived edges are
+-- sleep-mined and live only here, because they are a re-derivable function of the corpus and the
+-- embedder. `derived` is the firewall: the retention penalty counts only `derived = 0`, so an
+-- uncorroborated machine suspicion can never evict a memory.
+--
+-- No FK on src_path/dst_path. A <link> may legitimately point at a file the indexer has not reached
+-- yet, or at an archived path; a hard FK would make the indexer order-dependent. Dangling links are
+-- found by a LEFT JOIN in the integrity phase and repaired in a commit.
+
+CREATE TABLE edges (
+  src_path     TEXT NOT NULL,
+  rel          TEXT NOT NULL,
+  dst_path     TEXT NOT NULL,
+  -- The three classes do not mix. A person edge is structurally incapable of entering PageRank,
+  -- MMR, or the retention bridge count, because every memory-graph query filters on this column
+  -- and the CHECKs below refuse a rel from another class.
+  edge_class   TEXT NOT NULL DEFAULT 'memory'
+               CHECK (edge_class IN ('memory','person','provenance')),
+  derived      INTEGER NOT NULL DEFAULT 0 CHECK (derived IN (0,1)),
+  -- Unitless in [0, 1]. An authored edge is 1.0; a mined one carries its cosine.
+  strength     REAL NOT NULL DEFAULT 1.0 CHECK (strength BETWEEN 0 AND 1),
+  provenance   TEXT NOT NULL DEFAULT 'authored'
+               CHECK (provenance IN ('authored','sleep','import')),
+  sleep_run    TEXT,
+  src_hash     TEXT,
+  dst_hash     TEXT,
+  created_at   TEXT NOT NULL,
+  PRIMARY KEY (src_path, rel, dst_path),
+  CHECK (src_path <> dst_path),
+  CHECK (edge_class <> 'memory' OR rel IN (
+    'supersedes','contradicts','caused_by','leads_to','part_of',
+    'relates_to','example_of','supports','laterally_related')),
+  CHECK (edge_class <> 'person'  OR rel IN ('about_person','authored_by')),
+  CHECK (edge_class <> 'provenance' OR rel IN ('from_session')),
+  CHECK (derived = 0 OR provenance = 'sleep')
+);
+CREATE INDEX edges_src ON edges (src_path, edge_class) WHERE derived = 0;
+CREATE INDEX edges_dst ON edges (dst_path, edge_class) WHERE derived = 0;
+CREATE INDEX edges_rel ON edges (rel, edge_class);
+CREATE INDEX edges_derived ON edges (derived, rel);

package/migrations/0005_traces.sql

@@ -0,0 +1,92 @@
+-- The trace plane: a read-only index over ~/.claude/projects. `.memhtml` never holds session content,
+-- so every column here is a pointer or a capped head, never a copy.
+--
+-- Firewalled from retrieval. Nothing in the retrieval SQL assembler names `traces` or
+-- `trace_prompts`, and a test greps every assembled statement to prove it. The schema separation
+-- the predecessor memory system got from a second Postgres schema is a table-name firewall here.
+
+CREATE TABLE traces (
+  session_id   TEXT PRIMARY KEY,
+  -- The ~/.claude/projects/<slug> directory name: a PATH slug, derived from the cwd. Not the
+  -- `slug` field on a subagent record, which is a title slug for the agent's task.
+  slug         TEXT NOT NULL,
+  cwd          TEXT,
+  git_branch   TEXT,
+  entrypoint   TEXT,
+  model        TEXT,
+  version      TEXT,
+  started_at   TEXT,
+  ended_at     TEXT,
+  prompt_count INTEGER NOT NULL DEFAULT 0,
+  turn_count   INTEGER NOT NULL DEFAULT 0,
+  agent_count  INTEGER NOT NULL DEFAULT 0,
+  first_prompt TEXT NOT NULL DEFAULT '',
+  ai_title     TEXT,
+  -- The main transcript's path. A session's subagent sidecars are separate files upserting into
+  -- this one row, so this is always the `kind: "session"` file.
+  file_path    TEXT NOT NULL,
+  file_size    INTEGER NOT NULL,
+  file_mtime   TEXT NOT NULL,
+  -- first_prompt + ai_title joined by a newline, for the same single-column reason as files.fts_text.
+  search_text  TEXT NOT NULL DEFAULT '',
+  indexed_at   TEXT NOT NULL
+);
+CREATE INDEX traces_slug    ON traces (slug);
+CREATE INDEX traces_cwd     ON traces (cwd);
+CREATE INDEX traces_started ON traces (started_at);
+CREATE INDEX traces_mtime   ON traces (file_mtime);
+
+-- Trace search, on the same external-content pattern as `files_fts` (see 0003_fts.sql for why).
+CREATE VIRTUAL TABLE traces_fts USING fts5(
+  search_text,
+  content='traces',
+  content_rowid='rowid'
+);
+
+CREATE TRIGGER traces_fts_insert AFTER INSERT ON traces BEGIN
+  INSERT INTO traces_fts(rowid, search_text) VALUES (new.rowid, new.search_text);
+END;
+
+CREATE TRIGGER traces_fts_delete AFTER DELETE ON traces BEGIN
+  INSERT INTO traces_fts(traces_fts, rowid, search_text)
+    VALUES ('delete', old.rowid, old.search_text);
+END;
+
+CREATE TRIGGER traces_fts_update AFTER UPDATE OF search_text ON traces BEGIN
+  INSERT INTO traces_fts(traces_fts, rowid, search_text)
+    VALUES ('delete', old.rowid, old.search_text);
+  INSERT INTO traces_fts(rowid, search_text) VALUES (new.rowid, new.search_text);
+END;
+
+CREATE TABLE trace_prompts (
+  session_id TEXT NOT NULL REFERENCES traces (session_id) ON DELETE CASCADE,
+  prompt_id  TEXT NOT NULL,
+  turn_uuid  TEXT NOT NULL,
+  -- 0-based position among the distinct prompts of THIS session, in first-appearance order.
+  -- Per-session scope: comparable only within one session_id.
+  ordinal    INTEGER NOT NULL,
+  at         TEXT NOT NULL,
+  agent_id   TEXT,
+  -- Capped at 200 characters by the extractor. This is an index, not a copy.
+  text_head  TEXT NOT NULL DEFAULT '',
+  PRIMARY KEY (session_id, prompt_id)
+);
+CREATE INDEX trace_prompts_uuid ON trace_prompts (session_id, turn_uuid);
+
+-- Written at memory-write time by the store's injected recorder, not by the trace scanner. The
+-- same link is also file-borne as memhtml-session/memhtml-prompt/memhtml-turn, so it survives a rebuild;
+-- this table is what makes it queryable in both directions.
+--
+-- No FK to `traces`: a memory can be written in a session whose transcript has not been scanned
+-- yet, and refusing the link would lose the provenance the file already carries.
+CREATE TABLE memory_session_links (
+  path       TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  prompt_id  TEXT,
+  turn_uuid  TEXT,
+  link_kind  TEXT NOT NULL CHECK (link_kind IN ('wrote','read','corrected','reinforced')),
+  at         TEXT NOT NULL,
+  PRIMARY KEY (path, session_id, link_kind, at)
+);
+CREATE INDEX msl_session ON memory_session_links (session_id);
+CREATE INDEX msl_path    ON memory_session_links (path);

package/migrations/0006_sleep.sql

@@ -0,0 +1,33 @@
+-- Sleep-run reporting. Not load-bearing: the commit trailers on the sleep branch are what
+-- `memhtml sleep resume` reads (`git log --format=%B base..HEAD | grep '^Memhtml-Phase:'`), so this pair of
+-- tables is a reporting convenience the git history can regenerate. That is deliberate. A journal
+-- table that a resume depended on would be a second source of truth for what already happened.
+
+CREATE TABLE sleep_runs (
+  -- `sleep/<YYYY-MM-DD>`, suffixed `-2` on a same-day rerun. Also the branch name.
+  run_id     TEXT PRIMARY KEY,
+  branch     TEXT NOT NULL,
+  base_sha   TEXT NOT NULL,
+  head_sha   TEXT,
+  status     TEXT NOT NULL CHECK (status IN ('running','review','merged','abandoned','failed')),
+  started_at TEXT NOT NULL,
+  ended_at   TEXT
+);
+CREATE INDEX sleep_runs_started ON sleep_runs (started_at);
+
+CREATE TABLE sleep_phases (
+  run_id     TEXT NOT NULL REFERENCES sleep_runs (run_id) ON DELETE CASCADE,
+  phase      TEXT NOT NULL,
+  -- 1-based ordinal of the phase within the 15-phase sequence. A display label, never arithmetic.
+  ordinal    INTEGER NOT NULL,
+  -- Per-phase isolation is the design driver: a failed phase keeps every prior phase's commits and
+  -- later phases still run, so `failed` here is a normal terminal state, not an aborted run.
+  status     TEXT NOT NULL CHECK (status IN ('ok','failed','skipped')),
+  commit_sha TEXT,
+  counts     TEXT NOT NULL DEFAULT '{}',
+  error      TEXT,
+  llm_calls  INTEGER NOT NULL DEFAULT 0,
+  started_at TEXT NOT NULL,
+  ended_at   TEXT,
+  PRIMARY KEY (run_id, phase)
+);

package/migrations/0007_watermark.sql

@@ -0,0 +1,32 @@
+-- The two watermarks. Each answers "what did the last run already consume", and each is what makes
+-- the corresponding incremental path cheap enough to run on a cron.
+
+-- Exactly one row, by CHECK. The incremental indexer's watermark.
+CREATE TABLE index_state (
+  id            INTEGER PRIMARY KEY CHECK (id = 1),
+  -- The commit the index describes. NULL before the first rebuild. `git diff <head_sha> HEAD`
+  -- is the whole change set the next update has to apply.
+  head_sha      TEXT,
+  -- The vector space, as `<model-id>@<dim>` (@memhtml/llm's EMBED_WATERMARK). A mismatch against
+  -- configuration is a hard refusal, never a silent reindex: a half-migrated vector space degrades
+  -- every cosine and is invisible in tests. Only `rebuild --embed-model` rewrites it, and it
+  -- truncates `embeddings` first.
+  embed_model   TEXT NOT NULL,
+  embed_dim     INTEGER NOT NULL CHECK (embed_dim > 0),
+  rebuilt_at    TEXT NOT NULL,
+  updated_at    TEXT NOT NULL
+);
+
+-- One row per transcript file. Size AND mtime must both match to skip: size alone misses an
+-- in-place rewrite that preserves the length, mtime alone misses a write inside the same clock tick.
+CREATE TABLE trace_watermarks (
+  file_path  TEXT PRIMARY KEY,
+  size       INTEGER NOT NULL,
+  -- ISO-8601 UTC. @memhtml/traces reports mtime in epoch MILLISECONDS, so the adapter converts at this
+  -- boundary and the column carries exactly one unit.
+  mtime      TEXT NOT NULL,
+  -- 0-based byte offset: one past the last byte consumed, and therefore the `start` of the next
+  -- read. Equal to `size` after a complete scan.
+  byte_off   INTEGER NOT NULL DEFAULT 0 CHECK (byte_off >= 0),
+  scanned_at TEXT NOT NULL
+);