omo-memory 0.1.11 → 0.1.12

package/README.md

@@ -21,8 +21,14 @@ It gives lazycodex, omo-on-opencode, lfg, and future OMO adapters a shared local
 npm install
 npm run build
 node dist/cli.js init
+node dist/cli.js global scan --root ..
+node dist/cli.js global migrate --root .. --global-db ~/.omo/memory/global.sqlite
 node dist/cli.js session start --host grok --adapter lfg
 node dist/cli.js event record --type decision --summary "Chose SQLite + MCP + CLI for OMO shared memory"
+node dist/cli.js ontology candidates
+node dist/cli.js ontology score
+node dist/cli.js ontology recall --query "sqlite retention"
+node dist/cli.js graph tui
 node dist/cli.js recent
 node dist/cli.js mcp
 ```
@@ -33,8 +39,13 @@ After the package is published to npm, use the same package for CLI and MCP:
 
 ```sh
 npx -y omo-memory init
+npx -y omo-memory global scan --root .
+npx -y omo-memory global migrate --root . --global-db ~/.omo/memory/global.sqlite
 npx -y omo-memory session bootstrap --host codex --adapter lazycodex --limit 5
+npx -y omo-memory ontology recall --query "why did we choose sqlite" --limit 5
+npx -y omo-memory graph tui
 npx -y omo-memory recent --limit 5
+npx -y omo-memory recall --query "why did we choose sqlite" --limit 5
 npx -y omo-memory mcp
 ```
 
@@ -67,7 +78,7 @@ Both hosts use the current project ledger at `<project-root>/.omo/memory/state.s
 
 ## Session bootstrap
 
-Adapters should call the bootstrap tool at the beginning of each host session:
+Adapters may call the bootstrap tool when they need a session id for later writes:
 
 ```json
 {
@@ -80,7 +91,7 @@ Adapters should call the bootstrap tool at the beginning of each host session:
 }
 ```
 
-The response contains a new `sessionId` plus `recentEvents` for the current project. Reuse that `sessionId` when recording follow-up events:
+The response contains a new `sessionId` and project metadata only. It deliberately does not return recent memory, because starting a session should not inject the last session into every user prompt. Reuse that `sessionId` when recording follow-up events:
 
 ```json
 {
@@ -93,7 +104,16 @@ The response contains a new `sessionId` plus `recentEvents` for the current proj
 }
 ```
 
-This is local routing, not transcript scraping. OMO Memory does not automatically read full Codex or Grok transcripts; the host or adapter must call these MCP tools.
+This is local routing, not transcript scraping. OMO Memory does not automatically read full Codex or Grok transcripts. Hooks should record concise user actions, decisions, QA evidence, and handoffs; they should retrieve memory only when the user explicitly asks for OMO Memory or when the current user input can be matched to recorded intent.
+
+Use explicit retrieval for memory reads:
+
+```sh
+omo-memory recent --limit 5
+omo-memory recall --query "schema migration decision" --limit 5
+```
+
+For MCP, use `memory_recent_events` for explicit recent-history requests and `memory_recall_events` for query-gated recall.
 
 ## MCP tools
 
@@ -105,9 +125,69 @@ Initial stdio MCP tools:
 - `memory_bootstrap_session`
 - `memory_record_event`
 - `memory_recent_events`
+- `memory_recall_events`
 - `memory_write_handoff`
 - `memory_export`
 - `memory_purge`
+- `memory_global_scan`
+- `memory_global_migrate`
+- `memory_global_list`
+- `memory_ontology_candidates`
+- `memory_ontology_extract`
+- `memory_ontology_score`
+- `memory_ontology_promote`
+- `memory_ontology_demote`
+- `memory_ontology_supersede`
+- `memory_ontology_recall`
+
+## Second-brain layer
+
+The base ledger remains project-local and chronological: sessions, events, handoffs, and explicit recall. The second-brain layer adds deterministic ontology tables and lifecycle commands:
+
+- Global migration copies existing local `.omo/memory/state.sqlite` databases into one global SQLite store with source provenance and an aggregate OMO schema view. It does not delete or rewrite local project ledgers.
+- Concept extraction turns concise event summaries into vocabulary candidates and reference counts.
+- Retention scoring classifies memory as `forget`, `temporary`, `working`, `durable`, or `permanent`; manual pins force `permanent`.
+- Durable memories can be promoted, demoted, superseded, and recalled through CLI or MCP.
+- `omo-memory graph tui` opens an OpenTUI ontology graph viewer for concepts, relations, retention class, and detail panes. This command needs `bun` on `PATH` because OpenTUI's terminal renderer uses Bun native FFI; the rest of the CLI runs on Node.
+
+Retention classes:
+
+- `forget`: low-value or stale one-off context that can be dropped.
+- `temporary`: short-term context useful during a narrow task.
+- `working`: active project memory worth keeping across the current iteration.
+- `durable`: cross-session knowledge that should survive normal decay.
+- `permanent`: manually pinned or high-score knowledge; only explicit demote, supersede, or purge should change it.
+
+Ontology lifecycle commands:
+
+```sh
+omo-memory ontology candidates
+omo-memory ontology score
+omo-memory ontology promote --concept linaforge --summary "Linaforge is an active game-engine project"
+omo-memory ontology recall --query "linaforge"
+omo-memory ontology demote --id <durable-id>
+omo-memory ontology supersede --id <durable-id> --summary "Updated durable memory"
+```
+
+Global second-brain flow:
+
+```sh
+omo-memory global scan --root /Users/ilseoblee/workspace
+omo-memory global migrate --root /Users/ilseoblee/workspace --global-db ~/.omo/memory/global.sqlite
+OMO_MEMORY_DB=~/.omo/memory/global.sqlite omo-memory ontology candidates
+OMO_MEMORY_DB=~/.omo/memory/global.sqlite omo-memory ontology score
+bun --version
+omo-memory graph tui --db ~/.omo/memory/global.sqlite --query linaforge
+```
+
+OpenTUI graph controls:
+
+- `q`: quit.
+- `Up` / `Down`: move selected concept.
+- `Tab`: move to the next concept.
+- `/` or `f`: focus filter input when supported by the terminal runtime.
+
+The graph is terminal-native. It does not require a browser, web server, cloud service, or embeddings, but it does require Bun for the OpenTUI renderer.
 
 ## Non-goals for MVP
 

package/dist/cli.js

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { applyConceptExtraction } from "./conceptExtraction.js";
+import { migrateToGlobalMemory, scanForMemoryDbs } from "./globalMemory.js";
+import { runGraphTui } from "./graphTui.js";
 import { runMcpServer } from "./mcp.js";
-import { bootstrapSession, doctorReport, exportMemory, purgeMemory, recentEvents, recordEvent, startSession, writeHandoff } from "./memory.js";
+import { bootstrapSession, exportMemory, purgeMemory, recentEvents, recordEvent, startSession, writeHandoff } from "./memory.js";
 import { initMemory } from "./memoryDb.js";
+import { recallEvents } from "./memoryRecall.js";
+import { doctorReport } from "./memoryReport.js";
+import { createDurableMemory, listOntologyRows, recordMemoryReference, supersedeDurableMemory, updateDurableRetention } from "./ontologyCore.js";
+import { defaultDbPath } from "./projectContext.js";
+import { recomputeRetentionScores } from "./retentionRecompute.js";
 async function main(argv) {
     const [command, subcommand, ...rest] = argv;
     if (command === undefined || command === "help" || command === "--help" || command === "-h") {
@@ -13,6 +21,11 @@ async function main(argv) {
         await runMcpServer();
         return;
     }
+    if (command === "graph" && subcommand === "tui") {
+        const query = readFlag(rest, "--query");
+        await runGraphTui({ dbPath: readFlag(rest, "--db") ?? defaultDbPath(), ...(query === undefined ? {} : { query }) });
+        return;
+    }
     const result = runCommand(command, subcommand, rest);
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }
@@ -30,6 +43,12 @@ function runCommand(command, subcommand, rest) {
         const args = [subcommand, ...rest].filter((value) => value !== undefined);
         return { ok: true, ...purgeMemory({ yes: args.includes("--yes") }) };
     }
+    if (command === "global") {
+        return runGlobalCommand(subcommand, rest);
+    }
+    if (command === "ontology") {
+        return runOntologyCommand(subcommand, rest);
+    }
     if (command === "session" && subcommand === "start") {
         const host = parseHost(readFlag(rest, "--host") ?? "unknown");
         const adapter = readFlag(rest, "--adapter") ?? "unknown";
@@ -54,6 +73,11 @@ function runCommand(command, subcommand, rest) {
         const limitRaw = readFlag([subcommand, ...rest].filter((value) => value !== undefined), "--limit");
         return { ok: true, events: recentEvents(parsePositiveInt(limitRaw, "recent --limit")) };
     }
+    if (command === "recall") {
+        const args = [subcommand, ...rest].filter((value) => value !== undefined);
+        const query = readFlag(args, "--query") ?? fail("recall requires --query");
+        return { ok: true, events: recallEvents({ query, limit: readPositiveIntFlag(args, "--limit", 10) }) };
+    }
     if (command === "handoff" && subcommand === "write") {
         const summary = readFlag(rest, "--summary");
         const summaryFile = readFlag(rest, "--summary-file");
@@ -63,6 +87,92 @@ function runCommand(command, subcommand, rest) {
     }
     fail(`unknown command: ${[command, subcommand].filter(Boolean).join(" ")}`);
 }
+function runGlobalCommand(subcommand, rest) {
+    if (subcommand === "scan") {
+        const rootPath = readFlag(rest, "--root") ?? fail("global scan requires --root");
+        return { ok: true, ...scanForMemoryDbs(rootPath) };
+    }
+    if (subcommand === "migrate") {
+        const rootPath = readFlag(rest, "--root") ?? fail("global migrate requires --root");
+        const globalDbPath = readFlag(rest, "--global-db") ?? fail("global migrate requires --global-db");
+        return { ok: true, ...migrateToGlobalMemory({ rootPath, globalDbPath }) };
+    }
+    fail(`unknown command: global ${subcommand ?? ""}`.trim());
+}
+function runOntologyCommand(subcommand, rest) {
+    const dbPath = defaultDbPath();
+    if (subcommand === "candidates")
+        return ontologyCandidates(dbPath);
+    if (subcommand === "score" || subcommand === "recompute") {
+        return { ok: true, ...recomputeRetentionScores({ dbPath, nowIso: new Date().toISOString() }) };
+    }
+    if (subcommand === "promote")
+        return ontologyPromote(dbPath, rest);
+    if (subcommand === "demote") {
+        const id = readFlag(rest, "--id") ?? fail("ontology demote requires --id");
+        return { ok: true, durableMemory: updateDurableRetention(dbPath, exportMemory(dbPath).project, id, { retentionClass: "temporary" }) };
+    }
+    if (subcommand === "supersede") {
+        const id = readFlag(rest, "--id") ?? fail("ontology supersede requires --id");
+        const newSummary = readFlag(rest, "--summary");
+        return { ok: true, ...supersedeDurableMemory(dbPath, exportMemory(dbPath).project, id, newSummary === undefined ? {} : { newSummary }) };
+    }
+    if (subcommand === "recall") {
+        const query = readFlag(rest, "--query") ?? fail("ontology recall requires --query");
+        const limit = readPositiveIntFlag(rest, "--limit", 10);
+        return { ok: true, durableMemories: recallDurableMemories(dbPath, query, limit) };
+    }
+    fail(`unknown command: ontology ${subcommand ?? ""}`.trim());
+}
+function ontologyCandidates(dbPath) {
+    const memory = exportMemory(dbPath);
+    let references = 0;
+    for (const event of memory.events) {
+        references += applyConceptExtraction(dbPath, memory.project, event.id, event.summary, event.type).references.length;
+    }
+    return { ok: true, concepts: listOntologyRows(dbPath, memory.project).concepts, references };
+}
+function ontologyPromote(dbPath, rest) {
+    const memory = exportMemory(dbPath);
+    const conceptSelector = readFlag(rest, "--concept") ?? readFlag(rest, "--concept-id") ?? fail("ontology promote requires --concept");
+    const concept = findConcept(memory.concepts, conceptSelector) ?? fail(`ontology promote candidate not found: ${conceptSelector}`);
+    const summary = readFlag(rest, "--summary") ?? `Durable memory: ${concept.label}`;
+    const body = readFlag(rest, "--body") ?? concept.description ?? concept.label;
+    const durableMemory = createDurableMemory(dbPath, memory.project, {
+        type: "concept",
+        summary,
+        body,
+        confidence: Math.min(1, Math.max(0, concept.score / 100)),
+        status: "active",
+        retentionClass: "durable",
+    });
+    const reference = recordMemoryReference(dbPath, memory.project, {
+        sourceType: "concept",
+        sourceId: concept.id,
+        targetType: "durable_memory",
+        targetId: durableMemory.id,
+        refKind: "promotes",
+        weight: 1,
+    });
+    return { ok: true, concept, durableMemory, reference };
+}
+function findConcept(concepts, selector) {
+    const normalized = selector.trim().toLowerCase();
+    return concepts.find((concept) => concept.id === selector || concept.label.toLowerCase() === normalized);
+}
+function recallDurableMemories(dbPath, query, limit) {
+    const memory = exportMemory(dbPath);
+    const terms = query.toLowerCase().match(/[\p{L}\p{N}_-]{3,}/gu) ?? [];
+    if (terms.length === 0)
+        return [];
+    return listOntologyRows(dbPath, memory.project)
+        .durableMemories.filter((durable) => durable.status === "active")
+        .filter((durable) => {
+        const haystack = `${durable.summary} ${durable.body ?? ""}`.toLowerCase();
+        return terms.some((term) => haystack.includes(term));
+    })
+        .slice(0, limit);
+}
 function readFlag(args, name) {
     const index = args.indexOf(name);
     if (index === -1)
@@ -90,10 +200,10 @@ function fail(message) {
     throw new Error(message);
 }
 function printHelp() {
-    process.stdout.write(`OMO Memory\n\nCommands:\n  omo-memory init\n  omo-memory doctor\n  omo-memory export\n  omo-memory purge --yes\n  omo-memory session start --host <codex|opencode|grok|unknown> --adapter <name>\n  omo-memory session bootstrap --host <codex|opencode|grok|unknown> --adapter <name> [--limit <n>]\n  omo-memory event record --type <type> --summary <text> [--session-id <id>]\n  omo-memory recent [--limit <n>]\n  omo-memory handoff write (--summary <text> | --summary-file <path>) [--session-id <id>]\n  omo-memory mcp\n`);
+    process.stdout.write(`OMO Memory\n\nCommands:\n  omo-memory init\n  omo-memory doctor\n  omo-memory export\n  omo-memory purge --yes\n  omo-memory global scan --root <path> [--json]\n  omo-memory global migrate --root <path> --global-db <path> [--json]\n  omo-memory ontology candidates\n  omo-memory ontology score\n  omo-memory ontology promote --concept <label|id> [--summary <text>] [--body <text>]\n  omo-memory ontology demote --id <durable-id>\n  omo-memory ontology supersede --id <durable-id> [--summary <text>]\n  omo-memory ontology recall --query <text> [--limit <n>]\n  omo-memory session start --host <codex|opencode|grok|unknown> --adapter <name>\n  omo-memory session bootstrap --host <codex|opencode|grok|unknown> --adapter <name> [--limit <n>]\n  omo-memory event record --type <type> --summary <text> [--session-id <id>]\n  omo-memory recent [--limit <n>]\n  omo-memory recall --query <text> [--limit <n>]\n  omo-memory handoff write (--summary <text> | --summary-file <path>) [--session-id <id>]\n  omo-memory graph tui [--db <path>] [--query <text>]  (requires Bun on PATH)\n  omo-memory mcp\n`);
 }
 main(process.argv.slice(2)).catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`${message}\n`);
+    process.stdout.write(`${JSON.stringify({ ok: false, error: message }, null, 2)}\n`);
     process.exitCode = 1;
 });

package/dist/conceptExtraction.js

@@ -0,0 +1,188 @@
+import { recordMemoryReference, upsertConcept } from "./ontologyCore.js";
+import { redactSecrets } from "./privacy.js";
+// Comprehensive generic/hook stopwords. Keep domain terms out.
+const STOPWORDS = new Set([
+    // from recall + hook words
+    "action",
+    "asked",
+    "current",
+    "help",
+    "memory",
+    "need",
+    "needs",
+    "omo",
+    "please",
+    "prompt",
+    "request",
+    "requested",
+    "session",
+    "user",
+    "want",
+    "wants",
+    "work",
+    "working",
+    // common English + dev noise
+    "the",
+    "and",
+    "for",
+    "with",
+    "from",
+    "into",
+    "about",
+    "this",
+    "that",
+    "these",
+    "those",
+    "start",
+    "now",
+    "test",
+    "run",
+    "check",
+    "fix",
+    "add",
+    "change",
+    "update",
+    "get",
+    "set",
+    "make",
+    "create",
+    "delete",
+    "remove",
+    "show",
+    "list",
+    "use",
+    "using",
+    "via",
+    "task",
+    "todo",
+    "step",
+    "item",
+    "thing",
+    "stuff",
+    "new",
+    "old",
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+    "nine",
+    "ten",
+    "please",
+    "thanks",
+    "thank",
+    "also",
+    "just",
+    "only",
+    "like",
+    "such",
+    "very",
+    "really",
+    "should",
+    "could",
+    "would",
+    "will",
+    "can",
+    "may",
+    "must",
+    "have",
+    "has",
+    "had",
+    "been",
+    "being",
+    "are",
+    "was",
+    "were",
+    "is",
+    "be",
+    "to",
+    "of",
+    "in",
+    "on",
+    "at",
+    "by",
+    "as",
+    "it",
+    "its",
+    "if",
+    "or",
+    "and",
+    "but",
+    "not",
+    "no",
+    "yes",
+    "all",
+    "any",
+    "each",
+    "few",
+    "more",
+    "most",
+    "other",
+    "some",
+    "such",
+    "than",
+    "too",
+    "very",
+]);
+function normalizeLabel(raw) {
+    return raw.trim().toLowerCase();
+}
+function tokenize(input) {
+    // Preserve hyphenated compounds (local-first), keep alnum _ -
+    const cleaned = input
+        .toLowerCase()
+        .replace(/[^a-z0-9_\-\s]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!cleaned)
+        return [];
+    return cleaned.split(" ").filter((t) => t.length >= 3);
+}
+export function extractConceptCandidates(summary, _eventType) {
+    if (!summary || typeof summary !== "string")
+        return [];
+    // Never operate on large blobs: caller must pass short summary only.
+    const redacted = redactSecrets(summary);
+    const tokens = tokenize(redacted);
+    const seen = new Set();
+    const out = [];
+    for (const t of tokens) {
+        if (STOPWORDS.has(t))
+            continue;
+        const norm = normalizeLabel(t);
+        if (norm.length < 3)
+            continue;
+        if (seen.has(norm))
+            continue;
+        seen.add(norm);
+        out.push(norm);
+    }
+    return out;
+}
+export function applyConceptExtraction(dbPath, project, sourceEventId, summary, eventType) {
+    const candidates = extractConceptCandidates(summary, eventType);
+    const concepts = [];
+    const references = [];
+    for (const label of candidates) {
+        // upsertConcept will be made idempotent + bump ref_count by label
+        const concept = upsertConcept(dbPath, project, {
+            kind: "term",
+            label,
+            // score/retention left to scorer (Todo 6); default working
+        });
+        concepts.push(concept);
+        const ref = recordMemoryReference(dbPath, project, {
+            sourceType: "event",
+            sourceId: sourceEventId,
+            targetType: "concept",
+            targetId: concept.id,
+            refKind: "mentions",
+            weight: 1,
+        });
+        references.push(ref);
+    }
+    return { concepts, references };
+}

package/dist/globalMemory.js

@@ -0,0 +1,162 @@
+import { mkdirSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import Database from "better-sqlite3";
+import { importCandidates, listGlobalMemoryFromDb } from "./globalMemoryImport.js";
+import { migrate } from "./memoryDb.js";
+import { resolveProjectContext } from "./projectContext.js";
+const STATE_DB_SUFFIX = join(".omo", "memory", "state.sqlite");
+const REQUIRED_TABLES = ["schema_meta", "projects", "events"];
+export function initGlobalMemory(globalDbPath) {
+    mkdirSync(dirname(globalDbPath), { recursive: true });
+    const db = new Database(globalDbPath);
+    try {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS sources (
+        id TEXT PRIMARY KEY,
+        db_path TEXT UNIQUE NOT NULL,
+        schema_version INTEGER NOT NULL,
+        imported_at TEXT NOT NULL,
+        last_seen_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS global_projects (
+        id TEXT PRIMARY KEY,
+        source_id TEXT NOT NULL,
+        source_project_id TEXT NOT NULL,
+        repo_root TEXT NOT NULL,
+        git_remote TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        last_seen_at TEXT NOT NULL,
+        UNIQUE(source_id, source_project_id)
+      );
+      CREATE TABLE IF NOT EXISTS global_sessions (
+        id TEXT PRIMARY KEY,
+        source_id TEXT NOT NULL,
+        source_session_id TEXT NOT NULL,
+        source_project_id TEXT NOT NULL,
+        host TEXT NOT NULL,
+        adapter TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        ended_at TEXT,
+        git_branch TEXT,
+        git_head TEXT,
+        UNIQUE(source_id, source_session_id)
+      );
+      CREATE TABLE IF NOT EXISTS global_events (
+        id TEXT PRIMARY KEY,
+        source_id TEXT NOT NULL,
+        source_event_id TEXT NOT NULL,
+        source_session_id TEXT NOT NULL,
+        source_project_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        summary TEXT NOT NULL,
+        payload_json TEXT,
+        created_at TEXT NOT NULL,
+        UNIQUE(source_id, source_event_id)
+      );
+      CREATE TABLE IF NOT EXISTS global_handoffs (
+        id TEXT PRIMARY KEY,
+        source_id TEXT NOT NULL,
+        source_handoff_id TEXT NOT NULL,
+        source_project_id TEXT NOT NULL,
+        source_session_id TEXT,
+        summary_md TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        UNIQUE(source_id, source_handoff_id)
+      );
+    `);
+        migrate(db);
+        return { dbPath: globalDbPath };
+    }
+    finally {
+        db.close();
+    }
+}
+export function scanForMemoryDbs(rootPath) {
+    const candidates = [];
+    const skipped = [];
+    for (const dbPath of findStateDbs(rootPath)) {
+        const scan = scanSourceDb(dbPath);
+        if (scan.kind === "candidate")
+            candidates.push(scan.candidate);
+        else
+            skipped.push({ dbPath, reason: scan.reason });
+    }
+    return { candidates, skipped };
+}
+export function migrateToGlobalMemory(input) {
+    const scan = scanForMemoryDbs(input.rootPath);
+    initGlobalMemory(input.globalDbPath);
+    return importCandidates(input.globalDbPath, scan, resolveProjectContext());
+}
+export function listGlobalMemory(globalDbPath) {
+    return listGlobalMemoryFromDb(globalDbPath);
+}
+function findStateDbs(rootPath) {
+    const dbPaths = [];
+    const visit = (path) => {
+        let entries;
+        try {
+            entries = readdirSync(path, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error instanceof Error)
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const entryPath = join(path, entry.name);
+            if (entry.isDirectory())
+                visit(entryPath);
+            else if (entry.isFile() && entryPath.endsWith(STATE_DB_SUFFIX))
+                dbPaths.push(entryPath);
+        }
+    };
+    visit(rootPath);
+    return dbPaths.sort();
+}
+function scanSourceDb(dbPath) {
+    let db;
+    try {
+        db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return { kind: "skipped", reason: error.message };
+        throw error;
+    }
+    try {
+        for (const tableName of REQUIRED_TABLES) {
+            if (!tableExists(db, tableName))
+                return { kind: "skipped", reason: `missing table ${tableName}` };
+        }
+        return {
+            kind: "candidate",
+            candidate: { dbPath, schemaVersion: readSchemaVersion(db), projectCount: readCount(db, "projects"), eventCount: readCount(db, "events") },
+        };
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return { kind: "skipped", reason: error.message };
+        throw error;
+    }
+    finally {
+        db.close();
+    }
+}
+function tableExists(db, tableName) {
+    const row = db.prepare("SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name = ?").get(tableName);
+    return row !== undefined && row.count === 1;
+}
+function readSchemaVersion(db) {
+    const row = db
+        .prepare("SELECT value FROM schema_meta WHERE key IN ('schema_version', 'version') ORDER BY CASE key WHEN 'schema_version' THEN 0 ELSE 1 END LIMIT 1")
+        .get();
+    if (row === undefined)
+        return 0;
+    const parsed = Number.parseInt(row.value, 10);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function readCount(db, tableName) {
+    const row = db.prepare(`SELECT COUNT(*) AS count FROM ${tableName}`).get();
+    return row?.count ?? 0;
+}

package/dist/globalMemoryCanonical.js

@@ -0,0 +1,32 @@
+export function upsertAggregateProject(db, project) {
+    const now = new Date().toISOString();
+    db.prepare(`
+    INSERT INTO projects (id, repo_root, git_remote, created_at, last_seen_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET repo_root = excluded.repo_root, git_remote = excluded.git_remote, last_seen_at = excluded.last_seen_at
+  `).run(project.id, project.repoRoot, project.gitRemote, now, now);
+}
+export function upsertCanonicalSession(db, sourceId, aggregateProjectId, row) {
+    db.prepare(`
+    INSERT INTO sessions (id, project_id, host, adapter, started_at, ended_at, git_branch, git_head)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET host = excluded.host, adapter = excluded.adapter, ended_at = excluded.ended_at, git_branch = excluded.git_branch, git_head = excluded.git_head
+  `).run(globalRowId(sourceId, row.id), aggregateProjectId, row.host, row.adapter, row.startedAt, row.endedAt, row.gitBranch, row.gitHead);
+}
+export function upsertCanonicalEvent(db, sourceId, aggregateProjectId, row) {
+    db.prepare(`
+    INSERT INTO events (id, session_id, project_id, type, summary, payload_json, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET session_id = excluded.session_id, type = excluded.type, summary = excluded.summary, payload_json = excluded.payload_json, created_at = excluded.created_at
+  `).run(globalRowId(sourceId, row.id), row.sessionId === null ? null : globalRowId(sourceId, row.sessionId), aggregateProjectId, row.type, row.summary, row.payloadJson, row.createdAt);
+}
+export function upsertCanonicalHandoff(db, sourceId, aggregateProjectId, row) {
+    db.prepare(`
+    INSERT INTO handoffs (id, project_id, session_id, summary_md, created_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET session_id = excluded.session_id, summary_md = excluded.summary_md, created_at = excluded.created_at
+  `).run(globalRowId(sourceId, row.id), aggregateProjectId, row.sessionId === null ? null : globalRowId(sourceId, row.sessionId), row.summaryMd, row.createdAt);
+}
+function globalRowId(sourceId, sourceRowId) {
+    return `${sourceId}:${sourceRowId}`;
+}