@unblocklabs/unblock-memory 0.2.2 → 0.2.4

package/README.md

@@ -2,8 +2,8 @@
 
 Workspace-native memory for OpenClaw, powered internally by `@unblocklabs/qmd`.
 It keeps one warm QMD store per agent and exposes the standard `memory_search`
-and `memory_get` tools. Search uses semantic chunking v2 and QMD vsearch without
-a reranker.
+and `memory_get` tools. Search uses semantic chunking v2 and direct QMD vector
+search without query expansion or a reranker, so only the embedding model loads.
 
 Optional memory analysis uses those same stored vectors in the same SQLite
 index. It does not re-embed memory, copy vectors, or create another database.
@@ -39,6 +39,8 @@ directories, or globs into named corpora:
     entries: {
       "unblock-memory": {
         config: {
+          // Default: avoid repeated model cold starts after idle periods.
+          keepEmbeddingModelWarm: true,
           corpora: [
             {
               name: "memory",
@@ -73,6 +75,10 @@ omitted, the plugin creates a `memory` corpus containing `MEMORY.md`, `USER.md`,
 and `memory/**/*.md`. Explicit configuration must include exactly one `memory`
 corpus; other unique names may be added for custom material.
 
+`keepEmbeddingModelWarm` defaults to `true`, keeping the embedding model and
+context resident after first use. Set it to `false` to restore QMD's five-minute
+idle unload behavior.
+
 `memory_search` searches every configured corpus by default. Pass
 `corpora: ["projects"]` to search selected corpora or `corpora: ["all"]` to
 request all of them explicitly. Search results include their corpus name and
@@ -107,9 +113,10 @@ channel and group conversations; add `direct` explicitly to include DMs. Run
 check its progress or result. Projections are private derived Markdown
 under the agent's `unblock-memory/sessions` state directory and can be rebuilt
 from OpenClaw at any time. Session results include provider, chat type,
-conversation identity, and start time. They participate in the same search and
-clustering index as file memory. This phase does not sync sessions at startup or
-on a schedule; refreshes are manual through `memory_sync_sessions`.
+conversation identity, and start time as an ISO 8601 timestamp. They participate
+in the same search and clustering index as file memory. This phase does not sync
+sessions at startup or on a schedule; refreshes are manual through
+`memory_sync_sessions`.
 
 Indexes live at `~/.openclaw/agents/<agentId>/unblock-memory/index.sqlite` (or the
 equivalent configured OpenClaw state directory). The first lookup builds the

package/dist/src/config.d.ts

@@ -14,6 +14,7 @@ export type CorpusConfig = FileCorpusConfig | SessionCorpusConfig;
 export declare const DEFAULT_CORPORA: readonly FileCorpusConfig[];
 export type UnblockMemoryConfig = {
     corpora: readonly CorpusConfig[];
+    keepEmbeddingModelWarm: boolean;
     analysis: {
         executable?: string;
     };

package/dist/src/config.js

@@ -65,16 +65,20 @@ function resolveCorpora(value) {
 }
 export function resolveConfig(value) {
     if (value === undefined || value === null) {
-        return { corpora: DEFAULT_CORPORA, analysis: {} };
+        return { corpora: DEFAULT_CORPORA, keepEmbeddingModelWarm: true, analysis: {} };
     }
     if (typeof value !== "object" || Array.isArray(value)) {
         throw new Error("unblock-memory config must be an object");
     }
     const config = value;
-    assertOnlyKeys(config, ["corpora", "analysis"], "config");
+    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis"], "config");
     const corpora = resolveCorpora(config.corpora);
+    if (config.keepEmbeddingModelWarm !== undefined && typeof config.keepEmbeddingModelWarm !== "boolean") {
+        throw new Error("unblock-memory keepEmbeddingModelWarm must be a boolean");
+    }
+    const keepEmbeddingModelWarm = config.keepEmbeddingModelWarm ?? true;
     if (config.analysis === undefined)
-        return { corpora, analysis: {} };
+        return { corpora, keepEmbeddingModelWarm, analysis: {} };
     if (!config.analysis || typeof config.analysis !== "object" || Array.isArray(config.analysis)) {
         throw new Error("unblock-memory analysis must be an object");
     }
@@ -82,9 +86,9 @@ export function resolveConfig(value) {
     assertOnlyKeys(analysis, ["executable"], "analysis");
     const configured = analysis.executable;
     if (configured === undefined)
-        return { corpora, analysis: {} };
+        return { corpora, keepEmbeddingModelWarm, analysis: {} };
     if (typeof configured !== "string" || !configured.trim() || !isAbsolute(configured.trim())) {
         throw new Error("unblock-memory analysis.executable must be an absolute non-empty path");
     }
-    return { corpora, analysis: { executable: configured.trim() } };
+    return { corpora, keepEmbeddingModelWarm, analysis: { executable: configured.trim() } };
 }

package/dist/src/manager.d.ts

@@ -31,6 +31,7 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         workspaceDir: string;
         sources: readonly ResolvedSource[];
         storeFactory?: () => Promise<ManagerStore>;
+        keepModelsWarm?: boolean;
         analysisExecutable?: string;
         analysisRunner?: AnalysisRunner;
         sessions?: ManagerSessionConfig;

package/dist/src/manager.js

@@ -137,6 +137,7 @@ export class QmdMemoryManager {
     #workspaceDir;
     #sources;
     #storeFactory;
+    #keepModelsWarm;
     #analysisExecutable;
     #analysisRunner;
     #sessions;
@@ -157,6 +158,7 @@ export class QmdMemoryManager {
         this.#workspaceDir = params.workspaceDir;
         this.#sources = new Map(params.sources.map((source) => [source.collection, source]));
         this.#storeFactory = params.storeFactory;
+        this.#keepModelsWarm = params.keepModelsWarm ?? true;
         this.#analysisExecutable = params.analysisExecutable;
         this.#analysisRunner = params.analysisRunner ?? runAnalysisWorker;
         this.#sessions = params.sessions;
@@ -240,6 +242,7 @@ export class QmdMemoryManager {
         const { createStore } = await qmdModule;
         const store = await createStore({
             dbPath: this.#dbPath,
+            keepModelsWarm: this.#keepModelsWarm,
             config: {
                 collections: Object.fromEntries([...this.#sources.values()].map((source) => [
                     source.collection,
@@ -436,6 +439,7 @@ export class QmdMemoryManager {
             limit: opts?.maxResults ?? 5,
             minScore: opts?.minScore ?? 0.3,
             allowedPaths,
+            expand: false,
         });
         return hits.flatMap((hit) => {
             const collection = /^qmd:\/\/([^/]+)\//.exec(hit.file)?.[1];

package/dist/src/plugin.js

@@ -58,7 +58,18 @@ function createSearchTool(runtime, ctx) {
                 minScore,
                 signal,
             });
-            return jsonResult({ results, provider: "unblock-memory" });
+            return jsonResult({
+                results: results.map((result) => result.session
+                    ? {
+                        ...result,
+                        session: {
+                            ...result.session,
+                            startedAt: new Date(result.session.startedAt).toISOString(),
+                        },
+                    }
+                    : result),
+                provider: "unblock-memory",
+            });
         },
     };
 }
@@ -96,7 +107,7 @@ function createSyncSessionsTool(runtime, ctx) {
         parameters: syncSessionsParameters,
         async execute(_toolCallId, params) {
             const { force } = Value.Parse(syncSessionsParameters, params);
-            return jsonResult(runtime.startSessionSync(active, force));
+            return jsonResult(await runtime.startSessionSync(active, force));
         },
     };
 }
@@ -111,7 +122,7 @@ function createSyncStatusTool(runtime, ctx) {
         parameters: syncStatusParameters,
         async execute(_toolCallId, params) {
             Value.Parse(syncStatusParameters, params);
-            return jsonResult(runtime.sessionSyncStatus(active.agentId));
+            return jsonResult(await runtime.sessionSyncStatus(active.agentId));
         },
     };
 }
@@ -272,7 +283,10 @@ export function resolveFlushPlan(params = {}) {
 }
 export function registerUnblockMemory(api) {
     const config = resolveConfig(api.pluginConfig);
-    const runtime = new QmdMemoryRuntime(config.corpora, config.analysis.executable);
+    const runtime = new QmdMemoryRuntime(config.corpora, {
+        analysisExecutable: config.analysis.executable,
+        keepEmbeddingModelWarm: config.keepEmbeddingModelWarm,
+    });
     const capability = {
         deterministicRecallToolName: "memory_search",
         supportsPrivateTranscriptRecall: false,

package/dist/src/runtime.d.ts

@@ -29,9 +29,22 @@ export type SessionSyncStartResult = {
     status: "unavailable";
     error: string;
 };
+type StoredSessionSyncStatus = Exclude<SessionSyncStatus, {
+    status: "idle";
+}>;
+type StoredRunningSessionSync = Extract<StoredSessionSyncStatus, {
+    status: "running";
+}> & {
+    pid: number;
+};
+export declare function recoverInterruptedSessionSync(directory: string, statusPath: string, stale: StoredRunningSessionSync): Promise<SessionSyncStatus>;
 export declare class QmdMemoryRuntime implements MemoryPluginRuntimeContract {
     #private;
-    constructor(corpora: readonly CorpusConfig[], analysisExecutable?: string);
+    constructor(corpora: readonly CorpusConfig[], options?: {
+        analysisExecutable?: string;
+        keepEmbeddingModelWarm?: boolean;
+        stateRoot?: string;
+    });
     getMemorySearchManager(params: {
         cfg: OpenClawConfig;
         agentId: string;
@@ -49,10 +62,11 @@ export declare class QmdMemoryRuntime implements MemoryPluginRuntimeContract {
     startSessionSync(params: {
         cfg: OpenClawConfig;
         agentId: string;
-    }, force?: boolean): SessionSyncStartResult;
-    sessionSyncStatus(agentId: string): SessionSyncStatus;
+    }, force?: boolean): Promise<SessionSyncStartResult>;
+    sessionSyncStatus(agentId: string): Promise<SessionSyncStatus>;
     closeMemorySearchManager(params: {
         agentId: string;
     }): Promise<void>;
     closeAllMemorySearchManagers(): Promise<void>;
 }
+export {};

package/dist/src/runtime.js

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { resolveAgentDir, resolveAgentWorkspaceDir, resolveStateDir, } from "openclaw/plugin-sdk/memory-core-host-engine-foundation";
 import { resolveAgentIdentity } from "openclaw/plugin-sdk/agent-runtime";
@@ -5,14 +7,72 @@ import { QmdMemoryManager } from "./manager.js";
 import { resolveTimezone } from "./session-projector.js";
 import { resolveSessionSource, resolveSources } from "./sources.js";
 import { classifyWorkspaceMemoryPaths } from "./workspace-path-classifier.js";
+const activeSessionSyncs = new Map();
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function removeIfPresent(path) {
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+async function atomicWriteJson(path, value) {
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        await rename(temporary, path);
+    }
+    finally {
+        await removeIfPresent(temporary);
+    }
+}
+export async function recoverInterruptedSessionSync(directory, statusPath, stale) {
+    activeSessionSyncs.set(directory, stale.startedAt);
+    try {
+        const current = await readJson(statusPath);
+        if (!current)
+            return { status: "idle" };
+        if (current.status !== "running")
+            return current;
+        if (current.startedAt !== stale.startedAt) {
+            return { status: "running", phase: current.phase, startedAt: current.startedAt };
+        }
+        const failed = {
+            status: "failed",
+            startedAt: stale.startedAt,
+            completedAt: new Date().toISOString(),
+            error: "session sync interrupted by Gateway restart",
+        };
+        await atomicWriteJson(statusPath, failed);
+        return failed;
+    }
+    finally {
+        if (activeSessionSyncs.get(directory) === stale.startedAt)
+            activeSessionSyncs.delete(directory);
+    }
+}
 export class QmdMemoryRuntime {
     #corpora;
     #analysisExecutable;
+    #keepEmbeddingModelWarm;
+    #stateRoot;
     #managers = new Map();
-    #sessionSyncStatuses = new Map();
-    constructor(corpora, analysisExecutable) {
+    constructor(corpora, options = {}) {
         this.#corpora = corpora;
-        this.#analysisExecutable = analysisExecutable;
+        this.#analysisExecutable = options.analysisExecutable;
+        this.#keepEmbeddingModelWarm = options.keepEmbeddingModelWarm ?? true;
+        this.#stateRoot = options.stateRoot ?? resolveStateDir();
     }
     async getMemorySearchManager(params) {
         let pending = this.#managers.get(params.agentId);
@@ -32,46 +92,93 @@ export class QmdMemoryRuntime {
         return { backend: "builtin" };
     }
     classifyWorkspaceMemoryPaths = classifyWorkspaceMemoryPaths;
-    startSessionSync(params, force = false) {
+    async startSessionSync(params, force = false) {
         if (!this.#corpora.some((corpus) => corpus.kind === "sessions")) {
             return {
                 status: "unavailable",
                 error: 'memory session sync requires a configured "sessions" corpus',
             };
         }
-        const current = this.sessionSyncStatus(params.agentId);
-        if (current.status === "running") {
-            return { status: "already_running", startedAt: current.startedAt };
-        }
+        const directory = this.#sessionSyncDirectory(params.agentId);
+        const statusPath = join(directory, "session-sync-status.json");
+        const running = activeSessionSyncs.get(directory);
+        if (running)
+            return { status: "already_running", startedAt: running };
         const startedAt = new Date().toISOString();
-        this.#sessionSyncStatuses.set(params.agentId, { status: "running", phase: "queued", startedAt });
-        const run = async () => {
-            const { manager, error } = await this.getMemorySearchManager(params);
-            if (!manager)
-                throw new Error(error ?? "memory unavailable");
-            return await manager.syncSessions(force, (phase) => {
-                this.#sessionSyncStatuses.set(params.agentId, { status: "running", phase, startedAt });
-            });
-        };
-        void run().then((result) => {
-            this.#sessionSyncStatuses.set(params.agentId, {
-                status: "completed",
-                startedAt,
-                completedAt: new Date().toISOString(),
-                ...result,
-            });
-        }, (error) => {
-            this.#sessionSyncStatuses.set(params.agentId, {
-                status: "failed",
+        activeSessionSyncs.set(directory, startedAt);
+        try {
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            await atomicWriteJson(statusPath, {
+                status: "running",
+                phase: "queued",
+                pid: process.pid,
                 startedAt,
-                completedAt: new Date().toISOString(),
-                error: error instanceof Error ? error.message : String(error),
             });
-        });
+        }
+        catch (error) {
+            if (activeSessionSyncs.get(directory) === startedAt)
+                activeSessionSyncs.delete(directory);
+            throw error;
+        }
+        void (async () => {
+            let statusWrites = Promise.resolve();
+            const writePhase = (phase) => {
+                statusWrites = statusWrites.then(() => atomicWriteJson(statusPath, {
+                    status: "running",
+                    phase,
+                    pid: process.pid,
+                    startedAt,
+                }));
+            };
+            try {
+                const { manager, error } = await this.getMemorySearchManager(params);
+                if (!manager)
+                    throw new Error(error ?? "memory unavailable");
+                const result = await manager.syncSessions(force, writePhase);
+                await statusWrites;
+                await atomicWriteJson(statusPath, {
+                    status: "completed",
+                    startedAt,
+                    completedAt: new Date().toISOString(),
+                    ...result,
+                });
+            }
+            catch (error) {
+                await statusWrites.catch(() => { });
+                try {
+                    await atomicWriteJson(statusPath, {
+                        status: "failed",
+                        startedAt,
+                        completedAt: new Date().toISOString(),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                catch {
+                    // The next status read converts the persisted running state to interrupted.
+                }
+            }
+            finally {
+                if (activeSessionSyncs.get(directory) === startedAt)
+                    activeSessionSyncs.delete(directory);
+            }
+        })().catch(() => { });
         return { status: "started", startedAt };
     }
-    sessionSyncStatus(agentId) {
-        return this.#sessionSyncStatuses.get(agentId) ?? { status: "idle" };
+    async sessionSyncStatus(agentId) {
+        const directory = this.#sessionSyncDirectory(agentId);
+        const statusPath = join(directory, "session-sync-status.json");
+        const status = await readJson(statusPath);
+        const running = activeSessionSyncs.get(directory);
+        if (running) {
+            return status?.status === "running" && status.startedAt === running
+                ? { status: "running", phase: status.phase, startedAt: running }
+                : { status: "running", phase: "queued", startedAt: running };
+        }
+        if (!status)
+            return { status: "idle" };
+        if (status.status !== "running")
+            return status;
+        return await recoverInterruptedSessionSync(directory, statusPath, status);
     }
     async closeMemorySearchManager(params) {
         const pending = this.#managers.get(params.agentId);
@@ -85,7 +192,7 @@ export class QmdMemoryRuntime {
     }
     async #createManager(cfg, agentId) {
         const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
-        const stateDir = join(resolveStateDir(), "agents", agentId, "unblock-memory");
+        const stateDir = join(this.#stateRoot, "agents", agentId, "unblock-memory");
         const fileCorpora = this.#corpora.filter((corpus) => corpus.kind === "files");
         const sessionCorpus = this.#corpora.find((corpus) => corpus.kind === "sessions");
         const sources = resolveSources(workspaceDir, fileCorpora);
@@ -98,6 +205,7 @@ export class QmdMemoryRuntime {
             workspaceDir,
             dbPath: join(stateDir, "index.sqlite"),
             sources,
+            keepModelsWarm: this.#keepEmbeddingModelWarm,
             analysisExecutable: this.#analysisExecutable,
             ...(sessionCorpus && sessionSource ? {
                 sessions: {
@@ -115,4 +223,7 @@ export class QmdMemoryRuntime {
         await manager.start();
         return manager;
     }
+    #sessionSyncDirectory(agentId) {
+        return join(this.#stateRoot, "agents", agentId, "unblock-memory");
+    }
 }

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },
@@ -14,6 +14,10 @@
     "memory_fetch_cluster": { "replaySafe": true }
   },
   "uiHints": {
+    "keepEmbeddingModelWarm": {
+      "label": "Keep Embedding Model Warm",
+      "help": "Keep the QMD embedding model resident after first use. Disable to unload it after five minutes without model activity."
+    },
     "corpora": {
       "label": "Memory Corpora",
       "help": "Named groups of exact Markdown files, directories, or globs. Relative paths resolve from each agent workspace."
@@ -27,6 +31,10 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
+      "keepEmbeddingModelWarm": {
+        "type": "boolean",
+        "default": true
+      },
       "corpora": {
         "type": "array",
         "minItems": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "preflight": "npm run knip && npm run build && npm run typecheck && npm test && npm run plugin:inspect && npm run plugin:inspect:runtime && npm pack --dry-run"
   },
   "dependencies": {
-    "@unblocklabs/qmd": "https://github.com/unblocklabs-ai/qmd/releases/download/v2.9.1/unblocklabs-qmd-2.9.1.tgz",
+    "@unblocklabs/qmd": "https://github.com/unblocklabs-ai/qmd/releases/download/v2.9.2/unblocklabs-qmd-2.9.2.tgz",
     "chokidar": "5.0.0",
     "picomatch": "^4.0.5",
     "typebox": "1.3.6"