openclaw-plugin-memory-engine 3.1.0 → 4.0.0

package/dist/entry.js

@@ -6,27 +6,30 @@ import { Type } from "typebox";
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { createTools, VERSION } from "./tools.js";
 import { Curator } from "./curator.js";
+import { buildAdminDefs } from "./admin.js";
+import { buildSemanticDefs } from "./semantic.js";
+import { buildMaintenanceDefs } from "./maintenance.js";
 import { buildSessionDigest } from "./digest.js";
 import { createHash } from "node:crypto";
 /** Il gateway puo' passare un tool-call id (stringa) come primo argomento:
  *  i params stanno in uno degli argomenti successivi, o in un envelope. */
 const PARAM_KEYS = ["query", "title", "content", "id", "session_id", "atom_id", "from_id", "to_id", "relation", "task_description", "task_type", "mistake", "correction", "old_atom_id", "limit", "domain", "type", "confidence", "depth", "strength", "token_budget", "body", "reason"];
 function normalizeParams(a, rest = []) {
+    const merged = {};
     const cands = [a, ...rest].filter((x) => x && typeof x === "object" && !Array.isArray(x));
-    // 1) envelope
     for (const c of cands) {
         for (const k of ["arguments", "input", "params", "args"]) {
             if (c[k] && typeof c[k] === "object" && !Array.isArray(c[k]))
-                return c[k];
+                Object.assign(merged, c[k]);
         }
     }
-    // 2) primo candidato con chiavi param note
     for (const c of cands) {
-        if (PARAM_KEYS.some((k) => k in c))
-            return c;
+        for (const k of Object.keys(c)) {
+            if (!(k in merged))
+                merged[k] = c[k];
+        }
     }
-    // 3) fallback: primo oggetto
-    return cands[0] ?? {};
+    return merged;
 }
 const T = Type;
 /** Wrap nel tool-result shape richiesto dal contract "tools" di OpenClaw. */
@@ -46,7 +49,7 @@ export default definePluginEntry({
         // ── Tools ─────────────────────────────────────────────
         const defs = [
             { name: "memory_version", description: "Memory Engine TS version.", parameters: T.Object({}), execute: () => me.version() },
-            { name: "memory_recall", description: "Smart recall of past memories. Query short and specific.", parameters: T.Object({ query: T.String(), limit: T.Optional(T.Number()), domain: T.Optional(T.String()) }), execute: (a) => me.recall(a.query, a.limit ?? 5, a.domain) },
+            { name: "memory_recall", description: "Smart recall of past memories. Query short and specific. semantic=true merges embedding search.", parameters: T.Object({ query: T.String(), limit: T.Optional(T.Number()), domain: T.Optional(T.String()), semantic: T.Optional(T.Boolean()) }), execute: (a) => me.recall(a.query, a.limit ?? 5, a.domain, a.semantic ?? false) },
             { name: "memory_remember", description: "Save a durable memory (fact, decision, procedure, preference).", parameters: T.Object({ title: T.String(), content: T.String(), type: T.Optional(T.String()), domain: T.Optional(T.String()), confidence: T.Optional(T.Number()) }), execute: (a) => me.remember(a.title, a.content, a.type ?? "fact", a.domain ?? "general", a.confidence ?? 0.8) },
             { name: "memory_working_set", description: "Task context pack with token budget.", parameters: T.Object({ query: T.String(), domain: T.Optional(T.String()), limit: T.Optional(T.Number()), token_budget: T.Optional(T.Number()) }), execute: (a) => me.working_set(a.query, a.domain, a.limit ?? 8, a.token_budget ?? 2000) },
             { name: "memory_get_atom", description: "Full atom by id.", parameters: T.Object({ id: T.String() }), execute: (a) => me.get_atom(a.id) },
@@ -65,6 +68,12 @@ export default definePluginEntry({
             { name: "memory_curator_run", description: "Conservative curation pass: compact, bonds, isolated classification, promotions, merges. dry_run default true.", parameters: T.Object({ dry_run: T.Optional(T.Boolean()), auto_apply: T.Optional(T.Boolean()), max_atoms: T.Optional(T.Number()) }), execute: (a) => curator.run(a.dry_run ?? true, a.auto_apply ?? false, a.max_atoms) },
             { name: "memory_cognitive_status", description: "Cognitive health metrics for the memory graph.", parameters: T.Object({}), execute: () => curator.status() },
         ];
+        for (const d of buildAdminDefs(me.__db))
+            defs.push(d);
+        for (const d of buildSemanticDefs(me.__db, curator))
+            defs.push(d);
+        for (const d of buildMaintenanceDefs(me.__db, dbPath))
+            defs.push(d);
         for (const d of defs) {
             api.registerTool({
                 name: d.name,
@@ -122,7 +131,7 @@ export default definePluginEntry({
                 db.prepare("INSERT OR REPLACE INTO atoms (id, type, memory_tier, domain, title, body, confidence, status, source, weight, tags, meta, created_at, updated_at, accessed_at, ttl) VALUES (?,?,?,?,?,?,0.7,'active','ai',1.0,'[]','{}',?,?,?,?)").run(draft.id, "session_digest", "episodic", "session/" + sid, draft.title, draft.body, now, now, now, now + 7 * 86400);
             }
             flushedCount.set(sid, msgs.length);
-            logger.info?.("[memory-engine-ts] periodic flush session " + sid + " (" + fresh.length + " new msgs, digest " + (draft ? "ok" : "skip") + ")");
+            logger.info?.("[memory-engine] periodic flush session " + sid + " (" + fresh.length + " new msgs, digest " + (draft ? "ok" : "skip") + ")");
         }
         const FLUSH_MS = 60_000;
         const timer = setInterval(() => {
@@ -133,10 +142,10 @@ export default definePluginEntry({
                 }
             }
             catch (err) {
-                logger.warn?.("[memory-engine-ts] periodic flush error: " + String(err));
+                logger.warn?.("[memory-engine] periodic flush error: " + String(err));
             }
         }, FLUSH_MS);
         timer.unref?.();
-        logger.info?.("[memory-engine-ts] v" + VERSION + " registered: 17 tools + periodic ingest/digest (" + (FLUSH_MS / 1000) + "s)");
+        logger.info?.("[memory-engine] v" + VERSION + " registered: " + defs.length + " tools + periodic ingest/digest (" + (FLUSH_MS / 1000) + "s)");
     },
 });

package/dist/index.d.ts

@@ -1 +1,14 @@
-export { default } from "./entry.js";
+declare const _default: Omit<{
+    id: string;
+    name: string;
+    description: string;
+    kind?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["kind"];
+    configSchema?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema | (() => import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema);
+    reload?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["reload"];
+    nodeHostCommands?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["nodeHostCommands"];
+    securityAuditCollectors?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["securityAuditCollectors"];
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+}, "configSchema"> & {
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+};
+export default _default;

package/dist/index.js

@@ -1 +1,13 @@
-export { default } from "./entry.js";
+import { defineFeaturePlugin } from "openclaw/plugin-sdk/feature-plugin";
+import { contract } from "./ui-contract.js";
+import { createFeatureHandlers } from "./ui-feature.js";
+import pluginEntry from "./entry.js";
+export default defineFeaturePlugin({
+    contract,
+    name: "Memory Engine",
+    description: "Native Memory Engine: 45 memory tools, session ingest/digest, curator and Control UI.",
+    setup(api, events) {
+        pluginEntry.register(api);
+        return createFeatureHandlers();
+    },
+});

package/dist/maintenance.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Memory Engine TS — Step 3 (backup/import/export) + Step 4 (learning).
+ * Parity port of Python backup.py + learning.py; no Python residue.
+ */
+import { DatabaseSync } from "node:sqlite";
+export interface MaintToolDef {
+    name: string;
+    description: string;
+    parameters: any;
+    execute: (a: any) => any;
+}
+export declare function buildMaintenanceDefs(db: DatabaseSync, dbPath: string): MaintToolDef[];

package/dist/maintenance.js

@@ -0,0 +1,192 @@
+import { Type } from "typebox";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const T = Type;
+export function buildMaintenanceDefs(db, dbPath) {
+    const q = (sql, ...p) => db.prepare(sql).all(...p);
+    const q1 = (sql, ...p) => db.prepare(sql).get(...p);
+    const x = (sql, ...p) => db.prepare(sql).run(...p);
+    const backupDir = path.join(path.dirname(dbPath), "backups");
+    return [
+        // ── STEP 3: BACKUP ────────────────────────────────
+        {
+            name: "memory_backup_database",
+            description: "Create a SQLite backup (VACUUM INTO) with timestamp. Returns backup path and size.",
+            parameters: T.Object({ label: T.Optional(T.String()) }),
+            execute: (a) => {
+                fs.mkdirSync(backupDir, { recursive: true });
+                const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+                const dest = path.join(backupDir, "memory-backup-" + ts + (a.label ? "-" + a.label : "") + ".db");
+                x("VACUUM INTO ?", dest);
+                const stat = fs.statSync(dest);
+                return { ok: true, path: dest, size_bytes: stat.size };
+            },
+        },
+        {
+            name: "memory_restore_database",
+            description: "Restore from a backup file. DANGEROUS: overwrites current DB. Requires confirm=true.",
+            parameters: T.Object({ backup_path: T.String(), confirm: T.Optional(T.Boolean()) }),
+            execute: (a) => {
+                if (!a.confirm)
+                    return { ok: false, reason: "confirm=true required for restore" };
+                if (!fs.existsSync(a.backup_path))
+                    return { ok: false, reason: "backup file not found" };
+                fs.copyFileSync(a.backup_path, dbPath);
+                return { ok: true, restored_from: a.backup_path, note: "Gateway restart required to reload the DB." };
+            },
+        },
+        {
+            name: "memory_list_backups",
+            description: "List available backup files with sizes and dates.",
+            parameters: T.Object({}),
+            execute: () => {
+                if (!fs.existsSync(backupDir))
+                    return { backups: [] };
+                return {
+                    backups: fs.readdirSync(backupDir).filter((f) => f.endsWith(".db")).map((f) => {
+                        const st = fs.statSync(path.join(backupDir, f));
+                        return { file: f, path: path.join(backupDir, f), size_bytes: st.size, created: st.mtime.toISOString() };
+                    }).sort((a, b) => b.created.localeCompare(a.created)),
+                };
+            },
+        },
+        {
+            name: "memory_export_all",
+            description: "Export all atoms + bonds to a JSON file. Returns file path and counts.",
+            parameters: T.Object({ output_path: T.Optional(T.String()), include_deleted: T.Optional(T.Boolean()) }),
+            execute: (a) => {
+                const status = a.include_deleted ? "all" : "active";
+                const atoms = status === "active" ? q("SELECT * FROM atoms WHERE status='active'") : q("SELECT * FROM atoms");
+                const bonds = q("SELECT * FROM bonds");
+                const data = { exported_at: new Date().toISOString(), version: "3.3.0", atoms, bonds };
+                const out = a.output_path || path.join(path.dirname(dbPath), "memory-export-" + Date.now() + ".json");
+                fs.writeFileSync(out, JSON.stringify(data, null, 2));
+                return { ok: true, path: out, atoms: atoms.length, bonds: bonds.length };
+            },
+        },
+        {
+            name: "memory_export_atom",
+            description: "Export a single atom (with bonds) to JSON. Returns the data.",
+            parameters: T.Object({ atom_id: T.String() }),
+            execute: (a) => {
+                const atom = q1("SELECT * FROM atoms WHERE id=?", a.atom_id);
+                if (!atom)
+                    return { error: "atom not found" };
+                const bonds = q("SELECT * FROM bonds WHERE from_id=? OR to_id=?", a.atom_id, a.atom_id);
+                return { atom, bonds };
+            },
+        },
+        {
+            name: "memory_import_data",
+            description: "Import atoms from a JSON export file (merge mode: skip existing IDs). Returns import counts.",
+            parameters: T.Object({ json_path: T.String() }),
+            execute: (a) => {
+                if (!fs.existsSync(a.json_path))
+                    return { ok: false, reason: "file not found" };
+                const data = JSON.parse(fs.readFileSync(a.json_path, "utf8"));
+                if (!data.atoms)
+                    return { ok: false, reason: "no atoms in file" };
+                let imported = 0, skipped = 0;
+                for (const at of data.atoms) {
+                    const exists = q1("SELECT id FROM atoms WHERE id=?", at.id);
+                    if (exists) {
+                        skipped++;
+                        continue;
+                    }
+                    x("INSERT INTO atoms (id, type, memory_tier, domain, title, body, body_compact, confidence, status, source, weight, tags, meta, created_at, updated_at, accessed_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", at.id, at.type || "fact", at.memory_tier || "semantic", at.domain || "general", at.title || at.id, at.body || "", at.body_compact || "", at.confidence ?? 0.7, at.status || "active", at.source || "import", at.weight ?? 1.0, at.tags || "[]", at.meta || "{}", at.created_at || Math.floor(Date.now() / 1000), Math.floor(Date.now() / 1000), Math.floor(Date.now() / 1000));
+                    imported++;
+                }
+                let bondsAdded = 0;
+                if (data.bonds)
+                    for (const b of data.bonds) {
+                        x("INSERT OR IGNORE INTO bonds (from_id, to_id, relation, strength, evidence, created_at) VALUES (?,?,?,?,?,unixepoch())", b.from_id, b.to_id, b.relation, b.strength ?? 0.5, b.evidence || '{}');
+                        bondsAdded++;
+                    }
+                return { ok: true, atoms_imported: imported, atoms_skipped: skipped, bonds_added: bondsAdded };
+            },
+        },
+        {
+            name: "memory_import_markdown",
+            description: "Import atoms from a markdown file: each heading (##/###) becomes an atom, body is the content.",
+            parameters: T.Object({ md_path: T.String(), domain: T.Optional(T.String()), default_type: T.Optional(T.String()) }),
+            execute: (a) => {
+                if (!fs.existsSync(a.md_path))
+                    return { ok: false, reason: "file not found" };
+                const text = fs.readFileSync(a.md_path, "utf8");
+                const lines = text.split(chr(10));
+                const domain = a.domain || "import/markdown";
+                const defType = a.default_type || "fact";
+                let imported = 0, currentTitle = "", currentBody = [];
+                const flush = () => {
+                    if (!currentTitle)
+                        return;
+                    const id = currentTitle.toLowerCase().replace(/[^a-z0-9_]+/g, "_").slice(0, 50) + "_" + Date.now() + "_" + imported;
+                    x("INSERT INTO atoms (id, type, memory_tier, domain, title, body, confidence, status, source, weight, tags, meta, created_at, updated_at, accessed_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", id, defType, "semantic", domain, currentTitle, currentBody.join(chr(10)).trim(), 0.7, "active", "import:markdown", 1.0, "[]", JSON.stringify({ source_file: a.md_path }), Math.floor(Date.now() / 1000), Math.floor(Date.now() / 1000), Math.floor(Date.now() / 1000));
+                    imported++;
+                };
+                for (const ln of lines) {
+                    const m = ln.match(/^(#{2,3}) (.+)/);
+                    if (m) {
+                        flush();
+                        currentTitle = m[2].trim();
+                        currentBody = [];
+                    }
+                    else if (currentTitle)
+                        currentBody.push(ln);
+                }
+                flush();
+                return { ok: true, atoms_imported: imported, domain };
+            },
+        },
+        // ── STEP 4: LEARNING ──────────────────────────────
+        {
+            name: "memory_learning_run",
+            description: "Run learning checks: stale facts, missing compacts, low-bond durables. Creates human_questions for items needing review.",
+            parameters: T.Object({ dry_run: T.Optional(T.Boolean()) }),
+            execute: (a) => {
+                const now = Math.floor(Date.now() / 1000);
+                const questions = [];
+                // check 1: stale durable atoms (not accessed in 180 days)
+                const stale = q("SELECT id, title FROM atoms WHERE status='active' AND type IN ('fact','decision','procedure') AND ? - accessed_at > ? LIMIT 5", now, 180 * 86400);
+                for (const s of stale)
+                    questions.push({ question_type: "stale_fact", atom_id: s.id, question: "Is '" + s.title.slice(0, 60) + "' still accurate and needed?" });
+                // check 2: isolated durable atoms
+                const isolated = q("SELECT a.id, a.title 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 ('fact','decision','procedure') AND b.from_id IS NULL AND a.domain NOT LIKE 'session/%' AND a.domain NOT LIKE 'daily/%' ORDER BY a.weight DESC LIMIT 5");
+                for (const s of isolated)
+                    questions.push({ question_type: "needs_link", atom_id: s.id, question: "Should '" + s.title.slice(0, 60) + "' be linked to related atoms?" });
+                let created = 0;
+                if (!a.dry_run) {
+                    for (const qq of questions) {
+                        const id = "q_" + qq.question_type + "_" + qq.atom_id.slice(0, 30) + "_" + now;
+                        x("INSERT OR IGNORE INTO human_questions (id, atom_ids, question_type, question, status, created_at) VALUES (?,?,?,?,?,?)", id, JSON.stringify([qq.atom_id]), qq.question_type, qq.question, "pending", now);
+                        created++;
+                    }
+                }
+                return { dry_run: !!a.dry_run, questions_created: created, questions: questions.slice(0, 10) };
+            },
+        },
+        {
+            name: "memory_ask_pending",
+            description: "List pending human questions for review.",
+            parameters: T.Object({ limit: T.Optional(T.Number()) }),
+            execute: (a) => q("SELECT * FROM human_questions WHERE status='pending' ORDER BY created_at DESC LIMIT ?", a.limit ?? 10),
+        },
+        {
+            name: "memory_answer_human",
+            description: "Answer a pending question: resolves it and optionally updates the linked atom status.",
+            parameters: T.Object({ question_id: T.String(), answer: T.String(), action: T.Optional(T.String()) }),
+            execute: (a) => {
+                const row = q1("SELECT * FROM human_questions WHERE id=? AND status='pending'", a.question_id);
+                if (!row)
+                    return { ok: false, reason: "question not found or not pending" };
+                x("UPDATE human_questions SET status='answered', answer=?, answered_at=unixepoch() WHERE id=?", a.answer, a.question_id);
+                if (a.action === "archive_atom" && JSON.parse(row.atom_ids || "[]")[0])
+                    x("UPDATE atoms SET status='archived', updated_at=unixepoch() WHERE id=?", JSON.parse(row.atom_ids || "[]")[0]);
+                if (a.action === "delete_atom" && JSON.parse(row.atom_ids || "[]")[0])
+                    x("UPDATE atoms SET status='deleted', updated_at=unixepoch() WHERE id=?", JSON.parse(row.atom_ids || "[]")[0]);
+                return { ok: true, question_id: a.question_id, answer: a.answer, action: a.action || "resolve_only" };
+            },
+        },
+    ];
+}
+const chr = (c) => String.fromCharCode(c);

package/dist/semantic.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Memory Engine TS — semantic tools (Step 2 parity port).
+ * semantic_search, reindex_embeddings, suggest_bonds(+all) via Ollama embeddings.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { Curator } from "./curator.js";
+export interface SemanticToolDef {
+    name: string;
+    description: string;
+    parameters: any;
+    execute: (a: any) => any;
+}
+export declare function buildSemanticDefs(db: DatabaseSync, curator: Curator): SemanticToolDef[];

package/dist/semantic.js

@@ -0,0 +1,91 @@
+import { Type } from "typebox";
+const T = Type;
+import { semanticSearch, embedAtom, embed } from "./embeddings.js";
+export function buildSemanticDefs(db, curator) {
+    const q = (sql, ...p) => db.prepare(sql).all(...p);
+    const q1 = (sql, ...p) => db.prepare(sql).get(...p);
+    const x = (sql, ...p) => db.prepare(sql).run(...p);
+    return [
+        {
+            name: "memory_semantic_search",
+            description: "Semantic search over atom embeddings (Ollama). Falls back to FTS with a note when embeddings/Ollama are unavailable.",
+            parameters: T.Object({ query: T.String(), limit: T.Optional(T.Number()), domain: T.Optional(T.String()) }),
+            execute: async (a) => {
+                const embedded = q1("SELECT COUNT(*) n FROM atom_embeddings").n;
+                const res = await semanticSearch(db, a.query, a.limit ?? 10, a.domain);
+                if (res.length)
+                    return { mode: "semantic", embeddings_available: embedded, results: res };
+                const fts = q("SELECT id, title, domain FROM atoms_fts JOIN atoms a ON atoms_fts.rowid = a.rowid WHERE atoms_fts MATCH ? AND a.status='active' LIMIT ?", '"' + String(a.query).replace(/[^a-zA-Z0-9 ]/g, " ").trim() + '"', a.limit ?? 10);
+                return { mode: "fts-fallback", note: "ollama non raggiungibile o nessun embedding", embeddings_available: embedded, results: fts };
+            },
+        },
+        {
+            name: "memory_reindex_embeddings",
+            description: "(Re)generate embeddings for active durable atoms missing one. Batch with max_atoms; returns indexed/failed counts.",
+            parameters: T.Object({ max_atoms: T.Optional(T.Number()) }),
+            execute: async (a) => {
+                const probe = await embed("probe");
+                if (!probe)
+                    return { ok: false, reason: "ollama non raggiungibile (OLLAMA_HOST / ME_EMBED_MODEL)" };
+                const rows = q("SELECT id, title, COALESCE(body_compact, body, '') body FROM atoms a WHERE a.status='active' AND a.type IN ('fact','decision','procedure','preference','project','note') AND NOT EXISTS (SELECT 1 FROM atom_embeddings e WHERE e.atom_id = a.id) LIMIT ?", a.max_atoms ?? 100);
+                let indexed = 0, failed = 0;
+                for (const r of rows) {
+                    const ok = await embedAtom(db, r.id, r.title + ". " + String(r.body || "").slice(0, 1500));
+                    if (ok)
+                        indexed++;
+                    else
+                        failed++;
+                }
+                const total = q1("SELECT COUNT(*) n FROM atom_embeddings").n;
+                return { ok: true, indexed, failed, scanned: rows.length, embeddings_total: total };
+            },
+        },
+        {
+            name: "memory_suggest_bonds",
+            description: "Suggest bonds for one atom (domain cluster, keyword overlap, id patterns). auto_apply=false by default.",
+            parameters: T.Object({ atom_id: T.String(), auto_apply: T.Optional(T.Boolean()), limit: T.Optional(T.Number()) }),
+            execute: (a) => {
+                const atom = q1("SELECT * FROM atoms WHERE id=?", a.atom_id);
+                if (!atom)
+                    return { error: "atom not found" };
+                const seen = new Set();
+                const suggestions = curator.suggestBondsForAtom(atom, seen).slice(0, a.limit ?? 5);
+                let applied = 0;
+                if (a.auto_apply) {
+                    for (const s of suggestions) {
+                        x("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 { atom_id: a.atom_id, suggestions: suggestions.length, applied, detail: suggestions };
+            },
+        },
+        {
+            name: "memory_suggest_bonds_all",
+            description: "Bulk bond suggestion across active atoms (fast strategies only). auto_apply=false by default.",
+            parameters: T.Object({ auto_apply: T.Optional(T.Boolean()), max_atoms: T.Optional(T.Number()), limit_per_atom: T.Optional(T.Number()) }),
+            execute: (a) => {
+                const maxAtoms = a.max_atoms ?? 200;
+                const perAtom = a.limit_per_atom ?? 3;
+                const atoms = q("SELECT * FROM atoms WHERE status='active' ORDER BY weight DESC, access_count DESC LIMIT ?", maxAtoms);
+                const seen = new Set();
+                const all = [];
+                let appliedCount = 0;
+                for (const atom of atoms) {
+                    const sug = curator.suggestBondsForAtom(atom, seen).slice(0, perAtom);
+                    for (const s of sug) {
+                        all.push(s);
+                        if (a.auto_apply) {
+                            x("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 }));
+                            appliedCount++;
+                        }
+                    }
+                }
+                return {
+                    atoms_scanned: atoms.length, suggestions: all.length, applied: appliedCount,
+                    top_suggestions: all.sort((p, c) => c.confidence - p.confidence).slice(0, 15).map((s) => ({ from: s.from_id, to: s.to_id, relation: s.relation, confidence: s.confidence, reason: s.reason.slice(0, 80) })),
+                };
+            },
+        },
+    ];
+}

package/dist/tools.d.ts

@@ -4,21 +4,21 @@
  * Python server and are exposed as explicit pointers.
  */
 import { DatabaseSync } from "node:sqlite";
-export declare const VERSION = "3.1.0";
+export declare const VERSION = "4.0.0";
 export declare function createTools(dbPath: string): {
     __db: DatabaseSync;
     version: () => {
         version: string;
         note: string;
     };
-    recall: (query: string, limit?: number, domain?: string) => {
+    recall: (query: string, limit?: number, domain?: string, semantic?: boolean) => Promise<{
         id: any;
         title: any;
         domain: any;
         type: any;
         confidence: any;
         snippet: string;
-    }[];
+    }[]>;
     semantic_search: (query: string, limit?: number, domain?: string) => Promise<{
         id: string;
         title: string;

package/dist/tools.js

@@ -6,7 +6,7 @@
 import { DatabaseSync } from "node:sqlite";
 import { Engine } from "./engine.js";
 import { buildSessionDigest } from "./digest.js";
-export const VERSION = "3.1.0";
+export const VERSION = "4.0.0";
 export function createTools(dbPath) {
     const db = new DatabaseSync(dbPath);
     const engine = new Engine(db, {});
@@ -17,7 +17,20 @@ export function createTools(dbPath) {
     return {
         __db: db,
         version: () => ({ version: VERSION, note: "Native Memory Engine plugin: 19 tools + session ingest/digest + curator." }),
-        recall: (query, limit = 5, domain) => engine.recall(query, limit, { domain: domain ?? undefined, semantic: false }).map(slim),
+        recall: async (query, limit = 5, domain, semantic = false) => {
+            const base = engine.recall(query, limit, { domain: domain ?? undefined, semantic: false });
+            if (!semantic)
+                return base.map(slim);
+            const { semanticSearch } = await import("./embeddings.js");
+            const sem = await semanticSearch(db, query, limit, domain);
+            const seen = new Set(base.map((r) => r.id));
+            const merged = base.map(slim);
+            for (const s of sem) {
+                if (!seen.has(s.id))
+                    merged.push(slim(s));
+            }
+            return merged;
+        },
         semantic_search: async (query, limit = 10, domain) => {
             const { semanticSearch } = await import("./embeddings.js");
             const results = await semanticSearch(db, query, limit, domain);

package/dist/ui-contract.d.ts

@@ -0,0 +1,135 @@
+import { Type } from "typebox";
+export declare const contract: {
+    readonly pluginId: "memory-engine";
+    readonly operations: {
+        readonly status: {
+            readonly kind: "query";
+            readonly description: "Cognitive health metrics for the memory graph.";
+            readonly input: Type.TObject<{}>;
+            readonly output: Type.TObject<{
+                atoms_active: Type.TInteger;
+                durable_atoms: Type.TInteger;
+                bonds: Type.TInteger;
+                isolated: Type.TInteger;
+                pending: Type.TInteger;
+                missing_compact: Type.TInteger;
+                by_type: Type.TRecord<"^.*$", Type.TInteger>;
+                recommendations: Type.TArray<Type.TString>;
+            }>;
+        };
+        readonly search: {
+            readonly kind: "query";
+            readonly description: "FTS search over memory atoms with optional type/domain filters.";
+            readonly input: Type.TObject<{
+                query: Type.TString;
+                limit: Type.TOptional<Type.TInteger>;
+                type: Type.TOptional<Type.TString>;
+                domain: Type.TOptional<Type.TString>;
+            }>;
+            readonly output: Type.TObject<{
+                results: Type.TArray<Type.TObject<{
+                    id: Type.TString;
+                    title: Type.TString;
+                    domain: Type.TOptional<Type.TString>;
+                    type: Type.TOptional<Type.TString>;
+                }>>;
+            }>;
+        };
+        readonly atom: {
+            readonly kind: "query";
+            readonly description: "Full atom detail with bonds.";
+            readonly input: Type.TObject<{
+                id: Type.TString;
+            }>;
+            readonly output: Type.TObject<{}>;
+        };
+        readonly domains: {
+            readonly kind: "query";
+            readonly description: "List distinct domains with atom counts.";
+            readonly input: Type.TObject<{}>;
+            readonly output: Type.TObject<{
+                domains: Type.TArray<Type.TObject<{
+                    domain: Type.TString;
+                    count: Type.TInteger;
+                }>>;
+            }>;
+        };
+        readonly curator_dry: {
+            readonly kind: "action";
+            readonly description: "Run curator in dry-run mode.";
+            readonly input: Type.TObject<{
+                max_atoms: Type.TOptional<Type.TInteger>;
+            }>;
+            readonly output: Type.TObject<{}>;
+        };
+        readonly curator_apply: {
+            readonly kind: "action";
+            readonly description: "Run curator with auto_apply (safe actions only).";
+            readonly input: Type.TObject<{
+                max_atoms: Type.TOptional<Type.TInteger>;
+            }>;
+            readonly output: Type.TObject<{}>;
+        };
+        readonly backups_list: {
+            readonly kind: "query";
+            readonly description: "List available backups.";
+            readonly input: Type.TObject<{}>;
+            readonly output: Type.TObject<{
+                backups: Type.TArray<Type.TObject<{
+                    file: Type.TString;
+                    size_bytes: Type.TInteger;
+                    created: Type.TString;
+                }>>;
+            }>;
+        };
+        readonly backup_now: {
+            readonly kind: "action";
+            readonly description: "Create a database backup now.";
+            readonly input: Type.TObject<{}>;
+            readonly output: Type.TObject<{}>;
+        };
+        readonly questions_list: {
+            readonly kind: "query";
+            readonly description: "List pending human questions.";
+            readonly input: Type.TObject<{
+                limit: Type.TOptional<Type.TInteger>;
+            }>;
+            readonly output: Type.TObject<{
+                questions: Type.TArray<Type.TObject<{
+                    id: Type.TString;
+                    question: Type.TString;
+                    question_type: Type.TOptional<Type.TString>;
+                    status: Type.TString;
+                }>>;
+            }>;
+        };
+        readonly question_answer: {
+            readonly kind: "action";
+            readonly description: "Answer a pending question (resolve, optionally archive atom).";
+            readonly input: Type.TObject<{
+                question_id: Type.TString;
+                answer: Type.TString;
+                action: Type.TOptional<Type.TString>;
+            }>;
+            readonly output: Type.TObject<{}>;
+        };
+        readonly atom_soft_delete: {
+            readonly kind: "action";
+            readonly description: "Soft-delete an atom (status='deleted', reversible).";
+            readonly input: Type.TObject<{
+                id: Type.TString;
+            }>;
+            readonly output: Type.TObject<{}>;
+        };
+        readonly atom_update_domain: {
+            readonly kind: "action";
+            readonly description: "Move an atom to a different domain.";
+            readonly input: Type.TObject<{
+                id: Type.TString;
+                new_domain: Type.TString;
+            }>;
+            readonly output: Type.TObject<{}>;
+        };
+    };
+    readonly events: {};
+};