@unblocklabs/unblock-memory 0.2.0 → 0.2.2

package/README.md

@@ -103,7 +103,8 @@ eligible.
 The optional `sessions` corpus reads the current agent's normal OpenClaw SQLite
 store and indexes its active user/assistant transcript branch. It defaults to
 channel and group conversations; add `direct` explicitly to include DMs. Run
-`memory_sync_sessions` to refresh it. Projections are private derived Markdown
+`memory_sync_sessions` to start a refresh, then use `memory_sync_status` to
+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

package/dist/src/manager.d.ts

@@ -37,7 +37,7 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
     });
     start(): Promise<void>;
     sync(params?: MemorySyncParams): Promise<void>;
-    syncSessions(force?: boolean): Promise<SessionSyncResult>;
+    syncSessions(force?: boolean, onPhase?: (phase: "projecting" | "indexing") => void): Promise<SessionSyncResult>;
     recluster(options?: MemoryReclusterOptions, signal?: AbortSignal): Promise<MemoryAnalysisSummary>;
     listClusters(limit?: number): Promise<MemoryClusterList>;
     fetchCluster(params: {

package/dist/src/manager.js

@@ -1,4 +1,4 @@
-import { mkdir } from "node:fs/promises";
+import { mkdir, stat } from "node:fs/promises";
 import { dirname } from "node:path";
 import chokidar from "chokidar";
 import { ensureMemoryAnalysisSchema, latestAnalysisRunId, markMemoryAnalysisStale, readAnalysisSummary, readCluster, readClusters, runAnalysisWorker, } from "./analysis.js";
@@ -151,6 +151,7 @@ export class QmdMemoryManager {
     #files = 0;
     #dirty = true;
     #sessionMetadata = new Map();
+    #sessionManifestMtimeNs;
     constructor(params) {
         this.#dbPath = params.dbPath;
         this.#workspaceDir = params.workspaceDir;
@@ -162,12 +163,39 @@ export class QmdMemoryManager {
     }
     async start() {
         if (this.#sessions) {
-            this.#sessionMetadata = sessionMetadataByPath(await readSessionManifest(this.#sessions.manifestPath));
+            await this.#reloadSessionMetadata();
         }
         this.#startWatcher();
         await this.sync({ reason: "first-use" });
         await this.#watchReady;
     }
+    async #manifestMtimeNs(path) {
+        try {
+            return (await stat(path, { bigint: true })).mtimeNs;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    async #reloadSessionMetadata() {
+        const sessions = this.#sessions;
+        if (!sessions)
+            return;
+        const mtimeNs = await this.#manifestMtimeNs(sessions.manifestPath);
+        const manifest = await readSessionManifest(sessions.manifestPath);
+        this.#sessionMetadata = sessionMetadataByPath(manifest);
+        this.#sessionManifestMtimeNs = mtimeNs;
+    }
+    async #refreshSessionMetadata() {
+        const sessions = this.#sessions;
+        if (!sessions)
+            return;
+        const mtimeNs = await this.#manifestMtimeNs(sessions.manifestPath);
+        if (mtimeNs !== this.#sessionManifestMtimeNs)
+            await this.#reloadSessionMetadata();
+    }
     #startWatcher() {
         const paths = [...new Set([...this.#sources.values()]
                 .filter((source) => source.kind === "files")
@@ -291,16 +319,18 @@ export class QmdMemoryManager {
         };
         return this.#enqueue(run);
     }
-    syncSessions(force = false) {
+    syncSessions(force = false, onPhase) {
         return this.#enqueue(async () => {
             const sessions = this.#sessions;
             if (!sessions)
                 throw new Error('memory session sync requires a configured "sessions" corpus');
+            onPhase?.("projecting");
             const store = await this.#getStore();
             const synced = await syncSessionProjections({
                 ...sessions,
                 force,
                 index: async () => {
+                    onPhase?.("indexing");
                     const update = await store.update({ collections: [sessions.collection] });
                     this.#cleanupRemovedDocuments?.(update.updated + update.removed);
                     const analysisStore = store;
@@ -380,6 +410,9 @@ export class QmdMemoryManager {
         opts?.signal?.throwIfAborted();
         await this.#operationChain;
         const sessions = this.#sessions;
+        if (opts?.sessionFilter && sessions && collections.includes(sessions.collection)) {
+            await this.#refreshSessionMetadata();
+        }
         const allowedPaths = opts?.sessionFilter && sessions && collections.includes(sessions.collection)
             ? sessionAllowedPaths(this.#sessionMetadata, sessions.collection, opts.sessionFilter)
             : undefined;

package/dist/src/plugin.js

@@ -35,6 +35,7 @@ const getParameters = Type.Object({
 const syncSessionsParameters = Type.Object({
     force: Type.Optional(Type.Boolean()),
 }, { additionalProperties: false });
+const syncStatusParameters = Type.Object({}, { additionalProperties: false });
 function createSearchTool(runtime, ctx) {
     const active = getContext(ctx);
     if (!active)
@@ -91,22 +92,26 @@ function createSyncSessionsTool(runtime, ctx) {
     return {
         name: "memory_sync_sessions",
         label: "Sync Memory Sessions",
-        description: "Project and index this agent's configured OpenClaw session transcripts.",
+        description: "Start projecting and indexing this agent's configured OpenClaw session transcripts. Use memory_sync_status to check completion.",
         parameters: syncSessionsParameters,
         async execute(_toolCallId, params) {
             const { force } = Value.Parse(syncSessionsParameters, params);
-            const { manager, error } = await runtime.getMemorySearchManager(active);
-            if (!manager)
-                return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });
-            try {
-                return jsonResult(await manager.syncSessions(force));
-            }
-            catch (syncError) {
-                return jsonResult({
-                    status: "unavailable",
-                    error: syncError instanceof Error ? syncError.message : String(syncError),
-                });
-            }
+            return jsonResult(runtime.startSessionSync(active, force));
+        },
+    };
+}
+function createSyncStatusTool(runtime, ctx) {
+    const active = getContext(ctx);
+    if (!active)
+        return null;
+    return {
+        name: "memory_sync_status",
+        label: "Memory Session Sync Status",
+        description: "Check the current or latest session transcript sync.",
+        parameters: syncStatusParameters,
+        async execute(_toolCallId, params) {
+            Value.Parse(syncStatusParameters, params);
+            return jsonResult(runtime.sessionSyncStatus(active.agentId));
         },
     };
 }
@@ -281,6 +286,7 @@ export function registerUnblockMemory(api) {
     api.registerTool((ctx) => createSearchTool(runtime, ctx), { names: ["memory_search"] });
     api.registerTool((ctx) => createGetTool(runtime, ctx), { names: ["memory_get"] });
     api.registerTool((ctx) => createSyncSessionsTool(runtime, ctx), { names: ["memory_sync_sessions"] });
+    api.registerTool((ctx) => createSyncStatusTool(runtime, ctx), { names: ["memory_sync_status"] });
     api.registerTool((ctx) => createReclusterTool(runtime, ctx), { names: ["memory_recluster"] });
     api.registerTool((ctx) => createListClustersTool(runtime, ctx), { names: ["memory_list_clusters"] });
     api.registerTool((ctx) => createFetchClusterTool(runtime, ctx), { names: ["memory_fetch_cluster"] });

package/dist/src/runtime.d.ts

@@ -2,6 +2,33 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk/plugin-entry";
 import type { CorpusConfig } from "./config.js";
 import type { MemoryPluginRuntimeContract } from "./contracts.js";
 import { QmdMemoryManager } from "./manager.js";
+import type { SessionSyncResult } from "./session-sync.js";
+export type SessionSyncStatus = {
+    status: "idle";
+} | {
+    status: "running";
+    phase: "queued" | "projecting" | "indexing";
+    startedAt: string;
+} | ({
+    status: "completed";
+    startedAt: string;
+    completedAt: string;
+} & SessionSyncResult) | {
+    status: "failed";
+    startedAt: string;
+    completedAt: string;
+    error: string;
+};
+export type SessionSyncStartResult = {
+    status: "started";
+    startedAt: string;
+} | {
+    status: "already_running";
+    startedAt: string;
+} | {
+    status: "unavailable";
+    error: string;
+};
 export declare class QmdMemoryRuntime implements MemoryPluginRuntimeContract {
     #private;
     constructor(corpora: readonly CorpusConfig[], analysisExecutable?: string);
@@ -18,6 +45,12 @@ export declare class QmdMemoryRuntime implements MemoryPluginRuntimeContract {
     resolveMemoryBackendConfig(): {
         backend: "builtin";
     };
+    classifyWorkspaceMemoryPaths: NonNullable<MemoryPluginRuntimeContract["classifyWorkspaceMemoryPaths"]>;
+    startSessionSync(params: {
+        cfg: OpenClawConfig;
+        agentId: string;
+    }, force?: boolean): SessionSyncStartResult;
+    sessionSyncStatus(agentId: string): SessionSyncStatus;
     closeMemorySearchManager(params: {
         agentId: string;
     }): Promise<void>;

package/dist/src/runtime.js

@@ -4,10 +4,12 @@ import { resolveAgentIdentity } from "openclaw/plugin-sdk/agent-runtime";
 import { QmdMemoryManager } from "./manager.js";
 import { resolveTimezone } from "./session-projector.js";
 import { resolveSessionSource, resolveSources } from "./sources.js";
+import { classifyWorkspaceMemoryPaths } from "./workspace-path-classifier.js";
 export class QmdMemoryRuntime {
     #corpora;
     #analysisExecutable;
     #managers = new Map();
+    #sessionSyncStatuses = new Map();
     constructor(corpora, analysisExecutable) {
         this.#corpora = corpora;
         this.#analysisExecutable = analysisExecutable;
@@ -29,6 +31,48 @@ export class QmdMemoryRuntime {
     resolveMemoryBackendConfig() {
         return { backend: "builtin" };
     }
+    classifyWorkspaceMemoryPaths = classifyWorkspaceMemoryPaths;
+    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 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",
+                startedAt,
+                completedAt: new Date().toISOString(),
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+        return { status: "started", startedAt };
+    }
+    sessionSyncStatus(agentId) {
+        return this.#sessionSyncStatuses.get(agentId) ?? { status: "idle" };
+    }
     async closeMemorySearchManager(params) {
         const pending = this.#managers.get(params.agentId);
         this.#managers.delete(params.agentId);

package/dist/src/workspace-path-classifier.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryPluginRuntimeContract } from "./contracts.js";
+type ClassifyWorkspaceMemoryPaths = NonNullable<MemoryPluginRuntimeContract["classifyWorkspaceMemoryPaths"]>;
+export declare const classifyWorkspaceMemoryPaths: ClassifyWorkspaceMemoryPaths;
+export {};

package/dist/src/workspace-path-classifier.js

@@ -0,0 +1,41 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isPathStrictlyInside } from "openclaw/plugin-sdk/file-access-runtime";
+import { readMemoryArtifactProvenance } from "openclaw/plugin-sdk/memory-core-host-runtime-core";
+export const classifyWorkspaceMemoryPaths = async (params) => await Promise.all(params.relativePaths.map(async (relativePath) => {
+    let workspacePath;
+    let filePath;
+    try {
+        [workspacePath, filePath] = await Promise.all([
+            fs.realpath(params.workspaceDir),
+            fs.realpath(path.resolve(params.workspaceDir, relativePath)),
+        ]);
+    }
+    catch {
+        return { relativePath, originClass: "untrusted" };
+    }
+    if (!isPathStrictlyInside(workspacePath, filePath)) {
+        return { relativePath, originClass: "untrusted" };
+    }
+    const workspaceRelativePath = path.relative(workspacePath, filePath);
+    const segments = workspaceRelativePath.split(path.sep);
+    const curatedRoot = segments.length === 1 &&
+        ["MEMORY.md", "memory.md", "USER.md"].includes(segments[0]);
+    if ((segments.length === 1 && ["DREAMS.md", "dreams.md"].includes(segments[0])) ||
+        (segments[0] === "memory" && ["dreaming", ".dreams"].includes(segments[1]))) {
+        return { relativePath, originClass: "system" };
+    }
+    const isWorkspaceMemory = curatedRoot ||
+        (segments[0] === "memory" && segments.at(-1)?.endsWith(".md") === true);
+    const normalizedPath = workspaceRelativePath.replaceAll(path.sep, "/");
+    const recorded = isWorkspaceMemory
+        ? await readMemoryArtifactProvenance({
+            workspaceDir: params.workspaceDir,
+            relativePath: normalizedPath,
+        })
+        : undefined;
+    return {
+        relativePath,
+        originClass: recorded?.originClass ?? (isWorkspaceMemory ? "agent" : "untrusted"),
+    };
+}));

package/openclaw.plugin.json

@@ -1,13 +1,14 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },
-  "contracts": { "tools": ["memory_search", "memory_get", "memory_sync_sessions", "memory_recluster", "memory_list_clusters", "memory_fetch_cluster"] },
+  "contracts": { "tools": ["memory_search", "memory_get", "memory_sync_sessions", "memory_sync_status", "memory_recluster", "memory_list_clusters", "memory_fetch_cluster"] },
   "toolMetadata": {
     "memory_sync_sessions": { "sideEffecting": true },
+    "memory_sync_status": { "replaySafe": true },
     "memory_recluster": { "sideEffecting": true },
     "memory_list_clusters": { "replaySafe": true },
     "memory_fetch_cluster": { "replaySafe": true }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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": "github:unblocklabs-ai/qmd#937cd82f9b41818d9eb5f78b94394cb5023b5daf",
+    "@unblocklabs/qmd": "https://github.com/unblocklabs-ai/qmd/releases/download/v2.9.1/unblocklabs-qmd-2.9.1.tgz",
     "chokidar": "5.0.0",
     "picomatch": "^4.0.5",
     "typebox": "1.3.6"