@unblocklabs/unblock-memory 0.3.8 → 0.3.9

package/README.md

@@ -145,11 +145,10 @@ message content. Other channels are ignored.
 
 PeopleSQL registers three tools when enabled:
 
-- `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_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.
 
@@ -160,12 +159,24 @@ may need to be allowed explicitly. The sync is bounded to
 keeps only normalized ID, name, handle, and avatar fields. Slack requires the
 `users:read` scope.
 
-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.
+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`,
@@ -175,6 +186,33 @@ 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:
+
+```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.
+```
+
+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`
 (inclusive ISO 8601 timestamps), `provider`, `chatType`, `accountId`, and

package/dist/src/config.js

@@ -114,22 +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");
-    // 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 whisperer = people.whisperer ?? {};
     if (!whisperer || typeof whisperer !== "object" || Array.isArray(whisperer)) {
         throw new Error("unblock-memory people.whisperer must be an object");

package/dist/src/people-hooks.js

@@ -45,11 +45,11 @@ export function registerPeopleHooks(api, stores, config) {
             if (threadKey) {
                 const identityKey = promptIdentityKey(sessionKey, accountScope, externalId);
                 if (runId) {
-                    pendingThreadByIdentity.delete(identityKey);
                     threadByRun.set(runId, threadKey);
                 }
                 else {
-                    pendingThreadByIdentity.set(identityKey, threadKey);
+                    const pendingThreadKey = pendingThreadByIdentity.get(identityKey);
+                    pendingThreadByIdentity.set(identityKey, pendingThreadKey === undefined || pendingThreadKey === threadKey ? threadKey : null);
                 }
             }
         }
@@ -94,12 +94,15 @@ export function registerPeopleHooks(api, stores, config) {
         if (!sessionKey || !parsed || !accountScope || !externalId || !runId)
             return;
         const identityKey = promptIdentityKey(sessionKey, accountScope, externalId);
-        const pendingThreadKey = pendingThreadByIdentity.get(identityKey);
-        const threadKey = threadByRun.get(runId) ?? pendingThreadKey;
+        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 (pendingThreadKey) {
-            pendingThreadByIdentity.delete(identityKey);
+        if (typeof pendingThreadKey === "string") {
             threadByRun.set(runId, pendingThreadKey);
         }
         try {

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

@@ -17,6 +17,19 @@ 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;
@@ -97,12 +110,11 @@ export declare class PeopleStore {
         name: string;
         primaryDomain?: string;
     }): Company | undefined;
-    listActivePeople(): Person[];
+    listActivePeople(limit?: number, offset?: number): Person[];
     findIdentity(provider: string, accountScope: string, externalId: string): PersonIdentity | undefined;
     setInjection(personId: string, enabled: boolean): Person | undefined;
-    replaceDossier(personId: string, input: unknown | undefined, consumedEvidenceLocators?: readonly string[]): PersonDossier | undefined;
-    deleteDossier(personId: string): boolean;
-    listProcessedEvidenceLocators(personId: string, source: "session"): Set<string>;
+    replaceDossier(personId: string, reasonInput: string, input: unknown): PersonDossier;
+    deleteDossier(personId: string, reasonInput: string): boolean;
     getWhisperReceipt(threadKey: string, personId: string): {
         runId: string;
         contribution: string;
@@ -122,6 +134,9 @@ export declare class PeopleStore {
         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;

package/dist/src/people-store.js

@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 import { randomUUID } from "node:crypto";
 import { chmodSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -46,6 +47,17 @@ export const PERSON_DOSSIER_SCHEMA = Type.Object({
         claims: Type.Array(claimSchema, { minItems: 1, maxItems: 100 }),
     }, { additionalProperties: false }), { maxItems: BASELINE_DOSSIER_CATEGORIES.length }),
 }, { additionalProperties: false });
+const MAX_DOSSIER_JSON_BYTES = 64 * 1024;
+function serializeDossier(dossier) {
+    const json = JSON.stringify(dossier);
+    if (Buffer.byteLength(json, "utf8") > MAX_DOSSIER_JSON_BYTES) {
+        throw new Error(`dossier must serialize to at most ${MAX_DOSSIER_JSON_BYTES} bytes`);
+    }
+    return json;
+}
+function parseDossierJson(json) {
+    return Value.Parse(PERSON_DOSSIER_SCHEMA, JSON.parse(json));
+}
 const OVERFLOW_KEY = "__people_todo_overflow__";
 function required(value, label) {
     const normalized = value.trim();
@@ -56,6 +68,12 @@ function required(value, label) {
 function optional(value) {
     return value?.trim() || null;
 }
+function dossierReason(value) {
+    const reason = required(value, "reason");
+    if (reason.length > 1000)
+        throw new Error("reason must not exceed 1000 characters");
+    return reason;
+}
 function person(row) {
     return {
         id: row.id,
@@ -290,14 +308,15 @@ export class PeopleStore {
             throw error;
         }
     }
-    listActivePeople() {
+    listActivePeople(limit = 50, offset = 0) {
         return this.#db
             .prepare(`
       SELECT * FROM people
       WHERE status = 'active'
       ORDER BY last_seen_at DESC, id
+      LIMIT ? OFFSET ?
     `)
-            .all()
+            .all(limit, offset)
             .map((row) => person(row));
     }
     findIdentity(provider, accountScope, externalId) {
@@ -312,20 +331,24 @@ export class PeopleStore {
         const row = this.#db.prepare("SELECT * FROM people WHERE id = ?").get(personId);
         return row ? person(row) : undefined;
     }
-    replaceDossier(personId, input, consumedEvidenceLocators = []) {
-        const dossier = input === undefined ? undefined : Value.Parse(PERSON_DOSSIER_SCHEMA, input);
-        if (dossier)
-            this.#validateDossier(dossier);
-        const locators = this.#validateEvidenceLocators(consumedEvidenceLocators);
+    replaceDossier(personId, reasonInput, input) {
+        const dossier = Value.Parse(PERSON_DOSSIER_SCHEMA, input);
+        this.#validateDossier(dossier);
+        const dossierJson = serializeDossier(dossier);
+        const reason = dossierReason(reasonInput);
         const reviewedAt = new Date().toISOString();
         this.#db.exec("BEGIN IMMEDIATE");
         try {
             const target = this.#db.prepare("SELECT id FROM people WHERE id = ?").get(personId);
             if (!target)
                 throw new Error(`person not found: ${personId}`);
-            if (dossier) {
-                this.#db
-                    .prepare(`
+            const existing = this.#db
+                .prepare("SELECT dossier_json FROM person_dossiers WHERE person_id = ?")
+                .get(personId);
+            if (existing)
+                parseDossierJson(existing.dossier_json);
+            this.#db
+                .prepare(`
           INSERT INTO person_dossiers (person_id, dossier_json, blurb, reviewed_at)
           VALUES (?, ?, ?, ?)
           ON CONFLICT(person_id) DO UPDATE SET
@@ -333,36 +356,50 @@ export class PeopleStore {
             blurb = excluded.blurb,
             reviewed_at = excluded.reviewed_at
         `)
-                    .run(personId, JSON.stringify(dossier), dossier.blurb, reviewedAt);
-            }
-            const consume = this.#db.prepare(`
-        INSERT OR IGNORE INTO person_evidence_receipts
-          (person_id, source, locator, processed_at)
-        VALUES (?, 'session', ?, ?)
-      `);
-            for (const locator of locators) {
-                consume.run(personId, locator, reviewedAt);
-            }
+                .run(personId, dossierJson, dossier.blurb, reviewedAt);
+            this.#db
+                .prepare(`
+          INSERT INTO person_dossier_changes
+            (id, person_id, action, before_dossier_json, after_dossier_json, reason, changed_at)
+          VALUES (?, ?, 'replace', ?, ?, ?, ?)
+        `)
+                .run(randomUUID(), personId, existing?.dossier_json ?? null, dossierJson, reason, reviewedAt);
             this.#db.exec("COMMIT");
-            return dossier ?? this.getDossier(personId)?.dossier;
+            return dossier;
         }
         catch (error) {
             this.#db.exec("ROLLBACK");
             throw error;
         }
     }
-    deleteDossier(personId) {
-        return this.#db.prepare("DELETE FROM person_dossiers WHERE person_id = ?").run(personId)
-            .changes === 1;
-    }
-    listProcessedEvidenceLocators(personId, source) {
-        const rows = this.#db
-            .prepare(`
-      SELECT locator FROM person_evidence_receipts
-      WHERE person_id = ? AND source = ?
-    `)
-            .all(personId, source);
-        return new Set(rows.map((row) => row.locator));
+    deleteDossier(personId, reasonInput) {
+        const reason = dossierReason(reasonInput);
+        const changedAt = new Date().toISOString();
+        this.#db.exec("BEGIN IMMEDIATE");
+        try {
+            const existing = this.#db
+                .prepare("SELECT dossier_json FROM person_dossiers WHERE person_id = ?")
+                .get(personId);
+            if (!existing) {
+                this.#db.exec("COMMIT");
+                return false;
+            }
+            parseDossierJson(existing.dossier_json);
+            this.#db.prepare("DELETE FROM person_dossiers WHERE person_id = ?").run(personId);
+            this.#db
+                .prepare(`
+          INSERT INTO person_dossier_changes
+            (id, person_id, action, before_dossier_json, after_dossier_json, reason, changed_at)
+          VALUES (?, ?, 'delete', ?, NULL, ?, ?)
+        `)
+                .run(randomUUID(), personId, existing.dossier_json, reason, changedAt);
+            this.#db.exec("COMMIT");
+            return true;
+        }
+        catch (error) {
+            this.#db.exec("ROLLBACK");
+            throw error;
+        }
     }
     getWhisperReceipt(threadKey, personId) {
         const row = this.#db
@@ -395,11 +432,64 @@ export class PeopleStore {
             .get(personId);
         return row
             ? {
-                dossier: Value.Parse(PERSON_DOSSIER_SCHEMA, JSON.parse(row.dossier_json)),
+                dossier: parseDossierJson(row.dossier_json),
                 reviewedAt: row.reviewed_at,
             }
             : undefined;
     }
+    getDossierReviewedAt(personId) {
+        const row = this.#db
+            .prepare("SELECT reviewed_at FROM person_dossiers WHERE person_id = ?")
+            .get(personId);
+        return row?.reviewed_at;
+    }
+    listDossierChanges(personId, limit = 20, offset = 0) {
+        return this.#db
+            .prepare(`
+        SELECT id, person_id, action, reason, changed_at,
+          CASE WHEN before_dossier_json IS NULL THEN NULL
+            ELSE length(CAST(before_dossier_json AS BLOB)) END AS before_dossier_bytes,
+          CASE WHEN after_dossier_json IS NULL THEN NULL
+            ELSE length(CAST(after_dossier_json AS BLOB)) END AS after_dossier_bytes
+        FROM person_dossier_changes
+        WHERE person_id = ?
+        ORDER BY changed_at DESC, rowid DESC
+        LIMIT ? OFFSET ?
+      `)
+            .all(personId, limit, offset)
+            .map((value) => {
+            const row = value;
+            return {
+                id: row.id,
+                personId: row.person_id,
+                action: row.action,
+                beforeDossierBytes: row.before_dossier_bytes,
+                afterDossierBytes: row.after_dossier_bytes,
+                reason: row.reason,
+                changedAt: row.changed_at,
+            };
+        });
+    }
+    getDossierChange(personId, changeId) {
+        const row = this.#db
+            .prepare("SELECT * FROM person_dossier_changes WHERE person_id = ? AND id = ?")
+            .get(personId, changeId);
+        return row
+            ? {
+                id: row.id,
+                personId: row.person_id,
+                action: row.action,
+                beforeDossier: row.before_dossier_json === null
+                    ? null
+                    : parseDossierJson(row.before_dossier_json),
+                afterDossier: row.after_dossier_json === null
+                    ? null
+                    : parseDossierJson(row.after_dossier_json),
+                reason: row.reason,
+                changedAt: row.changed_at,
+            }
+            : undefined;
+    }
     getDossierBlurb(personId) {
         const row = this.#db
             .prepare("SELECT blurb FROM person_dossiers WHERE person_id = ?")
@@ -591,36 +681,29 @@ export class PeopleStore {
             throw new Error("dossier sections must have unique categories");
         }
     }
-    #validateEvidenceLocators(locators) {
-        const unique = [...new Set(locators.map((locator) => locator.trim()))];
-        const invalid = unique.find((locator) => !/^session:.+:event:\d+$/.test(locator));
-        if (invalid !== undefined)
-            throw new Error(`invalid session evidence locator: ${invalid}`);
-        return unique;
-    }
     #migrate() {
         const current = this.#db.prepare("PRAGMA user_version").get();
-        if (current.user_version === 2)
+        if (current.user_version === 4)
             return;
-        if (current.user_version !== 0 && current.user_version !== 1) {
+        if (current.user_version !== 0 &&
+            current.user_version !== 1 &&
+            current.user_version !== 2 &&
+            current.user_version !== 3) {
             throw new Error(`unsupported PeopleSQL schema version: ${current.user_version}`);
         }
         this.#db.exec("BEGIN IMMEDIATE");
         try {
-            if (current.user_version === 1) {
+            if (current.user_version === 2) {
+                this.#db.exec(`
+          DROP TABLE person_evidence_receipts;
+        `);
+            }
+            else if (current.user_version === 1) {
                 this.#db.exec(`
           DROP INDEX people_policy_seen;
           ALTER TABLE people DROP COLUMN refinement_enabled;
           UPDATE people SET injection_enabled = 1 WHERE status = 'active';
 
-          CREATE TABLE person_evidence_receipts (
-            person_id TEXT NOT NULL REFERENCES people(id) ON DELETE CASCADE,
-            source TEXT NOT NULL,
-            locator TEXT NOT NULL,
-            processed_at TEXT NOT NULL,
-            PRIMARY KEY (person_id, source, locator)
-          ) STRICT;
-
           CREATE TABLE person_whisper_receipts (
             thread_key TEXT NOT NULL,
             person_id TEXT NOT NULL REFERENCES people(id) ON DELETE CASCADE,
@@ -629,13 +712,10 @@ export class PeopleStore {
             injected_at TEXT NOT NULL,
             PRIMARY KEY (thread_key, person_id)
           ) STRICT;
-
-          PRAGMA user_version = 2;
         `);
-                this.#db.exec("COMMIT");
-                return;
             }
-            this.#db.exec(`
+            else if (current.user_version === 0) {
+                this.#db.exec(`
         CREATE TABLE companies (
           id TEXT PRIMARY KEY,
           name TEXT NOT NULL,
@@ -695,14 +775,6 @@ export class PeopleStore {
           resolution_note TEXT
         ) STRICT;
 
-        CREATE TABLE person_evidence_receipts (
-          person_id TEXT NOT NULL REFERENCES people(id) ON DELETE CASCADE,
-          source TEXT NOT NULL,
-          locator TEXT NOT NULL,
-          processed_at TEXT NOT NULL,
-          PRIMARY KEY (person_id, source, locator)
-        ) STRICT;
-
         CREATE TABLE person_whisper_receipts (
           thread_key TEXT NOT NULL,
           person_id TEXT NOT NULL REFERENCES people(id) ON DELETE CASCADE,
@@ -714,7 +786,22 @@ export class PeopleStore {
 
         CREATE INDEX people_status_seen ON people(status, last_seen_at);
         CREATE INDEX people_todos_status_seen ON people_todos(status, last_seen_at);
-        PRAGMA user_version = 2;
+        `);
+            }
+            this.#db.exec(`
+        CREATE TABLE person_dossier_changes (
+          id TEXT PRIMARY KEY,
+          person_id TEXT NOT NULL REFERENCES people(id) ON DELETE CASCADE,
+          action TEXT NOT NULL CHECK (action IN ('replace', 'delete')),
+          before_dossier_json TEXT,
+          after_dossier_json TEXT,
+          reason TEXT NOT NULL,
+          changed_at TEXT NOT NULL
+        ) STRICT;
+
+        CREATE INDEX person_dossier_changes_person_changed
+          ON person_dossier_changes(person_id, changed_at DESC);
+        PRAGMA user_version = 4;
       `);
             this.#db.exec("COMMIT");
         }

package/dist/src/people-tools.js

@@ -1,9 +1,7 @@
 import { jsonResult } from "openclaw/plugin-sdk/agent-runtime";
-import { resolveAgentDir } from "openclaw/plugin-sdk/memory-core-host-engine-foundation";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { renderPeopleWhisper } from "./people-hooks.js";
-import { nextPeopleRefinement } from "./people-refinement.js";
 import { PERSON_DOSSIER_SCHEMA } from "./people-store.js";
 import { createOpenClawSlackDirectory, syncSlackDirectory, } from "./slack-directory.js";
 const nonEmpty = Type.String({ pattern: "\\S", maxLength: 1000 });
@@ -36,16 +34,36 @@ const inspectParameters = Type.Union([
         }),
     }, { additionalProperties: false }),
     Type.Object({
-        view: Type.Literal("todos"),
+        view: Type.Literal("people"),
         limit: Type.Optional(Type.Integer({
             minimum: 1,
             maximum: 100,
-            description: "Maximum actionable todos to return.",
+            description: "Maximum active people to return.",
+        })),
+        offset: Type.Optional(Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER, description: "People to skip." })),
+    }, { additionalProperties: false }),
+    Type.Object({
+        view: Type.Literal("dossier_changes"),
+        personId: nonEmpty,
+        limit: Type.Optional(Type.Integer({
+            minimum: 1,
+            maximum: 100,
+            description: "Maximum dossier change summaries to return, newest first.",
         })),
+        offset: Type.Optional(Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER, description: "Changes to skip." })),
+    }, { additionalProperties: false }),
+    Type.Object({
+        view: Type.Literal("dossier_change"),
+        personId: nonEmpty,
+        changeId: nonEmpty,
     }, { additionalProperties: false }),
     Type.Object({
-        view: Type.Literal("refinement_next"),
-        evidenceLimit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+        view: Type.Literal("todos"),
+        limit: Type.Optional(Type.Integer({
+            minimum: 1,
+            maximum: 100,
+            description: "Maximum actionable todos to return.",
+        })),
     }, { additionalProperties: false }),
 ]);
 const updateParameters = Type.Union([
@@ -57,16 +75,13 @@ const updateParameters = Type.Union([
     Type.Object({
         action: Type.Literal("replace_dossier"),
         personId: nonEmpty,
-        dossier: Type.Optional(PERSON_DOSSIER_SCHEMA),
-        consumedEvidenceLocators: Type.Optional(Type.Array(Type.String({ pattern: "^session:.+:event:\\d+$", maxLength: 1000 }), {
-            minItems: 1,
-            maxItems: 50,
-            uniqueItems: true,
-        })),
+        dossier: PERSON_DOSSIER_SCHEMA,
+        reason: nonEmpty,
     }, { additionalProperties: false }),
     Type.Object({
         action: Type.Literal("delete_dossier"),
         personId: nonEmpty,
+        reason: nonEmpty,
     }, { additionalProperties: false }),
     Type.Object({
         action: Type.Literal("set_company"),
@@ -94,7 +109,7 @@ const syncParameters = Type.Object({
 }, { additionalProperties: false });
 function context(ctx) {
     const cfg = ctx.getRuntimeConfig?.() ?? ctx.runtimeConfig ?? ctx.config;
-    return cfg && ctx.agentId ? { agentId: ctx.agentId, cfg } : undefined;
+    return cfg && ctx.agentId ? { agentId: ctx.agentId } : undefined;
 }
 function personView(stores, agentId, selector, maxChars) {
     const store = stores.get(agentId);
@@ -124,33 +139,49 @@ function createInspectTool(stores, config, ctx) {
     return {
         name: "memory_people_inspect",
         label: "Inspect People Memory",
-        description: "Inspect a person, list actionable people todos, or read the next person's unseen interaction evidence for dossier refinement.",
+        description: "List active people, inspect one person, read dossier change history, or list actionable people todos.",
         parameters: inspectParameters,
         async execute(_toolCallId, raw) {
             const input = Value.Parse(inspectParameters, raw);
             if (input.view === "person") {
                 return jsonResult(personView(stores, active.agentId, input, config.whisperer.maxChars));
             }
-            if (input.view === "refinement_next") {
-                try {
-                    const refinement = nextPeopleRefinement({
-                        store: stores.get(active.agentId),
-                        agentId: active.agentId,
-                        agentDatabasePath: `${resolveAgentDir(active.cfg, active.agentId)}/openclaw-agent.sqlite`,
-                        evidenceLimit: input.evidenceLimit,
-                    });
-                    return jsonResult(refinement ? { status: "ok", refinement } : { status: "empty" });
-                }
-                catch (error) {
-                    return jsonResult({
-                        status: "unavailable",
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                }
+            const store = stores.get(active.agentId);
+            if (input.view === "people") {
+                const limit = input.limit ?? 50;
+                const offset = input.offset ?? 0;
+                const people = store.listActivePeople(limit, offset).map((person) => {
+                    const dossierReviewedAt = store.getDossierReviewedAt(person.id);
+                    return {
+                        person,
+                        identities: store.listIdentities(person.id),
+                        hasDossier: dossierReviewedAt !== undefined,
+                        dossierReviewedAt: dossierReviewedAt ?? null,
+                    };
+                });
+                return jsonResult({
+                    status: "ok",
+                    people,
+                    nextOffset: people.length === limit ? offset + people.length : null,
+                });
+            }
+            if (input.view === "dossier_changes") {
+                const limit = input.limit ?? 20;
+                const offset = input.offset ?? 0;
+                const changes = store.listDossierChanges(input.personId, limit, offset);
+                return jsonResult({
+                    status: "ok",
+                    changes,
+                    nextOffset: changes.length === limit ? offset + changes.length : null,
+                });
+            }
+            if (input.view === "dossier_change") {
+                const change = store.getDossierChange(input.personId, input.changeId);
+                return jsonResult(change ? { status: "ok", change } : { status: "not_found" });
             }
             return jsonResult({
                 status: "ok",
-                todos: stores.get(active.agentId).listTodos(input.limit ?? 20),
+                todos: store.listTodos(input.limit ?? 20),
             });
         },
     };
@@ -172,14 +203,8 @@ function createUpdateTool(stores, ctx) {
                 return jsonResult(person ? { status: "ok", person } : { status: "not_found" });
             }
             if (input.action === "replace_dossier") {
-                if (input.dossier === undefined && input.consumedEvidenceLocators === undefined) {
-                    return jsonResult({
-                        status: "invalid",
-                        error: "replace_dossier requires a dossier or consumed evidence locators",
-                    });
-                }
                 try {
-                    const dossier = store.replaceDossier(input.personId, input.dossier, input.consumedEvidenceLocators);
+                    const dossier = store.replaceDossier(input.personId, input.reason, input.dossier);
                     return jsonResult({ status: "ok", dossier });
                 }
                 catch (error) {
@@ -190,7 +215,9 @@ function createUpdateTool(stores, ctx) {
                 }
             }
             if (input.action === "delete_dossier") {
-                return jsonResult(store.deleteDossier(input.personId) ? { status: "ok" } : { status: "not_found" });
+                return jsonResult(store.deleteDossier(input.personId, input.reason)
+                    ? { status: "ok" }
+                    : { status: "not_found" });
             }
             if (input.action === "set_company") {
                 const company = store.setCompany(input.personId, {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },
@@ -138,14 +138,6 @@
         "additionalProperties": false,
         "properties": {
           "enabled": { "type": "boolean", "default": false },
-          "refinement": {
-            "type": "object",
-            "description": "Deprecated compatibility field; accepted but ignored.",
-            "additionalProperties": false,
-            "properties": {
-              "maxPeoplePerRun": { "type": "integer", "minimum": 1, "maximum": 50 }
-            }
-          },
           "whisperer": {
             "type": "object",
             "additionalProperties": false,

package/package.json

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

package/skills/people-whisperer/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: people-whisperer
+description: Maintain useful PeopleSQL dossiers from ordinary memory and session evidence so future conversations start with accurate person context.
+---
+
+# People Whisperer
+
+Improve the agent's durable understanding of people it interacts with. Prefer no
+write over routine, repetitive, weakly inferred, or already captured information.
+The goal is a useful future conversation, not processing every interaction.
+
+## Choose and inspect
+
+- For a named or current person, call `memory_people_inspect` with
+  `view: "person"` and their `personId` or exact Slack identity.
+- For autonomous maintenance, call `memory_people_inspect` with
+  `view: "people"` and an optional `limit`. Use the returned identity,
+  `lastSeenAt`, dossier presence, and dossier `reviewedAt` only as context for
+  your judgment. `reviewedAt` is the last dossier write, not a due date.
+- Do not assume every listed person needs work. You may update several people or
+  nobody.
+
+## Investigate
+
+1. Read the current dossier when one exists.
+2. Search for meaningful information with `memory_search`. Use targeted queries,
+   relevant corpora, and session metadata filters rather than treating a fixed
+   recent-message window as the person's history.
+3. Follow useful `qmd://` results with `memory_get`. If recent OpenClaw sessions
+   are not indexed, use `memory_sync_sessions` and check `memory_sync_status`
+   before searching again.
+4. Prefer direct statements, repeated behavior, decisions, feedback, and
+   outcomes. Distinguish observation, reported information, inference, and agent
+   assessment. Do not promote small talk or one ambiguous exchange into a durable
+   claim.
+5. Preserve still-useful existing claims. Dossier replacement is complete, not
+   a patch.
+
+Ordinary `memory_search` supports multiple targeted calls and up to 20 results
+per call. People Whisperer does not impose its own result window or require the
+agent to acknowledge what it inspected.
+
+## Write only when useful
+
+Call `memory_people_update` with `action: "replace_dossier"`, the `personId`, a
+concise `reason` for the change, and a complete dossier. The plugin records the
+reason and exact before/after snapshots transactionally. Keep the complete dossier
+under the plugin's 64 KiB serialized limit:
+
+```json
+{
+  "action": "replace_dossier",
+  "personId": "PeopleSQL person ID",
+  "reason": "Added a durable preference supported by recent sessions.",
+  "dossier": {
+    "schemaVersion": 1,
+    "blurb": "Concise context worth having before the next conversation.",
+    "sections": [
+      {
+        "category": "preferences",
+        "claims": [
+          {
+            "statement": "A durable, specific claim.",
+            "evidence": [
+              {
+                "source": "session",
+                "locator": "qmd://path-returned-by-memory-search",
+                "observedAt": "2026-08-31T12:00:00Z"
+              }
+            ],
+            "epistemicType": "observed",
+            "confidence": "high"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Allowed section categories are `role`, `priorities`, `preferences`,
+`successCriteria`, `workingStyle`, `relationship`, and `openLoops`. Evidence
+sources are `session`, `memory`, `directory`, or `manual`; `observedAt` and
+`confidence` are optional. Epistemic types are `observed`, `reported`,
+`inferred`, or `agent_assessment`.
+
+Make the blurb immediately useful, concise, and honest about uncertainty. Do not
+stuff it with biography or raw evidence. Claim evidence references are
+provenance, not work receipts.
+
+Use `delete_dossier` when the current dossier is too unreliable to inject and
+cannot be responsibly repaired; deletion also requires a concise `reason`. Use
+`memory_people_inspect` with `view: "dossier_changes"`, the `personId`, and
+optional `limit`/`offset` to list small newest-first history summaries. Follow a
+summary with `view: "dossier_change"`, the `personId`, and its `changeId` only
+when you need the exact before/after dossier and blurb. Follow `nextOffset` to page.
+Use `set_injection` to disable or re-enable
+whispers for one person without deleting their dossier. Company, todo, and
+person-status actions are available for the corresponding data changes.
+
+## Finish
+
+Report whom you investigated, which memory or sessions informed any write, what
+changed, and why skipped people did not need an update. Do not manufacture a
+write to show activity.

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

@@ -1,21 +0,0 @@
-export type PersonSessionEvidence = {
-    source: "session";
-    locator: string;
-    observedAt: string;
-    text: string;
-    context: Array<{
-        locator: string;
-        role: string;
-        text: string;
-        senderId?: string;
-    }>;
-};
-export declare function readPersonSessionEvidence(params: {
-    databasePath: string;
-    agentId: string;
-    accountScope: string;
-    externalId: string;
-    limit?: number;
-    maxMessageChars?: number;
-    excludeLocators?: ReadonlySet<string>;
-}): PersonSessionEvidence[];

package/dist/src/people-evidence.js

@@ -1,126 +0,0 @@
-import { DatabaseSync } from "node:sqlite";
-function record(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : undefined;
-}
-function messageText(value) {
-    if (typeof value === "string")
-        return value.trim() || undefined;
-    if (!Array.isArray(value))
-        return undefined;
-    const text = value
-        .flatMap((part) => {
-        const block = record(part);
-        return block?.type === "text" && typeof block.text === "string" ? [block.text] : [];
-    })
-        .join("\n")
-        .trim();
-    return text || undefined;
-}
-function evidenceTimestamp(event, fallback) {
-    const raw = event.timestamp;
-    const milliseconds = typeof raw === "number" && Number.isFinite(raw)
-        ? raw
-        : typeof raw === "string"
-            ? Date.parse(raw)
-            : fallback;
-    return new Date(Number.isFinite(milliseconds) ? milliseconds : fallback).toISOString();
-}
-export function readPersonSessionEvidence(params) {
-    const limit = Math.max(1, Math.min(50, Math.floor(params.limit ?? 20)));
-    const maxMessageChars = Math.max(1, Math.min(4000, Math.floor(params.maxMessageChars ?? 2000)));
-    const db = new DatabaseSync(params.databasePath, { readOnly: true });
-    try {
-        db.exec("PRAGMA query_only = ON; PRAGMA busy_timeout = 5000; BEGIN");
-        const version = db.prepare("PRAGMA user_version").get();
-        const meta = db
-            .prepare("SELECT schema_version, agent_id FROM schema_meta WHERE meta_key = 'primary'")
-            .get();
-        if (version?.user_version !== 17 ||
-            meta?.schema_version !== 17 ||
-            meta.agent_id !== params.agentId) {
-            throw new Error("unsupported or mismatched OpenClaw agent database");
-        }
-        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
-      JOIN session_windows AS sessions ON sessions.session_id = active.session_id
-      LEFT JOIN conversations ON conversations.conversation_id = sessions.primary_conversation_id
-      WHERE active.message_position IS NOT NULL
-        AND COALESCE(sessions.channel, conversations.channel) = 'slack'
-        AND COALESCE(sessions.account_id, conversations.account_id) = ?
-        AND json_extract(events.event_json, '$.type') = 'message'
-        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
-    `);
-        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)
-                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;
-    }
-    catch (error) {
-        try {
-            db.exec("ROLLBACK");
-        }
-        catch {
-            // The read transaction may not have started if opening the schema failed.
-        }
-        throw error;
-    }
-    finally {
-        db.close();
-    }
-}

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

@@ -1,14 +0,0 @@
-import { type PersonSessionEvidence } from "./people-evidence.js";
-import type { PeopleStore, Person, PersonDossier, PersonIdentity } from "./people-store.js";
-export type PeopleRefinementPacket = {
-    person: Person;
-    identities: PersonIdentity[];
-    currentDossier?: PersonDossier;
-    evidence: PersonSessionEvidence[];
-};
-export declare function nextPeopleRefinement(params: {
-    store: PeopleStore;
-    agentId: string;
-    agentDatabasePath: string;
-    evidenceLimit?: number;
-}): PeopleRefinementPacket | undefined;

package/dist/src/people-refinement.js

@@ -1,30 +0,0 @@
-import { readPersonSessionEvidence } from "./people-evidence.js";
-export function nextPeopleRefinement(params) {
-    const evidenceLimit = Math.max(1, Math.min(50, Math.floor(params.evidenceLimit ?? 20)));
-    for (const person of params.store.listActivePeople()) {
-        const identities = params.store.listIdentities(person.id);
-        const processed = params.store.listProcessedEvidenceLocators(person.id, "session");
-        const evidence = identities
-            .filter((identity) => identity.provider === "slack")
-            .flatMap((identity) => readPersonSessionEvidence({
-            databasePath: params.agentDatabasePath,
-            agentId: params.agentId,
-            accountScope: identity.accountScope,
-            externalId: identity.externalId,
-            limit: evidenceLimit,
-            excludeLocators: processed,
-        }))
-            .filter((entry, index, all) => all.findIndex((candidate) => candidate.locator === entry.locator) === index)
-            .sort((left, right) => right.observedAt.localeCompare(left.observedAt))
-            .slice(0, evidenceLimit);
-        if (evidence.length === 0)
-            continue;
-        return {
-            person,
-            identities,
-            currentDossier: params.store.getDossier(person.id)?.dossier,
-            evidence,
-        };
-    }
-    return undefined;
-}