@unblocklabs/unblock-memory 0.2.6 → 0.3.0

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);
@@ -219,6 +220,81 @@ function createFetchClusterTool(runtime, ctx) {
         },
     };
 }
+const maintenanceStatus = Type.Union([
+    Type.Literal("pending"),
+    Type.Literal("resolved"),
+    Type.Literal("deferred"),
+    Type.Literal("irrelevant"),
+]);
+const listMaintenanceParameters = Type.Object({
+    status: Type.Optional(maintenanceStatus),
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
+}, { additionalProperties: false });
+function createListMaintenanceTool(runtime, ctx) {
+    const active = getContext(ctx);
+    if (!active)
+        return null;
+    return {
+        name: "memory_list_maintenance_tasks",
+        label: "List Memory Maintenance Tasks",
+        description: "List a bounded curation inbox of memory chronology and duplicate-review proposals.",
+        parameters: listMaintenanceParameters,
+        async execute(_toolCallId, params) {
+            const options = Value.Parse(listMaintenanceParameters, params);
+            const { manager, error } = await runtime.getMemorySearchManager(active);
+            if (!manager)
+                return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });
+            return jsonResult({ status: "ok", tasks: manager.listMaintenanceTasks(options) });
+        },
+    };
+}
+const isoTimestamp = Type.String({
+    pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?(?:Z|[+-]\\d{2}:\\d{2})$",
+});
+const updateMaintenanceParameters = Type.Object({
+    taskId: Type.String({ pattern: "\\S" }),
+    action: Type.Union([
+        Type.Literal("resolve"),
+        Type.Literal("defer"),
+        Type.Literal("irrelevant"),
+    ]),
+    note: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+    annotation: Type.Optional(Type.Object({
+        scope: Type.Optional(Type.Union([Type.Literal("chunk"), Type.Literal("document")])),
+        eventTime: isoTimestamp,
+        basis: Type.Union([
+            Type.Literal("path"),
+            Type.Literal("frontmatter"),
+            Type.Literal("session"),
+            Type.Literal("agent_verified"),
+        ]),
+        evidence: Type.String({ minLength: 1, maxLength: 500 }),
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
+function createUpdateMaintenanceTool(runtime, ctx) {
+    const active = getContext(ctx);
+    if (!active)
+        return null;
+    return {
+        name: "memory_update_maintenance_task",
+        label: "Update Memory Maintenance Task",
+        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);
+            const { manager, error } = await runtime.getMemorySearchManager(active);
+            if (!manager)
+                return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });
+            const updated = manager.updateMaintenanceTask({
+                id: taskId,
+                status: action === "resolve" ? "resolved" : action === "defer" ? "deferred" : "irrelevant",
+                note,
+                ...(annotation ? { annotation: { ...annotation, scope: annotation.scope ?? "chunk" } } : {}),
+            });
+            return jsonResult(updated ? { status: "ok", task: updated } : { status: "not_found" });
+        },
+    };
+}
 function formatDateInTimezone(timestamp, timezone) {
     const parts = new Intl.DateTimeFormat("en-US", {
         timeZone: timezone,
@@ -305,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"] });
@@ -312,4 +389,6 @@ export function registerUnblockMemory(api) {
     api.registerTool((ctx) => createReclusterTool(runtime, ctx), { names: ["memory_recluster"] });
     api.registerTool((ctx) => createListClustersTool(runtime, ctx), { names: ["memory_list_clusters"] });
     api.registerTool((ctx) => createFetchClusterTool(runtime, ctx), { names: ["memory_fetch_cluster"] });
+    api.registerTool((ctx) => createListMaintenanceTool(runtime, ctx), { names: ["memory_list_maintenance_tasks"] });
+    api.registerTool((ctx) => createUpdateMaintenanceTool(runtime, ctx), { names: ["memory_update_maintenance_task"] });
 }

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
@@ -204,6 +215,7 @@ export class QmdMemoryRuntime {
         const manager = new QmdMemoryManager({
             workspaceDir,
             dbPath: join(stateDir, "index.sqlite"),
+            curationPath: join(stateDir, "curation.sqlite"),
             sources,
             keepModelsWarm: this.#keepEmbeddingModelWarm,
             analysisExecutable: this.#analysisExecutable,

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,18 +1,20 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "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"] },
+  "contracts": { "tools": ["memory_search", "memory_get", "memory_sync_sessions", "memory_sync_status", "memory_recluster", "memory_list_clusters", "memory_fetch_cluster", "memory_list_maintenance_tasks", "memory_update_maintenance_task"] },
   "toolMetadata": {
     "memory_sync_sessions": { "sideEffecting": true },
     "memory_sync_status": { "replaySafe": true },
     "memory_recluster": { "sideEffecting": true },
     "memory_list_clusters": { "replaySafe": true },
-    "memory_fetch_cluster": { "replaySafe": true }
+    "memory_fetch_cluster": { "replaySafe": true },
+    "memory_list_maintenance_tasks": { "replaySafe": true },
+    "memory_update_maintenance_task": { "sideEffecting": true }
   },
   "uiHints": {
     "keepEmbeddingModelWarm": {
@@ -21,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",
@@ -69,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" }
+                }
+              }
             }
           ]
         },
@@ -86,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.6",
+  "version": "0.3.0",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "preflight": "npm run knip && npm run build && npm run typecheck && npm test && npm run plugin:inspect && npm run plugin:inspect:runtime && npm pack --dry-run"
   },
   "dependencies": {
-    "@unblocklabs/qmd": "https://github.com/unblocklabs-ai/qmd/releases/download/v2.9.2/unblocklabs-qmd-2.9.2.tgz",
+    "@unblocklabs/qmd": "https://github.com/unblocklabs-ai/qmd/releases/download/v2.9.3/unblocklabs-qmd-2.9.3.tgz",
     "chokidar": "5.0.0",
     "picomatch": "^4.0.5",
     "typebox": "1.3.6"

package/skills/memory-curator/SKILL.md

@@ -16,7 +16,9 @@ weak, duplicative, or easily looked-up knowledge.
    `memory_recluster`, then list again.
 2. Fetch a useful cluster with `memory_fetch_cluster`. Start with
    `sort: "representative"`; use `score_desc`, `date_asc`, or `date_desc` and
-   pagination when relevance, evolution, or recent state matters.
+   pagination when relevance, evolution, or recent state matters. Treat
+   `eventTime` as event chronology; `sourceModifiedAt` is only a labeled
+   fallback when `eventTime` is unresolved.
 3. State the question the cluster raises: what may be repeated, contradictory,
    changing, or worth understanding?
 4. Search existing knowledge with `memory_search`, using
@@ -67,6 +69,15 @@ rigid document template.
 ## Finish the cycle
 
 - Do not rewrite raw memory or session projections.
+- Review a small page from `memory_list_maintenance_tasks`. For ambiguous dates,
+  investigate supporting evidence and use `memory_update_maintenance_task` to
+  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.
+  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,