aidimag 1.0.0

package/dist/critique/critique.d.ts

@@ -0,0 +1,40 @@
+/**
+ * memory_critique (KARPATHY_LAYERS Feature 3) — Verifier layer.
+ *
+ * The "second AI critic" Karpathy recommends, but grounded in *verified project
+ * memory* rather than another model's opinions. Given a summary of what an agent
+ * did (and the files it touched), it surfaces:
+ *   - guardrail violations  (kind=GUARDRAIL, level never/ask-first)
+ *   - confirmations         (memory the work is consistent with)
+ *   - contradictions        (in-scope rules the summary doesn't appear to honor)
+ *   - missing coverage      (changed files with no memory → ask the user)
+ *
+ * Matching is heuristic (keyword overlap + scope) layered on real retrieval —
+ * deliberately conservative: it raises questions, the agent decides.
+ */
+import type { MemoryStore } from "../db/store.js";
+import type { GuardrailLevel, MemoryEntry } from "../types.js";
+export interface CritiqueInput {
+    summary: string;
+    filesChanged: string[];
+}
+export interface CritiqueResult {
+    guardrailsViolated: Array<{
+        memory: MemoryEntry;
+        level: GuardrailLevel;
+        concern: string;
+    }>;
+    contradictions: Array<{
+        memory: MemoryEntry;
+        concern: string;
+    }>;
+    confirmations: Array<{
+        memory: MemoryEntry;
+    }>;
+    missingCoverage: string[];
+}
+/**
+ * Critique a unit of work against project memory. Async because it folds in
+ * semantic recall when embeddings are configured (degrades to keyword-only).
+ */
+export declare function critique(store: MemoryStore, input: CritiqueInput): Promise<CritiqueResult>;

package/dist/critique/critique.js

@@ -0,0 +1,110 @@
+/**
+ * memory_critique (KARPATHY_LAYERS Feature 3) — Verifier layer.
+ *
+ * The "second AI critic" Karpathy recommends, but grounded in *verified project
+ * memory* rather than another model's opinions. Given a summary of what an agent
+ * did (and the files it touched), it surfaces:
+ *   - guardrail violations  (kind=GUARDRAIL, level never/ask-first)
+ *   - confirmations         (memory the work is consistent with)
+ *   - contradictions        (in-scope rules the summary doesn't appear to honor)
+ *   - missing coverage      (changed files with no memory → ask the user)
+ *
+ * Matching is heuristic (keyword overlap + scope) layered on real retrieval —
+ * deliberately conservative: it raises questions, the agent decides.
+ */
+import { hybridSearch } from "../embeddings/search.js";
+const STOP = new Set([
+    "the", "a", "an", "and", "or", "but", "to", "of", "in", "on", "for", "with", "is", "are",
+    "be", "this", "that", "it", "as", "at", "by", "from", "we", "i", "you", "should", "will",
+    "add", "added", "adds", "use", "used", "uses", "change", "changed", "update", "updated",
+]);
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/)
+        .filter((t) => t.length > 2 && !STOP.has(t)));
+}
+/** Jaccard overlap between two token sets (0..1). */
+function overlap(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}
+function scopesFile(m, files) {
+    if (m.scope.paths.length === 0)
+        return false; // repo-wide → not "specific to" a file
+    return m.scope.paths.some((sp) => files.some((f) => f.startsWith(sp) || sp.startsWith(f)));
+}
+const CONFIRM_THRESHOLD = 0.1;
+const GUARDRAIL_THRESHOLD = 0.06; // guardrails surface on weaker signal — better safe
+/**
+ * Critique a unit of work against project memory. Async because it folds in
+ * semantic recall when embeddings are configured (degrades to keyword-only).
+ */
+export async function critique(store, input) {
+    const summaryTokens = tokenize(input.summary);
+    const files = input.filesChanged ?? [];
+    // 1) memories scoped to the touched files
+    const scoped = files.length ? store.getForFiles(files, 50) : [];
+    // 2) semantically/keyword-related memories beyond scope
+    const { results: related } = await hybridSearch(store, { query: input.summary, limit: 20 }).catch(() => ({
+        results: [],
+        semantic: false,
+    }));
+    // 3) every guardrail, project-wide
+    const guardrails = store.list(10_000).filter((m) => m.kind === "GUARDRAIL" && m.status !== "REFUTED");
+    const pool = new Map();
+    for (const m of [...scoped, ...related]) {
+        if (m.status === "REFUTED" || m.kind === "GUARDRAIL")
+            continue;
+        pool.set(m.id, m);
+    }
+    const result = {
+        guardrailsViolated: [],
+        contradictions: [],
+        confirmations: [],
+        missingCoverage: [],
+    };
+    for (const g of guardrails) {
+        const score = overlap(summaryTokens, tokenize(g.claim));
+        const inScope = scopesFile(g, files);
+        if ((score >= GUARDRAIL_THRESHOLD || inScope) && g.guardrailLevel !== "always") {
+            const level = g.guardrailLevel ?? "ask-first";
+            result.guardrailsViolated.push({
+                memory: g,
+                level,
+                concern: level === "never"
+                    ? "Your change appears to touch a NEVER guardrail. Refuse or justify explicitly before proceeding."
+                    : "An ASK-FIRST guardrail covers this area. Confirm with the user before continuing.",
+            });
+        }
+    }
+    for (const m of pool.values()) {
+        const score = overlap(summaryTokens, tokenize(m.claim));
+        const inScope = scopesFile(m, files);
+        if (score >= CONFIRM_THRESHOLD) {
+            result.confirmations.push({ memory: m });
+        }
+        else if (inScope && (m.kind === "INVARIANT" || m.kind === "CONVENTION" || m.kind === "DECISION")) {
+            // in scope but the summary doesn't mention honoring it → worth a look
+            result.contradictions.push({
+                memory: m,
+                concern: `This ${m.kind} governs ${m.scope.paths.join(", ")} which you changed, but your summary doesn't confirm it still holds. Re-check it.`,
+            });
+        }
+    }
+    // changed files with no scoped memory at all → suggest asking the user
+    const covered = new Set();
+    for (const m of scoped)
+        for (const sp of m.scope.paths)
+            for (const f of files)
+                if (f.startsWith(sp) || sp.startsWith(f))
+                    covered.add(f);
+    result.missingCoverage = files.filter((f) => !covered.has(f));
+    return result;
+}
+//# sourceMappingURL=critique.js.map

package/dist/db/schema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SQLite schema for aidimag. Lives in <repo>/.aidimag/memory.db
+ * FTS5 powers Phase 1 search; sqlite-vec embeddings arrive in Phase 2.
+ */
+export declare const SCHEMA_VERSION = 9;
+/** Idempotent migrations for pre-existing DBs (failures = already applied). */
+export declare const MIGRATIONS: string[];
+/**
+ * v6 guarded migration: SQLite can't ALTER a CHECK constraint, so adding the
+ * TICKET_REF evidence type requires rebuilding the evidence table. Runs once,
+ * gated on the stored schema_version (store.ts).
+ */
+export declare const EVIDENCE_REBUILD_V6 = "\nALTER TABLE evidence RENAME TO evidence_v5;\nCREATE TABLE evidence (\n  id        TEXT PRIMARY KEY,\n  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,\n  type      TEXT NOT NULL CHECK (type IN (\n              'COMMIT_REF','TEST_RESULT','EXEC_TRACE','STATIC_CHECK','HUMAN_ATTESTED','TICKET_REF')),\n  payload   TEXT NOT NULL,\n  last_run  TEXT,\n  result    TEXT NOT NULL DEFAULT 'UNKNOWN' CHECK (result IN ('PASS','FAIL','UNKNOWN'))\n);\nINSERT INTO evidence SELECT * FROM evidence_v5;\nDROP TABLE evidence_v5;\nCREATE INDEX IF NOT EXISTS idx_evidence_memory ON evidence(memory_id);\n";
+/**
+ * v8 guarded rebuild: SQLite can't ALTER a CHECK constraint, so adding the
+ * GUARDRAIL + SKILL memory kinds requires rebuilding the memories and proposals
+ * tables. Rowids are preserved (FTS is a contentless mirror keyed on rowid) and
+ * the FTS index is rebuilt afterwards. Runs once, gated on the stored
+ * schema_version (store.ts), with foreign_keys disabled around it.
+ */
+export declare const MEMORIES_REBUILD_V8 = "\nCREATE TABLE memories_v8 (\n  id            TEXT PRIMARY KEY,\n  kind          TEXT NOT NULL CHECK (kind IN (\n                  'DECISION','CONVENTION','GOTCHA','FAILED_APPROACH',\n                  'ARCHITECTURE','INVARIANT','TODO_CONTEXT','GUARDRAIL','SKILL')),\n  claim         TEXT NOT NULL,\n  confidence    REAL NOT NULL DEFAULT 0.5,\n  status        TEXT NOT NULL DEFAULT 'UNVERIFIED' CHECK (status IN (\n                  'VERIFIED','UNVERIFIED','STALE','REFUTED')),\n  created_by    TEXT NOT NULL DEFAULT 'human',\n  created_at    TEXT NOT NULL,\n  verified_at   TEXT,\n  superseded_by TEXT REFERENCES memories(id),\n  updated_at    TEXT,\n  pinned        INTEGER NOT NULL DEFAULT 0,\n  guardrail_level TEXT CHECK (guardrail_level IN ('always','ask-first','never'))\n);\nINSERT INTO memories_v8 (rowid, id, kind, claim, confidence, status, created_by,\n                         created_at, verified_at, superseded_by, updated_at, pinned, guardrail_level)\n  SELECT rowid, id, kind, claim, confidence, status, created_by,\n         created_at, verified_at, superseded_by, updated_at, pinned, guardrail_level FROM memories;\nDROP TABLE memories;\nALTER TABLE memories_v8 RENAME TO memories;\nINSERT INTO memories_fts(memories_fts) VALUES('rebuild');\n";
+export declare const PROPOSALS_REBUILD_V8 = "\nCREATE TABLE proposals_v8 (\n  id         TEXT PRIMARY KEY,\n  kind       TEXT NOT NULL CHECK (kind IN (\n               'DECISION','CONVENTION','GOTCHA','FAILED_APPROACH',\n               'ARCHITECTURE','INVARIANT','TODO_CONTEXT','GUARDRAIL','SKILL')),\n  claim      TEXT NOT NULL,\n  paths      TEXT NOT NULL DEFAULT '[]',\n  symbols    TEXT NOT NULL DEFAULT '[]',\n  evidence   TEXT NOT NULL DEFAULT '[]',\n  source     TEXT NOT NULL,\n  source_ref TEXT,\n  rationale  TEXT,\n  created_at TEXT NOT NULL,\n  status     TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','APPROVED','REJECTED')),\n  memory_id  TEXT REFERENCES memories(id) ON DELETE SET NULL,\n  updated_at TEXT,\n  ticket_ref TEXT,\n  guardrail_level TEXT CHECK (guardrail_level IN ('always','ask-first','never'))\n);\nINSERT INTO proposals_v8 (id, kind, claim, paths, symbols, evidence, source, source_ref,\n                          rationale, created_at, status, memory_id, updated_at, ticket_ref, guardrail_level)\n  SELECT id, kind, claim, paths, symbols, evidence, source, source_ref,\n         rationale, created_at, status, memory_id, updated_at, ticket_ref, guardrail_level FROM proposals;\nDROP TABLE proposals;\nALTER TABLE proposals_v8 RENAME TO proposals;\n";
+/**
+ * v9 guarded rebuild: Add new event types (updated, evidence_added, evidence_removed)
+ * to the events table CHECK constraint. SQLite can't ALTER a CHECK constraint.
+ */
+export declare const EVENTS_REBUILD_V9 = "\nALTER TABLE events RENAME TO events_v8;\nCREATE TABLE events (\n  seq            INTEGER PRIMARY KEY AUTOINCREMENT,\n  id             TEXT NOT NULL UNIQUE,\n  type           TEXT NOT NULL CHECK (type IN (\n                   'memory_created','status_changed','evidence_result',\n                   'refuted','superseded','forgotten',\n                   'proposal_created','proposal_approved','proposal_rejected',\n                   'verification_report','updated','evidence_added','evidence_removed')),\n  memory_id      TEXT,\n  payload        TEXT NOT NULL DEFAULT '{}',\n  machine        TEXT NOT NULL,\n  schema_version INTEGER NOT NULL,\n  created_at     TEXT NOT NULL,\n  synced         INTEGER NOT NULL DEFAULT 0\n);\nINSERT INTO events SELECT * FROM events_v8;\nDROP TABLE events_v8;\nCREATE INDEX IF NOT EXISTS idx_events_synced ON events(synced, seq);\n";
+export declare const SCHEMA_SQL = "\nPRAGMA journal_mode = WAL;\nPRAGMA foreign_keys = ON;\n\nCREATE TABLE IF NOT EXISTS meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS memories (\n  id            TEXT PRIMARY KEY,\n  kind          TEXT NOT NULL CHECK (kind IN (\n                  'DECISION','CONVENTION','GOTCHA','FAILED_APPROACH',\n                  'ARCHITECTURE','INVARIANT','TODO_CONTEXT','GUARDRAIL','SKILL')),\n  claim         TEXT NOT NULL,\n  confidence    REAL NOT NULL DEFAULT 0.5,\n  status        TEXT NOT NULL DEFAULT 'UNVERIFIED' CHECK (status IN (\n                  'VERIFIED','UNVERIFIED','STALE','REFUTED')),\n  created_by    TEXT NOT NULL DEFAULT 'human',\n  created_at    TEXT NOT NULL,\n  verified_at   TEXT,\n  superseded_by TEXT REFERENCES memories(id),\n  updated_at    TEXT,\n  pinned        INTEGER NOT NULL DEFAULT 0,\n  guardrail_level TEXT CHECK (guardrail_level IN ('always','ask-first','never'))\n);\n\n-- scope: one row per path / symbol a memory applies to\nCREATE TABLE IF NOT EXISTS memory_scopes (\n  memory_id  TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,\n  scope_type TEXT NOT NULL CHECK (scope_type IN ('path','symbol')),\n  value      TEXT NOT NULL,\n  PRIMARY KEY (memory_id, scope_type, value)\n);\n\nCREATE TABLE IF NOT EXISTS evidence (\n  id        TEXT PRIMARY KEY,\n  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,\n  type      TEXT NOT NULL CHECK (type IN (\n              'COMMIT_REF','TEST_RESULT','EXEC_TRACE','STATIC_CHECK','HUMAN_ATTESTED','TICKET_REF')),\n  payload   TEXT NOT NULL,\n  last_run  TEXT,\n  result    TEXT NOT NULL DEFAULT 'UNKNOWN' CHECK (result IN ('PASS','FAIL','UNKNOWN'))\n);\n\nCREATE TABLE IF NOT EXISTS memory_links (\n  from_id  TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,\n  to_id    TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,\n  relation TEXT NOT NULL CHECK (relation IN ('supports','contradicts','refines')),\n  PRIMARY KEY (from_id, to_id, relation)\n);\n\n-- Full-text search over claims (Phase 1 retrieval)\nCREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(\n  claim,\n  content='memories',\n  content_rowid='rowid'\n);\n\nCREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN\n  INSERT INTO memories_fts(rowid, claim) VALUES (new.rowid, new.claim);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN\n  INSERT INTO memories_fts(memories_fts, rowid, claim) VALUES ('delete', old.rowid, old.claim);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE OF claim ON memories BEGIN\n  INSERT INTO memories_fts(memories_fts, rowid, claim) VALUES ('delete', old.rowid, old.claim);\n  INSERT INTO memories_fts(rowid, claim) VALUES (new.rowid, new.claim);\nEND;\n\n-- Phase 2: capture pipeline \u2014 proposed memories awaiting human review\nCREATE TABLE IF NOT EXISTS proposals (\n  id         TEXT PRIMARY KEY,\n  kind       TEXT NOT NULL CHECK (kind IN (\n               'DECISION','CONVENTION','GOTCHA','FAILED_APPROACH',\n               'ARCHITECTURE','INVARIANT','TODO_CONTEXT','GUARDRAIL','SKILL')),\n  claim      TEXT NOT NULL,\n  paths      TEXT NOT NULL DEFAULT '[]',    -- JSON string[]\n  symbols    TEXT NOT NULL DEFAULT '[]',    -- JSON string[]\n  evidence   TEXT NOT NULL DEFAULT '[]',    -- JSON {type,payload}[]\n  source     TEXT NOT NULL,                 -- 'commit-miner' | 'session:<agent-id>' | ...\n  source_ref TEXT,                          -- e.g. commit sha\n  rationale  TEXT,                          -- why the source thinks this is worth remembering\n  created_at TEXT NOT NULL,\n  status     TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','APPROVED','REJECTED')),\n  memory_id  TEXT REFERENCES memories(id) ON DELETE SET NULL,  -- set when approved\n  updated_at TEXT,\n  ticket_ref TEXT,                          -- ticket id (e.g. XXX-2100) when known\n  guardrail_level TEXT                      -- always | ask-first | never (GUARDRAIL proposals)\n);\n\nCREATE INDEX IF NOT EXISTS idx_proposals_status ON proposals(status);\nCREATE UNIQUE INDEX IF NOT EXISTS idx_proposals_dedupe ON proposals(source, source_ref, claim);\n\n-- Phase 6: sync \u2014 deletions must propagate, so deletes leave tombstones\nCREATE TABLE IF NOT EXISTS tombstones (\n  id         TEXT NOT NULL,                 -- deleted row id\n  tbl        TEXT NOT NULL CHECK (tbl IN ('memories','proposals')),\n  deleted_at TEXT NOT NULL,\n  PRIMARY KEY (id, tbl)\n);\n\nCREATE INDEX IF NOT EXISTS idx_memories_status ON memories(status);\nCREATE INDEX IF NOT EXISTS idx_memories_kind   ON memories(kind);\nCREATE INDEX IF NOT EXISTS idx_scopes_value    ON memory_scopes(value);\nCREATE INDEX IF NOT EXISTS idx_evidence_memory ON evidence(memory_id);\n\n-- Passive capture: every MCP memory_search is logged locally. Zero-hit\n-- queries are coverage gaps \u2014 things agents needed but memory couldn't answer.\n-- Surfaced via `dim gaps` and the session briefing; never synced.\nCREATE TABLE IF NOT EXISTS search_log (\n  id           TEXT PRIMARY KEY,\n  query        TEXT NOT NULL,\n  paths        TEXT NOT NULL DEFAULT '[]',   -- JSON string[] (scope filter, if any)\n  result_count INTEGER NOT NULL,\n  source       TEXT NOT NULL DEFAULT 'mcp',  -- 'mcp' | 'cli'\n  created_at   TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS idx_search_log_created ON search_log(created_at);\nCREATE INDEX IF NOT EXISTS idx_search_log_hits ON search_log(result_count, created_at);\n\n-- SaaS groundwork: local append-only event log (CLOUD_DESIGN sync model).\n-- Every memory-lifecycle change is recorded here and shipped to the sync\n-- server on `dim sync`; the server aggregates evidence_result events from\n-- multiple machines into consensus confidence.\nCREATE TABLE IF NOT EXISTS events (\n  seq            INTEGER PRIMARY KEY AUTOINCREMENT,\n  id             TEXT NOT NULL UNIQUE,          -- uuid (idempotent server ingest)\n  type           TEXT NOT NULL CHECK (type IN (\n                   'memory_created','status_changed','evidence_result',\n                   'refuted','superseded','forgotten',\n                   'proposal_created','proposal_approved','proposal_rejected',\n                   'verification_report')),\n  memory_id      TEXT,                          -- subject memory/proposal id\n  payload        TEXT NOT NULL DEFAULT '{}',    -- JSON event body\n  machine        TEXT NOT NULL,                 -- stable per-machine id\n  schema_version INTEGER NOT NULL,\n  created_at     TEXT NOT NULL,\n  synced         INTEGER NOT NULL DEFAULT 0     -- 1 once pushed to the server\n);\nCREATE INDEX IF NOT EXISTS idx_events_synced ON events(synced, seq);\n";

package/dist/db/schema.js

@@ -0,0 +1,269 @@
+/**
+ * SQLite schema for aidimag. Lives in <repo>/.aidimag/memory.db
+ * FTS5 powers Phase 1 search; sqlite-vec embeddings arrive in Phase 2.
+ */
+export const SCHEMA_VERSION = 9;
+/** Idempotent migrations for pre-existing DBs (failures = already applied). */
+export const MIGRATIONS = [
+    "ALTER TABLE memories ADD COLUMN updated_at TEXT",
+    "ALTER TABLE proposals ADD COLUMN updated_at TEXT",
+    // T1 tickets: ticket id extracted from branch/commit message (offline)
+    "ALTER TABLE proposals ADD COLUMN ticket_ref TEXT",
+    // v7: pinned memories — exempt from time decay, still falsifiable by evidence
+    "ALTER TABLE memories ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0",
+    // v8: GUARDRAIL enforcement level (always | ask-first | never). The new kind
+    // values themselves need a CHECK rebuild (MEMORIES_REBUILD_V8), but the
+    // column adds cleanly on old DBs.
+    "ALTER TABLE memories ADD COLUMN guardrail_level TEXT",
+    "ALTER TABLE proposals ADD COLUMN guardrail_level TEXT",
+];
+/**
+ * v6 guarded migration: SQLite can't ALTER a CHECK constraint, so adding the
+ * TICKET_REF evidence type requires rebuilding the evidence table. Runs once,
+ * gated on the stored schema_version (store.ts).
+ */
+export const EVIDENCE_REBUILD_V6 = `
+ALTER TABLE evidence RENAME TO evidence_v5;
+CREATE TABLE evidence (
+  id        TEXT PRIMARY KEY,
+  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  type      TEXT NOT NULL CHECK (type IN (
+              'COMMIT_REF','TEST_RESULT','EXEC_TRACE','STATIC_CHECK','HUMAN_ATTESTED','TICKET_REF')),
+  payload   TEXT NOT NULL,
+  last_run  TEXT,
+  result    TEXT NOT NULL DEFAULT 'UNKNOWN' CHECK (result IN ('PASS','FAIL','UNKNOWN'))
+);
+INSERT INTO evidence SELECT * FROM evidence_v5;
+DROP TABLE evidence_v5;
+CREATE INDEX IF NOT EXISTS idx_evidence_memory ON evidence(memory_id);
+`;
+/**
+ * v8 guarded rebuild: SQLite can't ALTER a CHECK constraint, so adding the
+ * GUARDRAIL + SKILL memory kinds requires rebuilding the memories and proposals
+ * tables. Rowids are preserved (FTS is a contentless mirror keyed on rowid) and
+ * the FTS index is rebuilt afterwards. Runs once, gated on the stored
+ * schema_version (store.ts), with foreign_keys disabled around it.
+ */
+export const MEMORIES_REBUILD_V8 = `
+CREATE TABLE memories_v8 (
+  id            TEXT PRIMARY KEY,
+  kind          TEXT NOT NULL CHECK (kind IN (
+                  'DECISION','CONVENTION','GOTCHA','FAILED_APPROACH',
+                  'ARCHITECTURE','INVARIANT','TODO_CONTEXT','GUARDRAIL','SKILL')),
+  claim         TEXT NOT NULL,
+  confidence    REAL NOT NULL DEFAULT 0.5,
+  status        TEXT NOT NULL DEFAULT 'UNVERIFIED' CHECK (status IN (
+                  'VERIFIED','UNVERIFIED','STALE','REFUTED')),
+  created_by    TEXT NOT NULL DEFAULT 'human',
+  created_at    TEXT NOT NULL,
+  verified_at   TEXT,
+  superseded_by TEXT REFERENCES memories(id),
+  updated_at    TEXT,
+  pinned        INTEGER NOT NULL DEFAULT 0,
+  guardrail_level TEXT CHECK (guardrail_level IN ('always','ask-first','never'))
+);
+INSERT INTO memories_v8 (rowid, id, kind, claim, confidence, status, created_by,
+                         created_at, verified_at, superseded_by, updated_at, pinned, guardrail_level)
+  SELECT rowid, id, kind, claim, confidence, status, created_by,
+         created_at, verified_at, superseded_by, updated_at, pinned, guardrail_level FROM memories;
+DROP TABLE memories;
+ALTER TABLE memories_v8 RENAME TO memories;
+INSERT INTO memories_fts(memories_fts) VALUES('rebuild');
+`;
+export const PROPOSALS_REBUILD_V8 = `
+CREATE TABLE proposals_v8 (
+  id         TEXT PRIMARY KEY,
+  kind       TEXT NOT NULL CHECK (kind IN (
+               'DECISION','CONVENTION','GOTCHA','FAILED_APPROACH',
+               'ARCHITECTURE','INVARIANT','TODO_CONTEXT','GUARDRAIL','SKILL')),
+  claim      TEXT NOT NULL,
+  paths      TEXT NOT NULL DEFAULT '[]',
+  symbols    TEXT NOT NULL DEFAULT '[]',
+  evidence   TEXT NOT NULL DEFAULT '[]',
+  source     TEXT NOT NULL,
+  source_ref TEXT,
+  rationale  TEXT,
+  created_at TEXT NOT NULL,
+  status     TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','APPROVED','REJECTED')),
+  memory_id  TEXT REFERENCES memories(id) ON DELETE SET NULL,
+  updated_at TEXT,
+  ticket_ref TEXT,
+  guardrail_level TEXT CHECK (guardrail_level IN ('always','ask-first','never'))
+);
+INSERT INTO proposals_v8 (id, kind, claim, paths, symbols, evidence, source, source_ref,
+                          rationale, created_at, status, memory_id, updated_at, ticket_ref, guardrail_level)
+  SELECT id, kind, claim, paths, symbols, evidence, source, source_ref,
+         rationale, created_at, status, memory_id, updated_at, ticket_ref, guardrail_level FROM proposals;
+DROP TABLE proposals;
+ALTER TABLE proposals_v8 RENAME TO proposals;
+`;
+/**
+ * v9 guarded rebuild: Add new event types (updated, evidence_added, evidence_removed)
+ * to the events table CHECK constraint. SQLite can't ALTER a CHECK constraint.
+ */
+export const EVENTS_REBUILD_V9 = `
+ALTER TABLE events RENAME TO events_v8;
+CREATE TABLE events (
+  seq            INTEGER PRIMARY KEY AUTOINCREMENT,
+  id             TEXT NOT NULL UNIQUE,
+  type           TEXT NOT NULL CHECK (type IN (
+                   'memory_created','status_changed','evidence_result',
+                   'refuted','superseded','forgotten',
+                   'proposal_created','proposal_approved','proposal_rejected',
+                   'verification_report','updated','evidence_added','evidence_removed')),
+  memory_id      TEXT,
+  payload        TEXT NOT NULL DEFAULT '{}',
+  machine        TEXT NOT NULL,
+  schema_version INTEGER NOT NULL,
+  created_at     TEXT NOT NULL,
+  synced         INTEGER NOT NULL DEFAULT 0
+);
+INSERT INTO events SELECT * FROM events_v8;
+DROP TABLE events_v8;
+CREATE INDEX IF NOT EXISTS idx_events_synced ON events(synced, seq);
+`;
+export const SCHEMA_SQL = `
+PRAGMA journal_mode = WAL;
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS memories (
+  id            TEXT PRIMARY KEY,
+  kind          TEXT NOT NULL CHECK (kind IN (
+                  'DECISION','CONVENTION','GOTCHA','FAILED_APPROACH',
+                  'ARCHITECTURE','INVARIANT','TODO_CONTEXT','GUARDRAIL','SKILL')),
+  claim         TEXT NOT NULL,
+  confidence    REAL NOT NULL DEFAULT 0.5,
+  status        TEXT NOT NULL DEFAULT 'UNVERIFIED' CHECK (status IN (
+                  'VERIFIED','UNVERIFIED','STALE','REFUTED')),
+  created_by    TEXT NOT NULL DEFAULT 'human',
+  created_at    TEXT NOT NULL,
+  verified_at   TEXT,
+  superseded_by TEXT REFERENCES memories(id),
+  updated_at    TEXT,
+  pinned        INTEGER NOT NULL DEFAULT 0,
+  guardrail_level TEXT CHECK (guardrail_level IN ('always','ask-first','never'))
+);
+
+-- scope: one row per path / symbol a memory applies to
+CREATE TABLE IF NOT EXISTS memory_scopes (
+  memory_id  TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  scope_type TEXT NOT NULL CHECK (scope_type IN ('path','symbol')),
+  value      TEXT NOT NULL,
+  PRIMARY KEY (memory_id, scope_type, value)
+);
+
+CREATE TABLE IF NOT EXISTS evidence (
+  id        TEXT PRIMARY KEY,
+  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  type      TEXT NOT NULL CHECK (type IN (
+              'COMMIT_REF','TEST_RESULT','EXEC_TRACE','STATIC_CHECK','HUMAN_ATTESTED','TICKET_REF')),
+  payload   TEXT NOT NULL,
+  last_run  TEXT,
+  result    TEXT NOT NULL DEFAULT 'UNKNOWN' CHECK (result IN ('PASS','FAIL','UNKNOWN'))
+);
+
+CREATE TABLE IF NOT EXISTS memory_links (
+  from_id  TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  to_id    TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  relation TEXT NOT NULL CHECK (relation IN ('supports','contradicts','refines')),
+  PRIMARY KEY (from_id, to_id, relation)
+);
+
+-- Full-text search over claims (Phase 1 retrieval)
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  claim,
+  content='memories',
+  content_rowid='rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, claim) VALUES (new.rowid, new.claim);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, claim) VALUES ('delete', old.rowid, old.claim);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE OF claim ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, claim) VALUES ('delete', old.rowid, old.claim);
+  INSERT INTO memories_fts(rowid, claim) VALUES (new.rowid, new.claim);
+END;
+
+-- Phase 2: capture pipeline — proposed memories awaiting human review
+CREATE TABLE IF NOT EXISTS proposals (
+  id         TEXT PRIMARY KEY,
+  kind       TEXT NOT NULL CHECK (kind IN (
+               'DECISION','CONVENTION','GOTCHA','FAILED_APPROACH',
+               'ARCHITECTURE','INVARIANT','TODO_CONTEXT','GUARDRAIL','SKILL')),
+  claim      TEXT NOT NULL,
+  paths      TEXT NOT NULL DEFAULT '[]',    -- JSON string[]
+  symbols    TEXT NOT NULL DEFAULT '[]',    -- JSON string[]
+  evidence   TEXT NOT NULL DEFAULT '[]',    -- JSON {type,payload}[]
+  source     TEXT NOT NULL,                 -- 'commit-miner' | 'session:<agent-id>' | ...
+  source_ref TEXT,                          -- e.g. commit sha
+  rationale  TEXT,                          -- why the source thinks this is worth remembering
+  created_at TEXT NOT NULL,
+  status     TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','APPROVED','REJECTED')),
+  memory_id  TEXT REFERENCES memories(id) ON DELETE SET NULL,  -- set when approved
+  updated_at TEXT,
+  ticket_ref TEXT,                          -- ticket id (e.g. XXX-2100) when known
+  guardrail_level TEXT                      -- always | ask-first | never (GUARDRAIL proposals)
+);
+
+CREATE INDEX IF NOT EXISTS idx_proposals_status ON proposals(status);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_proposals_dedupe ON proposals(source, source_ref, claim);
+
+-- Phase 6: sync — deletions must propagate, so deletes leave tombstones
+CREATE TABLE IF NOT EXISTS tombstones (
+  id         TEXT NOT NULL,                 -- deleted row id
+  tbl        TEXT NOT NULL CHECK (tbl IN ('memories','proposals')),
+  deleted_at TEXT NOT NULL,
+  PRIMARY KEY (id, tbl)
+);
+
+CREATE INDEX IF NOT EXISTS idx_memories_status ON memories(status);
+CREATE INDEX IF NOT EXISTS idx_memories_kind   ON memories(kind);
+CREATE INDEX IF NOT EXISTS idx_scopes_value    ON memory_scopes(value);
+CREATE INDEX IF NOT EXISTS idx_evidence_memory ON evidence(memory_id);
+
+-- Passive capture: every MCP memory_search is logged locally. Zero-hit
+-- queries are coverage gaps — things agents needed but memory couldn't answer.
+-- Surfaced via \`dim gaps\` and the session briefing; never synced.
+CREATE TABLE IF NOT EXISTS search_log (
+  id           TEXT PRIMARY KEY,
+  query        TEXT NOT NULL,
+  paths        TEXT NOT NULL DEFAULT '[]',   -- JSON string[] (scope filter, if any)
+  result_count INTEGER NOT NULL,
+  source       TEXT NOT NULL DEFAULT 'mcp',  -- 'mcp' | 'cli'
+  created_at   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_search_log_created ON search_log(created_at);
+CREATE INDEX IF NOT EXISTS idx_search_log_hits ON search_log(result_count, created_at);
+
+-- SaaS groundwork: local append-only event log (CLOUD_DESIGN sync model).
+-- Every memory-lifecycle change is recorded here and shipped to the sync
+-- server on \`dim sync\`; the server aggregates evidence_result events from
+-- multiple machines into consensus confidence.
+CREATE TABLE IF NOT EXISTS events (
+  seq            INTEGER PRIMARY KEY AUTOINCREMENT,
+  id             TEXT NOT NULL UNIQUE,          -- uuid (idempotent server ingest)
+  type           TEXT NOT NULL CHECK (type IN (
+                   'memory_created','status_changed','evidence_result',
+                   'refuted','superseded','forgotten',
+                   'proposal_created','proposal_approved','proposal_rejected',
+                   'verification_report')),
+  memory_id      TEXT,                          -- subject memory/proposal id
+  payload        TEXT NOT NULL DEFAULT '{}',    -- JSON event body
+  machine        TEXT NOT NULL,                 -- stable per-machine id
+  schema_version INTEGER NOT NULL,
+  created_at     TEXT NOT NULL,
+  synced         INTEGER NOT NULL DEFAULT 0     -- 1 once pushed to the server
+);
+CREATE INDEX IF NOT EXISTS idx_events_synced ON events(synced, seq);
+`;
+//# sourceMappingURL=schema.js.map

package/dist/db/store.d.ts

@@ -0,0 +1,182 @@
+/**
+ * MemoryStore — all persistence for aidimag.
+ * Local-first: a single SQLite file at <repo>/.aidimag/memory.db
+ */
+import type { Evidence, EvidenceType, GuardrailLevel, MemoryEntry, MemoryKind, MemoryLink, MemorySearchOptions, MemoryStatus, MemoryStatusSummary, MemoryWriteInput, Proposal, ProposalInput, ProposalStatus } from "../types.js";
+export declare const AIDIMAG_DIR = ".aidimag";
+export declare const DB_FILE = "memory.db";
+/** Walk up from `start` looking for an existing .aidimag dir (or .git as repo root). */
+export declare function findRepoRoot(start?: string): string | null;
+export declare function dbPathFor(repoRoot: string): string;
+/**
+ * Stable per-machine id (CLOUD_DESIGN: "3 of 4 machines confirm…").
+ * Persisted once in ~/.aidimag/machine-id; hostname-prefixed for readability.
+ */
+export declare function machineId(): string;
+/** Event types shipped to the sync server (see schema.ts events table). */
+export type MemoryEventType = "memory_created" | "status_changed" | "evidence_result" | "refuted" | "superseded" | "forgotten" | "proposal_created" | "proposal_approved" | "proposal_rejected" | "verification_report" | "updated" | "evidence_added" | "evidence_removed";
+export interface MemoryEvent {
+    seq: number;
+    id: string;
+    type: MemoryEventType;
+    memoryId: string | null;
+    payload: Record<string, unknown>;
+    machine: string;
+    schemaVersion: number;
+    createdAt: string;
+}
+export declare class MemoryStore {
+    private db;
+    readonly dbPath: string;
+    /** true if the sqlite-vec extension loaded (vector search available) */
+    readonly vecAvailable: boolean;
+    private readonly machine;
+    constructor(dbPath: string);
+    /** Open the store for the repo containing `cwd`. Throws if not initialized and create=false. */
+    static open(cwd?: string, opts?: {
+        create?: boolean;
+    }): MemoryStore;
+    /** Append an event to the local log (shipped to the sync server on `dim sync`). */
+    recordEvent(type: MemoryEventType, memoryId: string | null, payload?: Record<string, unknown>): void;
+    /** Events not yet pushed to the sync server, oldest first. */
+    unsyncedEvents(limit?: number): MemoryEvent[];
+    markEventsSynced(seqs: number[]): void;
+    write(input: MemoryWriteInput): MemoryEntry;
+    private static evTrustKey;
+    /** Mark an evidence payload as approved to execute on this machine. */
+    trustEvidencePayload(payload: string): void;
+    isEvidencePayloadTrusted(payload: string): boolean;
+    /** Executable-evidence payloads currently NOT trusted (i.e. arrived via sync). */
+    untrustedEvidence(): Array<{
+        memoryId: string;
+        claim: string;
+        type: string;
+        payload: string;
+    }>;
+    /** Trust every currently-untrusted executable payload (after human inspection). Returns count. */
+    trustAllEvidence(): number;
+    /**
+     * One-time migration: evidence that existed before the trust gate shipped
+     * was locally authored (sync always re-writes through applyRemoteMemory,
+     * which doesn't trust) — grandfather it so `dim verify` keeps working.
+     */
+    private migrateEvidenceTrust;
+    get(id: string): MemoryEntry | null;
+    search(opts: MemorySearchOptions): MemoryEntry[];
+    /** All memories whose scope overlaps the given file paths (plus repo-wide memories). */
+    getForFiles(paths: string[], limit?: number): MemoryEntry[];
+    list(limit?: number): MemoryEntry[];
+    statusSummary(): MemoryStatusSummary;
+    /**
+     * Ensure the vec0 table exists for the given model+dimension.
+     * If the model changed since last index, drops and requires reindex.
+     * Returns false if vector search is unavailable.
+     */
+    ensureVecTable(model: string, dim: number): boolean;
+    upsertEmbedding(memoryId: string, vector: number[]): void;
+    /** Memory ids missing an embedding (for reindex/backfill). */
+    unembeddedIds(): string[];
+    /** KNN over memory embeddings → [memoryId, distance] pairs, nearest first. */
+    knn(queryVector: number[], k?: number): Array<{
+        id: string;
+        distance: number;
+    }>;
+    /** Queue a proposed memory for human review. Returns null if a duplicate already exists. */
+    propose(input: ProposalInput): Proposal | null;
+    getProposal(id: string): Proposal | null;
+    listProposals(status?: ProposalStatus, limit?: number): Proposal[];
+    /**
+     * Approve a proposal: creates the verified memory and removes the proposal row
+     * (tombstoned for team sync). `overrides.claim` lets the reviewer reword before promote.
+     */
+    approveProposal(id: string, overrides?: {
+        claim?: string;
+        pinned?: boolean;
+    }): MemoryEntry;
+    rejectProposal(id: string): Proposal;
+    /** Claims from rejected proposals — used by triage (survives proposal row deletion). */
+    listRejectedClaims(limit?: number): string[];
+    /**
+     * Remove resolved proposals (approved/rejected) and tombstone for sync.
+     * Use after upgrading brains that still carry historical APPROVED rows.
+     */
+    gcResolvedProposals(opts?: {
+        dryRun?: boolean;
+    }): {
+        removed: number;
+    };
+    findProposalByPrefix(idOrPrefix: string): Proposal | null;
+    /**
+     * Record a memory search (MCP or CLI). Zero-hit queries are coverage gaps:
+     * an agent needed knowledge the brain couldn't supply. Local-only, never synced.
+     */
+    logSearch(query: string, paths: string[], resultCount: number, source?: string): void;
+    /**
+     * Zero-hit searches grouped by normalized query — the repo's knowledge gaps,
+     * most-asked first. `sinceDays` bounds the window (default 30).
+     */
+    searchGaps(opts?: {
+        sinceDays?: number;
+        limit?: number;
+    }): Array<{
+        query: string;
+        misses: number;
+        lastAsked: string;
+        paths: string[];
+    }>;
+    /** Clear logged searches (e.g. after the gaps have been addressed). */
+    clearSearchGaps(): number;
+    /** Last mined commit sha (commit-miner cursor), or null. */
+    getMeta(key: string): string | null;
+    setMeta(key: string, value: string): void;
+    private hydrateProposal;
+    setStatus(id: string, status: MemoryStatus): void;
+    setConfidence(id: string, confidence: number): void;
+    /**
+     * Pin/unpin a memory. Pinned memories never decay with time (but evidence
+     * failure still marks them STALE — pinning removes the clock, not the test).
+     */
+    setPinned(id: string, pinned: boolean): void;
+    touchVerified(id: string): void;
+    updateEvidenceResult(evidenceId: string, result: Evidence["result"], lastRun: string): void;
+    refute(id: string, supersededBy?: string): void;
+    forget(id: string): void;
+    /** Delete a proposal row and record a tombstone so team sync drops it on the remote brain. */
+    private discardProposal;
+    link(fromId: string, toId: string, relation: MemoryLink["relation"]): void;
+    update(id: string, updates: {
+        claim?: string;
+        kind?: MemoryKind;
+        guardrailLevel?: GuardrailLevel;
+    }): void;
+    addEvidence(memoryId: string, ev: {
+        type: EvidenceType;
+        payload: string;
+    }): string;
+    removeEvidence(evidenceId: string): void;
+    /** Local changes since `sinceIso` (null = everything), for pushing to a sync server. */
+    changedSince(sinceIso: string | null): {
+        memories: MemoryEntry[];
+        proposals: Proposal[];
+        tombstones: Array<{
+            id: string;
+            tbl: string;
+            deletedAt: string;
+        }>;
+    };
+    /** Per-memory updated_at (for LWW comparisons). */
+    memoryUpdatedAt(id: string): string | null;
+    isTombstoned(id: string, tbl: "memories" | "proposals"): boolean;
+    /** Upsert a remote memory snapshot (caller already did the LWW check). */
+    applyRemoteMemory(m: MemoryEntry & {
+        updatedAt?: string | null;
+    }): void;
+    proposalUpdatedAt(id: string): string | null;
+    applyRemoteProposal(p: Proposal & {
+        updatedAt?: string | null;
+    }): void;
+    /** Apply a remote tombstone: delete locally without creating a new tombstone loop. */
+    applyRemoteTombstone(id: string, tbl: "memories" | "proposals", deletedAt: string): void;
+    close(): void;
+    private hydrate;
+}