@unblocklabs/unblock-memory 0.3.7 → 0.3.8

package/README.md

@@ -139,57 +139,41 @@ 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
+- `memory_people_inspect` reads one exact person, bounded actionable todos, or
+  the next person's unseen exact-attributed interaction evidence;
+- `memory_people_update` replaces or deletes dossiers, consumes evidence,
+  toggles one person's injection, and manages 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
+- the optional `memory_people_sync` enriches one active OpenClaw Slack account;
+  its tool input accepts an account ID, not a token.
+
+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:
-
-```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.
+The agent owns dossier generation and refresh. A cron or isolated agent session
+can repeatedly inspect `refinement_next`, synthesize a dossier from its current
+state and bounded unseen interaction windows, then call `replace_dossier` with
+the evidence locators it consumed. Dossier replacement and evidence consumption
+commit atomically; a no-change run may consume evidence without replacing the
+dossier. The plugin performs no model call for refinement or prompt injection.
+
+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.
 
 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 },
 };
@@ -119,12 +118,18 @@ function resolvePeople(value) {
     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");
+    // Accepted only so existing installations can upgrade without first rewriting config.
+    const legacyRefinement = people.refinement;
+    if (legacyRefinement !== undefined) {
+        if (!legacyRefinement ||
+            typeof legacyRefinement !== "object" ||
+            Array.isArray(legacyRefinement)) {
+            throw new Error("unblock-memory people.refinement must be an object");
+        }
+        const legacy = legacyRefinement;
+        assertOnlyKeys(legacy, ["maxPeoplePerRun"], "people.refinement");
+        positiveInteger(legacy.maxPeoplePerRun, 10, "people.refinement.maxPeoplePerRun", 50);
     }
-    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 +148,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-evidence.d.ts

@@ -3,6 +3,12 @@ export type PersonSessionEvidence = {
     locator: string;
     observedAt: string;
     text: string;
+    context: Array<{
+        locator: string;
+        role: string;
+        text: string;
+        senderId?: string;
+    }>;
 };
 export declare function readPersonSessionEvidence(params: {
     databasePath: string;
@@ -11,4 +17,5 @@ export declare function readPersonSessionEvidence(params: {
     externalId: string;
     limit?: number;
     maxMessageChars?: number;
+    excludeLocators?: ReadonlySet<string>;
 }): PersonSessionEvidence[];

package/dist/src/people-evidence.js

@@ -42,9 +42,9 @@ export function readPersonSessionEvidence(params) {
             meta.agent_id !== params.agentId) {
             throw new Error("unsupported or mismatched OpenClaw agent database");
         }
-        const rows = db
-            .prepare(`
-      SELECT events.session_id, active.event_seq, events.event_json, events.created_at
+        const rows = db.prepare(`
+      SELECT events.session_id, active.active_position, active.event_seq,
+        events.event_json, events.created_at
       FROM session_transcript_active_events AS active
       JOIN transcript_events AS events
         ON events.session_id = active.session_id AND events.seq = active.event_seq
@@ -57,24 +57,57 @@ export function readPersonSessionEvidence(params) {
         AND json_extract(events.event_json, '$.message.role') = 'user'
         AND json_extract(events.event_json, '$.message.__openclaw.senderId') = ?
       ORDER BY events.created_at DESC, events.session_id, active.active_position DESC
-      LIMIT ?
-    `)
-            .all(params.accountScope, params.externalId, limit);
-        const evidence = rows.flatMap((row) => {
+    `);
+        const contextStatement = db.prepare(`
+      SELECT active.event_seq, events.event_json
+      FROM session_transcript_active_events AS active
+      JOIN transcript_events AS events
+        ON events.session_id = active.session_id AND events.seq = active.event_seq
+      WHERE active.session_id = ?
+        AND active.message_position IS NOT NULL
+        AND active.active_position BETWEEN ? AND ?
+        AND json_extract(events.event_json, '$.type') = 'message'
+      ORDER BY active.active_position
+    `);
+        const evidence = [];
+        for (const row of rows.iterate(params.accountScope, params.externalId)) {
+            const locator = `session:${row.session_id}:event:${row.event_seq}`;
+            if (params.excludeLocators?.has(locator))
+                continue;
             const event = record(JSON.parse(row.event_json));
             const message = record(event?.message);
             const text = messageText(message?.content);
             if (!event || !message || !text)
-                return [];
-            return [
-                {
-                    source: "session",
-                    locator: `session:${row.session_id}:event:${row.event_seq}`,
-                    observedAt: evidenceTimestamp(event, row.created_at),
-                    text: text.slice(0, maxMessageChars),
-                },
-            ];
-        });
+                continue;
+            const context = contextStatement
+                .all(row.session_id, row.active_position - 1, row.active_position + 2)
+                .flatMap((contextRow) => {
+                const candidate = contextRow;
+                const contextEvent = record(JSON.parse(candidate.event_json));
+                const contextMessage = record(contextEvent?.message);
+                const contextText = messageText(contextMessage?.content);
+                if (!contextMessage || !contextText || typeof contextMessage.role !== "string")
+                    return [];
+                const metadata = record(contextMessage.__openclaw);
+                return [
+                    {
+                        locator: `session:${row.session_id}:event:${candidate.event_seq}`,
+                        role: contextMessage.role,
+                        text: contextText.slice(0, maxMessageChars),
+                        ...(typeof metadata?.senderId === "string" ? { senderId: metadata.senderId } : {}),
+                    },
+                ];
+            });
+            evidence.push({
+                source: "session",
+                locator,
+                observedAt: evidenceTimestamp(event, row.created_at),
+                text: text.slice(0, maxMessageChars),
+                context,
+            });
+            if (evidence.length === limit)
+                break;
+        }
         db.exec("COMMIT");
         return evidence;
     }

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) {
+                    pendingThreadByIdentity.delete(identityKey);
+                    threadByRun.set(runId, threadKey);
+                }
+                else {
+                    pendingThreadByIdentity.set(identityKey, threadKey);
+                }
+            }
+        }
         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,56 @@ 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 pendingThreadKey = pendingThreadByIdentity.get(identityKey);
+        const threadKey = threadByRun.get(runId) ?? pendingThreadKey;
+        if (!threadKey)
             return;
+        if (pendingThreadKey) {
+            pendingThreadByIdentity.delete(identityKey);
+            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-refinement.d.ts

@@ -1,72 +1,14 @@
-import { Type } from "typebox";
 import { type PersonSessionEvidence } from "./people-evidence.js";
-import { type PeopleStore, type PersonDossier, type PersonIdentity } from "./people-store.js";
-export declare const REFINEMENT_OUTPUT_SCHEMA: Type.TObject<{
-    results: Type.TArray<Type.TObject<{
-        personId: Type.TString;
-        dossier: Type.TObject<{
-            schemaVersion: Type.TLiteral<1>;
-            blurb: Type.TString;
-            sections: Type.TArray<Type.TObject<{
-                category: Type.TUnion<Type.TLiteral<"role" | "priorities" | "preferences" | "successCriteria" | "workingStyle" | "relationship" | "openLoops">[]>;
-                claims: Type.TArray<Type.TObject<{
-                    statement: Type.TString;
-                    evidence: Type.TArray<Type.TObject<{
-                        source: Type.TUnion<[Type.TLiteral<"session">, Type.TLiteral<"memory">, Type.TLiteral<"directory">, Type.TLiteral<"manual">]>;
-                        locator: Type.TString;
-                        observedAt: Type.TOptional<Type.TString>;
-                    }>>;
-                    epistemicType: Type.TUnion<[Type.TLiteral<"observed">, Type.TLiteral<"reported">, Type.TLiteral<"inferred">, Type.TLiteral<"agent_assessment">]>;
-                    confidence: Type.TOptional<Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">]>>;
-                }>>;
-            }>>;
-        }>;
-    }>>;
-}>;
-type PeopleRefinementInput = {
-    people: Array<{
-        personId: string;
-        displayName: string;
-        lastSeenAt: string;
-        identities: PersonIdentity[];
-        currentDossier?: PersonDossier;
-        evidence: PersonSessionEvidence[];
-    }>;
+import type { PeopleStore, Person, PersonDossier, PersonIdentity } from "./people-store.js";
+export type PeopleRefinementPacket = {
+    person: Person;
+    identities: PersonIdentity[];
+    currentDossier?: PersonDossier;
+    evidence: PersonSessionEvidence[];
 };
-export type PeopleRefinementRunner = (params: {
-    input: PeopleRefinementInput;
-    outputSchema: typeof REFINEMENT_OUTPUT_SCHEMA;
-    signal?: AbortSignal;
-}) => Promise<unknown>;
-export type PeopleRefinementSummary = {
-    status: "ok";
-    selected: number;
-    refined: number;
-    skippedWithoutEvidence: number;
-    personIds: string[];
-};
-export declare function refinePeople(params: {
+export declare function nextPeopleRefinement(params: {
     store: PeopleStore;
     agentId: string;
     agentDatabasePath: string;
-    maxBlurbChars: number;
-    runner: PeopleRefinementRunner;
-    candidateLimit?: number;
     evidenceLimit?: number;
-    signal?: AbortSignal;
-}): Promise<PeopleRefinementSummary>;
-export type CodexCommandRunner = (params: {
-    executable: string;
-    args: string[];
-    cwd: string;
-    input: string;
-    env: NodeJS.ProcessEnv;
-    signal?: AbortSignal;
-}) => Promise<void>;
-export declare function createCodexPeopleRefinementRunner(runCommand?: CodexCommandRunner, options?: {
-    environment?: NodeJS.ProcessEnv;
-    timeoutMs?: number;
-    maxOutputBytes?: number;
-}): PeopleRefinementRunner;
-export declare const codexPeopleRefinementRunner: PeopleRefinementRunner;
-export {};
+}): PeopleRefinementPacket | undefined;