@unblocklabs/unblock-memory 0.3.7 → 0.3.9

package/README.md

@@ -139,57 +139,79 @@ directory.
 
 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.
+account and sender IDs create or refresh an injection-enabled 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:
+PeopleSQL registers three 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.
+- `memory_people_inspect` lists active people, reads one exact person, reads one
+  person's dossier change history, or lists bounded actionable todos;
+- `memory_people_update` replaces or deletes dossiers, toggles one person's
+  injection, and manages company, todo, deletion, or restoration state; and
+- the optional `memory_people_sync` enriches one active OpenClaw Slack account;
+  its tool input accepts an account ID, not 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
+The inspect and update tools are part of the normal agent tool surface; they do
+not depend on sender-owner authorization. Directory sync remains optional and
+may need to be allowed explicitly. The sync is bounded to
+200 normalized directory entries per call and is safe to rerun. Unblock Memory
+keeps only normalized ID, name, handle, and avatar fields. 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:
+The agent owns dossier generation and refresh. It can list people, inspect one
+person's current dossier, search ordinary memory and sessions with
+`memory_search`/`memory_get`, and replace the dossier when that would improve a
+future conversation. The plugin owns no dossier-maintenance workflow or refresh
+schedule. A dossier's `reviewedAt` value records its last successful write; it
+is not scheduling state. The plugin performs no model call for dossier
+maintenance or prompt injection.
+
+Every `replace_dossier` and `delete_dossier` action requires a concise `reason`.
+The plugin transactionally records that reason with its authoritative before and
+after dossier snapshots. List small newest-first summaries with
+`memory_people_inspect({ view: "dossier_changes", personId, limit?, offset? })`,
+then fetch one exact diff with
+`memory_people_inspect({ view: "dossier_change", personId, changeId })`. List
+responses include `nextOffset`, so all history remains reachable without loading
+many dossiers into one tool result. Because the injected snippet is the dossier's
+`blurb`, its changes are included in the same history. A complete new serialized
+dossier is capped at 64 KiB; larger legacy dossiers remain readable and repairable.
+
+Set `people.whisperer.enabled` to inject context. For each exact Slack sender,
+the plugin prepends that person's stored dossier blurb, bounded by `maxChars`,
+once per `(Slack thread, person)`. Receipts are durable across retries and
+Gateway restarts, while different people in one thread are handled independently.
+Unthreaded DMs use their OpenClaw session as the conversational scope. Unknown,
+unavailable, disabled, or dossierless people produce no context. Injection
+remains subject to OpenClaw's `allowPromptInjection` policy.
+
+The package includes a `$people-whisperer` skill with the canonical agent
+procedure and dossier shape. For a manual refresh, ask:
 
-```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
+```text
+Use $people-whisperer to improve your understanding of this person. Search memory
+and recent sessions, inspect their current PeopleSQL dossier, and update it only
+if the result would make future conversations meaningfully better.
+```
+
+For an optional cron or isolated agent session, use this goal:
+
+```text
+Use $people-whisperer to improve your understanding of people you interact with.
+
+Search recent sessions and memory for meaningful information about people. Inspect
+their existing PeopleSQL dossiers when useful. Update a dossier only when doing so
+would make future conversations meaningfully better. Ignore routine conversation,
+repetition, and weak inference. You may update several people or nobody.
 ```
 
-`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.
+Choose any cadence appropriate for the agent; the plugin does not require or
+track one. If session transcripts are a source, configure a `sessions` corpus
+(including `direct` when DMs matter) and refresh it with
+`memory_sync_sessions`. Ordinary `memory_search` calls accept targeted queries,
+corpora, session metadata filters, score thresholds, and up to 20 results per
+call; People Whisperer itself imposes no evidence-window limit.
 
 Use `sessionFilter` to restrict session results by metadata while leaving file
 corpora searchable. Supported fields are `startedFrom` and `startedTo`

package/dist/src/config.d.ts

@@ -25,9 +25,6 @@ export type UnblockMemoryConfig = {
     };
     people: {
         enabled: boolean;
-        refinement: {
-            maxPeoplePerRun: number;
-        };
         whisperer: {
             enabled: boolean;
             maxChars: number;

package/dist/src/config.js

@@ -10,7 +10,6 @@ export const DEFAULT_CORPORA = [
 ];
 export const DEFAULT_PEOPLE_CONFIG = {
     enabled: false,
-    refinement: { maxPeoplePerRun: 10 },
     whisperer: { enabled: false, maxChars: 1200 },
     todos: { maxOpen: 1000 },
 };
@@ -115,16 +114,10 @@ function resolvePeople(value) {
         throw new Error("unblock-memory people must be an object");
     }
     const people = value;
-    assertOnlyKeys(people, ["enabled", "refinement", "whisperer", "todos"], "people");
+    assertOnlyKeys(people, ["enabled", "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");
@@ -143,9 +136,6 @@ function resolvePeople(value) {
     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),

package/dist/src/people-hooks.js

@@ -2,6 +2,14 @@ import { parseAgentSessionKey } from "openclaw/plugin-sdk/routing";
 function nonBlank(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function identifier(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return nonBlank(value);
+}
+function promptIdentityKey(sessionKey, accountScope, externalId) {
+    return JSON.stringify([sessionKey, accountScope, externalId]);
+}
 function observedAt(timestamp) {
     if (timestamp === undefined || !Number.isFinite(timestamp))
         return undefined;
@@ -13,18 +21,41 @@ export function renderPeopleWhisper(blurb, maxChars) {
     return normalized ? normalized.slice(0, maxChars) : undefined;
 }
 export function registerPeopleHooks(api, stores, config) {
+    const threadByRun = new Map();
+    const pendingThreadByIdentity = new Map();
     api.on("message_received", (event, context) => {
         if (context.channelId !== "slack")
             return;
-        const agentId = parseAgentSessionKey(context.sessionKey)?.agentId;
-        if (!agentId)
+        const parsed = parseAgentSessionKey(context.sessionKey);
+        if (!parsed)
             return;
         const accountScope = nonBlank(context.accountId);
         const externalId = nonBlank(context.senderId);
+        const conversationId = nonBlank(context.conversationId);
+        const runId = nonBlank(event.runId) ?? nonBlank(context.runId);
+        const sessionKey = nonBlank(context.sessionKey);
+        if (config.whisperer.enabled && accountScope && externalId && conversationId && sessionKey) {
+            const threadRootId = identifier(event.threadId) ?? nonBlank(event.replyToId);
+            const rootMessageId = threadRootId ?? nonBlank(event.messageId);
+            const threadKey = conversationId.startsWith("D") && threadRootId === undefined
+                ? `slack:${accountScope}:${conversationId}:session:${sessionKey}`
+                : rootMessageId
+                    ? `slack:${accountScope}:${conversationId}:${rootMessageId}`
+                    : undefined;
+            if (threadKey) {
+                const identityKey = promptIdentityKey(sessionKey, accountScope, externalId);
+                if (runId) {
+                    threadByRun.set(runId, threadKey);
+                }
+                else {
+                    const pendingThreadKey = pendingThreadByIdentity.get(identityKey);
+                    pendingThreadByIdentity.set(identityKey, pendingThreadKey === undefined || pendingThreadKey === threadKey ? threadKey : null);
+                }
+            }
+        }
         try {
-            const store = stores.get(agentId);
+            const store = stores.get(parsed.agentId);
             if (!accountScope || !externalId) {
-                const conversationId = nonBlank(context.conversationId);
                 store.upsertTodo({
                     deduplicationKey: `incomplete-slack-identity:${accountScope ?? "missing"}:${externalId ?? "missing"}:` +
                         `${conversationId ?? "unknown"}`,
@@ -52,50 +83,59 @@ export function registerPeopleHooks(api, stores, config) {
     });
     if (!config.whisperer.enabled)
         return;
-    const injectedBySession = new Map();
     api.on("before_prompt_build", (_event, context) => {
         if (context.trigger !== "user" || context.messageProvider !== "slack")
             return;
-        const parsed = parseAgentSessionKey(context.sessionKey);
+        const sessionKey = nonBlank(context.sessionKey);
+        const parsed = parseAgentSessionKey(sessionKey);
         const accountScope = nonBlank(context.accountId);
         const externalId = nonBlank(context.senderId);
-        const sessionScope = nonBlank(context.sessionId) ?? nonBlank(context.sessionKey);
         const runId = nonBlank(context.runId);
-        if (!parsed || !accountScope || !externalId || !sessionScope || !runId)
+        if (!sessionKey || !parsed || !accountScope || !externalId || !runId)
+            return;
+        const identityKey = promptIdentityKey(sessionKey, accountScope, externalId);
+        const mappedThreadKey = threadByRun.get(runId);
+        const pendingThreadKey = mappedThreadKey ? undefined : pendingThreadByIdentity.get(identityKey);
+        if (!mappedThreadKey && pendingThreadByIdentity.has(identityKey)) {
+            pendingThreadByIdentity.delete(identityKey);
+        }
+        const threadKey = mappedThreadKey ?? pendingThreadKey ?? undefined;
+        if (!threadKey)
             return;
+        if (typeof pendingThreadKey === "string") {
+            threadByRun.set(runId, pendingThreadKey);
+        }
         try {
             const store = stores.get(parsed.agentId);
             const person = store.findPersonByIdentity("slack", accountScope, externalId);
             if (!person || person.status !== "active" || !person.injectionEnabled)
                 return;
-            const injected = injectedBySession.get(sessionScope);
-            const previous = injected?.get(person.id);
-            if (previous)
-                return previous.runId === runId ? previous.contribution : undefined;
+            const previous = store.getWhisperReceipt(threadKey, person.id);
+            if (previous) {
+                return previous.runId === runId ? { prependContext: previous.contribution } : undefined;
+            }
             const blurb = store.getDossierBlurb(person.id);
             const prependContext = blurb
                 ? renderPeopleWhisper(blurb, config.whisperer.maxChars)
                 : undefined;
             if (!prependContext)
                 return;
-            const contribution = { prependContext };
-            const state = { runId, contribution };
-            if (injected)
-                injected.set(person.id, state);
-            else
-                injectedBySession.set(sessionScope, new Map([[person.id, state]]));
-            return contribution;
+            const receipt = store.recordWhisperReceipt({
+                threadKey,
+                personId: person.id,
+                runId,
+                contribution: prependContext,
+            });
+            return receipt.runId === runId ? { prependContext: receipt.contribution } : undefined;
         }
         catch (error) {
             api.logger.warn(`unblock-memory people whisperer lookup failed: ${String(error)}`);
             return;
         }
     });
-    api.on("session_end", (event, context) => {
-        injectedBySession.delete(event.sessionId);
-        if (event.sessionKey)
-            injectedBySession.delete(event.sessionKey);
-        if (context.sessionKey)
-            injectedBySession.delete(context.sessionKey);
+    api.on("agent_end", (event, context) => {
+        const runId = nonBlank(event.runId) ?? nonBlank(context.runId);
+        if (runId)
+            threadByRun.delete(runId);
     });
 }

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

@@ -17,13 +17,25 @@ export declare const PERSON_DOSSIER_SCHEMA: Type.TObject<{
     }>>;
 }>;
 export type PersonDossier = Static<typeof PERSON_DOSSIER_SCHEMA>;
+export type PersonDossierChange = {
+    id: string;
+    personId: string;
+    action: "replace" | "delete";
+    beforeDossier: PersonDossier | null;
+    afterDossier: PersonDossier | null;
+    reason: string;
+    changedAt: string;
+};
+export type PersonDossierChangeSummary = Omit<PersonDossierChange, "beforeDossier" | "afterDossier"> & {
+    beforeDossierBytes: number | null;
+    afterDossierBytes: number | null;
+};
 export type Person = {
     id: string;
     displayName: string;
     preferredName: string | null;
     status: "active" | "unavailable" | "archived";
     companyId: string | null;
-    refinementEnabled: boolean;
     injectionEnabled: boolean;
     lastSeenAt: string | null;
     createdAt: string;
@@ -98,19 +110,33 @@ export declare class PeopleStore {
         name: string;
         primaryDomain?: string;
     }): Company | undefined;
-    listRefinementCandidates(limit: number): Person[];
+    listActivePeople(limit?: number, offset?: number): Person[];
     findIdentity(provider: string, accountScope: string, externalId: string): PersonIdentity | undefined;
-    setPolicies(personId: string, policies: {
-        refinementEnabled?: boolean;
-        injectionEnabled?: boolean;
-    }): Person | undefined;
-    replaceDossier(personId: string, input: unknown, reviewedAt?: string, options?: {
-        requireRefinementEnabled?: boolean;
-    }): PersonDossier;
+    setInjection(personId: string, enabled: boolean): Person | undefined;
+    replaceDossier(personId: string, reasonInput: string, input: unknown): PersonDossier;
+    deleteDossier(personId: string, reasonInput: string): boolean;
+    getWhisperReceipt(threadKey: string, personId: string): {
+        runId: string;
+        contribution: string;
+        injectedAt: string;
+    } | undefined;
+    recordWhisperReceipt(input: {
+        threadKey: string;
+        personId: string;
+        runId: string;
+        contribution: string;
+    }): {
+        runId: string;
+        contribution: string;
+        injectedAt: string;
+    };
     getDossier(personId: string): {
         dossier: PersonDossier;
         reviewedAt: string;
     } | undefined;
+    getDossierReviewedAt(personId: string): string | undefined;
+    listDossierChanges(personId: string, limit?: number, offset?: number): PersonDossierChangeSummary[];
+    getDossierChange(personId: string, changeId: string): PersonDossierChange | undefined;
     getDossierBlurb(personId: string): string | undefined;
     softDeletePerson(personId: string): Person | undefined;
     restorePerson(personId: string): Person | undefined;