openclaw-plugin-memory-engine 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simone Bonizzardi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# Memory Engine TS — OpenClaw Plugin
+
+Native memory engine for OpenClaw: 19 agent tools, event-driven session ingest,
+and a conservative night curator — all in one plugin, no external MCP server.
+
+## Features
+
+- **17 memory tools**: recall (FTS + ranking), working_set (token-budgeted context pack),
+  remember, get_atom, list_atoms, link/search_graph (knowledge graph), contradict,
+  impact, preference_search, error_check/error_log (error memory), stats,
+  session_summary/generate_session_digest
+- **Curator (v3.1)**: `memory_curator_run` — conservative maintenance pass
+  (extractive body_compact, auto-bonds by domain/keyword/pattern, isolated atom
+  classification, promotion and merge candidates). Dry-run by default.
+- **Cognitive status**: `memory_cognitive_status` — graph health metrics + recommendations
+- **Event hooks**: buffers chat messages and periodically (60s, only when changed)
+  ingests `session_msg` atoms and generates/refreshes `session_digest` atoms (7-day TTL)
+
+## Install
+
+```bash
+openclaw plugins install memory-engine-ts
+```
+
+Or from a local package:
+
+```bash
+openclaw plugins install ./openclaw-plugin-memory-engine-ts-3.1.0.tgz
+```
+
+## Configuration
+
+The database path is read from the `MEMORY_DB_PATH` environment variable
+(default `/data/memory.db`). The SQLite database is created with the expected
+schema on first use.
+
+Curator tuning (optional) via plugin config `curator`: max_atoms_per_run,
+compact_min_body_chars, bond_limit_per_atom, stale_after_days and more —
+sensible defaults apply.
+
+## Session hooks
+
+- `message_received` / `agent_end`: buffer chat content per session
+- every 60s: ingest new messages as episodic `session_msg` atoms (7-day TTL)
+  and refresh the session digest atom
+
+## License
+
+MIT

package/dist/curator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Memory Engine TS — Curator port (from Python CognitiveCurator + AutoBondEngine).
+ * Conservative maintenance: dry-run by default, safe reversible actions only.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { Engine } from "./engine.js";
+export declare const DURABLE_TYPES: readonly ["decision", "fact", "note", "preference", "procedure", "project"];
+export interface CuratorConfig {
+    max_atoms_per_run?: number;
+    compact_min_body_chars?: number;
+    compact_max_chars?: number;
+    bond_limit_per_atom?: number;
+    isolated_limit?: number;
+    isolated_min_age_days?: number;
+    isolated_archive_after_days?: number;
+    isolated_high_access_threshold?: number;
+    isolated_high_weight_threshold?: number;
+    stale_after_days?: number;
+    promotion_min_occurrences?: number;
+    domain_cluster_threshold?: number;
+}
+export declare class Curator {
+    private db;
+    private engine;
+    private cfg;
+    constructor(db: DatabaseSync, engine: Engine, config?: CuratorConfig);
+    private q;
+    private q1;
+    private exec;
+    status(): any;
+    private recommendations;
+    run(dryRun?: boolean, autoApply?: boolean, maxAtoms?: number): any;
+    private compactLongAtoms;
+    extractiveCompact(body: string, maxChars?: number): string;
+    private bondPass;
+    private suggestBondsForAtom;
+    private domainCluster;
+    private keywordOverlap;
+    private patternDetection;
+    private tagsToSet;
+    private classifyIsolatedAtoms;
+    private classifyOne;
+    private setIsolatedMeta;
+    private proposePromotions;
+    private candidatePhrases;
+    private proposeMerges;
+    private normTitle;
+}

package/dist/curator.js

@@ -0,0 +1,407 @@
+export const DURABLE_TYPES = ["decision", "fact", "note", "preference", "procedure", "project"];
+const STOP_WORDS = new Set([
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "and", "or", "but",
+    "in", "on", "at", "to", "for", "of", "with", "by", "from", "as", "this", "that",
+    "these", "those", "il", "lo", "la", "i", "gli", "le", "un", "una", "di", "del",
+    "della", "dei", "delle", "dello", "degli", "che", "non", "con", "per", "su",
+    "come", "dove", "questo", "questa", "quello", "quella",
+]);
+const IT_WORD = /[a-z0-9_àèéìòù]+/g;
+export class Curator {
+    db;
+    engine;
+    cfg;
+    constructor(db, engine, config = {}) {
+        this.db = db;
+        this.engine = engine;
+        this.cfg = {
+            max_atoms_per_run: config.max_atoms_per_run ?? 80,
+            compact_min_body_chars: config.compact_min_body_chars ?? 1200,
+            compact_max_chars: config.compact_max_chars ?? 600,
+            bond_limit_per_atom: config.bond_limit_per_atom ?? 2,
+            isolated_limit: config.isolated_limit ?? 40,
+            isolated_min_age_days: config.isolated_min_age_days ?? 7,
+            isolated_archive_after_days: config.isolated_archive_after_days ?? 90,
+            isolated_high_access_threshold: config.isolated_high_access_threshold ?? 3,
+            isolated_high_weight_threshold: config.isolated_high_weight_threshold ?? 0.9,
+            stale_after_days: config.stale_after_days ?? 180,
+            promotion_min_occurrences: config.promotion_min_occurrences ?? 3,
+            domain_cluster_threshold: config.domain_cluster_threshold ?? 0.5,
+        };
+    }
+    q(sql, ...p) { return this.db.prepare(sql).all(...p); }
+    q1(sql, ...p) { return this.db.prepare(sql).get(...p); }
+    exec(sql, ...p) { this.db.prepare(sql).run(...p); }
+    // ─── STATUS ─────────────────────────────────────────────
+    status() {
+        const now = Math.floor(Date.now() / 1000);
+        const ph = DURABLE_TYPES.map(() => "?").join(",");
+        const atomTotal = this.q1("SELECT COUNT(*) n FROM atoms WHERE status='active'").n;
+        const durableTotal = this.q1("SELECT COUNT(*) n FROM atoms WHERE status='active' AND type IN (" + ph + ")", ...DURABLE_TYPES).n;
+        const bondTotal = this.q1("SELECT COUNT(*) n FROM bonds").n;
+        const pending = this.q1("SELECT COUNT(*) n FROM human_questions WHERE status='pending'").n;
+        const answered = this.q1("SELECT COUNT(*) n FROM human_questions WHERE status='answered'").n;
+        const missingCompact = this.q1("SELECT COUNT(*) n FROM atoms WHERE status='active' AND length(COALESCE(body,'')) >= ? AND COALESCE(body_compact,'')=''", this.cfg.compact_min_body_chars).n;
+        const stale = this.q1("SELECT COUNT(*) n FROM atoms WHERE status='active' AND ? - accessed_at > ?", now, this.cfg.stale_after_days * 86400).n;
+        const isolated = this.q1("SELECT COUNT(*) n FROM atoms a LEFT JOIN bonds b ON b.from_id=a.id OR b.to_id=a.id " +
+            "WHERE a.status='active' AND a.type IN (" + ph + ") AND b.from_id IS NULL " +
+            "AND a.domain NOT LIKE 'daily/%' AND a.domain NOT LIKE 'session/%'", ...DURABLE_TYPES).n;
+        const byType = {};
+        for (const r of this.q("SELECT type k, COUNT(*) n FROM atoms WHERE status='active' GROUP BY type ORDER BY n DESC"))
+            byType[r.k] = r.n;
+        const topDomains = this.q("SELECT domain k, COUNT(*) n FROM atoms WHERE status='active' GROUP BY domain ORDER BY n DESC LIMIT 12")
+            .map((r) => ({ domain: r.k, count: r.n }));
+        const density = durableTotal ? Math.round((bondTotal / durableTotal) * 1000) / 1000 : 0;
+        return {
+            atoms_active: atomTotal,
+            durable_atoms: durableTotal,
+            bonds: bondTotal,
+            graph_density_bonds_per_durable_atom: density,
+            isolated_durable_atoms: isolated,
+            pending_questions: pending,
+            answered_questions: answered,
+            long_atoms_missing_compact: missingCompact,
+            stale_atoms: stale,
+            by_type: byType,
+            top_domains: topDomains,
+            recommendations: this.recommendations(isolated, pending, missingCompact, density),
+        };
+    }
+    recommendations(isolated, pending, missingCompact, density) {
+        const recs = [];
+        if (pending)
+            recs.push("Review/dismiss pending human questions before enabling scheduled learning.");
+        if (isolated > 20 || density < 0.8)
+            recs.push("Run curator_run(auto_apply=true) to enrich the graph.");
+        if (missingCompact)
+            recs.push("Generate body_compact for long atoms to speed recall.");
+        if (!recs.length)
+            recs.push("Memory graph looks healthy enough for scheduled curator runs.");
+        return recs;
+    }
+    // ─── RUN ────────────────────────────────────────────────
+    run(dryRun = true, autoApply = false, maxAtoms) {
+        const max = maxAtoms ?? this.cfg.max_atoms_per_run;
+        const report = {
+            dry_run: dryRun,
+            auto_apply: autoApply,
+            started_at: Math.floor(Date.now() / 1000),
+            actions: [],
+        };
+        const apply = !dryRun && autoApply;
+        report.actions.push(...this.compactLongAtoms(apply, max));
+        report.actions.push(this.bondPass(apply, max));
+        report.actions.push(this.classifyIsolatedAtoms(apply, max));
+        report.actions.push(...this.proposePromotions(max));
+        report.actions.push(...this.proposeMerges(max));
+        report.actions.push({ kind: "learning", status: "skipped", reason: "learning checks not ported to TS plugin yet" });
+        report.finished_at = Math.floor(Date.now() / 1000);
+        report.status_after = this.status();
+        return report;
+    }
+    // ─── COMPACT ────────────────────────────────────────────
+    compactLongAtoms(apply, maxAtoms) {
+        const rows = this.q("SELECT * FROM atoms WHERE status='active' AND length(COALESCE(body,'')) >= ? " +
+            "AND COALESCE(body_compact,'')='' ORDER BY weight DESC, access_count DESC LIMIT ?", this.cfg.compact_min_body_chars, maxAtoms);
+        const actions = [];
+        for (const atom of rows) {
+            const compact = this.extractiveCompact(String(atom.body || ""));
+            const action = {
+                kind: "compact", atom_id: atom.id, title: atom.title,
+                chars_before: String(atom.body || "").length, body_compact: compact, applied: false,
+            };
+            if (apply && compact) {
+                this.exec("UPDATE atoms SET body_compact=?, updated_at=unixepoch() WHERE id=?", compact, atom.id);
+                action.applied = true;
+            }
+            actions.push(action);
+        }
+        return actions;
+    }
+    extractiveCompact(body, maxChars) {
+        const max = maxChars ?? this.cfg.compact_max_chars;
+        const useful = [];
+        for (const raw of body.split("\n")) {
+            const ln = raw.trim();
+            if (!ln)
+                continue;
+            if (ln.startsWith("#") || ln.startsWith("-") || ln.startsWith("*") || ln.includes(":") || ln.length > 60) {
+                useful.push(ln.replace(/\s+/g, " "));
+            }
+            if (useful.join("\n").length >= max)
+                break;
+        }
+        if (!useful.length)
+            useful.push(body.slice(0, max).replace(/\s+/g, " ").trim());
+        return useful.join("\n").slice(0, max).replace(/\s+$/, "");
+    }
+    // ─── BOND PASS (AutoBondEngine port, skip semantic) ──────
+    bondPass(apply, maxAtoms) {
+        const atoms = this.q("SELECT * FROM atoms WHERE status='active' ORDER BY weight DESC, access_count DESC LIMIT ?", maxAtoms);
+        const seen = new Set();
+        const all = [];
+        let applied = 0;
+        for (const atom of atoms) {
+            const sug = this.suggestBondsForAtom(atom, seen);
+            const top = sug.slice(0, this.cfg.bond_limit_per_atom);
+            for (const s of top) {
+                all.push(s);
+                if (apply) {
+                    this.exec("INSERT OR IGNORE INTO bonds (from_id, to_id, relation, strength, evidence, created_at) VALUES (?,?,?,?,?,unixepoch())", s.from_id, s.to_id, s.relation, s.confidence, JSON.stringify({ strategy: s.strategy, reason: s.reason }));
+                    applied++;
+                }
+            }
+        }
+        return {
+            kind: "bond_pass", applied: apply, atoms_scanned: atoms.length,
+            suggestions: all.length, bonds_applied: applied,
+            top_suggestions: all.sort((a, b) => b.confidence - a.confidence).slice(0, 20)
+                .map(s => ({ from: s.from_id, to: s.to_id, relation: s.relation, confidence: s.confidence, reason: s.reason.slice(0, 80) })),
+        };
+    }
+    suggestBondsForAtom(atom, seen) {
+        return [
+            ...this.domainCluster(atom, seen),
+            ...this.keywordOverlap(atom, seen),
+            ...this.patternDetection(atom, seen),
+        ];
+    }
+    domainCluster(atom, seen) {
+        const domain = String(atom.domain || "general");
+        if (domain === "general" || domain === "session")
+            return [];
+        const siblings = this.q("SELECT * FROM atoms WHERE domain=? AND status='active' ORDER BY weight DESC LIMIT 50", domain);
+        const out = [];
+        const atomTags = this.tagsToSet(atom.tags);
+        for (const sib of siblings) {
+            if (sib.id === atom.id)
+                continue;
+            const key = atom.id + "|" + sib.id + "|related_to";
+            if (seen.has(key) || seen.has(sib.id + "|" + atom.id + "|related_to"))
+                continue;
+            const sibTags = this.tagsToSet(sib.tags);
+            let overlap = 0.3;
+            const union = new Set([...atomTags, ...sibTags]);
+            if (union.size) {
+                let inter = 0;
+                for (const t of atomTags)
+                    if (sibTags.has(t))
+                        inter++;
+                overlap = inter / union.size;
+            }
+            const conf = 0.3 + overlap * 0.3;
+            if (conf >= this.cfg.domain_cluster_threshold - 0.1) {
+                out.push({ from_id: atom.id, to_id: sib.id, relation: "related_to",
+                    confidence: Math.round(conf * 1000) / 1000,
+                    reason: "Same domain '" + domain + "', tag overlap " + Math.round(overlap * 100) + "%",
+                    strategy: "domain_cluster" });
+                seen.add(key);
+            }
+        }
+        return out;
+    }
+    keywordOverlap(atom, seen) {
+        const words = (String(atom.title || "").toLowerCase().match(IT_WORD) || [])
+            .filter(w => w.length > 2 && !STOP_WORDS.has(w));
+        if (!words.length)
+            return [];
+        const titleWords = new Set(words);
+        let ftsResults = [];
+        try {
+            ftsResults = this.engine.searchFts(words.join(" "), 15, ["active"]);
+        }
+        catch { /* fts optional */ }
+        const out = [];
+        for (const r of ftsResults) {
+            if (r.id === atom.id)
+                continue;
+            const key = atom.id + "|" + r.id + "|related_to";
+            if (seen.has(key))
+                continue;
+            const rWords = new Set((String(r.title || "").toLowerCase().match(IT_WORD) || []).filter(w => w.length > 2));
+            let overlap = 0;
+            for (const w of titleWords)
+                if (rWords.has(w))
+                    overlap++;
+            if (overlap >= 2) {
+                out.push({ from_id: atom.id, to_id: r.id, relation: "related_to",
+                    confidence: Math.min(0.8, 0.3 + overlap * 0.15),
+                    reason: "Title keyword overlap: " + overlap + " words", strategy: "keyword_overlap" });
+                seen.add(key);
+            }
+        }
+        return out;
+    }
+    patternDetection(atom, seen) {
+        const atomId = String(atom.id);
+        const parts = atomId.split("_");
+        if (parts.length < 2)
+            return [];
+        const out = [];
+        for (const prefixLen of [Math.min(3, parts.length - 1), 2]) {
+            if (prefixLen < 2)
+                break;
+            const prefix = parts.slice(0, prefixLen).join("_");
+            const rows = this.q("SELECT id FROM atoms WHERE id LIKE ? AND id != ? AND status='active' LIMIT 20", prefix + "%", atomId);
+            for (const r of rows) {
+                const isParent = /workspace|overview|setup|status/.test(atomId.toLowerCase());
+                const relation = isParent ? "part_of" : "detail_of";
+                const [fromId, toId] = isParent ? [atomId, r.id] : [r.id, atomId];
+                const key = fromId + "|" + toId + "|" + relation;
+                if (seen.has(key) || seen.has(toId + "|" + fromId + "|" + relation))
+                    continue;
+                out.push({ from_id: fromId, to_id: toId, relation,
+                    confidence: 0.7, reason: "Shared ID prefix '" + prefix + "'", strategy: "pattern_detection" });
+                seen.add(key);
+            }
+            if (out.length)
+                break;
+        }
+        return out;
+    }
+    tagsToSet(tags) {
+        if (Array.isArray(tags))
+            return new Set(tags);
+        if (typeof tags === "string") {
+            try {
+                return new Set(JSON.parse(tags));
+            }
+            catch {
+                return new Set();
+            }
+        }
+        return new Set();
+    }
+    // ─── ISOLATED CLASSIFICATION ────────────────────────────
+    classifyIsolatedAtoms(apply, maxAtoms) {
+        const now = Math.floor(Date.now() / 1000);
+        const limit = Math.min(maxAtoms, this.cfg.isolated_limit);
+        const rows = this.q("SELECT a.* FROM atoms a LEFT JOIN bonds b ON b.from_id=a.id OR b.to_id=a.id " +
+            "WHERE a.status='active' AND b.from_id IS NULL ORDER BY a.weight DESC, a.access_count DESC, a.created_at ASC LIMIT ?", limit * 3);
+        const buckets = { needs_link: [], standalone_ok: [], volatile_candidate: [], archive_candidate: [] };
+        let applied = 0;
+        for (const atom of rows) {
+            const [state, reason] = this.classifyOne(atom, now);
+            buckets[state].push({ id: atom.id, title: atom.title, domain: atom.domain, type: atom.type,
+                weight: atom.weight, access_count: atom.access_count, reason });
+            if (apply) {
+                this.setIsolatedMeta(atom.id, state, reason, now);
+                applied++;
+            }
+            if (Object.values(buckets).reduce((n, v) => n + v.length, 0) >= limit)
+                break;
+        }
+        return {
+            kind: "isolated_classification", applied: apply, updated_atoms: applied,
+            counts: Object.fromEntries(Object.entries(buckets).map(([k, v]) => [k, v.length])),
+            samples: Object.fromEntries(Object.entries(buckets).filter(([, v]) => v.length).map(([k, v]) => [k, v.slice(0, 5)])),
+            policy: "No pending questions created; curator tags meta and suggests links/archive candidates only.",
+        };
+    }
+    classifyOne(atom, now) {
+        const domain = String(atom.domain || "");
+        const type = String(atom.type || "");
+        const createdAt = atom.created_at || now;
+        const accessedAt = atom.accessed_at || createdAt;
+        const accessCount = atom.access_count || 0;
+        const weight = atom.weight || 0;
+        let meta = {};
+        try {
+            meta = JSON.parse(atom.meta || "{}");
+        }
+        catch {
+            meta = {};
+        }
+        if (meta.allow_isolated)
+            return ["standalone_ok", "Human/previous review marked allow_isolated"];
+        if (domain.startsWith("session/") || type === "session_msg")
+            return ["volatile_candidate", "Session/chat atom: let TTL/digest handle it"];
+        if (type === "preference")
+            return ["standalone_ok", "Type 'preference' can be naturally standalone"];
+        if (now - accessedAt > this.cfg.isolated_archive_after_days * 86400 && accessCount === 0)
+            return ["archive_candidate", "Old isolated atom with no access"];
+        if (now - createdAt < this.cfg.isolated_min_age_days * 86400 && accessCount < this.cfg.isolated_high_access_threshold)
+            return ["volatile_candidate", "Too new and not reused yet; observe"];
+        if (weight >= this.cfg.isolated_high_weight_threshold || accessCount >= this.cfg.isolated_high_access_threshold)
+            return ["needs_link", "Durable/high-signal isolated atom; suggest bonds"];
+        return ["standalone_ok", "Low-signal durable atom; keep standalone"];
+    }
+    setIsolatedMeta(atomId, state, reason, now) {
+        const row = this.q1("SELECT meta FROM atoms WHERE id=?", atomId);
+        if (!row)
+            return;
+        let meta = {};
+        try {
+            meta = JSON.parse(row.meta || "{}");
+        }
+        catch {
+            meta = {};
+        }
+        meta.isolated_state = state;
+        meta.isolated_reason = reason;
+        meta.isolated_reviewed_at = now;
+        this.exec("UPDATE atoms SET meta=?, updated_at=? WHERE id=?", JSON.stringify(meta), now, atomId);
+    }
+    // ─── PROMOTIONS / MERGES ────────────────────────────────
+    proposePromotions(maxAtoms) {
+        const rows = this.q("SELECT id, title FROM atoms WHERE status='active' AND (domain LIKE 'session/%' OR domain LIKE 'daily/%') " +
+            "ORDER BY accessed_at DESC LIMIT ?", maxAtoms * 4);
+        const counts = new Map();
+        const examples = new Map();
+        for (const r of rows)
+            for (const phrase of this.candidatePhrases(String(r.title || ""))) {
+                counts.set(phrase, (counts.get(phrase) || 0) + 1);
+                const ex = examples.get(phrase) || [];
+                if (ex.length < 3)
+                    ex.push(r.id);
+                examples.set(phrase, ex);
+            }
+        const actions = [];
+        const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10);
+        for (const [phrase, count] of sorted) {
+            if (count >= this.cfg.promotion_min_occurrences) {
+                actions.push({ kind: "promotion_candidate", phrase, occurrences: count,
+                    example_atom_ids: examples.get(phrase), applied: false,
+                    recommendation: "Create/update a durable fact/procedure if this concept is still useful." });
+            }
+        }
+        return actions;
+    }
+    candidatePhrases(title) {
+        const text = title.toLowerCase().replace(/[[^]]+]/g, " ");
+        const words = (text.match(IT_WORD) || []).filter(w => w.length >= 4 &&
+            !["assistant", "user", "fatto", "questo", "quello", "sono", "come", "della", "degli", "nelle"].includes(w));
+        const phrases = [];
+        for (const n of [2, 3])
+            for (let i = 0; i <= words.length - n; i++)
+                phrases.push(words.slice(i, i + n).join(" "));
+        return phrases.slice(0, 8);
+    }
+    proposeMerges(maxAtoms) {
+        const ph = DURABLE_TYPES.map(() => "?").join(",");
+        const rows = this.q("SELECT id, title, domain, type FROM atoms WHERE status='active' AND type IN (" + ph + ") " +
+            "ORDER BY updated_at DESC LIMIT ?", ...DURABLE_TYPES, maxAtoms * 3);
+        const buckets = new Map();
+        for (const r of rows) {
+            const key = this.normTitle(String(r.title || ""));
+            if (key.length >= 8) {
+                const b = buckets.get(key) || [];
+                b.push(r);
+                buckets.set(key, b);
+            }
+        }
+        const actions = [];
+        for (const [key, atoms] of buckets) {
+            if (atoms.length > 1) {
+                actions.push({ kind: "merge_candidate", normalized_title: key, atoms: atoms.slice(0, 5),
+                    applied: false, recommendation: "Review before merge; curator does not merge automatically." });
+            }
+        }
+        return actions.slice(0, 10);
+    }
+    normTitle(title) {
+        let text = title.toLowerCase().replace(/([^)]*)/g, " ");
+        text = text.replace(/20\d{2}[-_/]?\d{0,2}[-_/]?\d{0,2}/g, " ");
+        return ((text.match(IT_WORD) || []).slice(0, 8)).join(" ");
+    }
+}

package/dist/db.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Memory Engine TS — F1: data layer.
+ * Opens the SAME SQLite database used by the Python Memory Engine.
+ * Parity is the exit criterion: identical counts, identical schema.
+ */
+import { DatabaseSync } from "node:sqlite";
+export interface ParityReport {
+    db_path: string;
+    tables: string[];
+    atoms_total: number;
+    atoms_active: number;
+    atoms_by_status: Record<string, number>;
+    atoms_by_type: Record<string, number>;
+    atoms_by_tier: Record<string, number>;
+    bonds: number;
+    contradictions: number;
+    retrieval_events: number;
+    columns_atoms: string[];
+}
+export declare function openMemoryDb(path: string): DatabaseSync;
+export declare function parityReport(path: string): ParityReport;

package/dist/db.js

@@ -0,0 +1,41 @@
+/**
+ * Memory Engine TS — F1: data layer.
+ * Opens the SAME SQLite database used by the Python Memory Engine.
+ * Parity is the exit criterion: identical counts, identical schema.
+ */
+import { DatabaseSync } from "node:sqlite";
+export function openMemoryDb(path) {
+    return new DatabaseSync(path, { readOnly: true });
+}
+export function parityReport(path) {
+    const db = openMemoryDb(path);
+    const tables = db
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name")
+        .all()
+        .map((r) => r.name);
+    const cols = db
+        .prepare("PRAGMA table_info(atoms)")
+        .all()
+        .map((r) => r.name);
+    const group = (sql) => {
+        const out = {};
+        for (const row of db.prepare(sql).all())
+            out[row.k] = row.n;
+        return out;
+    };
+    const report = {
+        db_path: path,
+        tables,
+        columns_atoms: cols,
+        atoms_total: db.prepare("SELECT COUNT(*) n FROM atoms").get().n,
+        atoms_active: db.prepare("SELECT COUNT(*) n FROM atoms WHERE status = 'active'").get().n,
+        atoms_by_status: group("SELECT status k, COUNT(*) n FROM atoms GROUP BY status"),
+        atoms_by_type: group("SELECT type k, COUNT(*) n FROM atoms GROUP BY type"),
+        atoms_by_tier: group("SELECT memory_tier k, COUNT(*) n FROM atoms GROUP BY memory_tier"),
+        bonds: db.prepare("SELECT COUNT(*) n FROM bonds").get().n,
+        contradictions: db.prepare("SELECT COUNT(*) n FROM memory_contradictions").get().n,
+        retrieval_events: db.prepare("SELECT COUNT(*) n FROM retrieval_events").get().n,
+    };
+    db.close();
+    return report;
+}

package/dist/digest.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Memory Engine TS — F4/F5: session digest generator.
+ * Aligned with session_watcher._upsert_sqlite_digest (2.0 format).
+ */
+import { DatabaseSync } from "node:sqlite";
+export interface DigestDraft {
+    id: string;
+    title: string;
+    body: string;
+}
+export declare function buildSessionDigest(db: DatabaseSync, sessionId: string, meta?: {
+    ocSessionId?: string;
+    generation?: string;
+    segment?: number;
+    sourceKey?: string;
+}): DigestDraft | null;

package/dist/digest.js

@@ -0,0 +1,38 @@
+import { createHash, randomBytes } from "node:crypto";
+export function buildSessionDigest(db, sessionId, meta = {}) {
+    const rows = db
+        .prepare("SELECT body FROM atoms WHERE type = 'session_msg' AND domain = ? AND status = 'active' ORDER BY created_at ASC")
+        .all("session/" + sessionId);
+    if (!rows.length)
+        return null;
+    const messages = [];
+    for (const r of rows) {
+        try {
+            const b = JSON.parse(r.body);
+            messages.push({ role: b.role, content: String(b.content ?? ""), timestamp: b.timestamp });
+        }
+        catch {
+            continue;
+        }
+    }
+    const userMessages = messages.filter((m) => m.role === "user");
+    if (!userMessages.length)
+        return null;
+    let selected = userMessages;
+    if (selected.length > 30)
+        selected = [...selected.slice(0, 15), ...selected.slice(-15)];
+    const userLines = selected.map((m) => "- " + (m.content.length > 200 ? m.content.slice(0, 200) + "..." : m.content));
+    const firstTs = userMessages[0].timestamp ?? "";
+    const lastTs = userMessages[userMessages.length - 1].timestamp ?? "";
+    const body = "Session: " + sessionId + "\n" +
+        "OpenClaw session: " + (meta.ocSessionId ?? sessionId) + "\n" +
+        "Generation: " + (meta.generation ?? "active") + "; segment: " + (meta.segment ?? 0) + "\n" +
+        "Period: " + firstTs + " \u2192 " + lastTs + "\n" +
+        "Messages: " + messages.length + "\n\nUser messages:\n" +
+        userLines.join("\n");
+    const title = "Digest: " + userLines[0].slice(2, 62);
+    const id = meta.sourceKey
+        ? "digest_" + createHash("sha256").update(meta.sourceKey).digest("hex").slice(0, 24)
+        : "digest_" + sessionId.slice(0, 8) + "_" + randomBytes(3).toString("hex");
+    return { id, title, body };
+}

package/dist/embeddings.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Memory Engine TS — embeddings via Ollama (nomic-embed-text).
+ * Reads/writes the same atom_embeddings table used by the Python engine.
+ */
+import { DatabaseSync } from "node:sqlite";
+export declare function embed(text: string): Promise<Float32Array | null>;
+export declare function semanticSearch(db: DatabaseSync, query: string, limit?: number, domain?: string): Promise<Array<{
+    id: string;
+    title: string;
+    domain: string;
+    type: string;
+    semantic_score: number;
+}>>;
+export declare function embedAtom(db: DatabaseSync, atomId: string, text: string): Promise<boolean>;