2. Data model

2.1 Tables read from claude-mem.db

Opened with readonly: true, PRAGMA query_only = ON, busy_timeout = 1500. Every SELECT goes through a helper that turns "no such table" and "no such column" into an empty result, so an older database still renders (and so a wrong column name fails silently, see finding F1).

created_at_epoch is milliseconds since 1970 everywhere.

Bounds on every read

2.2 Work-state entries

An entry is {project, list_name, fields}. fields.task selects a task inside the list; without it the fields apply to the list itself. Folding in order (by created_at_epoch, then device id, then origin_local_id/id as BigInt): each field sets its value, and a null value deletes the field. A task or list is closed when fields.status is done or dropped (case-insensitive). A list is open when it has fields of its own (and is not closed) or any open task.

Reserved list names:

Task fields the view understands (first non-empty wins, in this order):

2.3 The overlay (<dataDir>/overlay.db)

Same shape as work_state_entries (id, project, list_name, fields, created_at, created_at_epoch). Ids are stored as OVERLAY_ID_BASE + rowid with OVERLAY_ID_BASE = 2^40, so they never collide with source ids, still sort after them, and evidence lookups can route by id (>= 2^40 goes to the overlay). Source rows and overlay rows are folded together.

2.4 The review store (<dataDir>/work-view-reviews.db)

CREATE TABLE work_view_reviews (
  request_id TEXT PRIMARY KEY,
  content_fingerprint TEXT NOT NULL,
  checked_at_epoch INTEGER NOT NULL,
  actor TEXT NOT NULL CHECK (actor = 'local-user'));

A card is "checked" only while the stored fingerprint equals the card's current fingerprint. Any change to the work it cites un-checks it.

2.5 The ledger (<ledgerDir>/)

All JSON, mode 0600, written atomically (temp file then rename). Formats are the original's exactly.

request-groups.json            { version:1, updatedAt, conversations:{<convKey>: groupId}, groups:{<groupId>: Group}, ignored:{<convKey>: reason} }
progress/g_<12hex>.json        Review (one per group)
story.json                     { narrative, preferences:[{preference, kind, supportCount, quotes:[{quote, at}]}], writtenAt }
alignment.json                 { links:{<groupId>:[{goal, evidence}]}, unaligned:[groupId], basis:{<groupId>: hash16}, goals:[goalKey], alignedAt }
refresh.json                   { state, reason, agent, startedAt, finishedAt, needs, result, error, nextAt, steps:[{step, agent, startedAt, finishedAt, groups?}], pid? }
agent-written-prompts.json     { promptIds:[...], updatedAt }   (optional; prompts an agent wrote)
owner-goals/<YYYY-MM-DD>/      scratch for the goals step (owner-prompts.md, owner-map.md, owner-goals.json)
agent-runs/<hex>/              scratch for one refresh run, removed when it ends
failed-answers/                raw model answers that failed validation twice

Group = { title (<=120), anchor (convKey), projectRoot, links:[Link], decidedAt, anchorAsk }. Link = { kind: shared-work-list|shared-request-id|agent-judgment, conversations:[>=2 of the group's], evidence }. Review = { groupId, state: shipped|in-progress|stalled|abandoned|unknown, percent 0-100, startedAt, shippedAt, lastActivityAt, summary (<=280), narrative (<=1200), milestones (<=12 of {at,text<=200,evidence[]}), preferences (<=10 of {kind,preference<=200,quote<=300,at}), outcome|null, evidence (<=20), reviewedThrough, reviewedConversations, checkedAt, changedAt, readings (<=20 of {at,percent}) }. outcome = { landed:{text<=400,at,evidence}, usage:{level in-use|some-use|no-evidence|unknown,text,evidence}, value:{level high|medium|low|unclear,text,evidence}, regressions (<=10 of {text,at,fixedBy,evidence}), changes (<=12 of {what,why,at,evidence}) }.

Identifiers

Alignment basis

alignment.basis[groupId] is sha256(JSON{groupId,title,firstAsk[:400],state,percent,summary, conversations(sorted)}).slice(0,16). A group is "unaligned" (due) when it has no recorded decision, when its basis changed, when a link points at a goal that no longer exists, or when the goal set changed.

2.6 Other files