@unblocklabs/unblock-memory 0.3.27 → 0.3.29

package/dist/src/agent-transcript.d.ts

@@ -0,0 +1,8 @@
+import type { DatabaseSync } from "node:sqlite";
+/** The OpenClaw agent database versions whose transcript layout we read. */
+export declare function agentTranscriptSchemaVersion(db: DatabaseSync, errorMessage?: string): number;
+export declare function assertAgentTranscriptIdentity(db: DatabaseSync, agentId: string, version: number, errorMessage?: string): void;
+export declare function assertAgentTranscriptSchema(db: DatabaseSync, agentId: string, errorMessage?: string): void;
+export declare const ACTIVE_EVENTS_FROM = "FROM session_transcript_active_events a\n  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq";
+export declare const ACTIVE_EVENT_COUNT_SQL = "SELECT COUNT(*) n,COALESCE(SUM(length(e.event_json)),0) bytes\n  FROM session_transcript_active_events a\n  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq WHERE a.session_id=?";
+export declare const ACTIVE_EVENT_ROWS_SQL = "SELECT e.seq,e.event_json eventJson,e.created_at createdAt\n  FROM session_transcript_active_events a\n  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq WHERE a.session_id=? ORDER BY a.active_position";

package/dist/src/agent-transcript.js

@@ -0,0 +1,29 @@
+/** The OpenClaw agent database versions whose transcript layout we read. */
+export function agentTranscriptSchemaVersion(db, errorMessage) {
+    const version = db.prepare("PRAGMA user_version").get()?.user_version;
+    if (typeof version !== "number" || ![17, 18, 19].includes(version)) {
+        throw new Error(errorMessage ?? "unsupported OpenClaw agent database schema: expected one of 17, 18, 19, " +
+            `found ${String(version ?? "unknown")}`);
+    }
+    return version;
+}
+export function assertAgentTranscriptIdentity(db, agentId, version, errorMessage) {
+    const fail = (message) => { throw new Error(errorMessage ?? message); };
+    const meta = db.prepare("SELECT role, schema_version AS schemaVersion, agent_id AS agentId " +
+        "FROM schema_meta WHERE meta_key = 'primary' LIMIT 1").get();
+    if (meta?.role !== "agent" || meta.schemaVersion !== version) {
+        fail("unsupported OpenClaw agent database primary schema metadata");
+    }
+    if (meta?.agentId !== agentId) {
+        fail(`OpenClaw agent database belongs to ${String(meta?.agentId)}, not ${agentId}`);
+    }
+}
+export function assertAgentTranscriptSchema(db, agentId, errorMessage) {
+    assertAgentTranscriptIdentity(db, agentId, agentTranscriptSchemaVersion(db, errorMessage), errorMessage);
+}
+export const ACTIVE_EVENTS_FROM = `FROM session_transcript_active_events a
+  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq`;
+export const ACTIVE_EVENT_COUNT_SQL = `SELECT COUNT(*) n,COALESCE(SUM(length(e.event_json)),0) bytes
+  ${ACTIVE_EVENTS_FROM} WHERE a.session_id=?`;
+export const ACTIVE_EVENT_ROWS_SQL = `SELECT e.seq,e.event_json eventJson,e.created_at createdAt
+  ${ACTIVE_EVENTS_FROM} WHERE a.session_id=? ORDER BY a.active_position`;

package/dist/src/cluster-review.js

@@ -59,6 +59,6 @@ export async function reviewClusterIngestion(params) {
         });
         return { status: "ok", runId: snapshot.runId, clusterId: params.clusterId, members, recurring,
             sampled: sample.length, considered: snapshot.considered, clusterSize: snapshot.clusterSize,
-            policy: "jev-1.13.0:cluster-defects-v1", scope: "Center/edge sample of approved complete chunks only. Recurring labels are hypotheses, not proof of a shared cause or permission to change any member. Unreviewed members remain unknown." };
+            policy: "jev-1.13.0:cluster-defects-v2-isolated", scope: "Center/edge sample of approved complete chunks only. Recurring labels are hypotheses, not proof of a shared cause or permission to change any member. Unreviewed members remain unknown." };
     });
 }

package/dist/src/config.d.ts

@@ -69,6 +69,10 @@ export type UnblockMemoryConfig = {
         maxHints: number;
         cooldownTurns: number;
         timeoutMs: number;
+        mlx?: {
+            pythonPath: string;
+            modelPath: string;
+        };
     };
 };
 export declare const DEFAULT_PEOPLE_CONFIG: UnblockMemoryConfig["people"];

package/dist/src/config.js

@@ -91,7 +91,19 @@ function resolveMemoryWhisperer(value, corpora) {
         throw new Error("unblock-memory memoryWhisperer must be an object");
     }
     const config = value;
-    assertOnlyKeys(config, Object.keys(DEFAULT_MEMORY_WHISPERER), "memoryWhisperer");
+    assertOnlyKeys(config, [...Object.keys(DEFAULT_MEMORY_WHISPERER), "mlx"], "memoryWhisperer");
+    let mlx;
+    if (config.mlx !== undefined) {
+        if (!config.mlx || typeof config.mlx !== "object" || Array.isArray(config.mlx))
+            throw new Error("memoryWhisperer.mlx must be an object");
+        const value = config.mlx;
+        assertOnlyKeys(value, ["pythonPath", "modelPath"], "memoryWhisperer.mlx");
+        if (typeof value.pythonPath !== "string" || !isAbsolute(value.pythonPath) ||
+            typeof value.modelPath !== "string" || !isAbsolute(value.modelPath)) {
+            throw new Error("memoryWhisperer.mlx requires absolute pythonPath and modelPath");
+        }
+        mlx = { pythonPath: value.pythonPath, modelPath: value.modelPath };
+    }
     const enabled = config.enabled ?? false;
     if (typeof enabled !== "boolean")
         throw new Error("unblock-memory memoryWhisperer.enabled must be a boolean");
@@ -120,6 +132,7 @@ function resolveMemoryWhisperer(value, corpora) {
         enabled, complementaryHints, corpora: [...new Set(selected)], historyMessages, cooldownTurns, minUsefulness,
         maxHints: positiveInteger(config.maxHints, 2, "memoryWhisperer.maxHints", 2),
         timeoutMs: positiveInteger(config.timeoutMs, 3000, "memoryWhisperer.timeoutMs", 10_000),
+        ...(mlx ? { mlx } : {}),
     };
 }
 function assertOnlyKeys(value, allowed, label) {

package/dist/src/date-option.d.ts

@@ -0,0 +1 @@
+export declare function dateOption(value: string | undefined, fallback: number): number;

package/dist/src/date-option.js

@@ -0,0 +1,8 @@
+export function dateOption(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString().slice(0, 10) !== value) {
+        throw new Error("Dates must be valid YYYY-MM-DD UTC dates");
+    }
+    return Date.parse(value);
+}

package/dist/src/diagnostics.d.ts

@@ -1,17 +1,18 @@
 import { RetrievalTelemetry } from "./retrieval-telemetry.js";
 type Whisperer = "skill" | "memory";
-type Outcome = "missing_key" | "typesafe_disabled" | "no_candidates" | "rejected" | "cooldown" | "emitted" | "failed" | "timed_out" | "cancelled" | "unavailable" | "payload_limit" | "redundancy_unavailable";
+type Outcome = "missing_key" | "typesafe_disabled" | "no_candidates" | "rejected" | "cooldown" | "emitted" | "failed" | "timed_out" | "cancelled" | "unavailable" | "payload_limit" | "redundancy_unavailable" | "recall_not_needed" | "queries_generated" | "query_fallback" | "judge_candidate_failed";
 /** Process-local, content-free and bounded. Agent IDs are keys, never included in snapshots. */
 export declare class WhispererDiagnostics {
     #private;
+    static shared(): WhispererDiagnostics;
     record(agentId: string, whisperer: Whisperer, outcome: Outcome): void;
     measureMemory(agentId: string, observation: Parameters<RetrievalTelemetry["record"]>[1]): void;
     snapshot(agentId: string): {
         skill: {
+            cancelled?: number | undefined;
             unavailable?: number | undefined;
             rejected?: number | undefined;
             failed?: number | undefined;
-            cancelled?: number | undefined;
             timed_out?: number | undefined;
             missing_key?: number | undefined;
             typesafe_disabled?: number | undefined;
@@ -20,12 +21,16 @@ export declare class WhispererDiagnostics {
             emitted?: number | undefined;
             payload_limit?: number | undefined;
             redundancy_unavailable?: number | undefined;
+            recall_not_needed?: number | undefined;
+            queries_generated?: number | undefined;
+            query_fallback?: number | undefined;
+            judge_candidate_failed?: number | undefined;
         };
         memory: {
+            cancelled?: number | undefined;
             unavailable?: number | undefined;
             rejected?: number | undefined;
             failed?: number | undefined;
-            cancelled?: number | undefined;
             timed_out?: number | undefined;
             missing_key?: number | undefined;
             typesafe_disabled?: number | undefined;
@@ -34,6 +39,10 @@ export declare class WhispererDiagnostics {
             emitted?: number | undefined;
             payload_limit?: number | undefined;
             redundancy_unavailable?: number | undefined;
+            recall_not_needed?: number | undefined;
+            queries_generated?: number | undefined;
+            query_fallback?: number | undefined;
+            judge_candidate_failed?: number | undefined;
         };
         telemetry: {
             scope: string;
@@ -41,11 +50,11 @@ export declare class WhispererDiagnostics {
                 [k: string]: {
                     calls: number;
                     outcomes: {
+                        cancelled?: number | undefined;
                         ok?: number | undefined;
                         skipped?: number | undefined;
                         failed?: number | undefined;
                         empty?: number | undefined;
-                        cancelled?: number | undefined;
                         timed_out?: number | undefined;
                     };
                     measurements: {

package/dist/src/diagnostics.js

@@ -1,6 +1,11 @@
 import { RetrievalTelemetry } from "./retrieval-telemetry.js";
 /** Process-local, content-free and bounded. Agent IDs are keys, never included in snapshots. */
 export class WhispererDiagnostics {
+    static shared() {
+        const scope = globalThis;
+        const symbol = Symbol.for("unblock-memory.whisperer-diagnostics.v1");
+        return (scope[symbol] ??= new WhispererDiagnostics());
+    }
     #agents = new Map();
     #entry(agentId) {
         let entry = this.#agents.get(agentId);

package/dist/src/manager.d.ts

@@ -57,11 +57,11 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
                 [k: string]: {
                     calls: number;
                     outcomes: {
+                        cancelled?: number | undefined;
                         ok?: number | undefined;
                         skipped?: number | undefined;
                         failed?: number | undefined;
                         empty?: number | undefined;
-                        cancelled?: number | undefined;
                         timed_out?: number | undefined;
                     };
                     measurements: {
@@ -220,6 +220,8 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         };
     }): MaintenanceTask | undefined;
     search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
+    /** Whisperer-only discovery: exact trained recipe, no query-conditioned reranker or merged cap. */
+    searchWhisperer(queries: readonly string[], opts: Pick<CorpusSearchOptions, "corpora" | "signal" | "maxSnippetChars">): Promise<CorpusMemorySearchResult[]>;
     searchSkills(query: string, minScore: number, limit: number): Promise<SkillSearchCandidate[]>;
     readFile(params: {
         relPath: string;

package/dist/src/manager.js

@@ -16,6 +16,7 @@ import { reviewIndexedClaim } from "./evidence-review.js";
 import { reviewClusterIngestion } from "./cluster-review.js";
 import { abortable } from "./abortable.js";
 import { RetrievalTelemetry } from "./retrieval-telemetry.js";
+import { trainingCandidates } from "./training-candidates.js";
 const DEFAULT_READ_LINES = 120;
 const MAX_READ_CHARS = 12_000;
 const WATCH_DEBOUNCE_MS = 250;
@@ -486,50 +487,43 @@ export class QmdMemoryManager {
             .filter((source) => selected.has(source.corpus))
             .map((source) => source.collection);
     }
+    async #updateAndEmbed(store, collection, force) {
+        const update = await store.update({ collections: collection ? [collection] : [] });
+        this.#cleanupRemovedDocuments?.(update.updated + update.removed);
+        const analysisStore = store;
+        const changed = update.indexed + update.updated + update.removed > 0 || update.needsEmbedding > 0;
+        if ((changed || force) && analysisStore.internal)
+            markMemoryAnalysisStale(analysisStore.internal.db);
+        const embed = await store.embed({
+            ...(collection ? { collection } : {}),
+            force,
+            chunkStrategy: "semantic",
+        });
+        this.#recordEmbedding(embed);
+        const chunksEmbedded = completedEmbeddingCount(embed);
+        if (!changed && !force && chunksEmbedded > 0 && analysisStore.internal) {
+            markMemoryAnalysisStale(analysisStore.internal.db);
+        }
+        return chunksEmbedded;
+    }
+    async #refreshIndexStatus(store) {
+        const status = await store.getStatus();
+        const collections = await store.listCollections();
+        this.#files = collections.reduce((total, collection) => total + collection.active_count, 0);
+        this.#dirty = status.needsEmbedding > 0;
+    }
     sync(params) {
         const run = async () => {
             const store = await this.#getStore();
             this.#dirty = true;
-            const analysisStore = store;
             const collections = this.#qmdSources().filter((source) => source.kind !== "sessions");
-            let analysisMarkedStale = false;
-            const markAnalysisStale = () => {
-                if (analysisMarkedStale || !analysisStore.internal)
-                    return;
-                markMemoryAnalysisStale(analysisStore.internal.db);
-                analysisMarkedStale = true;
-            };
             if (collections.length === 0) {
-                const update = await store.update({ collections: [] });
-                this.#cleanupRemovedDocuments?.(update.updated + update.removed);
-                if (update.indexed + update.updated + update.removed > 0 ||
-                    update.needsEmbedding > 0 || params?.force === true) {
-                    markAnalysisStale();
-                }
-                const embed = await store.embed({ force: params?.force, chunkStrategy: "semantic" });
-                this.#recordEmbedding(embed);
-                if (completedEmbeddingCount(embed) > 0)
-                    markAnalysisStale();
+                await this.#updateAndEmbed(store, undefined, params?.force);
             }
             for (const source of collections) {
-                const update = await store.update({ collections: [source.collection] });
-                this.#cleanupRemovedDocuments?.(update.updated + update.removed);
-                const changed = update.indexed + update.updated + update.removed > 0 || update.needsEmbedding > 0;
-                if (changed || params?.force === true)
-                    markAnalysisStale();
-                const embed = await store.embed({
-                    collection: source.collection,
-                    force: params?.force,
-                    chunkStrategy: "semantic",
-                });
-                this.#recordEmbedding(embed);
-                if (completedEmbeddingCount(embed) > 0)
-                    markAnalysisStale();
+                await this.#updateAndEmbed(store, source.collection, params?.force);
             }
-            const status = await store.getStatus();
-            const indexedCollections = await store.listCollections();
-            this.#files = indexedCollections.reduce((total, collection) => total + collection.active_count, 0);
-            this.#dirty = status.needsEmbedding > 0;
+            await this.#refreshIndexStatus(store);
         };
         return this.#enqueue(run);
     }
@@ -547,24 +541,7 @@ export class QmdMemoryManager {
                 index: async () => {
                     onPhase?.("indexing");
                     const store = await this.#getStore();
-                    const update = await store.update({ collections: [sessions.collection] });
-                    this.#cleanupRemovedDocuments?.(update.updated + update.removed);
-                    const analysisStore = store;
-                    const invalidatesAnalysis = update.indexed + update.updated + update.removed > 0 ||
-                        update.needsEmbedding > 0;
-                    if (invalidatesAnalysis && analysisStore.internal) {
-                        markMemoryAnalysisStale(analysisStore.internal.db);
-                    }
-                    const embed = await store.embed({
-                        collection: sessions.collection,
-                        chunkStrategy: "semantic",
-                    });
-                    const chunksEmbedded = completedEmbeddingCount(embed);
-                    this.#recordEmbedding(embed);
-                    if (!invalidatesAnalysis && chunksEmbedded > 0 && analysisStore.internal) {
-                        markMemoryAnalysisStale(analysisStore.internal.db);
-                    }
-                    return chunksEmbedded;
+                    return this.#updateAndEmbed(store, sessions.collection);
                 },
             });
             this.#sessionMetadata = sessionMetadataByPath(synced.manifest);
@@ -572,10 +549,7 @@ export class QmdMemoryManager {
             if (synced.result.skipReason)
                 return synced.result;
             const store = await this.#getStore();
-            const status = await store.getStatus();
-            const collections = await store.listCollections();
-            this.#files = collections.reduce((total, collection) => total + collection.active_count, 0);
-            this.#dirty = status.needsEmbedding > 0;
+            await this.#refreshIndexStatus(store);
             return synced.result;
         });
     }
@@ -857,9 +831,39 @@ export class QmdMemoryManager {
             expand: false,
         });
         opts?.signal?.throwIfAborted();
+        return this.#renderSearchHits(hits, store, opts);
+    }
+    /** Whisperer-only discovery: exact trained recipe, no query-conditioned reranker or merged cap. */
+    async searchWhisperer(queries, opts) {
+        return this.#enqueue(async () => {
+            opts.signal?.throwIfAborted();
+            const collections = this.#collectionNames(opts.corpora);
+            if (!collections.length)
+                return [];
+            if (this.#sessions && collections.includes(this.#sessions.collection))
+                await this.#refreshSessionMetadata();
+            const store = await this.#getAnalysisStore();
+            const hits = new Map();
+            // Serialize native QMD work. Cancellation prevents further queries/collections.
+            for (const query of queries)
+                for (const collection of collections) {
+                    opts.signal?.throwIfAborted();
+                    for (const hit of await trainingCandidates(store, query, collection, query, opts.signal)) {
+                        const key = JSON.stringify([hit.file, hit.bestChunkPos, hit.bestChunk]);
+                        if (!hits.has(key))
+                            hits.set(key, { file: hit.file, body: hit.body, bestChunk: hit.bestChunk,
+                                chunkPos: hit.bestChunkPos, chunkLen: hit.bestChunk.length, displayPath: hit.file, score: hit.score });
+                    }
+                }
+            opts.signal?.throwIfAborted();
+            return this.#renderSearchHits([...hits.values()], store, opts);
+        });
+    }
+    async #renderSearchHits(hits, store, opts) {
         const tokenizer = store.internal?.llm;
         const results = [];
         for (const hit of hits) {
+            opts?.signal?.throwIfAborted();
             // Proactive hints must retain the entire matched chunk, even when expanded
             // turn/message context exceeds their budget. Ordinary search is unchanged.
             if (hit.bestChunk.length > (opts?.maxSnippetChars ?? Infinity))

package/dist/src/memory-whisperer.d.ts

@@ -9,8 +9,9 @@ type MemoryWhispererRuntime = {
     }): Promise<{
         manager: {
             search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
+            searchWhisperer?(queries: readonly string[], opts: Pick<CorpusSearchOptions, "corpora" | "signal" | "maxSnippetChars">): Promise<CorpusMemorySearchResult[]>;
         } | null;
     }>;
 };
-export declare function registerMemoryWhisperer(api: OpenClawPluginApi, runtime: MemoryWhispererRuntime, config: UnblockMemoryConfig["memoryWhisperer"], typesafe: UnblockMemoryConfig["typesafe"], diagnostics?: WhispererDiagnostics): void;
+export declare function registerMemoryWhisperer(api: OpenClawPluginApi, runtime: MemoryWhispererRuntime, config: UnblockMemoryConfig["memoryWhisperer"], typesafe: UnblockMemoryConfig["typesafe"], diagnostics?: WhispererDiagnostics): Parameters<typeof api.on<"before_prompt_build">>[1] | undefined;
 export {};