omo-memory 0.1.10 → 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();
+    }
+}