@unblocklabs/unblock-memory 0.2.3 → 0.2.5

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,22 +39,29 @@ directories, or globs into named corpora:
     entries: {
       "unblock-memory": {
         config: {
+          // Default: avoid repeated model cold starts after idle periods.
+          keepEmbeddingModelWarm: true,
           corpora: [
             {
               name: "memory",
               kind: "files",
               paths: ["MEMORY.md", "USER.md", "memory/**/*.md"],
             },
-            {
-              name: "projects",
-              kind: "files",
-              paths: ["/absolute/shared/**/*.md"],
-            },
             {
               name: "sessions",
               kind: "sessions",
               chatTypes: ["channel", "group"],
             },
+            {
+              name: "canon",
+              kind: "files",
+              paths: ["knowledge/canon/**/*.md"],
+            },
+            {
+              name: "reflections",
+              kind: "files",
+              paths: ["knowledge/reflections/**/*.md"],
+            },
           ],
           // Optional: omit unless the local analysis worker is installed.
           analysis: {
@@ -73,8 +80,12 @@ 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
+`corpora: ["canon"]` to search selected corpora or `corpora: ["all"]` to
 request all of them explicitly. Search results include their corpus name and
 remain readable by passing the returned `qmd://` path to `memory_get`.
 
@@ -107,9 +118,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
@@ -174,5 +186,50 @@ A failed rebuild leaves the stale result intact, while a successful rebuild
 atomically replaces it. Analysis is never scheduled automatically. If the worker
 is absent or fails, `memory_search` and `memory_get` continue to work.
 
+## Curating canon and reflections
+
+The plugin bundles the `memory-curator` skill for turning useful clusters into
+durable knowledge. It becomes available when the plugin is enabled. If the
+agent has an explicit skill allowlist, include `memory-curator`.
+
+Keep curated files outside `memory/**` so each file belongs to only one corpus:
+
+```text
+knowledge/
+├── canon/
+│   └── gateway-restarts.md
+└── reflections/
+    └── 2026-08-26.md
+```
+
+Canon files are stable topic files updated in place. Each one contains only the
+current affirmative rule or understanding, its update time, current rationale,
+and `qmd://` evidence links. Do not include old procedures, changelogs, or a
+`Supersedes` section: semantic chunking may retrieve those passages without the
+surrounding warning that they are obsolete.
+
+Reflection files are daily or timestamped and append-oriented. They hold useful
+patterns, hypotheses, contradictions, and uncertainty, but are not
+authoritative. Both corpora participate in later search and clustering, so a
+later run can reconsider prior reasoning. Repeated derived text is not
+independent corroboration; durable canon still needs underlying source evidence.
+
+For a manual run, ask the agent:
+
+```text
+Use $memory-curator to review my memory clusters and curate any durable updates.
+```
+
+For recurring curation, use an OpenClaw automation with the same thin message:
+
+```text
+Use $memory-curator to run the scheduled memory curation cycle.
+```
+
+The skill lists current clusters, reclusters only when analysis is missing or
+stale, follows representative sources with `memory_get`, and may correctly
+write nothing. Its own writes are indexed for the next cycle; it does not
+recluster recursively in the same run.
+
 Existing `unblock-qmd` indexes are derived caches and may be left in place;
 Unblock Memory rebuilds its own index from configured corpora.

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",
+            });
         },
     };
 }
@@ -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

@@ -40,7 +40,11 @@ type StoredRunningSessionSync = Extract<StoredSessionSyncStatus, {
 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, stateRoot?: string);
+    constructor(corpora: readonly CorpusConfig[], options?: {
+        analysisExecutable?: string;
+        keepEmbeddingModelWarm?: boolean;
+        stateRoot?: string;
+    });
     getMemorySearchManager(params: {
         cfg: OpenClawConfig;
         agentId: string;

package/dist/src/runtime.js

@@ -65,12 +65,14 @@ export async function recoverInterruptedSessionSync(directory, statusPath, stale
 export class QmdMemoryRuntime {
     #corpora;
     #analysisExecutable;
+    #keepEmbeddingModelWarm;
     #stateRoot;
     #managers = new Map();
-    constructor(corpora, analysisExecutable, stateRoot = resolveStateDir()) {
+    constructor(corpora, options = {}) {
         this.#corpora = corpora;
-        this.#analysisExecutable = analysisExecutable;
-        this.#stateRoot = stateRoot;
+        this.#analysisExecutable = options.analysisExecutable;
+        this.#keepEmbeddingModelWarm = options.keepEmbeddingModelWarm ?? true;
+        this.#stateRoot = options.stateRoot ?? resolveStateDir();
     }
     async getMemorySearchManager(params) {
         let pending = this.#managers.get(params.agentId);
@@ -203,6 +205,7 @@ export class QmdMemoryRuntime {
             workspaceDir,
             dbPath: join(stateDir, "index.sqlite"),
             sources,
+            keepModelsWarm: this.#keepEmbeddingModelWarm,
             analysisExecutable: this.#analysisExecutable,
             ...(sessionCorpus && sessionSource ? {
                 sessions: {

package/openclaw.plugin.json

@@ -1,10 +1,11 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },
+  "skills": ["./skills"],
   "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 },
@@ -14,6 +15,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 +32,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.3",
+  "version": "0.2.5",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "access": "public",
     "provenance": true
   },
-  "files": ["dist", "README.md", "openclaw.plugin.json"],
+  "files": ["dist", "skills", "README.md", "openclaw.plugin.json"],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -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"

package/skills/memory-curator/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: memory-curator
+description: Review Unblock Memory clusters and turn supported current knowledge into canon or exploratory reasoning into reflections.
+---
+
+# Memory Curator
+
+Use Unblock Memory's semantic clusters to maintain durable workspace knowledge.
+Clusters show similarity, not truth or consensus. Prefer no write over a weak or
+duplicative artifact.
+
+## Review clusters
+
+1. Call `memory_list_clusters`.
+2. If analysis is missing or stale, call `memory_recluster`, then list again.
+3. Fetch useful clusters with `memory_fetch_cluster`. Treat noise as optional
+   review material, not automatically important content.
+4. Follow representative `qmd://` source paths with `memory_get` whenever the
+   excerpt lacks context or a conclusion could change durable knowledge.
+5. Distinguish underlying memory or session evidence from earlier canon and
+   reflections. Derived artifacts may help locate, challenge, or revise an
+   understanding, but repetition does not make them independent evidence.
+6. For each reviewed cluster, choose canon, reflection, or no write.
+
+## Write canon
+
+Use `knowledge/canon/<stable-topic>.md` for a supported, durable rule or current
+understanding. Update the topic file in place instead of creating dated copies.
+
+Every semantic chunk in canon must remain correct if retrieved alone:
+
+- State only the current affirmative truth.
+- Remove obsolete instructions rather than preserving them for comparison.
+- Never add `Supersedes`, history, changelog, old-process, or migration sections.
+- Include a human-readable `Updated` timestamp, the current rationale, and
+  `qmd://` evidence citations.
+- Preserve uncertainty in the claim itself. If the evidence does not support a
+  stable current claim, write a reflection or nothing.
+
+A concise shape is sufficient:
+
+```markdown
+# Topic
+
+Updated: 2026-08-26 14:30 EDT
+
+## Current understanding
+
+Present-tense rule or facts.
+
+## Rationale
+
+Why this is the current understanding.
+
+## Evidence
+
+- qmd://memory/...
+- qmd://sessions/...
+```
+
+## Write reflections
+
+Use `knowledge/reflections/YYYY-MM-DD.md` for patterns, hypotheses,
+contradictions, open questions, or reasoning worth revisiting. Append a
+timestamped section when the day's file already exists. Label uncertainty
+plainly and include the `qmd://` evidence examined. Reflections are not
+authoritative instructions.
+
+## Finish the cycle
+
+- Do not rewrite raw memory or session projections.
+- Avoid restating knowledge already captured accurately.
+- Verify new or updated knowledge with `memory_search`, selecting `canon` or
+  `reflections` when useful.
+- Report clusters reviewed, files changed, evidence used, uncertainties, and
+  intentional skips.
+- Do not recluster again after this cycle's writes. Let them enter the next
+  scheduled cycle so the run cannot recursively react to its own output.