@unblocklabs/unblock-memory 0.3.2 → 0.3.4

package/README.md

@@ -39,7 +39,7 @@ directories, or globs into named corpora:
     entries: {
       "unblock-memory": {
         hooks: {
-          // Required only when skillWhisperer.enabled is true.
+          // Required when either whisperer is enabled.
           allowConversationAccess: true,
         },
         config: {
@@ -79,6 +79,10 @@ directories, or globs into named corpora:
             minScore: 0.5,
             cooldownTurns: 10,
           },
+          people: {
+            enabled: false,
+            whisperer: { enabled: false, maxChars: 1200 },
+          },
           // Optional: omit unless the local analysis worker is installed.
           analysis: {
             executable: "/absolute/path/to/unblock-cluster/bin/unblock-memory-analysis",
@@ -131,6 +135,62 @@ OpenClaw's effective skill inventory from `openclaw.json`. Configured skill
 globs follow symlinked directories, including OpenClaw's `plugin-skills`
 directory.
 
+### People Whisperer
+
+PeopleSQL is an optional agent-local people store. When `people.enabled` is
+true, incoming Slack messages with a canonical agent session key and exact
+account and sender IDs create or refresh a disabled-by-default person record.
+Incomplete Slack identities create a bounded, deduplicated todo without storing
+message content. Other channels are ignored.
+
+PeopleSQL registers three optional tools when enabled:
+
+- `memory_people_inspect` lets an owner read one exact person or bounded actionable todos;
+- `memory_people_update` changes explicit policy, company, todo, deletion, or
+  restoration state; and
+- `memory_people_sync` manually enriches one Slack account through OpenClaw's
+  authenticated directory CLI without accepting or reading a token.
+
+Allow the tools you intend the agent to use through OpenClaw's `tools.allow`
+configuration; enabling PeopleSQL alone does not expose optional tools.
+
+Inspection, administrative updates, and directory sync require OpenClaw's
+host-derived owner authorization. Dossier replacement runs only through the plugin-owned
+Codex refinement command. Soft-deleted people can be restored explicitly; restoration
+leaves both policies disabled. The sync is bounded to
+200 normalized directory entries per call and is safe to rerun. With pinned
+OpenClaw `2026.8.1-beta.3`, the directory contract supplies ID, name, and handle;
+Unblock Memory ignores raw provider payloads. Slack requires the
+`users:read` scope.
+
+For weekly dossier maintenance, schedule the plugin-owned CLI with an
+operator-authored OpenClaw command automation rather than adding a plugin
+scheduler:
+
+```bash
+openclaw automations create "0 4 * * 0" \
+  --name "People Whisperer refinement" \
+  --command-argv '["openclaw","unblock-memory","people","refine","--agent","main"]' \
+  --timeout-seconds 1800 \
+  --no-deliver
+```
+
+`openclaw unblock-memory people refine --agent <id>` selects a bounded candidate
+batch, reads exact-sender session evidence, and invokes one
+ephemeral, read-only `codex exec` with structured output. It validates the
+complete result set, person IDs, dossier schema, and evidence locators before
+writing each dossier transactionally. Refinement uses exact-attributed session
+evidence; additional evidence sources can be added when they are implemented.
+The host running the command must already have working Codex CLI authentication.
+The plugin performs no model call on the prompt-injection path.
+
+Set both `people.whisperer.enabled` and the person's injection policy to enable
+prompt context. The plugin then prepends only that exact person's stored dossier
+blurb, bounded by `maxChars`, once per session. Unknown, unavailable, or
+incomplete identities produce no context. This non-bundled prompt hook requires
+`plugins.entries.unblock-memory.hooks.allowConversationAccess: true` and remains
+subject to OpenClaw's `allowPromptInjection` policy.
+
 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

package/dist/src/analysis.js

@@ -123,30 +123,40 @@ export function runAnalysisWorker(params) {
             stderrBytes += Math.min(chunk.length, remaining);
         });
         let settled = false;
-        let abortError;
-        const cleanup = () => params.signal?.removeEventListener("abort", onAbort);
-        const finish = (error) => {
+        let aborted = false;
+        let abortReason;
+        let forceKill;
+        const cleanup = () => {
+            params.signal?.removeEventListener("abort", onAbort);
+            if (forceKill)
+                clearTimeout(forceKill);
+        };
+        const finish = (error, shouldReject = error !== undefined) => {
             if (settled)
                 return;
             settled = true;
             cleanup();
-            error ? reject(error) : resolve();
+            shouldReject ? reject(error) : resolve();
         };
         const onAbort = () => {
-            if (abortError)
+            if (aborted)
                 return;
-            abortError = params.signal?.reason instanceof Error
-                ? params.signal.reason
-                : new Error("Memory reclustering aborted");
+            aborted = true;
+            abortReason = params.signal?.reason;
             child.kill("SIGTERM");
+            forceKill = setTimeout(() => {
+                if (!settled)
+                    child.kill("SIGKILL");
+            }, 250);
+            forceKill.unref();
         };
         params.signal?.addEventListener("abort", onAbort, { once: true });
         if (params.signal?.aborted)
             onAbort();
-        child.on("error", (error) => finish(abortError ?? error));
+        child.on("error", (error) => finish(aborted ? abortReason : error, true));
         child.on("close", (code, signal) => {
-            if (abortError) {
-                finish(abortError);
+            if (aborted) {
+                finish(abortReason, true);
                 return;
             }
             if (code === 0) {

package/dist/src/config.d.ts

@@ -9,7 +9,7 @@ export type SkillCorpusConfig = {
     paths: readonly string[];
 };
 declare const CHAT_TYPES: readonly ["channel", "group", "direct"];
-export type ChatType = typeof CHAT_TYPES[number];
+export type ChatType = (typeof CHAT_TYPES)[number];
 type SessionCorpusConfig = {
     name: "sessions";
     kind: "sessions";
@@ -23,6 +23,19 @@ export type UnblockMemoryConfig = {
     analysis: {
         executable?: string;
     };
+    people: {
+        enabled: boolean;
+        refinement: {
+            maxPeoplePerRun: number;
+        };
+        whisperer: {
+            enabled: boolean;
+            maxChars: number;
+        };
+        todos: {
+            maxOpen: number;
+        };
+    };
     skillWhisperer: {
         enabled: boolean;
         historyMessages: number;
@@ -30,5 +43,6 @@ export type UnblockMemoryConfig = {
         cooldownTurns: number;
     };
 };
+export declare const DEFAULT_PEOPLE_CONFIG: UnblockMemoryConfig["people"];
 export declare function resolveConfig(value: unknown): UnblockMemoryConfig;
 export {};

package/dist/src/config.js

@@ -1,11 +1,19 @@
 import { isAbsolute } from "node:path";
 const DEFAULT_PATHS = ["MEMORY.md", "USER.md", "memory/**/*.md"];
 const CHAT_TYPES = ["channel", "group", "direct"];
-export const DEFAULT_CORPORA = [{
+export const DEFAULT_CORPORA = [
+    {
         name: "memory",
         kind: "files",
         paths: DEFAULT_PATHS,
-    }];
+    },
+];
+export const DEFAULT_PEOPLE_CONFIG = {
+    enabled: false,
+    refinement: { maxPeoplePerRun: 10 },
+    whisperer: { enabled: false, maxChars: 1200 },
+    todos: { maxOpen: 1000 },
+};
 const DEFAULT_SKILL_WHISPERER = {
     enabled: false,
     historyMessages: 5,
@@ -44,7 +52,8 @@ function resolveCorpora(value) {
             if (name !== "skills") {
                 throw new Error('unblock-memory skills corpus must be named "skills"');
             }
-            if (!Array.isArray(corpus.paths) || corpus.paths.length === 0 ||
+            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");
             }
@@ -56,11 +65,16 @@ function resolveCorpora(value) {
                 throw new Error('unblock-memory session corpus must be named "sessions"');
             }
             const chatTypes = corpus.chatTypes ?? ["channel", "group"];
-            if (!Array.isArray(chatTypes) || chatTypes.length === 0 ||
+            if (!Array.isArray(chatTypes) ||
+                chatTypes.length === 0 ||
                 !chatTypes.every((chatType) => CHAT_TYPES.includes(chatType))) {
                 throw new Error(`unblock-memory corpus sessions chatTypes must contain channel, group, or direct`);
             }
-            return { name: "sessions", kind: "sessions", chatTypes: [...new Set(chatTypes)] };
+            return {
+                name: "sessions",
+                kind: "sessions",
+                chatTypes: [...new Set(chatTypes)],
+            };
         }
         assertOnlyKeys(corpus, ["name", "kind", "paths"], `corpora[${index}]`);
         if (name === "sessions") {
@@ -72,7 +86,8 @@ function resolveCorpora(value) {
         if (corpus.kind !== "files") {
             throw new Error(`unblock-memory corpus ${name} must have kind "files", "skills", or "sessions"`);
         }
-        if (!Array.isArray(corpus.paths) || corpus.paths.length === 0 ||
+        if (!Array.isArray(corpus.paths) ||
+            corpus.paths.length === 0 ||
             !corpus.paths.every((path) => typeof path === "string" && path.trim())) {
             throw new Error(`unblock-memory corpus ${name} paths must be a non-empty array of non-empty strings`);
         }
@@ -83,12 +98,70 @@ function resolveCorpora(value) {
     }
     return corpora;
 }
+function positiveInteger(value, fallback, label, maximum) {
+    const resolved = value ?? fallback;
+    if (typeof resolved !== "number" ||
+        !Number.isInteger(resolved) ||
+        resolved < 1 ||
+        resolved > maximum) {
+        throw new Error(`unblock-memory ${label} must be a positive integer no greater than ${maximum}`);
+    }
+    return resolved;
+}
+function resolvePeople(value) {
+    if (value === undefined)
+        return DEFAULT_PEOPLE_CONFIG;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("unblock-memory people must be an object");
+    }
+    const people = value;
+    assertOnlyKeys(people, ["enabled", "refinement", "whisperer", "todos"], "people");
+    const enabled = people.enabled ?? false;
+    if (typeof enabled !== "boolean")
+        throw new Error("unblock-memory people.enabled must be a boolean");
+    const refinement = people.refinement ?? {};
+    if (!refinement || typeof refinement !== "object" || Array.isArray(refinement)) {
+        throw new Error("unblock-memory people.refinement must be an object");
+    }
+    const refinementRecord = refinement;
+    assertOnlyKeys(refinementRecord, ["maxPeoplePerRun"], "people.refinement");
+    const whisperer = people.whisperer ?? {};
+    if (!whisperer || typeof whisperer !== "object" || Array.isArray(whisperer)) {
+        throw new Error("unblock-memory people.whisperer must be an object");
+    }
+    const whispererRecord = whisperer;
+    assertOnlyKeys(whispererRecord, ["enabled", "maxChars"], "people.whisperer");
+    const whispererEnabled = whispererRecord.enabled ?? false;
+    if (typeof whispererEnabled !== "boolean") {
+        throw new Error("unblock-memory people.whisperer.enabled must be a boolean");
+    }
+    const todos = people.todos ?? {};
+    if (!todos || typeof todos !== "object" || Array.isArray(todos)) {
+        throw new Error("unblock-memory people.todos must be an object");
+    }
+    const todosRecord = todos;
+    assertOnlyKeys(todosRecord, ["maxOpen"], "people.todos");
+    return {
+        enabled,
+        refinement: {
+            maxPeoplePerRun: positiveInteger(refinementRecord.maxPeoplePerRun, DEFAULT_PEOPLE_CONFIG.refinement.maxPeoplePerRun, "people.refinement.maxPeoplePerRun", 50),
+        },
+        whisperer: {
+            enabled: whispererEnabled,
+            maxChars: positiveInteger(whispererRecord.maxChars, DEFAULT_PEOPLE_CONFIG.whisperer.maxChars, "people.whisperer.maxChars", 4000),
+        },
+        todos: {
+            maxOpen: positiveInteger(todosRecord.maxOpen, DEFAULT_PEOPLE_CONFIG.todos.maxOpen, "people.todos.maxOpen", 10_000),
+        },
+    };
+}
 export function resolveConfig(value) {
     if (value === undefined || value === null) {
         return {
             corpora: DEFAULT_CORPORA,
             keepEmbeddingModelWarm: true,
             analysis: {},
+            people: DEFAULT_PEOPLE_CONFIG,
             skillWhisperer: DEFAULT_SKILL_WHISPERER,
         };
     }
@@ -96,9 +169,11 @@ export function resolveConfig(value) {
         throw new Error("unblock-memory config must be an object");
     }
     const config = value;
-    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "skillWhisperer"], "config");
+    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "skillWhisperer"], "config");
     const corpora = resolveCorpora(config.corpora);
-    if (config.keepEmbeddingModelWarm !== undefined && typeof config.keepEmbeddingModelWarm !== "boolean") {
+    const people = resolvePeople(config.people);
+    if (config.keepEmbeddingModelWarm !== undefined &&
+        typeof config.keepEmbeddingModelWarm !== "boolean") {
         throw new Error("unblock-memory keepEmbeddingModelWarm must be a boolean");
     }
     const keepEmbeddingModelWarm = config.keepEmbeddingModelWarm ?? true;
@@ -119,7 +194,9 @@ export function resolveConfig(value) {
     }
     let skillWhisperer = DEFAULT_SKILL_WHISPERER;
     if (config.skillWhisperer !== undefined) {
-        if (!config.skillWhisperer || typeof config.skillWhisperer !== "object" || Array.isArray(config.skillWhisperer)) {
+        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;
@@ -130,13 +207,20 @@ export function resolveConfig(value) {
         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) {
+        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) {
+        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) {
+        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 };
@@ -144,5 +228,5 @@ export function resolveConfig(value) {
     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: analysisConfig, skillWhisperer };
+    return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, people, skillWhisperer };
 }

package/dist/src/contracts.d.ts

@@ -1,4 +1,5 @@
 import type { MemoryPluginCapability } from "openclaw/plugin-sdk/memory-host-core";
+import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk/plugin-entry";
 import type { SessionMetadata } from "./session-projector.js";
 import type { ChatType } from "./config.js";
 export type MemoryPluginRuntimeContract = NonNullable<MemoryPluginCapability["runtime"]>;
@@ -18,9 +19,11 @@ export type SessionSearchFilter = {
     accountId?: string;
     conversationId?: string;
 };
+export type MemoryRequestContext = Pick<OpenClawPluginToolContext, "sessionKey" | "sessionId" | "messageChannel" | "agentAccountId" | "nativeChannelId" | "deliveryContext">;
 export type CorpusSearchOptions = NonNullable<Parameters<MemorySearchManagerContract["search"]>[1]> & {
     corpora?: readonly string[];
     sessionFilter?: SessionSearchFilter;
+    requestContext?: MemoryRequestContext;
 };
 export type MemoryEmbeddingProbeResult = Awaited<ReturnType<MemorySearchManagerContract["probeEmbeddingAvailability"]>>;
 export type MemorySyncParams = Parameters<NonNullable<MemorySearchManagerContract["sync"]>>[0];

package/dist/src/manager.d.ts

@@ -1,6 +1,6 @@
 import type { QMDStore } from "@unblocklabs/qmd";
 import { type AnalysisRunner, type MemoryAnalysisSummary, type MemoryClusterDetail, type MemoryClusterList, type MemoryClusterSort, type MemoryReclusterOptions } from "./analysis.js";
-import type { CorpusMemorySearchResult, CorpusSearchOptions, MemoryEmbeddingProbeResult, MemoryProviderStatus, MemoryReadResult, MemorySearchManagerContract, MemorySyncParams } from "./contracts.js";
+import type { CorpusMemorySearchResult, CorpusSearchOptions, MemoryEmbeddingProbeResult, MemoryProviderStatus, MemoryReadResult, MemoryRequestContext, MemorySearchManagerContract, MemorySyncParams } from "./contracts.js";
 import type { ChatType } from "./config.js";
 import { type MaintenanceStatus, type TemporalBasis } from "./curation.js";
 import { type SessionSyncResult } from "./session-sync.js";
@@ -75,6 +75,7 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         relPath: string;
         from?: number;
         lines?: number;
+        requestContext?: MemoryRequestContext;
     }): Promise<MemoryReadResult>;
     status(): MemoryProviderStatus;
     probeEmbeddingAvailability(): Promise<MemoryEmbeddingProbeResult>;

package/dist/src/manager.js

@@ -6,7 +6,7 @@ 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";
-import { parseSafeVirtualPath } from "./sources.js";
+import { parseSafeVirtualPath, sourceMatchesPath } from "./sources.js";
 const DEFAULT_READ_LINES = 120;
 const MAX_READ_CHARS = 12_000;
 const WATCH_DEBOUNCE_MS = 250;
@@ -312,8 +312,11 @@ export class QmdMemoryManager {
         this.#watcher.on("all", (_event, path) => {
             if (this.#closed)
                 return;
-            if (basename(path).toLowerCase() === "skill.md")
+            const matchingSources = [...this.#sources.values()].filter((source) => source.kind !== "sessions" && sourceMatchesPath(source, path));
+            if (matchingSources.some((source) => source.kind === "skills"))
                 this.#skillIndex = undefined;
+            if (!matchingSources.some((source) => source.kind !== "skills"))
+                return;
             this.#dirty = true;
             if (this.#watchTimer)
                 clearTimeout(this.#watchTimer);
@@ -341,7 +344,7 @@ export class QmdMemoryManager {
             dbPath: this.#dbPath,
             keepModelsWarm: this.#keepModelsWarm,
             config: {
-                collections: Object.fromEntries([...this.#sources.values()].map((source) => [
+                collections: Object.fromEntries(this.#qmdSources().map((source) => [
                     source.collection,
                     { path: source.root, pattern: source.pattern },
                 ])),
@@ -350,7 +353,7 @@ export class QmdMemoryManager {
         enableSecureDelete(store);
         ensureMemoryAnalysisSchema(store.internal.db);
         markStaleForAnalysisCollectionChange(store.internal.db, this.#analysisCollectionNames(), this.#skillCollectionNames().length > 0);
-        const configuredCollections = new Set(this.#allCollectionNames());
+        const configuredCollections = new Set(this.#qmdSources().map((source) => source.collection));
         const staleCollections = (await store.getStatus()).collections
             .map((collection) => collection.name)
             .filter((collection) => !configuredCollections.has(collection));
@@ -383,8 +386,8 @@ export class QmdMemoryManager {
         this.#store = store;
         return store;
     }
-    #allCollectionNames() {
-        return [...this.#sources.keys()];
+    #qmdSources() {
+        return [...this.#sources.values()].filter((source) => source.kind !== "skills");
     }
     #analysisCollectionNames() {
         return [...this.#sources.values()]
@@ -421,7 +424,7 @@ export class QmdMemoryManager {
             const store = await this.#getStore();
             this.#dirty = true;
             const analysisStore = store;
-            const collections = [...this.#sources.values()].filter((source) => source.kind !== "sessions");
+            const collections = this.#qmdSources().filter((source) => source.kind !== "sessions");
             let analysisMarkedStale = false;
             const markAnalysisStale = () => {
                 if (analysisMarkedStale || !analysisStore.internal)
@@ -444,16 +447,14 @@ 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))
+                if (changed || params?.force === true)
                     markAnalysisStale();
                 const embed = await store.embed({
                     collection: source.collection,
                     force: params?.force,
                     chunkStrategy: "semantic",
                 });
-                if (source.kind !== "skills" && completedEmbeddingCount(embed) > 0)
+                if (completedEmbeddingCount(embed) > 0)
                     markAnalysisStale();
             }
             const status = await store.getStatus();
@@ -736,41 +737,47 @@ export class QmdMemoryManager {
         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,
-                        });
+        let skillIndex = this.#skillIndex;
+        if (!skillIndex) {
+            const pending = (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,
+                            });
+                        }
                     }
                 }
-            }
-            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 }] : [];
+                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 }] : [];
+                });
+            })();
+            skillIndex = pending.catch((error) => {
+                if (this.#skillIndex === skillIndex)
+                    this.#skillIndex = undefined;
+                throw error;
             });
-        })().catch((error) => {
-            this.#skillIndex = undefined;
-            throw error;
-        });
+            this.#skillIndex = skillIndex;
+        }
         const queryEmbedding = await llm.embed(queryText(query, llm.embedModelName), { isQuery: true });
         if (!queryEmbedding)
             return [];
-        const candidates = await this.#skillIndex;
+        const candidates = await skillIndex;
         return candidates
             .map(({ embedding, ...candidate }) => ({
             ...candidate,

package/dist/src/people-cli.d.ts

@@ -0,0 +1,4 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { UnblockMemoryConfig } from "./config.js";
+import { type PeopleRefinementRunner } from "./people-refinement.js";
+export declare function registerPeopleCli(api: OpenClawPluginApi, config: UnblockMemoryConfig["people"], runner?: PeopleRefinementRunner): void;

package/dist/src/people-cli.js

@@ -0,0 +1,47 @@
+import { join } from "node:path";
+import { resolveAgentDir } from "openclaw/plugin-sdk/memory-core-host-engine-foundation";
+import { PeopleStores } from "./people-store.js";
+import { codexPeopleRefinementRunner, refinePeople, } from "./people-refinement.js";
+export function registerPeopleCli(api, config, runner = codexPeopleRefinementRunner) {
+    api.registerCli(({ program, config: openClawConfig }) => {
+        const root = program.command("unblock-memory").description("Unblock Memory administration");
+        const people = root.command("people").description("Maintain the agent-local people store");
+        people
+            .command("refine")
+            .description("Refine stale enabled people with Codex")
+            .requiredOption("--agent <id>", "Agent id")
+            .action(async (options) => {
+            const agentId = options.agent.trim();
+            if (!agentId)
+                throw new Error("--agent must be a non-empty string");
+            if (!config.enabled)
+                throw new Error("PeopleSQL is disabled");
+            const stores = new PeopleStores({
+                maxOpenTodos: config.todos.maxOpen,
+                maxBlurbChars: config.whisperer.maxChars,
+            });
+            try {
+                const summary = await refinePeople({
+                    store: stores.get(agentId),
+                    agentId,
+                    agentDatabasePath: join(resolveAgentDir(openClawConfig, agentId), "openclaw-agent.sqlite"),
+                    candidateLimit: config.refinement.maxPeoplePerRun,
+                    maxBlurbChars: config.whisperer.maxChars,
+                    runner,
+                });
+                process.stdout.write(`${JSON.stringify(summary)}\n`);
+            }
+            finally {
+                stores.closeAll();
+            }
+        });
+    }, {
+        descriptors: [
+            {
+                name: "unblock-memory",
+                description: "Unblock Memory administration",
+                hasSubcommands: true,
+            },
+        ],
+    });
+}

package/dist/src/people-evidence.d.ts

@@ -0,0 +1,14 @@
+export type PersonSessionEvidence = {
+    source: "session";
+    locator: string;
+    observedAt: string;
+    text: string;
+};
+export declare function readPersonSessionEvidence(params: {
+    databasePath: string;
+    agentId: string;
+    accountScope: string;
+    externalId: string;
+    limit?: number;
+    maxMessageChars?: number;
+}): PersonSessionEvidence[];