omo-memory 0.1.11 → 0.1.12

package/dist/ontologyGraph.js

@@ -0,0 +1,173 @@
+import { migrate, openMemoryDb } from "./memoryDb.js";
+import { redactSecrets, sanitizeGitRemote } from "./privacy.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+function text(value) {
+    return typeof value === "string" ? value : String(value ?? "");
+}
+function nullableText(value) {
+    return value === null || value === undefined ? null : text(value);
+}
+function parseAliases(value) {
+    if (typeof value !== "string")
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((item) => typeof item === "string").map(redactSecrets);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return [];
+        throw error;
+    }
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : Number(value ?? 0);
+}
+function projectFrom(row) {
+    return {
+        id: row.projectId,
+        repoRoot: redactSecrets(row.repoRoot),
+        gitRemote: sanitizeGitRemote(row.gitRemote),
+    };
+}
+function parseConceptRow(value) {
+    if (!isRecord(value)) {
+        throw new Error("invalid concept row");
+    }
+    return {
+        id: text(value["id"]),
+        projectId: text(value["projectId"]),
+        kind: text(value["kind"]),
+        label: text(value["label"]),
+        description: nullableText(value["description"]),
+        aliases: parseAliases(value["aliasesJson"]),
+        score: numberValue(value["score"]),
+        retentionClass: text(value["retentionClass"]),
+        refCount: numberValue(value["refCount"]),
+        projectSpread: numberValue(value["projectSpread"]),
+        firstSeen: nullableText(value["firstSeen"]),
+        lastSeen: nullableText(value["lastSeen"]),
+        repoRoot: text(value["repoRoot"]),
+        gitRemote: nullableText(value["gitRemote"]),
+    };
+}
+function parseRelationRow(value) {
+    if (!isRecord(value)) {
+        throw new Error("invalid relation row");
+    }
+    return {
+        id: text(value["id"]),
+        projectId: text(value["projectId"]),
+        sourceId: text(value["sourceId"]),
+        targetId: text(value["targetId"]),
+        relation: text(value["relation"]),
+        weight: numberValue(value["weight"]),
+        repoRoot: text(value["repoRoot"]),
+        gitRemote: nullableText(value["gitRemote"]),
+    };
+}
+function matchesQuery(row, query) {
+    const haystack = `${row.label}\n${row.description ?? ""}\n${row.aliases.join("\n")}`.toLowerCase();
+    return haystack.includes(query);
+}
+function toNode(row, selectedId) {
+    const score = Math.round(row.score);
+    const retentionClass = redactSecrets(row.retentionClass);
+    return {
+        id: row.id,
+        kind: redactSecrets(row.kind),
+        label: redactSecrets(row.label),
+        description: row.description === null ? null : redactSecrets(row.description),
+        aliases: row.aliases,
+        retentionClass,
+        score,
+        scoreLabel: `${score} ${retentionClass}`,
+        refCount: Math.round(row.refCount),
+        projectSpread: Math.round(row.projectSpread),
+        project: projectFrom(row),
+        selected: selectedId === row.id,
+    };
+}
+function toDetail(row) {
+    const score = Math.round(row.score);
+    const retentionClass = redactSecrets(row.retentionClass);
+    return {
+        id: row.id,
+        label: redactSecrets(row.label),
+        kind: redactSecrets(row.kind),
+        description: row.description === null ? null : redactSecrets(row.description),
+        aliases: row.aliases,
+        retentionClass,
+        score,
+        scoreLabel: `${score} ${retentionClass}`,
+        refCount: Math.round(row.refCount),
+        projectSpread: Math.round(row.projectSpread),
+        firstSeen: row.firstSeen,
+        lastSeen: row.lastSeen,
+        project: projectFrom(row),
+    };
+}
+function toEdge(row) {
+    const weight = Number(row.weight.toFixed(2));
+    const relation = redactSecrets(row.relation);
+    return {
+        id: row.id,
+        sourceId: row.sourceId,
+        targetId: row.targetId,
+        relation,
+        label: `${relation} ${weight.toFixed(2)}`,
+        weight,
+        project: projectFrom(row),
+    };
+}
+export function projectOntologyGraph(options) {
+    const db = openMemoryDb(options.dbPath);
+    try {
+        migrate(db);
+        const query = options.query?.trim().toLowerCase() ?? "";
+        const conceptRows = db
+            .prepare(`
+        SELECT c.id, c.project_id AS projectId, c.kind, c.label, c.description, c.aliases_json AS aliasesJson,
+          COALESCE(c.score, 0) AS score, COALESCE(c.retention_class, 'working') AS retentionClass,
+          COALESCE(c.ref_count, 0) AS refCount, COALESCE(c.project_spread, 1) AS projectSpread,
+          c.first_seen AS firstSeen, c.last_seen AS lastSeen,
+          p.repo_root AS repoRoot, p.git_remote AS gitRemote
+        FROM concepts c
+        JOIN projects p ON p.id = c.project_id
+        WHERE c.valid_to IS NULL
+        ORDER BY lower(c.label) ASC, c.id ASC
+      `)
+            .all()
+            .map(parseConceptRow)
+            .filter((row) => query === "" || matchesQuery(row, query));
+        const conceptIds = new Set(conceptRows.map((row) => row.id));
+        const selectedId = options.selectedId && conceptIds.has(options.selectedId) ? options.selectedId : (conceptRows[0]?.id ?? null);
+        const nodes = conceptRows.map((row) => toNode(row, selectedId));
+        const selectedRow = selectedId === null ? undefined : conceptRows.find((row) => row.id === selectedId);
+        const relationRows = db
+            .prepare(`
+        SELECT r.id, r.project_id AS projectId, r.source_id AS sourceId, r.target_id AS targetId,
+          r.relation, COALESCE(r.weight, 1) AS weight, p.repo_root AS repoRoot, p.git_remote AS gitRemote
+        FROM relations r
+        JOIN projects p ON p.id = r.project_id
+        WHERE r.source_type = 'concept' AND r.target_type = 'concept' AND r.valid_to IS NULL
+        ORDER BY lower(r.relation) ASC, r.id ASC
+      `)
+            .all()
+            .map(parseRelationRow)
+            .filter((row) => conceptIds.has(row.sourceId) && conceptIds.has(row.targetId));
+        return {
+            nodes,
+            edges: relationRows.map(toEdge),
+            detail: selectedRow === undefined ? null : toDetail(selectedRow),
+            message: nodes.length === 0 ? "No ontology graph data is available yet." : null,
+        };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/ontologyQueries.js

@@ -0,0 +1,30 @@
+import { migrate, openMemoryDb } from "./memoryDb.js";
+export function listOntologyRows(dbPath, project) {
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        const concepts = db
+            .prepare(`SELECT id, kind, label, description, aliases_json AS aliasesJson, payload_json AS payloadJson,
+          valid_from AS validFrom, valid_to AS validTo, created_at AS createdAt, updated_at AS updatedAt,
+          COALESCE(score, 0) AS score, COALESCE(retention_class, 'working') AS retentionClass,
+          COALESCE(manual_pin, 0) AS manualPin, COALESCE(ref_count, 0) AS refCount,
+          COALESCE(project_spread, 1) AS projectSpread, first_seen AS firstSeen, last_seen AS lastSeen
+         FROM concepts WHERE project_id = ? ORDER BY created_at ASC, id ASC`)
+            .all(project.id);
+        const durableMemories = db
+            .prepare(`SELECT id, type, summary, body, source_event_id AS sourceEventId, source_handoff_id AS sourceHandoffId,
+          confidence, status, COALESCE(retention_class, 'durable') AS retentionClass,
+          valid_from AS validFrom, valid_to AS validTo, created_at AS createdAt, updated_at AS updatedAt
+         FROM durable_memories WHERE project_id = ? ORDER BY created_at ASC, id ASC`)
+            .all(project.id);
+        const memoryReferences = db
+            .prepare(`SELECT id, source_type AS sourceType, source_id AS sourceId, target_type AS targetType, target_id AS targetId,
+          ref_kind AS refKind, weight, created_at AS createdAt
+         FROM memory_references WHERE project_id = ? ORDER BY created_at ASC, id ASC`)
+            .all(project.id);
+        return { concepts, durableMemories, memoryReferences };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/ontologySupersede.js

@@ -0,0 +1,49 @@
+import { randomUUID } from "node:crypto";
+import { migrate, openMemoryDb } from "./memoryDb.js";
+import { redactSecrets } from "./privacy.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+function parseOriginal(value) {
+    if (!isRecord(value))
+        throw new Error("original durable not found");
+    const id = String(value["id"] ?? "");
+    if (id.length === 0)
+        throw new Error("original durable not found");
+    return {
+        id,
+        type: String(value["type"]),
+        summary: String(value["summary"]),
+        body: value["body"] == null ? null : String(value["body"]),
+        sourceEventId: value["source_event_id"] == null ? null : String(value["source_event_id"]),
+        sourceHandoffId: value["source_handoff_id"] == null ? null : String(value["source_handoff_id"]),
+        confidence: Number(value["confidence"] ?? 0),
+        retentionClass: value["retention_class"] == null ? null : String(value["retention_class"]),
+    };
+}
+export function supersedeDurableMemory(dbPath, project, originalId, opts = {}) {
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        const original = parseOriginal(db
+            .prepare("SELECT id, type, summary, body, source_event_id, source_handoff_id, confidence, retention_class FROM durable_memories WHERE id = ? AND project_id = ?")
+            .get(originalId, project.id));
+        const now = new Date().toISOString();
+        db.prepare("UPDATE durable_memories SET status = 'superseded', valid_to = ?, updated_at = ? WHERE id = ? AND project_id = ?").run(now, now, originalId, project.id);
+        const newId = randomUUID();
+        db.prepare(`
+      INSERT INTO durable_memories (
+        id, project_id, type, summary, body, source_event_id, source_handoff_id,
+        confidence, status, retention_class, valid_from, valid_to, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(newId, project.id, original.type, opts.newSummary ? redactSecrets(opts.newSummary) : redactSecrets(original.summary), original.body == null ? null : redactSecrets(original.body), original.sourceEventId, original.sourceHandoffId, original.confidence, "active", original.retentionClass ?? "durable", null, null, now, now);
+        db.prepare(`
+      INSERT INTO memory_references (id, project_id, source_type, source_id, target_type, target_id, ref_kind, weight, created_at)
+      VALUES (?, ?, 'durable_memory', ?, 'durable_memory', ?, 'supersedes', 1, ?)
+    `).run(randomUUID(), project.id, originalId, newId, now);
+        return { originalId, supersedingId: newId };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/retentionPolicy.js

@@ -0,0 +1,76 @@
+/**
+ * Deterministic retention scoring policy and classification contract.
+ * Pure functions. No ML, no embeddings, no side effects, no DB.
+ * All inputs are explicit evidence signals (frequency, recency, spread, weights, pin, decay, contradictions).
+ */
+export const RETENTION_CLASSES = ["forget", "temporary", "working", "durable", "permanent"];
+/**
+ * Minimum score (inclusive) required to enter each class when not manually pinned.
+ * Classification walks from highest to lowest.
+ */
+export const RETENTION_THRESHOLDS = {
+    forget: 0,
+    temporary: 30,
+    working: 50,
+    durable: 75,
+    permanent: 90,
+};
+/**
+ * Weights and factors for the deterministic linear scoring formula.
+ * Exposed so docs and tests can reference exact terms.
+ */
+export const RETENTION_WEIGHTS = {
+    frequency: 4.5,
+    spread: 7,
+    decision: 12,
+    qa: 10,
+    relation: 4,
+    confidence: 10,
+    recencyBase: 18,
+    recencyPerDay: 0.55,
+    agePerDay: 0.12,
+    ageCap: 22,
+    contradiction: 9,
+};
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+/**
+ * Deterministic retention score in [0, 110] range (rounded).
+ * Terms: frequency, spread, decision/qa importance, relation degree,
+ * confidence, recency bonus, age-based linear decay, contradiction penalty.
+ * Manual pin does NOT change the raw score; it forces "permanent" at classify time.
+ */
+export function computeRetentionScore(input) {
+    const freqPart = input.frequency * RETENTION_WEIGHTS.frequency;
+    const spreadPart = input.spread * RETENTION_WEIGHTS.spread;
+    const decisionPart = input.decisionWeight * RETENTION_WEIGHTS.decision;
+    const qaPart = input.qaWeight * RETENTION_WEIGHTS.qa;
+    const relPart = input.relationDegree * RETENTION_WEIGHTS.relation;
+    const confPart = input.confidence * RETENTION_WEIGHTS.confidence;
+    let score = freqPart + spreadPart + decisionPart + qaPart + relPart + confPart;
+    const recencyBonus = Math.max(0, RETENTION_WEIGHTS.recencyBase - input.recencyDays * RETENTION_WEIGHTS.recencyPerDay);
+    score += recencyBonus;
+    const ageDecay = Math.min(RETENTION_WEIGHTS.ageCap, input.ageDays * RETENTION_WEIGHTS.agePerDay);
+    score -= ageDecay;
+    score -= input.contradictionCount * RETENTION_WEIGHTS.contradiction;
+    return Math.round(clamp(score, 0, 110));
+}
+/**
+ * Classify a (score, manualPin) pair into one of the five retention classes.
+ * Manual pin is a hard override: pinned items are permanent and MUST NOT be
+ * auto-expired by any decay job or age-based rule.
+ */
+export function classifyRetention(score, manualPin) {
+    if (manualPin) {
+        return "permanent";
+    }
+    const s = Math.max(0, Math.round(score));
+    if (s >= RETENTION_THRESHOLDS.permanent)
+        return "permanent";
+    if (s >= RETENTION_THRESHOLDS.durable)
+        return "durable";
+    if (s >= RETENTION_THRESHOLDS.working)
+        return "working";
+    if (s >= RETENTION_THRESHOLDS.temporary)
+        return "temporary";
+    return "forget";
+}

package/dist/retentionRecompute.js

@@ -0,0 +1,175 @@
+import { migrate, openMemoryDb } from "./memoryDb.js";
+import { classifyRetention, computeRetentionScore } from "./retentionPolicy.js";
+function isRecord(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function parsePayload(payloadJson) {
+    try {
+        const parsed = JSON.parse(payloadJson);
+        if (!isRecord(parsed))
+            return {};
+        const confidence = parsed["confidence"];
+        if (typeof confidence === "number" && Number.isFinite(confidence)) {
+            return { confidence: Math.max(0, Math.min(1, confidence)) };
+        }
+        return {};
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return {};
+        throw error;
+    }
+}
+function ageDays(nowIso, seenIso) {
+    if (seenIso == null)
+        return 0;
+    const nowMs = Date.parse(nowIso);
+    const seenMs = Date.parse(seenIso);
+    if (!Number.isFinite(nowMs) || !Number.isFinite(seenMs))
+        return 0;
+    return Math.max(0, Math.floor((nowMs - seenMs) / 86_400_000));
+}
+function loadSignals(db) {
+    const rows = db
+        .prepare(`
+      SELECT
+        c.label AS label,
+        COALESCE(SUM(mr.weight), 0) AS frequency,
+        COUNT(DISTINCT c.project_id) AS projectSpread,
+        MIN(COALESCE(mr.created_at, c.first_seen, c.created_at)) AS firstSeen,
+        MAX(COALESCE(mr.created_at, c.last_seen, c.updated_at)) AS lastSeen,
+        COALESCE(SUM(CASE WHEN e.type IN ('decision', 'decide', 'decision_record') THEN mr.weight ELSE 0 END), 0) AS decisionWeight,
+        COALESCE(SUM(CASE WHEN e.type IN ('qa', 'test', 'verification', 'evidence') THEN mr.weight ELSE 0 END), 0) AS qaWeight,
+        COALESCE(SUM(CASE WHEN e.type IN ('contradiction', 'conflict', 'reversal') THEN 1 ELSE 0 END), 0) AS contradictionCount
+      FROM concepts c
+      LEFT JOIN memory_references mr ON mr.target_type = 'concept' AND mr.target_id = c.id
+      LEFT JOIN events e ON mr.source_type = 'event' AND e.id = mr.source_id
+      GROUP BY c.label
+    `)
+        .all();
+    return new Map(rows.map((row) => [
+        row.label,
+        {
+            frequency: row.frequency,
+            projectSpread: row.projectSpread,
+            firstSeen: row.firstSeen,
+            lastSeen: row.lastSeen,
+            decisionWeight: row.decisionWeight,
+            qaWeight: row.qaWeight,
+            contradictionCount: row.contradictionCount,
+        },
+    ]));
+}
+function loadReferenceCounts(db) {
+    const rows = db
+        .prepare(`
+      SELECT c.id AS conceptId, COUNT(mr.id) AS refCount
+      FROM concepts c
+      LEFT JOIN memory_references mr ON mr.target_type = 'concept' AND mr.target_id = c.id
+      GROUP BY c.id
+    `)
+        .all();
+    return new Map(rows.map((row) => [row.conceptId, row.refCount]));
+}
+function loadRelationDegrees(db) {
+    const rows = db
+        .prepare(`
+      SELECT concept_id AS conceptId, COUNT(DISTINCT relation_id) AS relationDegree
+      FROM (
+        SELECT source_id AS concept_id, id AS relation_id FROM relations WHERE source_type = 'concept'
+        UNION ALL
+        SELECT target_id AS concept_id, id AS relation_id FROM relations WHERE target_type = 'concept'
+      )
+      GROUP BY concept_id
+    `)
+        .all();
+    return new Map(rows.map((row) => [row.conceptId, row.relationDegree]));
+}
+function updateConcept(db, row, update) {
+    if (row.score === update.score &&
+        row.retentionClass === update.retentionClass &&
+        row.refCount === update.refCount &&
+        row.projectSpread === update.projectSpread &&
+        row.firstSeen === update.firstSeen &&
+        row.lastSeen === update.lastSeen) {
+        return false;
+    }
+    db.prepare(`
+    UPDATE concepts
+    SET score = ?, retention_class = ?, ref_count = ?, project_spread = ?,
+      first_seen = ?, last_seen = ?, updated_at = ?
+    WHERE id = ?
+  `).run(update.score, update.retentionClass, update.refCount, update.projectSpread, update.firstSeen, update.lastSeen, update.nowIso, row.id);
+    return true;
+}
+export function recomputeRetentionScores(options) {
+    const db = openMemoryDb(options.dbPath);
+    try {
+        migrate(db);
+        const rows = db
+            .prepare(`
+        SELECT id, label, payload_json AS payloadJson, COALESCE(score, 0) AS score,
+          COALESCE(retention_class, 'working') AS retentionClass, COALESCE(manual_pin, 0) AS manualPin,
+          COALESCE(ref_count, 0) AS refCount, COALESCE(project_spread, 1) AS projectSpread,
+          first_seen AS firstSeen, last_seen AS lastSeen
+        FROM concepts
+        ORDER BY id ASC
+      `)
+            .all();
+        const signals = loadSignals(db);
+        const referenceCounts = loadReferenceCounts(db);
+        const relationDegrees = loadRelationDegrees(db);
+        let updatedConcepts = 0;
+        let skippedPermanentConcepts = 0;
+        const recompute = db.transaction(() => {
+            for (const row of rows) {
+                if (row.manualPin === 1 || row.retentionClass === "permanent") {
+                    skippedPermanentConcepts += 1;
+                    continue;
+                }
+                const signal = signals.get(row.label) ?? {
+                    frequency: row.refCount,
+                    projectSpread: row.projectSpread,
+                    firstSeen: row.firstSeen,
+                    lastSeen: row.lastSeen,
+                    decisionWeight: 0,
+                    qaWeight: 0,
+                    contradictionCount: 0,
+                };
+                const score = computeRetentionScore({
+                    frequency: signal.frequency,
+                    recencyDays: ageDays(options.nowIso, signal.lastSeen),
+                    spread: signal.projectSpread,
+                    decisionWeight: signal.decisionWeight,
+                    qaWeight: signal.qaWeight,
+                    relationDegree: relationDegrees.get(row.id) ?? 0,
+                    confidence: parsePayload(row.payloadJson).confidence ?? 0,
+                    manualPin: false,
+                    ageDays: ageDays(options.nowIso, signal.firstSeen),
+                    contradictionCount: signal.contradictionCount,
+                });
+                const changed = updateConcept(db, row, {
+                    score,
+                    retentionClass: classifyRetention(score, false),
+                    refCount: referenceCounts.get(row.id) ?? row.refCount,
+                    projectSpread: signal.projectSpread,
+                    firstSeen: signal.firstSeen,
+                    lastSeen: signal.lastSeen,
+                    nowIso: options.nowIso,
+                });
+                if (changed)
+                    updatedConcepts += 1;
+            }
+        });
+        recompute();
+        return {
+            scannedConcepts: rows.length,
+            updatedConcepts,
+            skippedPermanentConcepts,
+            nowIso: options.nowIso,
+        };
+    }
+    finally {
+        db.close();
+    }
+}

package/docs/adapter-integration.md

@@ -32,6 +32,7 @@ npx -y omo-memory session bootstrap --host codex --adapter lazycodex --limit 5
 npx -y omo-memory session start --host codex --adapter lazycodex
 npx -y omo-memory session start --host grok --adapter lfg
 npx -y omo-memory recent --limit 10
+npx -y omo-memory recall --query "current roadmap decision" --limit 10
 ```
 
 For a source checkout:
@@ -45,6 +46,7 @@ node dist/cli.js event record --type decision --summary "Use OMO Memory as the s
 node dist/cli.js event record --type qa_evidence --summary "CLI smoke passed for init/session/event/recent."
 node dist/cli.js handoff write --summary "Continue from recent decision and qa_evidence events."
 node dist/cli.js recent --limit 10
+node dist/cli.js recall --query "qa evidence" --limit 10
 node dist/cli.js export
 node dist/cli.js purge --yes
 ```
@@ -85,7 +87,7 @@ Register the same MCP server in every host that needs memory access. Do not crea
 
 ## Session Bootstrap Flow
 
-At the beginning of a Codex, OpenCode, or Grok adapter session, call `memory_bootstrap_session` instead of separately calling `memory_start_session` and `memory_recent_events`.
+At the beginning of a Codex, OpenCode, or Grok adapter session, call `memory_bootstrap_session` only when the adapter needs a session id for subsequent writes. Do not use bootstrap as a prompt-time memory injection hook.
 
 ```json
 {
@@ -102,9 +104,8 @@ The tool returns:
 
 - `sessionId`: the new session row for subsequent event/handoff writes.
 - `project`: the current git/project namespace.
-- `recentEvents`: recent events from the same project namespace.
 
-During the session, write concise task state and evidence with the returned `sessionId`:
+During the session, hooks should write concise user-action summaries, task state, decisions, and evidence with the returned `sessionId`:
 
 ```json
 {
@@ -119,6 +120,13 @@ During the session, write concise task state and evidence with the returned `ses
 
 This package is the local MCP-to-SQLite router. It does not scrape host transcripts or centralize cloud state. Hosts and adapters must call the MCP tools at their own lifecycle points.
 
+Retrieval is opt-in or intent-gated:
+
+- Use `memory_recent_events` only when the user explicitly asks for recent OMO Memory context.
+- Use `memory_recall_events` when the current user input has a concrete query that can be matched to recorded summaries, decisions, or evidence.
+- Do not automatically attach the last session to every user prompt.
+- Do not store raw user prompts by default; record concise, redacted action summaries.
+
 Use these tools:
 
 - `memory_init`
@@ -127,9 +135,56 @@ Use these tools:
 - `memory_start_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`
+
+Global migration is copy/import only. Adapters may scan for existing project-local `.omo/memory/state.sqlite` databases and import them into a user-selected global SQLite file, but they must preserve source DBs and retain source provenance in the global store.
+
+Global migration also materializes an aggregate OMO schema view inside the global SQLite file. This lets existing ontology extraction, retention scoring, recall, and OpenTUI graph code operate on integrated cross-project events while `global_*` tables retain source database provenance.
+
+Example 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
+```
+
+`graph tui` requires `bun` on `PATH` for the OpenTUI terminal renderer. Other CLI and MCP commands run on Node.
+
+Lifecycle commands:
+
+- `memory_ontology_candidates`: derive candidate terms from concise summaries.
+- `memory_ontology_extract`: explicitly extract candidates from one summary/event.
+- `memory_ontology_score`: recompute deterministic scores and retention classes.
+- `memory_ontology_promote`: curate a concept into durable memory.
+- `memory_ontology_demote`: lower a durable memory's retention class.
+- `memory_ontology_supersede`: preserve the old memory and create a replacement.
+- `memory_ontology_recall`: retrieve ontology-backed memories only for an explicit query.
+
+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 UI is local terminal UI. It does not require a browser, web server, cloud account, or vector service.
 
 Example session start:
 
@@ -162,3 +217,58 @@ Example QA evidence:
 - Store sanitized summaries and evidence references instead of full logs.
 - Host-specific values may appear only in small redacted metadata payloads and must not require schema branches.
 - Export and purge are explicit lifecycle commands; purge requires explicit confirmation.
+
+## Ontology Schema Boundary
+
+OMO Memory's chronological ledger remains authoritative: sessions, events, and handoffs record what happened in a project. The ontology schema is an additive layer for durable memory derived from that ledger:
+
+- `concepts` stores vocabulary entries such as project terms, practices, tools, and recurring ideas.
+- `relations` stores typed links between concepts, decisions, events, sessions, and handoffs.
+- `durable_memories` stores approved long-term facts, preferences, and working rules.
+- `decision_records` stores important choices with rationale, evidence, status, reversibility, and provenance.
+
+Adapters must treat ontology rows as curated local memory, not as raw capture. Do not write full transcripts, raw logs, `.env` contents, auth files, cookies, bearer headers, or secret-bearing payloads into ontology tables. User-authored text must pass through the same redaction boundary used by event and handoff writes before it is promoted into durable memory.
+
+The ontology layer is intentionally not a new adapter surface by itself. CLI and MCP commands should continue to call shared core functions, and future concept/decision commands must not create host-specific schemas or side databases.
+
+## Retention Scoring Policy (Deterministic Contract)
+
+Retention classification is strictly deterministic. There is no ML, embeddings, or hidden model. A pure function maps explicit signals to a numeric score and then to one of five classes.
+
+Classes (in ascending durability):
+
+- `forget`: score < 30 (or after decay/contradiction). Safe to drop.
+- `temporary`: 30 <= score < 50. Short-term context only.
+- `working`: 50 <= score < 75. Active task/iteration memory.
+- `durable`: 75 <= score < 90. Cross-session value; survives typical decay.
+- `permanent`: score >= 90, or any manually pinned item. Manual pin is a hard override.
+
+Manual pin rule (critical): an item with `manualPin: true` is always classified `permanent` regardless of raw score, age, or frequency. Decay jobs and age-based expiration MUST NOT remove or downgrade pinned permanent memory; only explicit supersede/demote/purge may change it.
+
+### Score Formula (pure, exposed)
+
+Exported constants (see `src/retentionPolicy.ts`):
+
+- `RETENTION_CLASSES = ["forget", "temporary", "working", "durable", "permanent"] as const`
+- `RETENTION_THRESHOLDS = { forget: 0, temporary: 30, working: 50, durable: 75, permanent: 90 } as const`
+- `RETENTION_WEIGHTS = { frequency: 4.5, spread: 7, decision: 12, qa: 10, relation: 4, confidence: 10, recencyBase: 18, recencyPerDay: 0.55, agePerDay: 0.12, ageCap: 22, contradiction: 9 } as const`
+
+```
+score = clamp(
+  frequency * 4.5
+  + spread * 7
+  + decisionWeight * 12
+  + qaWeight * 10
+  + relationDegree * 4
+  + confidence * 10
+  + max(0, 18 - recencyDays * 0.55)
+  - min(22, ageDays * 0.12)
+  - contradictionCount * 9
+, 0, 110)
+```
+
+`computeRetentionScore(input)` returns the rounded integer. `classifyRetention(score, manualPin)` returns the class, applying the pin override first.
+
+Boundary cases (score, pin=false): 29→forget, 30→temporary, 49→temporary, 50→working, 74→working, 75→durable, 89→durable, 90→permanent. These are verified by the focused contract test.
+
+All scoring inputs are derived from ledger signals (event counts, last-seen deltas, project spread from index, decision/qa event types, explicit relation degree, stored confidence, manual pin flag, contradiction markers). No raw transcripts or secrets are inputs.