@unblocklabs/unblock-memory 0.3.0 → 0.3.2

package/README.md

@@ -76,7 +76,7 @@ directories, or globs into named corpora:
           skillWhisperer: {
             enabled: false,
             historyMessages: 5,
-            minScore: 0.4,
+            minScore: 0.5,
             cooldownTurns: 10,
           },
           // Optional: omit unless the local analysis worker is installed.
@@ -111,22 +111,25 @@ Skill Whisperer is an optional semantic reminder for user turns. Configure one
 isolated `skills` corpus, set `skillWhisperer.enabled` to `true`, and authorize
 `plugins.entries.unblock-memory.hooks.allowConversationAccess`. The feature
 embeds the current prompt plus the configured number of prior user/assistant
-messages, searches only skill files, and prepends at most one name/path hint
-when the best eligible match reaches `minScore`. It never opens or invokes a
-skill automatically.
+messages, compares it with each configured skill's frontmatter `name` and
+`description`, and prepends at most one name/path hint when the best match
+reaches `minScore`. Full skill procedures do not influence routing. The plugin
+never opens or invokes a skill automatically.
 
-The defaults use five prior messages, a calibrated score threshold of `0.4`,
+The defaults use five prior messages, a calibrated score threshold of `0.5`,
 and a ten-turn cooldown. A skill is cooling down after either a suggestion or a
-successful direct `read` of its indexed `SKILL.md`; the next result is eligible
-only when it independently meets the same score threshold. Cooldown state is
-per session and intentionally resets with the Gateway. Shell-command reads are
-not tracked.
+successful direct `read` of its indexed `SKILL.md`. When the best qualifying
+skill is cooling down, no hint is emitted; Skill Whisperer does not fall through
+to a weaker match. Cooldown state is per session and intentionally resets with
+the Gateway. Shell-command reads are not tracked.
 
 The `skills` corpus shares the existing QMD store and warm embedding model but
 is private to Skill Whisperer: it is excluded from ordinary `memory_search`
 (including `corpora: ["all"]`), `memory_get`, clustering, and memory-maintenance
 tasks. Paths are explicit by design; the plugin does not reconstruct
-OpenClaw's effective skill inventory from `openclaw.json`.
+OpenClaw's effective skill inventory from `openclaw.json`. Configured skill
+globs follow symlinked directories, including OpenClaw's `plugin-skills`
+directory.
 
 Use `sessionFilter` to restrict session results by metadata while leaving file
 corpora searchable. Supported fields are `startedFrom` and `startedTo`

package/dist/src/config.js

@@ -9,7 +9,7 @@ export const DEFAULT_CORPORA = [{
 const DEFAULT_SKILL_WHISPERER = {
     enabled: false,
     historyMessages: 5,
-    minScore: 0.4,
+    minScore: 0.5,
     cooldownTurns: 10,
 };
 function assertOnlyKeys(value, allowed, label) {
@@ -126,7 +126,7 @@ export function resolveConfig(value) {
         assertOnlyKeys(value, ["enabled", "historyMessages", "minScore", "cooldownTurns"], "skillWhisperer");
         const enabled = value.enabled ?? false;
         const historyMessages = value.historyMessages ?? 5;
-        const minScore = value.minScore ?? 0.4;
+        const minScore = value.minScore ?? 0.5;
         const cooldownTurns = value.cooldownTurns ?? 10;
         if (typeof enabled !== "boolean")
             throw new Error("unblock-memory skillWhisperer.enabled must be a boolean");

package/dist/src/manager.js

@@ -1,7 +1,8 @@
-import { realpathSync } from "node:fs";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { mkdir, stat } from "node:fs/promises";
-import { basename, dirname, resolve } from "node:path";
+import { basename, dirname, relative, resolve, sep } from "node:path";
 import chokidar from "chokidar";
+import picomatch from "picomatch";
 import { ensureMemoryAnalysisSchema, latestAnalysisCollections, latestAnalysisRunId, markMemoryAnalysisStale, readAnalysisSummary, readCluster, readClusters, runAnalysisWorker, } from "./analysis.js";
 import { CurationStore, chunkFingerprint, } from "./curation.js";
 import { readSessionManifest, sessionMetadataByPath, syncSessionProjections, } from "./session-sync.js";
@@ -10,6 +11,83 @@ const DEFAULT_READ_LINES = 120;
 const MAX_READ_CHARS = 12_000;
 const WATCH_DEBOUNCE_MS = 250;
 const qmdModule = import("@unblocklabs/qmd");
+function readSkillDocuments(source) {
+    const documents = [];
+    const visitedDirectories = new Set();
+    const visit = (directory) => {
+        let canonicalDirectory;
+        try {
+            canonicalDirectory = realpathSync(directory);
+        }
+        catch {
+            return;
+        }
+        if (visitedDirectories.has(canonicalDirectory))
+            return;
+        visitedDirectories.add(canonicalDirectory);
+        for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+            const path = resolve(directory, entry.name);
+            let kind = entry.isDirectory()
+                ? "directory"
+                : entry.isFile()
+                    ? "file"
+                    : undefined;
+            if (entry.isSymbolicLink()) {
+                try {
+                    const target = statSync(path);
+                    kind = target.isDirectory() ? "directory" : target.isFile() ? "file" : undefined;
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (kind === "directory") {
+                visit(path);
+                continue;
+            }
+            const relativePath = relative(source.root, path).split(sep).join("/");
+            if (kind !== "file" || basename(path).toLowerCase() !== "skill.md" ||
+                !picomatch.isMatch(relativePath, source.pattern, { dot: true }))
+                continue;
+            documents.push({ path, body: readFileSync(path, "utf8") });
+        }
+    };
+    visit(source.root);
+    return documents;
+}
+function frontmatterValue(body, key) {
+    const frontmatter = /^---\s*\n([\s\S]*?)\n---(?:\n|$)/u.exec(body)?.[1];
+    const raw = frontmatter?.split("\n")
+        .map((line) => new RegExp(`^${key}:\\s*(.+?)\\s*$`, "u").exec(line)?.[1])
+        .find((value) => value !== undefined);
+    return raw?.replace(/^(?:"(.*)"|'(.*)')$/u, "$1$2").trim();
+}
+function embeddingText(name, description, model) {
+    return model.toLowerCase().includes("qwen3-embedding")
+        ? `${name}\n${description}`
+        : `title: ${name} | text: ${description}`;
+}
+function queryText(query, model) {
+    return model.toLowerCase().includes("qwen3-embedding")
+        ? `Instruct: Retrieve relevant documents for the given query\nQuery: ${query}`
+        : `task: search result | query: ${query}`;
+}
+function cosineSimilarity(left, right) {
+    if (left.length !== right.length || left.length === 0)
+        return 0;
+    let dot = 0;
+    let leftMagnitude = 0;
+    let rightMagnitude = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        const leftValue = left[index];
+        const rightValue = right[index];
+        dot += leftValue * rightValue;
+        leftMagnitude += leftValue * leftValue;
+        rightMagnitude += rightValue * rightValue;
+    }
+    const denominator = Math.sqrt(leftMagnitude * rightMagnitude);
+    return denominator === 0 ? 0 : dot / denominator;
+}
 function markStaleForAnalysisCollectionChange(db, collections, hasSkills) {
     const current = collections.toSorted();
     const previous = latestAnalysisCollections(db)?.toSorted();
@@ -166,6 +244,7 @@ export class QmdMemoryManager {
     #dirty = true;
     #sessionMetadata = new Map();
     #sessionManifestMtimeNs;
+    #skillIndex;
     constructor(params) {
         this.#dbPath = params.dbPath;
         this.#curationPath = params.curationPath ?? `${params.dbPath}.curation.sqlite`;
@@ -230,9 +309,11 @@ export class QmdMemoryManager {
         this.#watcher.on("error", (error) => {
             this.#watchError = error instanceof Error ? error.message : String(error);
         });
-        this.#watcher.on("all", () => {
+        this.#watcher.on("all", (_event, path) => {
             if (this.#closed)
                 return;
+            if (basename(path).toLowerCase() === "skill.md")
+                this.#skillIndex = undefined;
             this.#dirty = true;
             if (this.#watchTimer)
                 clearTimeout(this.#watchTimer);
@@ -363,6 +444,8 @@ export class QmdMemoryManager {
                 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 (source.kind === "skills" && (changed || params?.force === true))
+                    this.#skillIndex = undefined;
                 if (source.kind !== "skills" && (changed || params?.force === true))
                     markAnalysisStale();
                 const embed = await store.embed({
@@ -649,41 +732,51 @@ export class QmdMemoryManager {
         if (collections.length === 0)
             return [];
         await this.#operationChain;
-        const hits = await (await this.#getStore()).vsearch(query, {
-            collection: collections,
-            limit,
-            minScore,
-            expand: false,
-        });
-        const sourceOrder = new Map([...this.#sources.keys()].map((collection, index) => [collection, index]));
-        const candidates = new Map();
-        for (const hit of hits) {
-            const safe = parseSafeVirtualPath(hit.file, this.#sources);
-            if (!safe || safe.source.kind !== "skills")
-                continue;
-            const path = realpathSync(resolve(safe.source.root, safe.relativePath));
-            if (basename(path).toLowerCase() !== "skill.md")
-                continue;
-            const frontmatter = /^---\s*\n([\s\S]*?)\n---(?:\n|$)/u.exec(hit.body)?.[1];
-            const configuredName = frontmatter?.split("\n")
-                .map((line) => /^name:\s*(.+?)\s*$/u.exec(line)?.[1])
-                .find((name) => name !== undefined)
-                ?.replace(/^(?:"(.*)"|'(.*)')$/u, "$1$2");
-            const candidate = {
-                name: configuredName?.trim() || basename(dirname(path)),
-                path,
-                score: hit.score,
-            };
-            const key = candidate.name.toLowerCase();
-            const order = sourceOrder.get(safe.source.collection) ?? Number.MAX_SAFE_INTEGER;
-            const current = candidates.get(key);
-            if (!current || order < current.sourceOrder ||
-                (order === current.sourceOrder && candidate.score > current.candidate.score)) {
-                candidates.set(key, { candidate, sourceOrder: order });
+        const store = await this.#getStore();
+        if (!store.internal?.llm)
+            throw new Error("Skill Whisperer requires the QMD embedding model");
+        const llm = store.internal.llm;
+        this.#skillIndex ??= (async () => {
+            const sourceOrder = new Map([...this.#sources.keys()].map((collection, index) => [collection, index]));
+            const metadata = new Map();
+            for (const source of this.#sources.values()) {
+                if (source.kind !== "skills")
+                    continue;
+                for (const document of readSkillDocuments(source)) {
+                    const name = frontmatterValue(document.body, "name") || basename(dirname(document.path));
+                    const description = frontmatterValue(document.body, "description") ?? "";
+                    const key = name.toLowerCase();
+                    const order = sourceOrder.get(source.collection) ?? Number.MAX_SAFE_INTEGER;
+                    const current = metadata.get(key);
+                    if (!current || order < current.sourceOrder) {
+                        metadata.set(key, {
+                            candidate: { name, path: document.path },
+                            description,
+                            sourceOrder: order,
+                        });
+                    }
+                }
             }
-        }
-        return [...candidates.values()]
-            .map(({ candidate }) => candidate)
+            const skills = [...metadata.values()];
+            const embeddings = await llm.embedBatch(skills.map(({ candidate, description }) => embeddingText(candidate.name, description, llm.embedModelName)));
+            return skills.flatMap(({ candidate }, index) => {
+                const embedding = embeddings[index]?.embedding;
+                return embedding ? [{ ...candidate, score: 0, embedding }] : [];
+            });
+        })().catch((error) => {
+            this.#skillIndex = undefined;
+            throw error;
+        });
+        const queryEmbedding = await llm.embed(queryText(query, llm.embedModelName), { isQuery: true });
+        if (!queryEmbedding)
+            return [];
+        const candidates = await this.#skillIndex;
+        return candidates
+            .map(({ embedding, ...candidate }) => ({
+            ...candidate,
+            score: cosineSimilarity(queryEmbedding.embedding, embedding),
+        }))
+            .filter((candidate) => candidate.score >= minScore)
             .sort((left, right) => right.score - left.score)
             .slice(0, limit);
     }

package/dist/src/skill-whisperer.js

@@ -60,14 +60,12 @@ export function registerSkillWhisperer(api, runtime, config) {
         state.turn += 1;
         try {
             const candidates = await runtime.searchSkills(active(context.agentId), buildSkillWhispererQuery(event.prompt, event.messages, config.historyMessages), config.minScore, CANDIDATE_LIMIT);
-            const selected = candidates.find((candidate) => {
-                if (candidate.score < config.minScore)
-                    return false;
-                const history = state.skills.get(candidate.path);
-                const lastSeen = Math.max(history?.suggested ?? -Infinity, history?.opened ?? -Infinity);
-                return state.turn - lastSeen > config.cooldownTurns;
-            });
-            if (!selected)
+            const selected = candidates[0];
+            if (!selected || selected.score < config.minScore)
+                return;
+            const previous = state.skills.get(selected.path);
+            const lastSeen = Math.max(previous?.suggested ?? -Infinity, previous?.opened ?? -Infinity);
+            if (state.turn - lastSeen <= config.cooldownTurns)
                 return;
             const history = state.skills.get(selected.path) ?? {};
             history.suggested = state.turn;

package/dist/src/sources.js

@@ -113,16 +113,10 @@ export function resolveConfiguredSkillPath(workspaceDir, inputPath, sources) {
     for (const source of sources) {
         if (source.kind !== "skills")
             continue;
-        let canonicalRoot;
-        try {
-            canonicalRoot = realpathSync(source.root);
-        }
-        catch {
+        const relativePath = relative(source.root, target);
+        if (relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath))
             continue;
-        }
-        const relativePath = relative(canonicalRoot, canonicalTarget);
-        const safe = parseSafeVirtualPath(`qmd://${source.collection}/${relativePath.split(sep).join("/")}`, new Map([[source.collection, source]]));
-        if (safe)
+        if (picomatch.isMatch(relativePath.split(sep).join("/"), source.pattern, { dot: true }))
             return canonicalTarget;
     }
     return undefined;

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },
@@ -113,13 +113,13 @@
         "properties": {
           "enabled": { "type": "boolean", "default": false },
           "historyMessages": { "type": "integer", "minimum": 0, "default": 5 },
-          "minScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.4 },
+          "minScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 },
           "cooldownTurns": { "type": "integer", "minimum": 0, "default": 10 }
         },
         "default": {
           "enabled": false,
           "historyMessages": 5,
-          "minScore": 0.4,
+          "minScore": 0.5,
           "cooldownTurns": 10
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,12 @@
     "access": "public",
     "provenance": true
   },
-  "files": ["dist", "skills", "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",
@@ -48,18 +53,33 @@
     "openclaw": ">=2026.8.1-beta.3"
   },
   "peerDependenciesMeta": {
-    "openclaw": { "optional": true }
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
   },
-  "engines": { "node": ">=22.0.0" },
   "openclaw": {
-    "extensions": ["./dist/index.js"],
-    "compat": { "pluginApi": ">=2026.8.1-beta.3", "minGatewayVersion": "2026.8.1-beta.3" },
-    "build": { "openclawVersion": "2026.8.1-beta.3", "pluginSdkVersion": "2026.8.1-beta.3" },
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.8.1-beta.3",
+      "minGatewayVersion": "2026.8.1-beta.3"
+    },
+    "build": {
+      "openclawVersion": "2026.8.1-beta.3",
+      "pluginSdkVersion": "2026.8.1-beta.3"
+    },
     "install": {
       "npmSpec": "@unblocklabs/unblock-memory",
       "defaultChoice": "npm",
       "minHostVersion": ">=2026.8.1-beta.3"
     },
-    "release": { "publishToClawHub": false, "publishToNpm": true }
+    "release": {
+      "publishToClawHub": false,
+      "publishToNpm": true
+    }
   }
 }