openclaw-plugin-memory-engine 4.4.1 → 4.5.1

package/dist/admin.js

@@ -1,3 +1,4 @@
+import { embed } from "./embeddings.js";
 import { Type } from "typebox";
 const T = Type;
 const NL = String.fromCharCode(10);
@@ -133,12 +134,40 @@ export function buildAdminDefs(db) {
         },
         {
             name: "memory_find_similar",
-            description: "Find atoms similar to a reference atom. Uses embeddings when available, FTS title/body overlap otherwise.",
+            description: "Find atoms similar to a reference atom. Semantic via embeddings (cosine) with FTS fallback.",
             parameters: T.Object({ atom_id: T.String(), limit: T.Optional(T.Number()) }),
-            execute: (a) => {
-                const ref = q1("SELECT * FROM atoms WHERE id=?", a.atom_id);
+            execute: async (a) => {
+                const ref = q1("SELECT id, title, COALESCE(body_compact, body, '') body, domain FROM atoms WHERE id=?", a.atom_id);
                 if (!ref)
                     return { error: "atom not found" };
+                // 1) semantica: embedding del riferimento + coseno su atom_embeddings (parita' Python find_similar_atoms)
+                const refEmb = await embed(String(ref.title) + ". " + String(ref.body || "").slice(0, 1500));
+                if (refEmb) {
+                    const rows = db.prepare("SELECT e.atom_id id, e.embedding, a.title, a.status, a.domain FROM atom_embeddings e JOIN atoms a ON a.id = e.atom_id WHERE a.status='active' AND e.atom_id != ?").all(ref.id);
+                    const scored = [];
+                    let skippedCorrupt = 0;
+                    for (const r of rows) {
+                        const buf = Buffer.isBuffer(r.embedding) ? r.embedding : Buffer.from(r.embedding?.buffer ?? r.embedding);
+                        if (!buf || !buf.length || buf.length % 4 !== 0 || buf.length / 4 !== refEmb.length) {
+                            skippedCorrupt++;
+                            continue;
+                        }
+                        const v = new Float32Array(buf.buffer, buf.byteOffset, buf.length / 4);
+                        let dot = 0, na = 0, nb = 0;
+                        for (let i = 0; i < v.length; i++) {
+                            dot += refEmb[i] * v[i];
+                            na += refEmb[i] * refEmb[i];
+                            nb += v[i] * v[i];
+                        }
+                        const cos = na && nb ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : 0;
+                        if (cos > 0.55)
+                            scored.push({ id: r.id, title: r.title, domain: r.domain, score: Math.round(cos * 10000) / 10000 });
+                    }
+                    scored.sort((p2, c) => c.score - p2.score);
+                    if (scored.length)
+                        return { reference: ref.id, mode: "semantic", skipped_corrupt: skippedCorrupt, similar: scored.slice(0, a.limit ?? 5) };
+                }
+                // 2) fallback FTS (ollama down o nessun embedding sopra soglia)
                 const words = String(ref.title || "").toLowerCase().split(/[^a-z0-9_]+/).filter((w) => w.length > 3);
                 const out = [];
                 const seen = new Set([ref.id]);
@@ -157,7 +186,7 @@ export function buildAdminDefs(db) {
                         out.push({ id: h.id, title: h.title, score: h.score });
                     }
                 }
-                return { reference: ref.id, mode: "fts (semantic embeddings: step 2)", similar: out.slice(0, a.limit ?? 5) };
+                return { reference: ref.id, mode: refEmb ? "fts (no embeddings above threshold)" : "fts-fallback (ollama non raggiungibile)", similar: out.slice(0, a.limit ?? 5) };
             },
         },
         {

package/dist/embeddings.js

@@ -32,6 +32,23 @@ function cosine(a, b) {
         return 0;
     return dot / (Math.sqrt(na) * Math.sqrt(nb));
 }
+// cache vettori Float32Array per atom_id (evita riconversione buffer a ogni query)
+const _vecCache = new Map();
+const VEC_CACHE_MAX = 20000;
+function _cachedVec(id, buf) {
+    if (!buf || !buf.length || buf.length % 4 !== 0)
+        return null;
+    const hit = _vecCache.get(id);
+    if (hit && hit.byteLength === buf.length)
+        return hit;
+    if (_vecCache.size >= VEC_CACHE_MAX)
+        _vecCache.clear();
+    const v = new Float32Array(buf.buffer, buf.byteOffset, buf.length / 4);
+    _vecCache.set(id, v);
+    return v;
+}
+// penalita' di dominio allineate all'engine FTS (session/daily inquinano la semantica)
+const DOMAIN_PENALTY = [["session/", -0.05], ["daily/", -0.05]];
 export async function semanticSearch(db, query, limit = 10, domain) {
     const qv = await embed(query);
     if (!qv)
@@ -47,16 +64,28 @@ export async function semanticSearch(db, query, limit = 10, domain) {
         if (domain && r.domain !== domain)
             continue;
         const buf = Buffer.isBuffer(r.embedding) ? r.embedding : Buffer.from(r.embedding?.buffer ?? r.embedding);
-        if (!buf || !buf.length || buf.length % 4 !== 0 || buf.length / 4 !== qv.length) {
+        const v = _cachedVec(r.id, buf);
+        if (!v || v.length !== qv.length) {
             skippedCorrupt++;
             continue;
         } // riga anomala: dimensione incoerente, scartata e conteggiata
-        const v = new Float32Array(buf.buffer, buf.byteOffset, buf.length / 4);
-        scored.push({ id: r.id, title: r.title, domain: r.domain, type: r.type, semantic_score: Math.round(cosine(qv, v) * 10000) / 10000 });
+        let score = cosine(qv, v);
+        for (const [pfx, pen] of DOMAIN_PENALTY) {
+            if (String(r.domain || "").startsWith(pfx)) {
+                score += pen;
+                break;
+            }
+        }
+        scored.push({ id: r.id, title: r.title, domain: r.domain, type: r.type, semantic_score: Math.round(score * 10000) / 10000 });
     }
     semanticSearch._lastSkippedCorrupt = skippedCorrupt;
     scored.sort((a, b) => b.semantic_score - a.semantic_score);
-    return scored.slice(0, limit);
+    // cutoff relativo: i punteggi nomic sono compressi (0.5-0.75); un top-N fisso mescola
+    // risultati rilevanti e rumore distanti pochi centesimi. Teniamo solo cio' che sta
+    // vicino al migliore, come fa un occhio umano a scartare i risultati "di riempimento".
+    const top = scored[0]?.semantic_score ?? 0;
+    const kept = scored.filter((s) => s.semantic_score >= top - 0.05);
+    return kept.slice(0, limit);
 }
 export async function embedAtom(db, atomId, text) {
     const v = await embed(text);

package/dist/entry.js

@@ -53,6 +53,7 @@ export default definePluginEntry({
         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. 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_recall_session", description: "Recall messages from a specific OpenClaw session (search within session/ domain atoms).", parameters: T.Object({ session_id: T.String(), query: T.String(), limit: T.Optional(T.Number()) }), execute: (a) => me.recall_session(a.session_id, a.query, a.limit ?? 10) },
             { 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) },

package/dist/learning.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Memory Engine TS — Learning module (full Python parity port, v4.5.0).
+ * 7 detector + dedup + capacity + answer side-effects, port fedele di learning.py/engine.py.
+ */
+import type { DatabaseSync } from "node:sqlite";
+export interface LearningConfig {
+    max_pending_questions?: number;
+    contradiction_threshold?: number;
+    weak_confidence_threshold?: number;
+    weak_access_threshold?: number;
+    merge_similarity_threshold?: number;
+    decay_critical_threshold?: number;
+    gap_body_min_chars?: number;
+    graph_gap_enabled?: boolean;
+    graph_gap_min_weight?: number;
+    graph_gap_limit?: number;
+    graph_gap_types?: string[];
+    graph_gap_excluded_domain_prefixes?: string[];
+}
+export declare function computeSimilarity(a: any, b: any): number;
+export declare class Learning {
+    private db;
+    config: LearningConfig;
+    constructor(db: DatabaseSync, config?: LearningConfig);
+    private q;
+    private q1;
+    private x;
+    /** Garantisce le colonne options/meta (migration idempotente). */
+    ensureSchema(): void;
+    detectContradictions(): any[];
+    detectWeakAtoms(): any[];
+    detectMergeCandidates(): any[];
+    detectDecayCritical(): any[];
+    detectGaps(): any[];
+    detectGraphGaps(): any[];
+    addQuestion(atomIds: string[], questionType: string, question: string, options: string[], meta: any): any;
+    runAllChecks(): any[];
+    applyAnswerSideEffects(qrow: any, answer: string): string[];
+}

package/dist/learning.js

@@ -0,0 +1,277 @@
+function parseTags(v) {
+    if (Array.isArray(v))
+        return new Set(v.map(String));
+    try {
+        return new Set(JSON.parse(v || "[]").map(String));
+    }
+    catch {
+        return new Set();
+    }
+}
+export function computeSimilarity(a, b) {
+    const wa = new Set(String(a.title || "").toLowerCase().split(/\s+/).filter(Boolean));
+    const wb = new Set(String(b.title || "").toLowerCase().split(/\s+/).filter(Boolean));
+    const inter = [...wa].filter((w) => wb.has(w)).length;
+    const union = new Set([...wa, ...wb]).size;
+    const jaccard = wa.size && wb.size && union ? inter / union : 0;
+    const domainBonus = a.domain === b.domain ? 0.2 : 0;
+    const ta = parseTags(a.tags), tb = parseTags(b.tags);
+    const tInter = [...ta].filter((t) => tb.has(t)).length;
+    const tUnion = new Set([...ta, ...tb]).size;
+    const tagSim = ta.size && tb.size && tUnion ? tInter / tUnion : 0;
+    return Math.min(1, jaccard * 0.5 + tagSim * 0.3 + domainBonus);
+}
+export class Learning {
+    db;
+    config;
+    constructor(db, config = {}) {
+        this.db = db;
+        this.config = config;
+    }
+    q(sql, ...p) { return this.db.prepare(sql).all(...p); }
+    q1(sql, ...p) { return this.db.prepare(sql).get(...p); }
+    x(sql, ...p) { this.db.prepare(sql).run(...p); }
+    /** Garantisce le colonne options/meta (migration idempotente). */
+    ensureSchema() {
+        const cols = new Set(this.q("PRAGMA table_info(human_questions)").map((c) => c.name));
+        if (!cols.has("options"))
+            this.x("ALTER TABLE human_questions ADD COLUMN options TEXT");
+        if (!cols.has("meta"))
+            this.x("ALTER TABLE human_questions ADD COLUMN meta TEXT");
+    }
+    // ─── DETECTOR (parità engine.py) ───────────────────────
+    detectContradictions() {
+        const thr = this.config.contradiction_threshold ?? 0.7;
+        const atoms = this.q("SELECT * FROM atoms WHERE status='active' ORDER BY id LIMIT 500");
+        const out = [];
+        for (let i = 0; i < atoms.length; i++) {
+            for (let j = i + 1; j < atoms.length; j++) {
+                const a = atoms[i], b = atoms[j];
+                if (a.domain !== b.domain)
+                    continue;
+                const sim = computeSimilarity(a, b);
+                if (sim >= thr)
+                    out.push({ atom_a: a.id, atom_b: b.id, title_a: a.title, title_b: b.title, similarity: Math.round(sim * 1000) / 1000 });
+            }
+        }
+        return out;
+    }
+    detectWeakAtoms() {
+        const conf = this.config.weak_confidence_threshold ?? 0.4;
+        const acc = this.config.weak_access_threshold ?? 5;
+        return this.q("SELECT * FROM atoms WHERE status='active' AND confidence < ? AND access_count >= ? ORDER BY access_count DESC", conf, acc);
+    }
+    detectMergeCandidates() {
+        const thr = this.config.merge_similarity_threshold ?? 0.85;
+        const atoms = this.q("SELECT * FROM atoms WHERE status='active' ORDER BY id LIMIT 500");
+        const out = [];
+        for (let i = 0; i < atoms.length; i++) {
+            for (let j = i + 1; j < atoms.length; j++) {
+                const sim = computeSimilarity(atoms[i], atoms[j]);
+                if (sim >= thr)
+                    out.push({ atom_a: atoms[i].id, atom_b: atoms[j].id, title_a: atoms[i].title, title_b: atoms[j].title, similarity: Math.round(sim * 1000) / 1000 });
+            }
+        }
+        return out;
+    }
+    detectDecayCritical() {
+        const thr = this.config.decay_critical_threshold ?? 0.15;
+        return this.q("SELECT * FROM atoms WHERE status='active' AND weight < ? ORDER BY weight ASC", thr);
+    }
+    detectGaps() {
+        const minChars = this.config.gap_body_min_chars ?? 50;
+        return this.q("SELECT * FROM atoms WHERE status='active' AND (body IS NULL OR LENGTH(COALESCE(body,'')) < ?) ORDER BY access_count DESC", minChars);
+    }
+    detectGraphGaps() {
+        const minWeight = this.config.graph_gap_min_weight ?? 0.6;
+        const limit = this.config.graph_gap_limit ?? 20;
+        const types = this.config.graph_gap_types ?? ["fact", "decision", "procedure", "preference", "project", "note"];
+        const excluded = this.config.graph_gap_excluded_domain_prefixes ?? ["daily/", "session/"];
+        const rows = this.q("SELECT a.* FROM atoms a LEFT JOIN bonds bo ON bo.from_id = a.id OR bo.to_id = a.id WHERE a.status='active' AND a.weight >= ? AND bo.from_id IS NULL ORDER BY a.weight DESC, a.access_count DESC LIMIT ?", minWeight, limit * 3);
+        return rows.filter((r) => {
+            const t = JSON.parse(r.type ? JSON.stringify(r.type) : '"' + r.type + '"');
+            return types.includes(String(r.type)) && !excluded.some((p) => String(r.domain || "").startsWith(p));
+        }).slice(0, limit);
+    }
+    // ─── RUN (parità learning.py run_all_checks) ───────────
+    addQuestion(atomIds, questionType, question, options, meta) {
+        const now = Math.floor(Date.now() / 1000);
+        const id = "q_" + questionType + "_" + atomIds.join("-").slice(0, 40) + "_" + now;
+        this.x("INSERT OR IGNORE INTO human_questions (id, atom_ids, question_type, question, options, meta, status, created_at) VALUES (?,?,?,?,?,?,?,?)", id, JSON.stringify(atomIds), questionType, question, JSON.stringify(options), JSON.stringify(meta), "pending", now);
+        return { id, question_type: questionType, question };
+    }
+    runAllChecks() {
+        this.ensureSchema();
+        const maxPending = this.config.max_pending_questions ?? 20;
+        const pending = this.q("SELECT * FROM human_questions WHERE status='pending' LIMIT 100");
+        if (pending.length >= maxPending)
+            return [];
+        // dedup: non ricreare domande già pending/answered/dismissed (atom_ids normalizzati sorted)
+        const existingKeys = new Set();
+        for (const qrow of this.q("SELECT question_type, atom_ids FROM human_questions WHERE status IN ('pending','answered','dismissed')")) {
+            let ids;
+            try {
+                ids = JSON.parse(qrow.atom_ids || "[]");
+            }
+            catch {
+                ids = [qrow.atom_ids];
+            }
+            existingKeys.add(qrow.question_type + "|" + JSON.stringify([...ids].sort()));
+        }
+        const created = [];
+        const hasCapacity = () => pending.length + created.length < maxPending;
+        const key = (t, ids) => t + "|" + JSON.stringify([...ids].sort());
+        const seen = (t, ids) => { const k = key(t, ids); if (existingKeys.has(k))
+            return true; existingKeys.add(k); return false; };
+        // 1. Contraddizioni
+        for (const c of this.detectContradictions()) {
+            if (!hasCapacity())
+                return created;
+            const ids = [c.atom_a, c.atom_b];
+            if (seen("contradiction", ids))
+                continue;
+            created.push(this.addQuestion(ids, "contradiction", `Ho due informazioni potenzialmente in conflitto:\n• ${c.title_a}\n• ${c.title_b}\nSimilarità: ${c.similarity}. Quale è corretta, o vanno unify?`, [c.title_a, c.title_b, "Entrambe corrette (contesti diversi)"], { similarity: c.similarity }));
+        }
+        // 2. Weak atoms
+        for (const w of this.detectWeakAtoms()) {
+            if (!hasCapacity())
+                return created;
+            if (seen("weak", [w.id]))
+                continue;
+            created.push(this.addQuestion([w.id], "weak", `'${w.title}' è consultato spesso (${w.access_count} volte) ma ha confidence bassa (${w.confidence}). Puoi confermare che è corretto?`, ["Sì, corretto", "No, da correggere", "Non sono sicuro"], { confidence: w.confidence, access_count: w.access_count }));
+        }
+        // 3. Merge candidates
+        for (const m of this.detectMergeCandidates()) {
+            if (!hasCapacity())
+                return created;
+            const ids = [m.atom_a, m.atom_b];
+            if (seen("merge_candidate", ids))
+                continue;
+            created.push(this.addQuestion(ids, "merge_candidate", `Questi due atomi sembrano duplicati (similarità ${m.similarity}):\n• ${m.title_a}\n• ${m.title_b}\nLi unifico?`, ["Sì, unifica", "No, sono diversi"], { similarity: m.similarity }));
+        }
+        // 4. Decay critical
+        for (const d of this.detectDecayCritical()) {
+            if (!hasCapacity())
+                return created;
+            if (seen("decay_critical", [d.id]))
+                continue;
+            created.push(this.addQuestion([d.id], "decay_critical", `'${d.title}' non è più consultato da tempo (weight: ${Number(d.weight).toFixed(3)}). Archivio o è ancora rilevante?`, ["Archivia", "Rilevante, aggiorna weight", "Elimina"], { weight: d.weight }));
+        }
+        // 5. Gaps
+        for (const g of this.detectGaps()) {
+            if (!hasCapacity())
+                return created;
+            if (seen("gap", [g.id]))
+                continue;
+            created.push(this.addQuestion([g.id], "gap", `'${g.title}' ha informazioni incomplete. Puoi aggiungere dettagli?`, [], { body_length: String(g.body || "").length }));
+        }
+        // 6. Graph gaps (default OFF, come Python v1.5.2)
+        if (this.config.graph_gap_enabled === true) {
+            for (const g of this.detectGraphGaps()) {
+                if (!hasCapacity())
+                    return created;
+                if (seen("graph_gap", [g.id]))
+                    continue;
+                created.push(this.addQuestion([g.id], "graph_gap", `'${g.title}' è un atomo importante ma isolato nel grafo. Vuoi collegarlo ad altri atomi correlati?`, ["Suggerisci bond", "Mantieni isolato", "Archivia"], { weight: g.weight, access_count: g.access_count }));
+            }
+        }
+        return created;
+    }
+    // ─── ANSWER SIDE-EFFECTS (parità learning.py process_answer) ───
+    applyAnswerSideEffects(qrow, answer) {
+        const effects = [];
+        let atomIds = [];
+        try {
+            atomIds = JSON.parse(qrow.atom_ids || "[]");
+        }
+        catch { /* noop */ }
+        const now = Math.floor(Date.now() / 1000);
+        const low = answer.toLowerCase();
+        const updateAtom = (id, sets, ...vals) => {
+            this.x(`UPDATE atoms SET ${sets}, updated_at=? WHERE id=?`, ...vals, now, id);
+            effects.push(`${id}: ${sets}`);
+        };
+        switch (qrow.question_type) {
+            case "weak":
+                if (low.includes("corretto") || low.includes("sì") || low.includes("si,")) {
+                    for (const aid of atomIds)
+                        updateAtom(aid, "confidence=0.9");
+                }
+                else if (low.includes("correggere")) {
+                    for (const aid of atomIds)
+                        updateAtom(aid, "confidence=0.2");
+                }
+                break;
+            case "decay_critical":
+                if (low.includes("archivia")) {
+                    for (const aid of atomIds)
+                        updateAtom(aid, "status='archived'");
+                }
+                else if (low.includes("rilevante")) {
+                    for (const aid of atomIds)
+                        updateAtom(aid, "weight=1.0");
+                }
+                break;
+            case "merge_candidate":
+                if (low.includes("unifi") && atomIds.length >= 2) {
+                    // merge soft: bond + status merged sul duplicato (stessa semantica di memory_merge_atoms)
+                    for (const b of this.q("SELECT * FROM bonds WHERE from_id=? OR to_id=?", atomIds[1], atomIds[1])) {
+                        const nf = b.from_id === atomIds[1] ? atomIds[0] : b.from_id;
+                        const nt = b.to_id === atomIds[1] ? atomIds[0] : b.to_id;
+                        if (nf !== nt)
+                            this.x("INSERT OR IGNORE INTO bonds (from_id, to_id, relation, strength, evidence, created_at) VALUES (?,?,?,?,?,unixepoch())", nf, nt, b.relation, b.strength, b.evidence);
+                    }
+                    updateAtom(atomIds[1], "status='merged'");
+                    effects.push(`merged ${atomIds[1]} -> ${atomIds[0]}`);
+                }
+                break;
+            case "contradiction":
+                if (atomIds.length >= 2) {
+                    for (const aid of atomIds) {
+                        const at = this.q1("SELECT meta FROM atoms WHERE id=?", aid);
+                        if (!at)
+                            continue;
+                        let meta = {};
+                        try {
+                            meta = JSON.parse(at.meta || "{}");
+                        }
+                        catch { /* noop */ }
+                        meta.contradiction_resolution = answer;
+                        updateAtom(aid, "meta=?", JSON.stringify(meta));
+                    }
+                }
+                break;
+            case "gap":
+                // la risposta umana arricchisce il body in place ([Human note], come il Python)
+                for (const aid of atomIds) {
+                    const at = this.q1("SELECT body FROM atoms WHERE id=?", aid);
+                    if (!at)
+                        continue;
+                    const newBody = String(at.body || "") + `\n\n[Human note]: ${answer}`;
+                    updateAtom(aid, "body=?", newBody);
+                }
+                break;
+            case "graph_gap":
+                if (low.includes("archivia")) {
+                    for (const aid of atomIds)
+                        updateAtom(aid, "status='archived'");
+                }
+                else if (low.includes("mantieni")) {
+                    for (const aid of atomIds) {
+                        const at = this.q1("SELECT meta FROM atoms WHERE id=?", aid);
+                        if (!at)
+                            continue;
+                        let meta = {};
+                        try {
+                            meta = JSON.parse(at.meta || "{}");
+                        }
+                        catch { /* noop */ }
+                        meta.allow_isolated = true;
+                        updateAtom(aid, "meta=?", JSON.stringify(meta));
+                    }
+                }
+                break;
+        }
+        return effects;
+    }
+}

package/dist/learning.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/learning.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it, beforeAll } from "vitest";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTools } from "./tools.js";
+import { Learning } from "./learning.js";
+describe("learning parity (v4.5.0)", () => {
+    let me, learning;
+    beforeAll(() => {
+        const dir = mkdtempSync(join(tmpdir(), "me-learn-"));
+        process.env.MEMORY_DB_PATH = join(dir, "memory.db");
+        me = createTools(process.env.MEMORY_DB_PATH);
+        const db = me.__db;
+        // schema minimo (in produzione il DB esiste già, migrato dal Python)
+        const now0 = Math.floor(Date.now() / 1000);
+        db.prepare("CREATE TABLE IF NOT EXISTS atoms (id TEXT PRIMARY KEY, title TEXT, domain TEXT, type TEXT, status TEXT, confidence REAL, access_count INTEGER, weight REAL, body TEXT, tags TEXT, meta TEXT, created_at INTEGER, updated_at INTEGER, accessed_at INTEGER)").run();
+        db.prepare("CREATE TABLE IF NOT EXISTS human_questions (id TEXT PRIMARY KEY, atom_ids TEXT, question_type TEXT, question TEXT, options TEXT, meta TEXT, status TEXT, answer TEXT, answered_at INTEGER, created_at INTEGER)").run();
+        db.prepare("CREATE TABLE IF NOT EXISTS bonds (from_id TEXT, to_id TEXT, relation TEXT, strength REAL, evidence TEXT, created_at INTEGER)").run();
+        learning = new Learning(db);
+        const now = Math.floor(Date.now() / 1000);
+        // gap: body quasi vuoto
+        db.prepare("INSERT INTO atoms (id, title, domain, type, status, confidence, access_count, weight, body, created_at, updated_at, accessed_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)")
+            .run("a-gap", "Config incompleta", "test:learn", "fact", "active", 0.9, 3, 0.8, "poche parole", now, now, now);
+        // weak: confidence bassa + molto access
+        db.prepare("INSERT INTO atoms (id, title, domain, type, status, confidence, access_count, weight, body, created_at, updated_at, accessed_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)")
+            .run("a-weak", "Porta garage", "test:learn", "fact", "active", 0.2, 9, 0.5, "descrizione sufficientemente lunga del fatto sulla porta del garage", now, now, now);
+        // decay: weight sotto soglia
+        db.prepare("INSERT INTO atoms (id, title, domain, type, status, confidence, access_count, weight, body, created_at, updated_at, accessed_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)")
+            .run("a-decay", "Vecchio server", "test:learn", "fact", "active", 0.8, 1, 0.05, "descrizione sufficientemente lunga del vecchio server di test", now, now, now);
+    });
+    it("crea domande gap/weak/decay_critical con i tipi Python", () => {
+        const created = learning.runAllChecks();
+        const types = created.map((c) => c.question_type);
+        expect(types).toContain("gap");
+        expect(types).toContain("weak");
+        expect(types).toContain("decay_critical");
+    });
+    it("dedup: un secondo run non ricrea le stesse domande", () => {
+        const second = learning.runAllChecks();
+        const overlap = second.filter((c) => ["gap", "weak", "decay_critical"].includes(c.question_type));
+        expect(overlap.length).toBe(0);
+    });
+    it("risposta gap appende [Human note] al body", () => {
+        const db = me.__db;
+        const qrow = db.prepare("SELECT * FROM human_questions WHERE question_type='gap' AND status='pending' LIMIT 1").get();
+        expect(qrow).toBeTruthy();
+        const effects = learning.applyAnswerSideEffects(qrow, "Il codice e' 1234");
+        expect(effects.length).toBeGreaterThan(0);
+        const body = db.prepare("SELECT body FROM atoms WHERE id='a-gap'").get();
+        expect(String(body.body)).toContain("[Human note]: Il codice e' 1234");
+    });
+});

package/dist/maintenance.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { Learning } from "./learning.js";
 const T = Type;
 export function buildMaintenanceDefs(db, dbPath) {
     const q = (sql, ...p) => db.prepare(sql).all(...p);
@@ -138,31 +139,48 @@ export function buildMaintenanceDefs(db, dbPath) {
                 return { ok: true, atoms_imported: imported, domain };
             },
         },
-        // ── STEP 4: LEARNING ──────────────────────────────
+        // ── STEP 4: LEARNING (parità Python: 7 tipi + extras TS) ─────
         {
             name: "memory_learning_run",
-            description: "Run learning checks: stale facts, missing compacts, low-bond durables. Creates human_questions for items needing review.",
+            description: "Run learning checks (full Python parity): contradictions, weak atoms, merge candidates, decay critical, gaps (body vuoti), graph gaps (opt-in) + stale_fact/needs_link. Creates deduped human_questions; answers apply side effects.",
             parameters: T.Object({ dry_run: T.Optional(T.Boolean()) }),
             execute: (a) => {
+                const learning = new Learning(db, (globalThis.__meLearningCfg ?? {}));
+                const created = a.dry_run ? [] : learning.runAllChecks();
                 const now = Math.floor(Date.now() / 1000);
-                const questions = [];
-                // check 1: stale durable atoms (not accessed in 180 days)
+                const dupKey = (t, ids) => t + "|" + JSON.stringify([...ids].sort());
+                const existing = new Set(q("SELECT question_type, atom_ids FROM human_questions WHERE status IN ('pending','answered','dismissed')").map((r) => { let ids; try {
+                    ids = JSON.parse(r.atom_ids || "[]");
+                }
+                catch {
+                    ids = [r.atom_ids];
+                } return dupKey(r.question_type, ids); }));
+                const extra = [];
                 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
+                for (const s of stale) {
+                    const k = dupKey("stale_fact", [s.id]);
+                    if (!existing.has(k)) {
+                        existing.add(k);
+                        extra.push({ question_type: "stale_fact", atom_id: s.id, question: "Is '" + s.title.slice(0, 60) + "' still accurate and needed?" });
+                    }
+                }
                 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;
+                for (const s of isolated) {
+                    const k = dupKey("needs_link", [s.id]);
+                    if (!existing.has(k)) {
+                        existing.add(k);
+                        extra.push({ question_type: "needs_link", atom_id: s.id, question: "Should '" + s.title.slice(0, 60) + "' be linked to related atoms?" });
+                    }
+                }
+                let extraCreated = 0;
                 if (!a.dry_run) {
-                    for (const qq of questions) {
+                    for (const qq of extra) {
                         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++;
+                        extraCreated++;
                     }
                 }
-                return { dry_run: !!a.dry_run, questions_created: created, questions: questions.slice(0, 10) };
+                return { dry_run: !!a.dry_run, questions_created: created.length + extraCreated, by_type: { python_parity: created.length, extras: extraCreated }, questions: [...created, ...extra].slice(0, 15) };
             },
         },
         {
@@ -180,11 +198,19 @@ export function buildMaintenanceDefs(db, dbPath) {
                 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);
+                // side-effects per tipo (parità Python learning.process_answer)
+                let effects = [];
+                try {
+                    effects = new Learning(db).applyAnswerSideEffects(row, a.answer);
+                }
+                catch (err) {
+                    effects = ["side-effect error: " + String(err?.message || err).slice(0, 120)];
+                }
                 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" };
+                return { ok: true, question_id: a.question_id, answer: a.answer, action: a.action || "resolve_only", side_effects: effects };
             },
         },
     ];

package/dist/parity451.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/parity451.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, it, beforeAll } from "vitest";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTools } from "./tools.js";
+import { buildAdminDefs } from "./admin.js";
+describe("parità 4.5.1: recall_session + find_similar", () => {
+    let me, findSimilar;
+    beforeAll(() => {
+        const dir = mkdtempSync(join(tmpdir(), "me-p451-"));
+        process.env.MEMORY_DB_PATH = join(dir, "memory.db");
+        me = createTools(process.env.MEMORY_DB_PATH);
+        const db = me.__db;
+        const now = Math.floor(Date.now() / 1000);
+        db.prepare("CREATE TABLE IF NOT EXISTS atoms (id TEXT PRIMARY KEY, title TEXT, domain TEXT, type TEXT, status TEXT, confidence REAL, access_count INTEGER, weight REAL, body TEXT, body_compact TEXT, tags TEXT, meta TEXT, created_at INTEGER, updated_at INTEGER, accessed_at INTEGER)").run();
+        db.prepare("CREATE TABLE IF NOT EXISTS human_questions (id TEXT PRIMARY KEY, atom_ids TEXT, question_type TEXT, question TEXT, options TEXT, meta TEXT, status TEXT, answer TEXT, answered_at INTEGER, created_at INTEGER)").run();
+        db.prepare("CREATE TABLE IF NOT EXISTS bonds (from_id TEXT, to_id TEXT, relation TEXT, strength REAL, evidence TEXT, created_at INTEGER)").run();
+        db.prepare("CREATE VIRTUAL TABLE IF NOT EXISTS atoms_fts USING fts5(title, body, content='atoms', content_rowid='rowid')").run();
+        db.prepare("CREATE TABLE IF NOT EXISTS atom_embeddings (atom_id TEXT PRIMARY KEY, embedding BLOB, model TEXT, dim INTEGER, created_at INTEGER, updated_at INTEGER)").run();
+        const ins = db.prepare("INSERT INTO atoms (id, title, domain, type, status, confidence, access_count, weight, body, created_at, updated_at, accessed_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)");
+        ins.run("s1-msg1", "Configurazione UPS NUT", "session/testsess", "session_msg", "active", 0.8, 1, 0.5, "abbiamo fermato il container nut-upsd e mascherato il NUT nativo", now, now, now);
+        ins.run("s1-msg2", "Diagnosi NAS rumoroso", "session/testsess", "session_msg", "active", 0.8, 1, 0.5, "il rumore era causato dal restart loop del container", now, now, now);
+        ins.run("other1", "Ricetta carbonara", "cucina", "fact", "active", 0.9, 2, 0.7, "guanciale, uova, pecorino, pepe nero", now, now, now);
+        db.prepare("INSERT INTO atoms_fts(atoms_fts) VALUES('rebuild')").run();
+        findSimilar = buildAdminDefs(db).find((d) => d.name === "memory_find_similar");
+    });
+    it("recall_session trova solo atomi del dominio session/testsess", async () => {
+        const res = await me.recall_session("testsess", "container NUT");
+        expect(Array.isArray(res)).toBe(true);
+        expect(res.length).toBeGreaterThan(0);
+        expect(res.every((r) => r.domain === "session/testsess")).toBe(true);
+    });
+    it("find_similar senza ollama: fallback FTS e mai crash", async () => {
+        const res = await findSimilar.execute({ atom_id: "s1-msg1", limit: 3 });
+        expect(res.reference).toBe("s1-msg1");
+        expect(typeof res.mode).toBe("string");
+        expect(Array.isArray(res.similar)).toBe(true);
+    });
+    it("find_similar su atomo inesistente: errore pulito", async () => {
+        const res = await findSimilar.execute({ atom_id: "non-esiste" });
+        expect(res.error).toBe("atom not found");
+    });
+});

package/dist/tools.d.ts

@@ -4,7 +4,8 @@
  * Python server and are exposed as explicit pointers.
  */
 import { DatabaseSync } from "node:sqlite";
-export declare const VERSION = "4.4.1";
+import { Row } from "./engine.js";
+export declare const VERSION = "4.5.1";
 export declare function createTools(dbPath: string): {
     __db: DatabaseSync;
     version: () => {
@@ -31,6 +32,7 @@ export declare function createTools(dbPath: string): {
         semantic_score: null;
         note: string;
     }[]>;
+    recall_session: (session_id: string, query: string, limit?: number) => Promise<Row[]>;
     remember: (title: string, content: string, type?: string, domain?: string, confidence?: number, tags?: string[]) => {
         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 = "4.4.1";
+export const VERSION = "4.5.1";
 export function createTools(dbPath) {
     const db = new DatabaseSync(dbPath);
     const engine = new Engine(db, {});
@@ -39,6 +39,10 @@ export function createTools(dbPath) {
             // fallback FTS se ollama non raggiungibile
             return engine.searchFts(query, limit, ["active"]).map((r) => ({ id: r.id, title: r.title, semantic_score: null, note: "fts-fallback (ollama non raggiungibile)" }));
         },
+        recall_session: async (session_id, query, limit = 10) => {
+            // parità Python recall_session: recall limitato al dominio della sessione
+            return engine.recall(query, limit, { domain: "session/" + session_id, semantic: false });
+        },
         remember: (title, content, type = "fact", domain = "general", confidence = 0.8, tags = []) => {
             const now = Math.floor(Date.now() / 1000);
             const id = title.toLowerCase().replace(/[^a-z0-9_\\s]/g, "").trim().replace(/[\\s_]+/g, "_").slice(0, 60) || "atom_" + now;
@@ -256,6 +260,6 @@ export function createTools(dbPath) {
             return { created: true, ...draft };
         },
         // ── Admin jobs: puntano al server Python ──
-        _admin_note: () => "curator_run, learning_run, decay_run, backup/restore, import/export, cleanup_*, reindex_embeddings, find_similar, suggest_bonds: disponibili sul server MCP Python.",
+        _admin_note: () => "curator_run, learning_run, decay_run, backup/restore, import/export, cleanup_*, reindex_embeddings, find_similar, suggest_bonds: tutti disponibili come tool nativi memory_* (parità completa dal 4.5.x).",
     };
 }

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "memory-engine",
   "name": "Memory Engine",
   "description": "Native Memory Engine: 45 memory tools, session ingest/digest, curator and Control UI.",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "configSchema": {
     "type": "object",
     "properties": {
@@ -78,7 +78,8 @@
       "memory_import_markdown",
       "memory_learning_run",
       "memory_ask_pending",
-      "memory_answer_human"
+      "memory_answer_human",
+      "memory_recall_session"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-plugin-memory-engine",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "type": "module",
   "scripts": {
     "build": "tsc -p tsconfig.json && openclaw plugins build",