@unblocklabs/unblock-memory 0.2.7 → 0.3.0

package/README.md

@@ -38,6 +38,10 @@ directories, or globs into named corpora:
     slots: { memory: "unblock-memory" },
     entries: {
       "unblock-memory": {
+        hooks: {
+          // Required only when skillWhisperer.enabled is true.
+          allowConversationAccess: true,
+        },
         config: {
           // Default: avoid repeated model cold starts after idle periods.
           keepEmbeddingModelWarm: true,
@@ -57,7 +61,24 @@ directories, or globs into named corpora:
               kind: "files",
               paths: ["knowledge/**/*.md"],
             },
+            {
+              name: "skills",
+              kind: "skills",
+              paths: [
+                "skills/**/SKILL.md",
+                ".agents/skills/**/SKILL.md",
+                "~/.agents/skills/**/SKILL.md",
+                "~/.openclaw/skills/**/SKILL.md",
+                "~/.openclaw/plugin-skills/**/SKILL.md",
+              ],
+            },
           ],
+          skillWhisperer: {
+            enabled: false,
+            historyMessages: 5,
+            minScore: 0.4,
+            cooldownTurns: 10,
+          },
           // Optional: omit unless the local analysis worker is installed.
           analysis: {
             executable: "/absolute/path/to/unblock-cluster/bin/unblock-memory-analysis",
@@ -79,11 +100,34 @@ corpus; other unique names may be added for custom material.
 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
+`memory_search` searches every configured non-skill corpus by default. Pass
 `corpora: ["knowledge"]` 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`.
 
+### Skill Whisperer
+
+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.
+
+The defaults use five prior messages, a calibrated score threshold of `0.4`,
+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.
+
+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`.
+
 Use `sessionFilter` to restrict session results by metadata while leaving file
 corpora searchable. Supported fields are `startedFrom` and `startedTo`
 (inclusive ISO 8601 timestamps), `provider`, `chatType`, `accountId`, and
@@ -145,9 +189,10 @@ python3 -m venv .venv
 Set `analysis.executable` to the absolute path of
 `bin/unblock-memory-analysis` in that checkout. One worker installation can
 serve every agent on the host. The plugin invokes it directly with
-`--db <the agent's known index path>` and, when requested, a validated
-`--config-json <clustering options>` payload. Agents cannot choose a database,
-executable, shell command, or arbitrary arguments.
+`--db <the agent's known index path>`, the plugin's non-skill collection IDs,
+and, when requested, a validated `--config-json <clustering options>` payload.
+Agents cannot choose a database, executable, collection, shell command, or
+arbitrary arguments.
 
 Without the worker, `memory_list_clusters` reports that memory has not been
 analyzed and `memory_recluster` reports that analysis is unavailable. Ordinary
@@ -189,9 +234,11 @@ whole corpus for chores. Persisted exact-duplicate analysis can likewise create
 review proposals for non-session Markdown. `memory_list_maintenance_tasks`
 returns at most ten tasks, while `memory_update_maintenance_task` can resolve,
 defer, or mark one irrelevant and optionally attach a supported event date.
-These tools never edit or delete source Markdown. Duplicate cleanup remains a
-reviewed source change outside the maintenance tool, and generated session
-projections must never be edited directly.
+For duplicate proposals, defer confirmed cleanup until the source change is
+complete, mark intentional repetition irrelevant, and resolve only completed
+work. These tools never edit or delete source Markdown. Duplicate cleanup
+remains a reviewed source change outside the maintenance tool, and generated
+session projections must never be edited directly.
 
 Member excerpts are capped at 2 KB each and 12 KB across a response; source
 aliases are capped at five per member and 50 across a response. These budgets

package/dist/src/analysis.d.ts

@@ -22,6 +22,7 @@ export type MemoryReclusterOptions = {
 export type AnalysisRunner = (params: {
     executable: string;
     dbPath: string;
+    collections: readonly string[];
     options?: MemoryReclusterOptions;
     signal?: AbortSignal;
 }) => Promise<void>;
@@ -95,10 +96,12 @@ export declare function clusterReference(runId: string, clusterId: number): stri
 export declare function runAnalysisWorker(params: {
     executable: string;
     dbPath: string;
+    collections: readonly string[];
     options?: MemoryReclusterOptions;
     signal?: AbortSignal;
 }): Promise<void>;
 export declare function latestAnalysisRunId(db: AnalysisDatabase): string | undefined;
+export declare function latestAnalysisCollections(db: AnalysisDatabase): readonly string[] | undefined;
 export declare function readAnalysisSummary(db: AnalysisDatabase): MemoryAnalysisSummary | undefined;
 export declare function readClusters(db: AnalysisDatabase, requestedLimit?: number): MemoryClusterList;
 export declare function readCluster(db: AnalysisDatabase, clusterReferenceId: string, requestedLimit?: number, requestedOffset?: number, sort?: MemoryClusterSort, temporal?: TemporalReadOptions): MemoryClusterDetail;

package/dist/src/analysis.js

@@ -104,7 +104,7 @@ export function clusterReference(runId, clusterId) {
 export function runAnalysisWorker(params) {
     return new Promise((resolve, reject) => {
         params.signal?.throwIfAborted();
-        const args = ["--db", params.dbPath];
+        const args = ["--db", params.dbPath, "--collections-json", JSON.stringify(params.collections)];
         if (params.options && Object.keys(params.options).length > 0) {
             args.push("--config-json", JSON.stringify(params.options));
         }
@@ -170,6 +170,26 @@ function latestRun(db) {
 export function latestAnalysisRunId(db) {
     return latestRun(db)?.id;
 }
+export function latestAnalysisCollections(db) {
+    const row = db.prepare(`
+    SELECT params_json
+    FROM memory_analysis_runs
+    WHERE completed_at IS NOT NULL
+    ORDER BY completed_at DESC, created_at DESC, id DESC
+    LIMIT 1
+  `).get();
+    if (!row)
+        return undefined;
+    try {
+        const collections = JSON.parse(row.params_json).collections;
+        return Array.isArray(collections) && collections.every((value) => typeof value === "string")
+            ? collections
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function count(db, sql, runId) {
     return db.prepare(sql).get(runId)?.count ?? 0;
 }

package/dist/src/config.d.ts

@@ -3,6 +3,11 @@ export type FileCorpusConfig = {
     kind: "files";
     paths: readonly string[];
 };
+export type SkillCorpusConfig = {
+    name: "skills";
+    kind: "skills";
+    paths: readonly string[];
+};
 declare const CHAT_TYPES: readonly ["channel", "group", "direct"];
 export type ChatType = typeof CHAT_TYPES[number];
 type SessionCorpusConfig = {
@@ -10,7 +15,7 @@ type SessionCorpusConfig = {
     kind: "sessions";
     chatTypes: readonly ChatType[];
 };
-export type CorpusConfig = FileCorpusConfig | SessionCorpusConfig;
+export type CorpusConfig = FileCorpusConfig | SkillCorpusConfig | SessionCorpusConfig;
 export declare const DEFAULT_CORPORA: readonly FileCorpusConfig[];
 export type UnblockMemoryConfig = {
     corpora: readonly CorpusConfig[];
@@ -18,6 +23,12 @@ export type UnblockMemoryConfig = {
     analysis: {
         executable?: string;
     };
+    skillWhisperer: {
+        enabled: boolean;
+        historyMessages: number;
+        minScore: number;
+        cooldownTurns: number;
+    };
 };
 export declare function resolveConfig(value: unknown): UnblockMemoryConfig;
 export {};

package/dist/src/config.js

@@ -6,6 +6,12 @@ export const DEFAULT_CORPORA = [{
         kind: "files",
         paths: DEFAULT_PATHS,
     }];
+const DEFAULT_SKILL_WHISPERER = {
+    enabled: false,
+    historyMessages: 5,
+    minScore: 0.4,
+    cooldownTurns: 10,
+};
 function assertOnlyKeys(value, allowed, label) {
     const unknown = Object.keys(value).find((key) => !allowed.includes(key));
     if (unknown)
@@ -33,6 +39,17 @@ function resolveCorpora(value) {
         if (names.has(name))
             throw new Error(`unblock-memory corpus names must be unique: ${name}`);
         names.add(name);
+        if (corpus.kind === "skills") {
+            assertOnlyKeys(corpus, ["name", "kind", "paths"], `corpora[${index}]`);
+            if (name !== "skills") {
+                throw new Error('unblock-memory skills corpus must be named "skills"');
+            }
+            if (!Array.isArray(corpus.paths) || corpus.paths.length === 0 ||
+                !corpus.paths.every((path) => typeof path === "string" && path.trim())) {
+                throw new Error("unblock-memory corpus skills paths must be a non-empty array of non-empty strings");
+            }
+            return { name: "skills", kind: "skills", paths: corpus.paths.map((path) => path.trim()) };
+        }
         if (corpus.kind === "sessions") {
             assertOnlyKeys(corpus, ["name", "kind", "chatTypes"], `corpora[${index}]`);
             if (name !== "sessions") {
@@ -49,8 +66,11 @@ function resolveCorpora(value) {
         if (name === "sessions") {
             throw new Error('unblock-memory corpus named "sessions" must have kind "sessions"');
         }
+        if (name === "skills") {
+            throw new Error('unblock-memory corpus named "skills" must have kind "skills"');
+        }
         if (corpus.kind !== "files") {
-            throw new Error(`unblock-memory corpus ${name} must have kind "files" or "sessions"`);
+            throw new Error(`unblock-memory corpus ${name} must have kind "files", "skills", or "sessions"`);
         }
         if (!Array.isArray(corpus.paths) || corpus.paths.length === 0 ||
             !corpus.paths.every((path) => typeof path === "string" && path.trim())) {
@@ -65,30 +85,64 @@ function resolveCorpora(value) {
 }
 export function resolveConfig(value) {
     if (value === undefined || value === null) {
-        return { corpora: DEFAULT_CORPORA, keepEmbeddingModelWarm: true, analysis: {} };
+        return {
+            corpora: DEFAULT_CORPORA,
+            keepEmbeddingModelWarm: true,
+            analysis: {},
+            skillWhisperer: DEFAULT_SKILL_WHISPERER,
+        };
     }
     if (typeof value !== "object" || Array.isArray(value)) {
         throw new Error("unblock-memory config must be an object");
     }
     const config = value;
-    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis"], "config");
+    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "skillWhisperer"], "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, keepEmbeddingModelWarm, analysis: {} };
-    if (!config.analysis || typeof config.analysis !== "object" || Array.isArray(config.analysis)) {
-        throw new Error("unblock-memory analysis must be an object");
+    let analysisConfig = {};
+    if (config.analysis !== undefined) {
+        if (!config.analysis || typeof config.analysis !== "object" || Array.isArray(config.analysis)) {
+            throw new Error("unblock-memory analysis must be an object");
+        }
+        const analysis = config.analysis;
+        assertOnlyKeys(analysis, ["executable"], "analysis");
+        const configured = analysis.executable;
+        if (configured !== undefined) {
+            if (typeof configured !== "string" || !configured.trim() || !isAbsolute(configured.trim())) {
+                throw new Error("unblock-memory analysis.executable must be an absolute non-empty path");
+            }
+            analysisConfig = { executable: configured.trim() };
+        }
+    }
+    let skillWhisperer = DEFAULT_SKILL_WHISPERER;
+    if (config.skillWhisperer !== undefined) {
+        if (!config.skillWhisperer || typeof config.skillWhisperer !== "object" || Array.isArray(config.skillWhisperer)) {
+            throw new Error("unblock-memory skillWhisperer must be an object");
+        }
+        const value = config.skillWhisperer;
+        assertOnlyKeys(value, ["enabled", "historyMessages", "minScore", "cooldownTurns"], "skillWhisperer");
+        const enabled = value.enabled ?? false;
+        const historyMessages = value.historyMessages ?? 5;
+        const minScore = value.minScore ?? 0.4;
+        const cooldownTurns = value.cooldownTurns ?? 10;
+        if (typeof enabled !== "boolean")
+            throw new Error("unblock-memory skillWhisperer.enabled must be a boolean");
+        if (typeof historyMessages !== "number" || !Number.isInteger(historyMessages) || historyMessages < 0) {
+            throw new Error("unblock-memory skillWhisperer.historyMessages must be a non-negative integer");
+        }
+        if (typeof minScore !== "number" || !Number.isFinite(minScore) || minScore < 0 || minScore > 1) {
+            throw new Error("unblock-memory skillWhisperer.minScore must be between 0 and 1");
+        }
+        if (typeof cooldownTurns !== "number" || !Number.isInteger(cooldownTurns) || cooldownTurns < 0) {
+            throw new Error("unblock-memory skillWhisperer.cooldownTurns must be a non-negative integer");
+        }
+        skillWhisperer = { enabled, historyMessages, minScore, cooldownTurns };
     }
-    const analysis = config.analysis;
-    assertOnlyKeys(analysis, ["executable"], "analysis");
-    const configured = analysis.executable;
-    if (configured === undefined)
-        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");
+    if (skillWhisperer.enabled && !corpora.some((corpus) => corpus.kind === "skills")) {
+        throw new Error('unblock-memory enabled skillWhisperer requires a corpus named "skills" with kind "skills"');
     }
-    return { corpora, keepEmbeddingModelWarm, analysis: { executable: configured.trim() } };
+    return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, skillWhisperer };
 }

package/dist/src/manager.d.ts

@@ -16,6 +16,11 @@ export type ManagerSessionConfig = {
     outputDir: string;
     timezone: string;
 };
+export type SkillSearchCandidate = {
+    name: string;
+    path: string;
+    score: number;
+};
 export declare function enableSecureDelete(store: QMDStore): void;
 export declare function cleanupRemovedDocuments(store: QMDStore, changedDocuments?: number): number;
 export declare function pruneStaleCollections(store: QMDStore, configuredCollections: ReadonlySet<string>): Promise<number>;
@@ -65,6 +70,7 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         };
     }): import("./curation.js").MaintenanceTask | undefined;
     search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
+    searchSkills(query: string, minScore: number, limit: number): Promise<SkillSearchCandidate[]>;
     readFile(params: {
         relPath: string;
         from?: number;

package/dist/src/manager.js

@@ -1,7 +1,8 @@
+import { realpathSync } from "node:fs";
 import { mkdir, stat } from "node:fs/promises";
-import { dirname } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import chokidar from "chokidar";
-import { ensureMemoryAnalysisSchema, latestAnalysisRunId, markMemoryAnalysisStale, readAnalysisSummary, readCluster, readClusters, runAnalysisWorker, } from "./analysis.js";
+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";
 import { parseSafeVirtualPath } from "./sources.js";
@@ -9,6 +10,15 @@ const DEFAULT_READ_LINES = 120;
 const MAX_READ_CHARS = 12_000;
 const WATCH_DEBOUNCE_MS = 250;
 const qmdModule = import("@unblocklabs/qmd");
+function markStaleForAnalysisCollectionChange(db, collections, hasSkills) {
+    const current = collections.toSorted();
+    const previous = latestAnalysisCollections(db)?.toSorted();
+    if (previous
+        ? previous.join("\0") !== current.join("\0")
+        : hasSkills && latestAnalysisRunId(db) !== undefined) {
+        markMemoryAnalysisStale(db);
+    }
+}
 function completedEmbeddingCount(result) {
     if (result.errors > 0) {
         throw new Error(`QMD failed to embed ${result.errors} chunk${result.errors === 1 ? "" : "s"}`);
@@ -204,7 +214,7 @@ export class QmdMemoryManager {
     }
     #startWatcher() {
         const paths = [...new Set([...this.#sources.values()]
-                .filter((source) => source.kind === "files")
+                .filter((source) => source.kind !== "sessions")
                 .map((source) => source.watchPath))];
         if (paths.length === 0 || this.#watcher)
             return;
@@ -239,8 +249,10 @@ export class QmdMemoryManager {
         if (this.#storeFactory) {
             this.#store = await this.#storeFactory();
             const store = this.#store;
-            if (store.internal)
+            if (store.internal) {
                 ensureMemoryAnalysisSchema(store.internal.db);
+                markStaleForAnalysisCollectionChange(store.internal.db, this.#analysisCollectionNames(), this.#skillCollectionNames().length > 0);
+            }
             return this.#store;
         }
         const { createStore } = await qmdModule;
@@ -256,8 +268,26 @@ export class QmdMemoryManager {
         });
         enableSecureDelete(store);
         ensureMemoryAnalysisSchema(store.internal.db);
-        const prunedDocuments = await pruneStaleCollections(store, new Set(this.#collectionNames()));
-        if (prunedDocuments > 0)
+        markStaleForAnalysisCollectionChange(store.internal.db, this.#analysisCollectionNames(), this.#skillCollectionNames().length > 0);
+        const configuredCollections = new Set(this.#allCollectionNames());
+        const staleCollections = (await store.getStatus()).collections
+            .map((collection) => collection.name)
+            .filter((collection) => !configuredCollections.has(collection));
+        const appearsInAnalysis = store.internal.db.prepare(`
+      SELECT 1
+      FROM memory_analysis_memberships membership
+      JOIN documents document ON document.hash = membership.hash
+      WHERE membership.run_id = (
+        SELECT id FROM memory_analysis_runs
+        WHERE completed_at IS NOT NULL
+        ORDER BY completed_at DESC, created_at DESC, id DESC
+        LIMIT 1
+      ) AND document.collection = ?
+      LIMIT 1
+    `);
+        const prunedAnalysisInput = staleCollections.some((collection) => appearsInAnalysis.get(collection));
+        const prunedDocuments = await pruneStaleCollections(store, configuredCollections);
+        if (prunedDocuments > 0 && prunedAnalysisInput)
             markMemoryAnalysisStale(store.internal.db);
         try {
             await ensureSemanticChunking(store);
@@ -272,22 +302,36 @@ export class QmdMemoryManager {
         this.#store = store;
         return store;
     }
+    #allCollectionNames() {
+        return [...this.#sources.keys()];
+    }
+    #analysisCollectionNames() {
+        return [...this.#sources.values()]
+            .filter((source) => source.kind !== "skills")
+            .map((source) => source.collection);
+    }
+    #skillCollectionNames() {
+        return [...this.#sources.values()]
+            .filter((source) => source.kind === "skills")
+            .map((source) => source.collection);
+    }
     #collectionNames(corpora) {
+        const publicSources = [...this.#sources.values()].filter((source) => source.kind !== "skills");
         if (corpora === undefined)
-            return [...this.#sources.keys()];
+            return publicSources.map((source) => source.collection);
         if (corpora.length === 0)
             throw new Error("memory_search corpora must not be empty");
         const selected = new Set(corpora);
         if (selected.has("all")) {
             if (selected.size > 1)
                 throw new Error('memory_search corpus "all" must be used alone');
-            return [...this.#sources.keys()];
+            return publicSources.map((source) => source.collection);
         }
-        const known = new Set([...this.#sources.values()].map((source) => source.corpus));
+        const known = new Set(publicSources.map((source) => source.corpus));
         const unknown = [...selected].find((corpus) => !known.has(corpus));
         if (unknown)
             throw new Error(`memory_search unknown corpus: ${unknown}`);
-        return [...this.#sources.values()]
+        return publicSources
             .filter((source) => selected.has(source.corpus))
             .map((source) => source.collection);
     }
@@ -295,29 +339,39 @@ export class QmdMemoryManager {
         const run = async () => {
             const store = await this.#getStore();
             this.#dirty = true;
-            const collections = [...this.#sources.values()]
-                .filter((source) => source.kind === "files")
-                .map((source) => source.collection);
-            const update = await store.update({ collections });
-            this.#cleanupRemovedDocuments?.(update.updated + update.removed);
             const analysisStore = store;
-            const invalidatesAnalysis = update.indexed + update.updated + update.removed > 0 ||
-                update.needsEmbedding > 0 ||
-                params?.force === true;
-            if (invalidatesAnalysis && analysisStore.internal) {
+            const collections = [...this.#sources.values()].filter((source) => source.kind !== "sessions");
+            let analysisMarkedStale = false;
+            const markAnalysisStale = () => {
+                if (analysisMarkedStale || !analysisStore.internal)
+                    return;
                 markMemoryAnalysisStale(analysisStore.internal.db);
+                analysisMarkedStale = true;
+            };
+            if (collections.length === 0) {
+                const update = await store.update({ collections: [] });
+                this.#cleanupRemovedDocuments?.(update.updated + update.removed);
+                if (update.indexed + update.updated + update.removed > 0 ||
+                    update.needsEmbedding > 0 || params?.force === true) {
+                    markAnalysisStale();
+                }
+                const embed = await store.embed({ force: params?.force, chunkStrategy: "semantic" });
+                if (completedEmbeddingCount(embed) > 0)
+                    markAnalysisStale();
             }
-            let chunksEmbedded = 0;
-            for (const collection of collections.length > 0 ? collections : [undefined]) {
+            for (const source of collections) {
+                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))
+                    markAnalysisStale();
                 const embed = await store.embed({
-                    ...(collection ? { collection } : {}),
+                    collection: source.collection,
                     force: params?.force,
                     chunkStrategy: "semantic",
                 });
-                chunksEmbedded += completedEmbeddingCount(embed);
-            }
-            if (!invalidatesAnalysis && chunksEmbedded > 0 && analysisStore.internal) {
-                markMemoryAnalysisStale(analysisStore.internal.db);
+                if (source.kind !== "skills" && completedEmbeddingCount(embed) > 0)
+                    markAnalysisStale();
             }
             const status = await store.getStatus();
             const indexedCollections = await store.listCollections();
@@ -381,6 +435,7 @@ export class QmdMemoryManager {
             await this.#analysisRunner({
                 executable: this.#analysisExecutable,
                 dbPath: this.#dbPath,
+                collections: this.#analysisCollectionNames(),
                 options,
                 signal,
             });
@@ -589,10 +644,54 @@ export class QmdMemoryManager {
                 }];
         });
     }
+    async searchSkills(query, minScore, limit) {
+        const collections = this.#skillCollectionNames();
+        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 });
+            }
+        }
+        return [...candidates.values()]
+            .map(({ candidate }) => candidate)
+            .sort((left, right) => right.score - left.score)
+            .slice(0, limit);
+    }
     async readFile(params) {
         const safe = parseSafeVirtualPath(params.relPath, this.#sources);
-        if (!safe)
+        if (!safe || safe.source.kind === "skills") {
             return { status: "not_found", text: "", path: params.relPath };
+        }
         await this.#operationChain;
         const store = await this.#getStore();
         const doc = await store.get(safe.normalized);
@@ -628,7 +727,11 @@ export class QmdMemoryManager {
             custom: {
                 corpora: [...corpora].map(([name, sources]) => sources[0]?.kind === "sessions"
                     ? { name, kind: "sessions", chatTypes: sources[0].chatTypes }
-                    : { name, kind: "files", paths: sources.map((source) => source.configuredPath) }),
+                    : {
+                        name,
+                        kind: sources[0]?.kind === "skills" ? "skills" : "files",
+                        paths: sources.map((source) => source.configuredPath),
+                    }),
                 ...(this.#watchError ? { watchError: this.#watchError } : {}),
             },
         };

package/dist/src/plugin.js

@@ -3,6 +3,7 @@ import { Value } from "typebox/value";
 import { jsonResult } from "openclaw/plugin-sdk/agent-runtime";
 import { resolveConfig } from "./config.js";
 import { QmdMemoryRuntime } from "./runtime.js";
+import { registerSkillWhisperer } from "./skill-whisperer.js";
 function getContext(ctx) {
     const cfg = ctx.getRuntimeConfig?.() ?? ctx.runtimeConfig ?? ctx.config;
     if (!cfg || !ctx.agentId)
@@ -43,7 +44,7 @@ function createSearchTool(runtime, ctx) {
     return {
         name: "memory_search",
         label: "Memory Search",
-        description: "Search configured Markdown corpora with semantic vector retrieval. Omit corpora to search all of them.",
+        description: "Search configured memory corpora with semantic vector retrieval. The isolated skills corpus is never included.",
         parameters: searchParameters,
         async execute(_toolCallId, params, signal) {
             const { query: untrimmedQuery, corpora, sessionFilter, maxResults, minScore } = Value.Parse(searchParameters, params);
@@ -277,7 +278,7 @@ function createUpdateMaintenanceTool(runtime, ctx) {
     return {
         name: "memory_update_maintenance_task",
         label: "Update Memory Maintenance Task",
-        description: "Resolve, defer, or dismiss a memory-maintenance proposal. This tool never edits source Markdown.",
+        description: "Resolve completed work, defer outstanding work, or dismiss an irrelevant memory-maintenance proposal. This tool never edits source Markdown.",
         parameters: updateMaintenanceParameters,
         async execute(_toolCallId, params) {
             const { taskId, action, note, annotation } = Value.Parse(updateMaintenanceParameters, params);
@@ -380,6 +381,7 @@ export function registerUnblockMemory(api) {
         runtime,
     };
     api.registerMemoryCapability(capability);
+    registerSkillWhisperer(api, runtime, config.skillWhisperer);
     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"] });

package/dist/src/runtime.d.ts

@@ -68,5 +68,13 @@ export declare class QmdMemoryRuntime implements MemoryPluginRuntimeContract {
         agentId: string;
     }): Promise<void>;
     closeAllMemorySearchManagers(): Promise<void>;
+    searchSkills(params: {
+        cfg: OpenClawConfig;
+        agentId: string;
+    }, query: string, minScore: number, limit: number): Promise<import("./manager.js").SkillSearchCandidate[]>;
+    resolveSkillPath(params: {
+        cfg: OpenClawConfig;
+        agentId: string;
+    }, path: string): string | undefined;
 }
 export {};

package/dist/src/runtime.js

@@ -5,7 +5,7 @@ import { resolveAgentDir, resolveAgentWorkspaceDir, resolveStateDir, } from "ope
 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 { resolveConfiguredSkillPath, resolveSessionSource, resolveSources } from "./sources.js";
 import { classifyWorkspaceMemoryPaths } from "./workspace-path-classifier.js";
 const activeSessionSyncs = new Map();
 async function readJson(path) {
@@ -190,10 +190,21 @@ export class QmdMemoryRuntime {
         this.#managers.clear();
         await Promise.all(managers.map(async (pending) => (await pending).close()));
     }
+    async searchSkills(params, query, minScore, limit) {
+        const { manager, error } = await this.getMemorySearchManager(params);
+        if (!manager)
+            throw new Error(error ?? "memory unavailable");
+        return manager.searchSkills(query, minScore, limit);
+    }
+    resolveSkillPath(params, path) {
+        const workspaceDir = resolveAgentWorkspaceDir(params.cfg, params.agentId);
+        const skillCorpora = this.#corpora.filter((corpus) => corpus.kind === "skills");
+        return resolveConfiguredSkillPath(workspaceDir, path, resolveSources(workspaceDir, skillCorpora));
+    }
     async #createManager(cfg, agentId) {
         const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
         const stateDir = join(this.#stateRoot, "agents", agentId, "unblock-memory");
-        const fileCorpora = this.#corpora.filter((corpus) => corpus.kind === "files");
+        const fileCorpora = this.#corpora.filter((corpus) => corpus.kind === "files" || corpus.kind === "skills");
         const sessionCorpus = this.#corpora.find((corpus) => corpus.kind === "sessions");
         const sources = resolveSources(workspaceDir, fileCorpora);
         const sessionSource = sessionCorpus

package/dist/src/skill-whisperer.d.ts

@@ -0,0 +1,16 @@
+import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { UnblockMemoryConfig } from "./config.js";
+import type { SkillSearchCandidate } from "./manager.js";
+type SkillWhispererRuntime = {
+    searchSkills(params: {
+        cfg: OpenClawConfig;
+        agentId: string;
+    }, query: string, minScore: number, limit: number): Promise<SkillSearchCandidate[]>;
+    resolveSkillPath(params: {
+        cfg: OpenClawConfig;
+        agentId: string;
+    }, path: string): string | undefined;
+};
+export declare function buildSkillWhispererQuery(prompt: string, messages: readonly unknown[], historyMessages: number): string;
+export declare function registerSkillWhisperer(api: OpenClawPluginApi, runtime: SkillWhispererRuntime, config: UnblockMemoryConfig["skillWhisperer"]): void;
+export {};

package/dist/src/skill-whisperer.js

@@ -0,0 +1,113 @@
+import { basename } from "node:path";
+const CANDIDATE_LIMIT = 10;
+const MAX_QUERY_CHARS = 12_000;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function messageText(message) {
+    if (!isRecord(message) || (message.role !== "user" && message.role !== "assistant"))
+        return undefined;
+    if (typeof message.content === "string") {
+        const text = message.content.trim();
+        return text ? { role: message.role, text } : undefined;
+    }
+    if (!Array.isArray(message.content))
+        return undefined;
+    const text = message.content.flatMap((part) => {
+        return isRecord(part) && part.type === "text" && typeof part.text === "string" ? [part.text] : [];
+    }).join("\n").trim();
+    return text ? { role: message.role, text } : undefined;
+}
+export function buildSkillWhispererQuery(prompt, messages, historyMessages) {
+    const availableHistory = messages.flatMap((message) => {
+        const parsed = messageText(message);
+        return parsed ? [`${parsed.role}: ${parsed.text}`] : [];
+    });
+    const history = historyMessages === 0 ? [] : availableHistory.slice(-historyMessages);
+    return [...history, `user: ${prompt.trim()}`].join("\n\n").slice(-MAX_QUERY_CHARS);
+}
+function readPath(params) {
+    for (const value of [params.path, params.file_path, params.filePath]) {
+        if (typeof value === "string" && basename(value).toLowerCase() === "skill.md")
+            return value;
+    }
+    return undefined;
+}
+function sessionScope(context) {
+    return context.sessionId || context.sessionKey;
+}
+export function registerSkillWhisperer(api, runtime, config) {
+    if (!config.enabled)
+        return;
+    const sessions = new Map();
+    const stateFor = (scope) => {
+        let state = sessions.get(scope);
+        if (!state) {
+            state = { turn: 0, skills: new Map() };
+            sessions.set(scope, state);
+        }
+        return state;
+    };
+    const active = (agentId) => ({ cfg: api.config, agentId });
+    api.on("before_prompt_build", async (event, context) => {
+        const scope = sessionScope(context);
+        if (context.trigger !== "user" || !scope || !context.runId || !context.agentId)
+            return;
+        const state = stateFor(scope);
+        if (state.lastRunId === context.runId)
+            return;
+        state.lastRunId = context.runId;
+        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)
+                return;
+            const history = state.skills.get(selected.path) ?? {};
+            history.suggested = state.turn;
+            state.skills.set(selected.path, history);
+            return {
+                prependContext: `A potentially relevant skill is available: ${JSON.stringify(selected.name)} ` +
+                    `at ${JSON.stringify(selected.path)}. Check it before proceeding if applicable.`,
+            };
+        }
+        catch (error) {
+            api.logger.warn(`unblock-memory skill whisperer search failed: ${String(error)}`);
+            return;
+        }
+    });
+    api.on("after_tool_call", (event, context) => {
+        if (event.toolName !== "read" || event.error ||
+            (isRecord(event.result) && event.result.isError === true) || !context.agentId)
+            return;
+        const scope = sessionScope(context);
+        const path = scope ? readPath(event.params) : undefined;
+        if (!scope || !path)
+            return;
+        try {
+            const canonicalPath = runtime.resolveSkillPath(active(context.agentId), path);
+            if (!canonicalPath)
+                return;
+            const state = stateFor(scope);
+            const history = state.skills.get(canonicalPath) ?? {};
+            history.opened = state.turn;
+            state.skills.set(canonicalPath, history);
+        }
+        catch (error) {
+            api.logger.warn(`unblock-memory skill whisperer read tracking failed: ${String(error)}`);
+        }
+    }, { matcher: ["read"] });
+    api.on("session_end", (event, context) => {
+        sessions.delete(event.sessionId);
+        if (event.sessionKey)
+            sessions.delete(event.sessionKey);
+        if (context.sessionKey)
+            sessions.delete(context.sessionKey);
+    });
+}

package/dist/src/sources.d.ts

@@ -1,9 +1,9 @@
-import type { ChatType, FileCorpusConfig } from "./config.js";
+import type { ChatType, FileCorpusConfig, SkillCorpusConfig } from "./config.js";
 export type ResolvedSource = {
     collection: string;
     corpus: string;
     configuredPath: string;
-    kind: "files" | "sessions";
+    kind: "files" | "skills" | "sessions";
     root: string;
     pattern: string;
     watchPath: string;
@@ -11,7 +11,8 @@ export type ResolvedSource = {
 };
 export declare function resolveSource(workspaceDir: string, configuredPath: string, corpus?: string): ResolvedSource;
 export declare function resolveSessionSource(sessionsDir: string, chatTypes: readonly ChatType[]): ResolvedSource;
-export declare function resolveSources(workspaceDir: string, corpora: readonly FileCorpusConfig[]): ResolvedSource[];
+export declare function resolveSources(workspaceDir: string, corpora: readonly (FileCorpusConfig | SkillCorpusConfig)[]): ResolvedSource[];
+export declare function resolveConfiguredSkillPath(workspaceDir: string, inputPath: string, sources: readonly ResolvedSource[]): string | undefined;
 export declare function parseSafeVirtualPath(virtualPath: string, sources: ReadonlyMap<string, ResolvedSource>): {
     source: ResolvedSource;
     relativePath: string;

package/dist/src/sources.js

@@ -68,6 +68,9 @@ export function resolveSource(workspaceDir, configuredPath, corpus = "memory") {
     assertWorkspaceSourceHasNoSymlinkRoot(workspaceDir, configuredPath, root);
     return { collection: collectionName(absolute), corpus, configuredPath, kind: "files", root, pattern, watchPath: root };
 }
+function resolveFileSource(workspaceDir, configuredPath, corpus) {
+    return { ...resolveSource(workspaceDir, configuredPath, corpus.name), kind: corpus.kind };
+}
 export function resolveSessionSource(sessionsDir, chatTypes) {
     return {
         ...resolveSource(sessionsDir, sessionsDir, "sessions"),
@@ -81,7 +84,7 @@ export function resolveSources(workspaceDir, corpora) {
     const configured = new Map();
     for (const corpus of corpora) {
         for (const path of corpus.paths) {
-            const source = resolveSource(workspaceDir, path, corpus.name);
+            const source = resolveFileSource(workspaceDir, path, corpus);
             const identity = `${source.root}\0${source.pattern}`;
             const duplicate = configured.get(identity);
             if (duplicate) {
@@ -94,6 +97,36 @@ export function resolveSources(workspaceDir, corpora) {
     }
     return sources;
 }
+export function resolveConfiguredSkillPath(workspaceDir, inputPath, sources) {
+    if (basename(inputPath).toLowerCase() !== "skill.md")
+        return undefined;
+    const target = resolve(isAbsolute(expandHome(inputPath))
+        ? expandHome(inputPath)
+        : resolve(workspaceDir, inputPath));
+    let canonicalTarget;
+    try {
+        canonicalTarget = realpathSync(target);
+    }
+    catch {
+        return undefined;
+    }
+    for (const source of sources) {
+        if (source.kind !== "skills")
+            continue;
+        let canonicalRoot;
+        try {
+            canonicalRoot = realpathSync(source.root);
+        }
+        catch {
+            continue;
+        }
+        const relativePath = relative(canonicalRoot, canonicalTarget);
+        const safe = parseSafeVirtualPath(`qmd://${source.collection}/${relativePath.split(sep).join("/")}`, new Map([[source.collection, source]]));
+        if (safe)
+            return canonicalTarget;
+    }
+    return undefined;
+}
 export function parseSafeVirtualPath(virtualPath, sources) {
     const match = /^qmd:\/\/([^/]+)\/(.+)$/.exec(virtualPath.trim());
     if (!match)

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },
@@ -23,7 +23,11 @@
     },
     "corpora": {
       "label": "Memory Corpora",
-      "help": "Named groups of exact Markdown files, directories, or globs. Relative paths resolve from each agent workspace."
+      "help": "Named groups of exact Markdown files, directories, or globs. Relative paths resolve from each agent workspace. Skill files use the isolated skills corpus."
+    },
+    "skillWhisperer.enabled": {
+      "label": "Skill Whisperer",
+      "help": "Suggest at most one semantically relevant configured skill before a user turn. Requires hook conversation access."
     },
     "analysis.executable": {
       "label": "Memory Analysis Worker",
@@ -71,6 +75,20 @@
                   "default": ["channel", "group"]
                 }
               }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["name", "kind", "paths"],
+              "properties": {
+                "name": { "const": "skills" },
+                "kind": { "const": "skills" },
+                "paths": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": { "type": "string", "pattern": "\\S" }
+                }
+              }
             }
           ]
         },
@@ -88,6 +106,22 @@
         "properties": {
           "executable": { "type": "string", "minLength": 1 }
         }
+      },
+      "skillWhisperer": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean", "default": false },
+          "historyMessages": { "type": "integer", "minimum": 0, "default": 5 },
+          "minScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.4 },
+          "cooldownTurns": { "type": "integer", "minimum": 0, "default": 10 }
+        },
+        "default": {
+          "enabled": false,
+          "historyMessages": 5,
+          "minScore": 0.4,
+          "cooldownTurns": 10
+        }
       }
     }
   }

package/package.json

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

package/skills/memory-curator/SKILL.md

@@ -74,8 +74,10 @@ rigid document template.
   attach a chunk or document date only when supported; otherwise defer or mark
   it irrelevant. For exact-duplicate proposals, decide whether cleanup should
   be proposed, but do not treat repetition across historical files as an error.
-  The maintenance tools never change source Markdown, and generated session
-  projections must never be manually cleaned.
+  Mark intentional repetition `irrelevant`, and keep accidental duplication
+  `deferred` until the source is actually cleaned. Mark it `resolved` only after
+  that cleanup is complete. The maintenance tools never change source Markdown,
+  and generated session projections must never be manually cleaned.
 - Verify an updated file with `memory_search`, using
   `corpora: ["knowledge"]`, and check all-corpora ranking when useful.
 - Report the questions investigated, evidence consulted beyond each cluster,