@unblocklabs/unblock-memory 0.3.17 → 0.3.18

package/README.md

@@ -731,12 +731,12 @@ session manifest. The projected file modification time matches the session
 start time for meaningful chronological cluster reads. Session results include
 provider, chat type, conversation identity, and start time as an ISO 8601 timestamp. They
 participate in the same search and clustering index as file memory. The plugin
-automatically refreshes each configured agent's sessions every 15 minutes while
+automatically checks each configured agent's sessions every 60 minutes while
 the Gateway runs. Set `syncIntervalMinutes` on the `sessions` corpus to an integer
 from `1` to `1440`, or `0` for manual-only syncing. For example:
 
 ```json
-{ "name": "sessions", "kind": "sessions", "syncIntervalMinutes": 15 }
+{ "name": "sessions", "kind": "sessions", "syncIntervalMinutes": 60 }
 ```
 
 The first refresh runs after one interval, not during startup. Restart the
@@ -745,6 +745,17 @@ sync is skipped, and failures are visible through `memory_sync_status` and retri
 at the next interval. `memory_sync_sessions` still provides an immediate manual
 refresh. Syncing and embedding run inside the Gateway process, without an LLM turn.
 
+Quiet checks compare source metadata and the last successful index checkpoint
+before initializing the memory manager. Unchanged sessions skip QMD updates and
+embedding. New assistant answers count too, not just human messages. Changed
+transcripts are projected and content-hashed; tool-only or filtered additions
+that leave the indexed text unchanged also skip indexing. Empty/filtered sessions
+are remembered. Index changes, missing projections, changed projection settings,
+QMD upgrades and incomplete runs invalidate the skip checkpoint; `force: true`
+bypasses both gates. `memory_sync_status` reports `lastCheckedAt`, `lastIndexedAt`
+and `skipReason` (`no_changes` or `no_indexable_changes`) separately. Existing
+explicit intervals remain unchanged on upgrade; set them to `60` for hourly checks.
+
 Indexes live at `~/.openclaw/agents/<agentId>/unblock-memory/index.sqlite` (or the
 equivalent configured OpenClaw state directory). Durable agent-supplied event
 dates and maintenance proposals live separately in `curation.sqlite`, so a QMD

package/dist/src/config.js

@@ -172,7 +172,7 @@ function resolveCorpora(value) {
                 !chatTypes.every((chatType) => CHAT_TYPES.includes(chatType))) {
                 throw new Error(`unblock-memory corpus sessions chatTypes must contain channel, group, or direct`);
             }
-            const syncIntervalMinutes = corpus.syncIntervalMinutes ?? 15;
+            const syncIntervalMinutes = corpus.syncIntervalMinutes ?? 60;
             if (typeof syncIntervalMinutes !== "number" || !Number.isInteger(syncIntervalMinutes) ||
                 syncIntervalMinutes < 0 || syncIntervalMinutes > 1440) {
                 throw new Error("unblock-memory corpus sessions syncIntervalMinutes must be an integer between 0 and 1440");

package/dist/src/manager.js

@@ -534,12 +534,14 @@ export class QmdMemoryManager {
             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,
+                indexPath: this.#dbPath,
+                indexReady: async () => (await (await this.#getStore()).getStatus()).needsEmbedding === 0,
                 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;
@@ -561,6 +563,9 @@ export class QmdMemoryManager {
                 },
             });
             this.#sessionMetadata = sessionMetadataByPath(synced.manifest);
+            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);

package/dist/src/runtime.d.ts

@@ -2,7 +2,7 @@ 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";
+import { type SessionSyncResult } from "./session-sync.js";
 export type SessionSyncStatus = {
     status: "idle";
 } | {

package/dist/src/runtime.js

@@ -5,6 +5,7 @@ import { resolveAgentDir, resolveAgentWorkspaceDir, resolveStateDir, } from "ope
 import { listAgentIds, resolveAgentIdentity } from "openclaw/plugin-sdk/agent-runtime";
 import { QmdMemoryManager } from "./manager.js";
 import { resolveTimezone } from "./session-projector.js";
+import { unchangedSessionSync } from "./session-sync.js";
 import { resolveConfiguredSkillPath, resolveSessionSource, resolveSources } from "./sources.js";
 import { classifyWorkspaceMemoryPaths } from "./workspace-path-classifier.js";
 const activeSessionSyncs = new Map();
@@ -149,10 +150,15 @@ export class QmdMemoryRuntime {
                 }));
             };
             try {
-                const { manager, error } = await this.getMemorySearchManager(params);
-                if (!manager)
-                    throw new Error(error ?? "memory unavailable");
-                const result = await manager.syncSessions(force, writePhase);
+                const sessions = this.#sessionConfig(params.cfg, params.agentId);
+                let result = !force && sessions
+                    ? await unchangedSessionSync(sessions, join(directory, "index.sqlite")) : undefined;
+                if (!result) {
+                    const { manager, error } = await this.getMemorySearchManager(params);
+                    if (!manager)
+                        throw new Error(error ?? "memory unavailable");
+                    result = await manager.syncSessions(force, writePhase);
+                }
                 await statusWrites;
                 await atomicWriteJson(statusPath, {
                     status: "completed",
@@ -224,10 +230,10 @@ export class QmdMemoryRuntime {
         const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
         const stateDir = join(this.#stateRoot, "agents", agentId, "unblock-memory");
         const fileCorpora = this.#corpora.filter((corpus) => corpus.kind === "files" || corpus.kind === "skills");
-        const sessionCorpus = this.#corpora.find((corpus) => corpus.kind === "sessions");
+        const sessions = this.#sessionConfig(cfg, agentId);
         const sources = resolveSources(workspaceDir, fileCorpora);
-        const sessionSource = sessionCorpus
-            ? resolveSessionSource(join(stateDir, "sessions"), sessionCorpus.chatTypes)
+        const sessionSource = sessions
+            ? resolveSessionSource(sessions.outputDir, sessions.chatTypes)
             : undefined;
         if (sessionSource)
             sources.push(sessionSource);
@@ -238,23 +244,26 @@ export class QmdMemoryRuntime {
             sources,
             keepModelsWarm: this.#keepEmbeddingModelWarm,
             analysisExecutable: this.#analysisExecutable,
-            ...(sessionCorpus && sessionSource ? {
-                sessions: {
-                    agentId,
-                    agentName: resolveAgentIdentity(cfg, agentId)?.name?.trim() || agentId,
-                    chatTypes: sessionCorpus.chatTypes,
-                    maxExpandedTokens: sessionCorpus.maxExpandedTokens,
-                    collection: sessionSource.collection,
-                    databasePath: join(resolveAgentDir(cfg, agentId), "openclaw-agent.sqlite"),
-                    manifestPath: join(stateDir, "sessions-manifest.json"),
-                    outputDir: sessionSource.root,
-                    timezone: resolveTimezone(cfg.agents?.defaults?.userTimezone?.trim()),
-                },
-            } : {}),
+            sessions,
         });
         await manager.start();
         return manager;
     }
+    #sessionConfig(cfg, agentId) {
+        const corpus = this.#corpora.find(corpus => corpus.kind === "sessions");
+        if (!corpus)
+            return;
+        const stateDir = this.#sessionSyncDirectory(agentId);
+        const source = resolveSessionSource(join(stateDir, "sessions"), corpus.chatTypes);
+        return {
+            agentId, agentName: resolveAgentIdentity(cfg, agentId)?.name?.trim() || agentId,
+            chatTypes: corpus.chatTypes, maxExpandedTokens: corpus.maxExpandedTokens,
+            collection: source.collection, outputDir: source.root,
+            databasePath: join(resolveAgentDir(cfg, agentId), "openclaw-agent.sqlite"),
+            manifestPath: join(stateDir, "sessions-manifest.json"),
+            timezone: resolveTimezone(cfg.agents?.defaults?.userTimezone?.trim()),
+        };
+    }
     #sessionSyncDirectory(agentId) {
         return join(this.#stateRoot, "agents", agentId, "unblock-memory");
     }

package/dist/src/session-sync.d.ts

@@ -9,10 +9,15 @@ type IndexedSession = SessionMetadata & {
     projectionHash: string;
     documentPath: string;
     projectorVersion: number;
+    sourceFingerprint?: string;
 };
 export type SessionManifest = {
     version: number;
     lastSuccessfulSyncAt?: number;
+    lastIndexedAt?: number;
+    projectionKey?: string;
+    indexSignature?: string;
+    ignoredSessions?: Record<string, string>;
     sessions: Record<string, IndexedSession>;
 };
 export type SessionSyncResult = {
@@ -24,11 +29,12 @@ export type SessionSyncResult = {
     failed: number;
     embedded: number;
     lastSuccessfulSyncAt: number;
+    lastCheckedAt?: number;
+    lastIndexedAt?: number;
+    skipReason?: "no_changes" | "no_indexable_changes";
     diagnostics?: NonNullable<SessionProjectionInput["diagnostics"]>;
 };
-export declare function readSessionManifest(path: string): Promise<SessionManifest>;
-export declare function sessionMetadataByPath(manifest: SessionManifest): Map<string, SessionMetadata>;
-export declare function syncSessionProjections(params: {
+type ProjectionOptions = {
     databasePath: string;
     outputDir: string;
     manifestPath: string;
@@ -36,7 +42,14 @@ export declare function syncSessionProjections(params: {
     agentName: string;
     timezone: string;
     chatTypes: readonly ChatType[];
+};
+export declare function unchangedSessionSync(params: ProjectionOptions, indexPath: string): Promise<SessionSyncResult | undefined>;
+export declare function readSessionManifest(path: string): Promise<SessionManifest>;
+export declare function sessionMetadataByPath(manifest: SessionManifest): Map<string, SessionMetadata>;
+export declare function syncSessionProjections(params: ProjectionOptions & {
     force?: boolean;
+    indexPath?: string;
+    indexReady?: () => Promise<boolean>;
     index?: () => Promise<number>;
 }): Promise<{
     result: SessionSyncResult;

package/dist/src/session-sync.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { chmod, mkdir, readFile, rename, unlink, utimes, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { DatabaseSync } from "node:sqlite";
@@ -7,6 +7,12 @@ import { projectSession, sessionDocumentPath, } from "./session-projector.js";
 const MANIFEST_VERSION = 1;
 export const PROJECTOR_VERSION = 6;
 const SUPPORTED_SCHEMA_VERSIONS = new Set([17, 18, 19]);
+// Source lives in src/, published code in dist/src/. Read our own pinned dependency
+// metadata, not QMD internals (which may also be substituted by runtime inspectors).
+const sourcePackage = new URL("../package.json", import.meta.url);
+const packageMetadata = JSON.parse(readFileSync(existsSync(sourcePackage)
+    ? sourcePackage : new URL("../../package.json", import.meta.url), "utf8"));
+const indexVersion = [packageMetadata.version, packageMetadata.dependencies["@unblocklabs/qmd"]];
 const REQUIRED_COLUMNS = {
     schema_meta: ["meta_key", "role", "schema_version", "agent_id", "app_version"],
     session_windows: [
@@ -21,6 +27,32 @@ const REQUIRED_COLUMNS = {
     session_transcript_active_events: ["session_id", "active_position", "event_seq", "message_position"],
     transcript_rewrite_watermarks: ["session_id", "generation"],
 };
+function projectionKey(params) {
+    return JSON.stringify([PROJECTOR_VERSION, params.databasePath, params.agentId,
+        params.agentName, params.timezone, [...params.chatTypes].sort()]);
+}
+// Conservative proof: any index/WAL write, replacement or QMD upgrade invalidates it.
+// This avoids depending on QMD's private embedding schema or opening/loading its store.
+function sessionIndexSignature(databasePath) {
+    try {
+        const fingerprint = (path) => {
+            const stat = statSync(path, { bigint: true });
+            return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].map(String);
+        };
+        let wal = null;
+        try {
+            wal = fingerprint(`${databasePath}-wal`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        return JSON.stringify([indexVersion, fingerprint(databasePath), wal]);
+    }
+    catch {
+        return undefined;
+    }
+}
 function projectionPath(outputDir, documentPath) {
     const root = resolve(outputDir);
     const target = resolve(root, documentPath);
@@ -106,6 +138,7 @@ function readSnapshot(params) {
       ORDER BY active.active_position
     `);
         const events = new Map();
+        const changed = new Set();
         for (const window of windows) {
             const metadata = {
                 sessionId: window.sessionId,
@@ -117,18 +150,21 @@ function readSnapshot(params) {
             };
             const previous = params.previousManifest.sessions[window.sessionId];
             const documentPath = sessionDocumentPath(metadata);
+            const sourceFingerprint = JSON.stringify(window);
             const unchanged = !params.force &&
-                previous?.sourceGeneration === window.sourceGeneration &&
-                previous.maxSeq === (window.maxSeq ?? 0) &&
-                previous.projectorVersion === PROJECTOR_VERSION &&
-                previous.documentPath === documentPath &&
-                existsSync(projectionPath(params.outputDir, documentPath));
+                (previous ? previous.sourceFingerprint === sourceFingerprint &&
+                    previous.projectorVersion === PROJECTOR_VERSION &&
+                    previous.documentPath === documentPath &&
+                    existsSync(projectionPath(params.outputDir, documentPath)) :
+                    params.previousManifest.ignoredSessions?.[window.sessionId] === sourceFingerprint);
             if (!unchanged) {
-                events.set(window.sessionId, readEvents.all(window.sessionId));
+                changed.add(window.sessionId);
+                if (!params.metadataOnly)
+                    events.set(window.sessionId, readEvents.all(window.sessionId));
             }
         }
         db.exec("COMMIT");
-        return { windows, events };
+        return { windows, events, changed };
     }
     catch (error) {
         try {
@@ -141,6 +177,20 @@ function readSnapshot(params) {
         db.close();
     }
 }
+export async function unchangedSessionSync(params, indexPath) {
+    const manifest = await readSessionManifest(params.manifestPath);
+    if (!manifest.lastSuccessfulSyncAt || manifest.projectionKey !== projectionKey(params) ||
+        !manifest.indexSignature || manifest.indexSignature !== sessionIndexSignature(indexPath))
+        return;
+    const snapshot = readSnapshot({ ...params, previousManifest: manifest, force: false, metadataOnly: true });
+    const ids = new Set(snapshot.windows.map(window => window.sessionId));
+    if (snapshot.changed.size || Object.keys(manifest.sessions).some(id => !ids.has(id)) ||
+        Object.keys(manifest.ignoredSessions ?? {}).some(id => !ids.has(id)))
+        return;
+    return { scanned: ids.size, unchanged: ids.size, updated: 0, removed: 0,
+        skipped: 0, failed: 0, embedded: 0, lastSuccessfulSyncAt: manifest.lastSuccessfulSyncAt,
+        lastCheckedAt: Date.now(), lastIndexedAt: manifest.lastIndexedAt, skipReason: "no_changes" };
+}
 function emptyManifest() {
     return { version: MANIFEST_VERSION, sessions: {} };
 }
@@ -205,10 +255,11 @@ export async function syncSessionProjections(params) {
     const previousManifest = await readSessionManifest(params.manifestPath);
     const snapshot = readSnapshot({
         ...params,
-        force: params.force === true,
+        force: params.force === true || previousManifest.projectionKey !== projectionKey(params),
         previousManifest,
     });
     const sessions = {};
+    const ignoredSessions = {};
     const counts = { unchanged: 0, updated: 0, removed: 0, skipped: 0, failed: 0 };
     const diagnostics = { internalMessagesCleaned: 0, attachmentsCleaned: 0, attachmentBudgetSkipped: 0 };
     await mkdir(params.outputDir, { recursive: true, mode: 0o700 });
@@ -226,7 +277,10 @@ export async function syncSessionProjections(params) {
         };
         const documentPath = sessionDocumentPath(metadata);
         if (events === undefined) {
-            sessions[window.sessionId] = previous;
+            if (previous)
+                sessions[window.sessionId] = previous;
+            else
+                ignoredSessions[window.sessionId] = JSON.stringify(window);
             counts.unchanged += 1;
             continue;
         }
@@ -255,6 +309,7 @@ export async function syncSessionProjections(params) {
             continue;
         }
         if (!content) {
+            ignoredSessions[window.sessionId] = JSON.stringify(window);
             counts.skipped += 1;
             if (previous) {
                 await remove(projectionPath(params.outputDir, previous.documentPath));
@@ -263,8 +318,13 @@ export async function syncSessionProjections(params) {
             continue;
         }
         const target = projectionPath(params.outputDir, documentPath);
-        await atomicWrite(target, content, 0o600);
-        await utimes(target, new Date(), new Date(metadata.startedAt));
+        const hash = projectionHash(content);
+        const contentChanged = params.force === true || previous?.projectorVersion !== PROJECTOR_VERSION ||
+            previous.projectionHash !== hash || previous.documentPath !== documentPath || !existsSync(target);
+        if (contentChanged) {
+            await atomicWrite(target, content, 0o600);
+            await utimes(target, new Date(), new Date(metadata.startedAt));
+        }
         if (previous?.documentPath && previous.documentPath !== documentPath) {
             await remove(projectionPath(params.outputDir, previous.documentPath));
         }
@@ -274,11 +334,15 @@ export async function syncSessionProjections(params) {
             maxSeq: window.maxSeq,
             activeEventCount: window.activeEventCount,
             sizeBytes: Buffer.byteLength(content),
-            projectionHash: projectionHash(content),
+            projectionHash: hash,
             documentPath,
             projectorVersion: PROJECTOR_VERSION,
+            sourceFingerprint: JSON.stringify(window),
         };
-        counts.updated += 1;
+        if (contentChanged)
+            counts.updated += 1;
+        else
+            counts.unchanged += 1;
     }
     for (const [sessionId, session] of Object.entries(previousManifest.sessions)) {
         if (sessions[sessionId] || snapshot.windows.some((window) => window.sessionId === sessionId))
@@ -286,11 +350,25 @@ export async function syncSessionProjections(params) {
         await remove(projectionPath(params.outputDir, session.documentPath));
         counts.removed += 1;
     }
-    const embedded = await params.index?.() ?? 0;
+    const needsIndex = params.force === true || counts.updated > 0 || counts.removed > 0 ||
+        previousManifest.projectionKey !== projectionKey(params) ||
+        !previousManifest.indexSignature || !params.indexPath ||
+        previousManifest.indexSignature !== sessionIndexSignature(params.indexPath);
+    const embedded = needsIndex ? await params.index?.() ?? 0 : 0;
     const lastSuccessfulSyncAt = Date.now();
+    const indexed = needsIndex && params.index !== undefined;
+    const signature = params.indexPath ? sessionIndexSignature(params.indexPath) : undefined;
+    const indexReady = indexed && (await params.indexReady?.() ?? false);
+    const lastIndexedAt = indexed ? lastSuccessfulSyncAt : previousManifest.lastIndexedAt;
     const manifest = {
         version: MANIFEST_VERSION,
         lastSuccessfulSyncAt,
+        lastIndexedAt,
+        projectionKey: projectionKey(params),
+        // Never certify an index mutation that happened during a skipped run or readiness check.
+        indexSignature: counts.failed > 0 ? undefined : !needsIndex ? previousManifest.indexSignature :
+            indexReady && params.indexPath && signature === sessionIndexSignature(params.indexPath) ? signature : undefined,
+        ignoredSessions,
         sessions,
     };
     await atomicWrite(params.manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 0o600);
@@ -300,6 +378,9 @@ export async function syncSessionProjections(params) {
             ...counts,
             embedded,
             lastSuccessfulSyncAt,
+            lastCheckedAt: lastSuccessfulSyncAt,
+            lastIndexedAt,
+            ...(!needsIndex ? { skipReason: "no_indexable_changes" } : {}),
             diagnostics,
         },
         manifest,

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": true },
@@ -186,8 +186,8 @@
                   "type": "integer",
                   "minimum": 0,
                   "maximum": 1440,
-                  "default": 15,
-                  "description": "Refresh sessions every N minutes while the Gateway runs; 0 disables automatic sync. First refresh is after one interval."
+                  "default": 60,
+                  "description": "Check for session changes every N minutes while the Gateway runs; unchanged sessions skip indexing. 0 disables automatic sync. First check is after one interval."
                 },
                 "chatTypes": {
                   "type": "array",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",