@unblocklabs/unblock-memory 0.3.21 → 0.3.23

package/docs/configuration.md

@@ -0,0 +1,380 @@
+# Configuration
+
+[Overview](../README.md) · [Retrieval](retrieval.md) · [People](peoplesql.md) · [Response audit](response-audit.md)
+
+All plugin settings below belong under
+`plugins.entries.unblock-memory.config`, not at the top level of OpenClaw.
+Unknown keys are rejected. Restart/reload the Gateway after changing plugin
+settings; a rotated credential file is reread without a restart.
+
+## Feature gates and fallbacks
+
+| Feature | Required settings/dependencies | TypeSafe disabled / no key | Provider or unreadable-key failure |
+| --- | --- | --- | --- |
+| Ordinary search/get | Installed/enabled memory slot; configured corpora | Unchanged local retrieval | Unchanged; its own indexing/embedding errors still matter |
+| Skill Whisperer | `skillWhisperer.enabled`, skills corpus, host hooks | Best local vector candidate meeting `minScore` | No hint; does not fall back |
+| Memory Whisperer | `memoryWhisperer.enabled`, explicit approved corpora, host hooks | No hints | No hints |
+| Complementary hints | Enabled Memory Whisperer + `complementaryHints` | No additional judgment; base hints also require a key | Keep baseline hints unless the total deadline expires |
+| People store/tools | `people.enabled` | Available; automatic save review needs primer/key or verified manual alternative | Storage/inspection still available |
+| People Whisperer | People + `people.whisperer.enabled`, host hooks, eligible person/dossier, no prior thread receipt | Unchanged local lookup | Unchanged local lookup |
+| People Primer / automatic dossier save review | People + `peoplePrimer.enabled`, approved corpora | No judgment; save requires source-specific manual verification | No automatic save; verify/retry instead |
+| Quality audit / cluster review | `qualityAudit.enabled`, approved corpora; cluster review also needs fresh analysis | No judgment | Unavailable/partial; preserve evidence and retry as documented |
+| Ordinary claim review | `evidenceReview.enabled`, approved corpora | No judgment | Unavailable; no claim verified |
+| Response quality/sentiment | `responseAudit.enabled`, approved humans/chat types | No inference | Unavailable; successful assessment stages stay cached |
+| Clustering | Configured local `analysis.executable` | Unchanged | Unchanged; worker failures do not disable ordinary search |
+
+Whisperers, people storage, the primer and audits default off. `typesafe.enabled` defaults true but does not
+enable any feature; `sentimentEnabled` defaults true only **within an enabled
+response audit**. `peoplePrimer` controls automatic dossier-save review;
+`evidenceReview` is a different advisory tool. Disabling people injection does
+not disable people tools/storage or erase dossiers.
+
+## Shared TypeSafe credentials
+
+All plugin TypeSafe features use `plugins.entries.unblock-memory.config.typesafe`:
+
+```json
+{
+  "typesafe": {
+    "enabled": true,
+    "apiKeyFile": "/absolute/path/to/secrets/unblock-memory-typesafe.env",
+    "timeoutMs": 1500
+  }
+}
+```
+
+This is a **plugin config fragment**, not a top-level OpenClaw configuration.
+The key file can contain a plaintext key or dotenv entries:
+
+```dotenv
+TYPESAFE_API_KEY="YOUR_TYPESAFE_KEY"
+```
+
+Credentials come from inline `typesafe.apiKey`, an absolute `typesafe.apiKeyFile`,
+or (when neither is configured) the Gateway process's `TYPESAFE_API_KEY` environment
+variable. Configure at most one of `apiKey` and `apiKeyFile`; prefer a private file
+over a secret in config. Defaults are `enabled: true` and `timeoutMs: 1500`.
+
+The file is reread when a feature resolves credentials, so replacing its contents
+does not require a Gateway restart. Restart/reload the Gateway after changing the
+configured path or other plugin settings. A dotenv file is not executed as shell
+code and does not change the process environment. Workspace `.env` files are not
+auto-discovered, and an interactive shell's exported key need not reach a managed
+Gateway service.
+
+Missing/empty files or dotenv files without `TYPESAFE_API_KEY` count as no key.
+An explicit file never falls back to an unrelated environment key. Missing or
+unreadable credentials do not break normal memory functionality or Gateway startup;
+the feature-specific fallback/skip behavior above applies. **Unreadable files and
+provider errors are not Skill Whisperer's no-key fallback:** they suppress its hint.
+Use `memory_diagnostics` for credential availability; it does not verify provider
+acceptance. Keep secret files mode `600`, secret directories mode `700`, and keys
+out of Git, chat, shell arguments and logs.
+
+The plugin reads only `TYPESAFE_API_KEY` from the environment. Standalone QMD also
+supports `TYPESAFE_API_KEY_FILE`; these are separate credential resolvers.
+`typesafe.timeoutMs` is not a universal total deadline: People Primer and dossier
+save review use `peoplePrimer.timeoutMs` per request; Memory Whisperer has its
+own overall budget.
+
+## Example profiles
+
+These are **alternative plugin config fragments**, not additive whole-host files.
+Merge only the intended settings. If supplying `corpora`, preserve every desired
+existing entry: the array replaces the default, and exactly one `memory` is required.
+Use the README's host wrapper and [host controls](#host-controls) separately.
+
+### Sessions, including DMs explicitly
+
+```json
+{
+  "corpora": [
+    { "name": "memory", "kind": "files", "paths": ["MEMORY.md", "USER.md", "memory/**/*.md"] },
+    { "name": "sessions", "kind": "sessions", "chatTypes": ["channel", "group", "direct"], "syncIntervalMinutes": 60 }
+  ]
+}
+```
+
+Omit `direct` when DMs should not be indexed. Start `memory_sync_sessions({})`
+and inspect `memory_sync_status({})` for an immediate refresh; the scheduled first
+refresh waits an interval.
+
+### Skill Whisperer, local only
+
+```json
+{
+  "corpora": [
+    { "name": "memory", "kind": "files", "paths": ["MEMORY.md", "USER.md", "memory/**/*.md"] },
+    { "name": "skills", "kind": "skills", "paths": ["skills/**/SKILL.md", ".agents/skills/**/SKILL.md", "~/.agents/skills/**/SKILL.md", "~/.openclaw/skills/**/SKILL.md", "~/.openclaw/plugin-skills/**/SKILL.md"] }
+  ],
+  "typesafe": { "enabled": false },
+  "skillWhisperer": { "enabled": true }
+}
+```
+
+Select only desired skill locations. To use TypeSafe selection instead, enable
+`typesafe` and configure credentials; the selected skill still is not auto-invoked.
+
+### Memory Whisperer over approved knowledge
+
+```json
+{
+  "corpora": [
+    { "name": "memory", "kind": "files", "paths": ["MEMORY.md", "USER.md", "memory/**/*.md"] },
+    { "name": "knowledge", "kind": "files", "paths": ["knowledge/**/*.md"] }
+  ],
+  "typesafe": { "apiKeyFile": "/absolute/path/to/secrets/unblock-memory-typesafe.env" },
+  "memoryWhisperer": { "enabled": true, "corpora": ["knowledge"] }
+}
+```
+
+Create the private key file first. Approve only knowledge suitable for every
+audience of this agent. For exact-current-session hints, configure a sessions
+corpus and add `sessions` to `memoryWhisperer.corpora`; missing session identity
+excludes that corpus. This does not make ordinary search current-session-only.
+
+### People storage, without injection
+
+```json
+{ "people": { "enabled": true, "whisperer": { "enabled": false } } }
+```
+
+### People injection and optional evidence primer
+
+```json
+{
+  "people": { "enabled": true, "whisperer": { "enabled": true } },
+  "peoplePrimer": { "enabled": true, "corpora": ["memory"] },
+  "typesafe": { "apiKeyFile": "/absolute/path/to/secrets/unblock-memory-typesafe.env" }
+}
+```
+
+The default memory corpus exists. This separately approves its evidence for
+TypeSafe; it does not create a dossier or schedule maintenance. Use the
+[people workflow](peoplesql.md). Adding `sessions` to primer approval, after
+configuring that corpus, approves **all indexed sessions**, unlike Memory Whisperer.
+
+### Optional analysis worker
+
+```json
+{ "analysis": { "executable": "/absolute/path/to/unblock-cluster/bin/unblock-memory-analysis" } }
+```
+
+Set this only after [installing the worker](retrieval.md#memory-analysis). No
+clustering or curation schedule is created. Response-audit setup and a dry-run-first
+workflow are in [its own guide](response-audit.md).
+
+## Settings reference
+
+The tables show resolved defaults. For source-specific entries,
+`corpora[sessions]` means the array entry with `name: "sessions"`, not a literal
+configuration key. The manifest schema and config resolvers are the machine
+contract; these tables explain their effects.
+
+## Sources and base runtime
+
+| Setting | Default | Meaning / supported range |
+| --- | --- | --- |
+| `corpora` | One files corpus `memory`: `MEMORY.md`, `USER.md`, `memory/**/*.md` | Explicit array replaces defaults; must contain exactly one `memory`; `all` is a search selector, not a corpus name |
+| `corpora[].name` | Required for explicit entries | Unique name; `sessions` and `skills` reserved for corresponding kinds |
+| `corpora[].kind` | Required for explicit entries | `files`, `sessions`, or `skills` |
+| `corpora[].paths` | Required for files/skills | Nonempty exact-file/directory/glob list; workspace-relative, absolute or `~/`; directory means recursive Markdown; does not grant host write trust |
+| `corpora[sessions].chatTypes` | `['channel','group']` | Nonempty subset of channel/group/direct; DMs require `direct` |
+| `corpora[sessions].maxExpandedTokens` | `500` | 1–10,000; use full turn/message when it fits, otherwise preserve full matched chunk; not a total result-size hard cap |
+| `corpora[sessions].syncIntervalMinutes` | `60` | 0–1,440; zero manual-only; first scheduled sync after one interval; requires running Gateway |
+| `keepEmbeddingModelWarm` | `true` | Retain embedding model/context after first use; false allows five-minute idle disposal |
+| `analysis.executable` | Unset | Optional absolute local worker path; enables ability to recluster, not automatic scheduling |
+
+## TypeSafe and whisperers
+
+| Setting | Default | Meaning / supported range |
+| --- | --- | --- |
+| `typesafe.enabled` | `true` | Shared plugin provider gate; no feature is opted in merely by adding a key |
+| `typesafe.apiKey` | Unset | Explicit inline key; mutually exclusive with key file; prefer file |
+| `typesafe.apiKeyFile` | Unset | Absolute raw-key or dotenv file, reread at credential resolution; explicit missing file never falls back to a different key |
+| `typesafe.timeoutMs` | `1500` | 1–10,000 per request for Skill/Memory Whisperer, quality/claim/cluster review and response audit; **primer and dossier save use `peoplePrimer.timeoutMs` instead** |
+| `skillWhisperer.enabled` | `false` | Requires explicit skills corpus and appropriate host hook access |
+| `skillWhisperer.historyMessages` | `5` | Nonnegative integer; prior visible messages used for routing |
+| `skillWhisperer.minScore` | `0.5` | 0–1, **local vector fallback only**, ignored for TypeSafe shortlist admission |
+| `skillWhisperer.cooldownTurns` | `10` | Nonnegative user-turn count; no fallback to weaker cooling-down alternatives |
+| `memoryWhisperer.enabled` | `false` | Requires explicit approved non-skill corpora, TypeSafe key and host hooks |
+| `memoryWhisperer.corpora` | `[]` | Explicit known corpus names; required nonempty when enabled; no `all` or skills |
+| `memoryWhisperer.historyMessages` | `5` | 0–50, retrieval history count, not judge-history limit |
+| `memoryWhisperer.minUsefulness` | `0.9` | 0–1, minimum Noul yes-probability per candidate |
+| `memoryWhisperer.maxHints` | `2` | 1–2 |
+| `memoryWhisperer.cooldownTurns` | `10` | 0–1,000; recently injected evidence |
+| `memoryWhisperer.timeoutMs` | `3000` | 1–10,000 total whisper deadline, not just the provider timeout |
+| `memoryWhisperer.complementaryHints` | `false` | Optional extra redundancy judgment; does not expand retrieval or enable the feature |
+
+No configured plugin credential means fallback to **`TYPESAFE_API_KEY` only** in
+the Gateway environment. Unlike QMD's resolver, the plugin does not read a
+`TYPESAFE_API_KEY_FILE` environment variable. Do not conflate these contracts.
+Missing/empty key and unreadable/erroring key are different for Skill Whisperer:
+the former allows vector fallback; the latter suppresses the hint.
+
+## People
+
+| Setting | Default | Meaning / supported range |
+| --- | --- | --- |
+| `people.enabled` | `false` | Store, Slack identity observation, people tools; independent of injection |
+| `people.whisperer.enabled` | `false` | Exact-identity prompt injection; requires people enabled |
+| `people.whisperer.maxChars` | `1200` | 1–4,000; also the **stored new-dossier blurb character limit even when injection is off**; independent 70-word ceiling remains |
+| `people.todos.maxOpen` | `1000` | 1–10,000; bounded open data-quality todos with overflow accounting |
+| `peoplePrimer.enabled` | `false` | Requires people enabled + explicit approved corpora; controls evidence primer and automatic save review |
+| `peoplePrimer.corpora` | `[]` | Explicit configured non-skill evidence approvals; sessions means all indexed sessions |
+| `peoplePrimer.hitsPerQuestion` | `30` | 1–40 vector results for each of three questions, before provider grading |
+| `peoplePrimer.minScore` | `0.35` | 0–1 vector admission threshold |
+| `peoplePrimer.minUsefulness` | `0.8` | 0.5–1; all background eligibility dimensions must pass |
+| `peoplePrimer.maxEvidencePerQuestion` | `3` | 1–10 selected evidence references per question, **not** a cap on grading work |
+| `peoplePrimer.timeoutMs` | `30000` | 1–60,000 per provider request, also used for draft/save review; tool's overall limit is 120 seconds |
+
+## Audits and advisory reviews
+
+| Setting | Default | Meaning / supported range |
+| --- | --- | --- |
+| `qualityAudit.enabled` | `false` | On-demand chunk-quality and sampled-cluster review |
+| `qualityAudit.corpora` | `[]` | Explicit non-skill approval; nonempty when enabled; sessions means all indexed sessions |
+| `qualityAudit.minNoise` | `0.8` | 0–1 threshold for model noise flags; deterministic empty/encoding indicators have separate rules |
+| `evidenceReview.enabled` | `false` | Ordinary atomic-claim review tool; does not turn on dossier save review |
+| `evidenceReview.corpora` | `[]` | Explicit non-skill approval; nonempty when enabled |
+| `responseAudit.enabled` | `false` | Operator-only response evaluation; requires approved senders and TypeSafe |
+| `responseAudit.sentimentEnabled` | `true` | Within opted-in audit; false removes emotion questions without disabling quality judgments |
+| `responseAudit.senderIds` | `[]` | Up to 50 approved Slack sender IDs; nonempty when enabled; trusted human/owner metadata also required, explicit bots excluded |
+| `responseAudit.chatTypes` | `['direct']` | Nonempty approved subset of direct/group/channel |
+| `responseAudit.historyMessages` | `6` | 0–20 preceding visible messages |
+| `responseAudit.lookbackDays` | `30` | 1–90 days |
+| `responseAudit.maxEpisodes` | `20` | 1–100 per run; a run need not clear the backlog |
+| `responseAudit.intervalMinutes` | `60` | 0–1,440; zero manual-only; persisted per-agent due time, bounded catch-up |
+| `responseAudit.memoryCorpora` | `[]` | Optional file-only corpus approvals for current-index memory-gap investigation; separate from response transcript approval |
+
+
+## Host controls
+
+These are **outside** `plugins.entries.unblock-memory.config`:
+
+- `plugins.slots.memory: "unblock-memory"` selects the memory owner. Installation,
+  plugin enablement and any host allowlists remain separate.
+- `plugins.entries.unblock-memory.hooks.allowConversationAccess` allows the
+  non-bundled plugin's conversation hooks. `allowPromptInjection` controls prompt
+  mutation. For whisperers, configure the plugin entry with this fragment:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "unblock-memory": {
+        "hooks": { "allowConversationAccess": true, "allowPromptInjection": true }
+      }
+    }
+  }
+}
+```
+
+Host hook timeouts may bound work independently of the plugin's internal deadline.
+The flags do not enable any whisperer by themselves.
+
+Optional `memory_people_sync` may need `tools.allow`; agent skill allowlists must
+include `people-whisperer` and/or `memory-curator` when used. Indexing a skill for
+routing neither authorizes nor installs it.
+
+### Compaction memory writes
+
+The plugin supplies OpenClaw a pre-compaction memory-flush plan unless
+`agents.defaults.compaction.memoryFlush.enabled` is false. This is a
+**host-triggered agent write**, not an independent plugin timer. It is separate
+from session sync, all whisperers and dossier maintenance.
+
+Its prompt writes durable information only to `memory/YYYY-MM-DD.md`, appending
+if the file exists, never overwriting it or bootstrap files. When nothing merits
+storage, `NO_REPLY` is appropriate. The date uses
+`agents.defaults.userTimezone`, otherwise the system timezone.
+
+Supported host settings: `enabled`, `softThresholdTokens` (default 4,000),
+`forceFlushTranscriptBytes` (default 2 MiB), and optional `model`. The plugin
+plan has a fixed 20,000-token reserve floor and supplies its own prompts; custom
+host `memoryFlush.prompt` / `systemPrompt` are not used by this resolver.
+
+Disable this plan with this **host config fragment**:
+
+```json
+{ "agents": { "defaults": { "compaction": { "memoryFlush": { "enabled": false } } } } }
+```
+
+Or customize its supported thresholds and date timezone:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "userTimezone": "America/New_York",
+      "compaction": {
+        "memoryFlush": { "enabled": true, "softThresholdTokens": 6000, "forceFlushTranscriptBytes": "3mb" }
+      }
+    }
+  }
+}
+```
+
+### Agent and audience scope
+
+Per-person injection state, dossier existence, availability and thread receipts
+are stored state, not config switches. See [people lifecycle](peoplesql.md#injection-and-person-state).
+
+Normal memory tools can access the agent's configured non-skill corpora. Corpus
+selectors are not audience ACLs. Per-feature TypeSafe approvals constrain that
+feature's remote processing, not general retrieval access. This is an agent/fleet
+boundary, not multi-tenant authorization. Approve sources for the agent's audiences.
+
+## TypeSafe data scope
+
+| Feature | Evidence sent when explicitly enabled/approved |
+| --- | --- |
+| Skill selection | Bounded visible current/recent conversation + shortlisted skill names/descriptions; not skill procedures or source-path fields |
+| Memory hints | Bounded visible conversation + up to 8 complete excerpts, corpus names and relevant session dates; exact current session only for session hits |
+| Complementarity | Up to 4 already-qualified excerpts for pairwise redundancy checks |
+| People primer | Person identity, agent name, approved retrieved excerpts and source/session metadata; all indexed sessions eligible if approved, not just the current chat |
+| Dossier save/draft review | Proposed blurb, person/agent names and 1–3 exact approved indexed evidence ranges, at most 6,000 characters total; existing dossier is not evidence |
+| Chunk quality | Up to 4 complete chunks of at most 6,000 characters each per request + source kinds; no conversation or source-path fields |
+| Ordinary claim review | One proposed claim + up to 3 approved indexed ranges, at most 6,000 characters total |
+| Cluster review | Up to 6 eligible complete sampled chunks, each at most 2,000 characters; conclusions only concern the sample |
+| Response audit | Approved visible request/answer/context/feedback and bounded later response evidence, separated by assessment stage; optional current-index whole-short-document evidence from approved file corpora |
+| Standalone QMD query | Query, optional intent, selected excerpts, source paths and evaluation time; separate process/SDK credentials and collection scope |
+
+Omitting tool-result/thinking/system fields does not remove their content if it
+was quoted in ordinary visible text. Provider judgments are advisory; probability
+or score is not proof. Enabling a feature approves only that feature's documented processing.
+
+
+## Storage, upgrades and recovery
+
+Each agent's state lives under the configured OpenClaw state directory, normally
+`~/.openclaw/agents/<agentId>/unblock-memory/`. `index.sqlite` is rebuildable;
+`unblock-memory.sqlite` holds durable people, curation and response-audit state.
+Disabling a feature does not delete its data.
+
+### Durable database migration
+
+Each agent has two active plugin databases: rebuildable `index.sqlite` and durable
+`unblock-memory.sqlite`. The latter uses WAL, private permissions and component
+schema versions. Store modules and tool access remain separate: consolidating files
+does not expose operator response audits to memory searches or whisperers.
+
+When upgrading from separate `curation.sqlite`, `people.sqlite` and
+`response-audit.sqlite` files, **stop the Gateway and any plugin CLI writers first**.
+On first durable-store access, the plugin imports all existing files, even for
+disabled features, in one transaction. It includes committed WAL data, verifies
+row counts/values and foreign keys, and records completion. Missing stores are
+normal; unsupported or invalid data aborts the import without a partial cutover.
+Restarting retries an incomplete import. QMD and transcript databases are untouched.
+
+The old files remain untouched as **inert recovery copies**, not active stores.
+Completed migration never reimports them or writes to them. Do not run old and new
+plugin versions together: old writers can continue changing their separate files.
+Back up the new database with SQLite's online backup API (or with all writers
+stopped and WAL safely checkpointed); copying only a live `.sqlite` file is unsafe.
+
+To roll back before any new writes, stop all writers, preserve the new database and
+its WAL/SHM sidecars, and restore the old plugin against the retained legacy files.
+**After new writes, those files are stale**: an old-version rollback requires an
+explicit reverse data migration or accepting the loss of post-upgrade changes.
+Keep recovery files until the upgrade has been verified; cleanup is a separate step.

package/docs/peoplesql.md

@@ -0,0 +1,223 @@
+# People dossiers and whispering
+
+[Overview](../README.md) · [Configuration and credentials](configuration.md)
+
+PeopleSQL stores identity, dossier and change history. The agent authors a brief
+recognition snippet; People Whisperer injects only its saved blurb. Enable the
+store with `people.enabled`; enable injection separately with
+`people.whisperer.enabled`. The optional `peoplePrimer` approves evidence preparation
+and automatic save review, not a maintenance scheduler. For independent setup
+examples, see the [configuration profiles](configuration.md#example-profiles).
+
+## Optional People Dossier Primer
+
+`memory_people_prime({ personId, agentName? })` prepares evidence for an existing person;
+it does **not** generate claims, update dossiers, or inject context. With
+`people.enabled: true`, opt in separately:
+
+```json
+{
+  "peoplePrimer": {
+    "enabled": true,
+    "corpora": ["memory", "knowledge", "sessions"],
+    "hitsPerQuestion": 30,
+    "minScore": 0.35,
+    "minUsefulness": 0.8,
+    "maxEvidencePerQuestion": 3,
+    "timeoutMs": 30000
+  }
+}
+```
+
+This is a plugin config fragment. List only configured, approved non-skill corpora. The feature is **off by
+default** and requires shared TypeSafe credentials. Disabled TypeSafe or missing/
+unreadable credentials safely skip the primer; agents can still research normally.
+Enabling it approves sending the person's identity, retrieved excerpts and optional
+draft snippet to TypeSafe. Existing dossiers are not sent as grading evidence.
+Sessions includes all indexed conversations;
+results are available to the agent's tool callers, so scope approval accordingly.
+Primer and dossier-save requests use `peoplePrimer.timeoutMs`, not
+`typesafe.timeoutMs`; the total tool deadline is two minutes.
+
+Three default questions cover explicit role/organization, enduring organizational
+background, and the person's relationship to the agent (not its business mission).
+Preferences, working styles, priorities, feedback and task history are excluded.
+Each uses QMD vector search (no query expansion) for up to 30 hits, configurable
+up to 40. All unique eligible hits above the vector threshold are graded, not just
+the final top three. Complete excerpts over 6,000 characters are counted and skipped,
+not silently truncated. Duplicate source spans across questions share a request;
+Independent attribution, explicit-background, durability, recognition-value and
+question-usefulness judgments run together; every dimension must pass the threshold.
+Every candidate is graded against all three questions, regardless of which search
+found it. Mixed excerpts may supply a useful background fact without making their
+surrounding behavioral content eligible for the snippet.
+Provider concurrency is four, with a two-minute overall tool deadline.
+
+Supply the agent's human-facing name when no identity name is configured; otherwise
+questions use "the assistant", never an internal routing ID such as `main`.
+The output includes a deduplicated source-linked excerpt list referenced by each
+question's evidence IDs, a bounded uncertain-review shortlist,
+and retrieval/cache/failure counts. Coverage is `evidence_found`, `uncertain` or
+`unknown`, not a claim that a question has been definitively answered. Partial
+provider failures are explicit; absence of selected hits does not prove absence of
+evidence. The agent must verify dates, speakers and contradictions before writing.
+Memory evidence never grants permissions or establishes that an old request is
+still open.
+
+`memory_people_update({ action: "replace_dossier", personId, dossier, reason,
+agentName? })` automatically checks the proposed blurb before saving. Exact
+`qmd://path#Lstart-Lend` claim evidence locators supply up to three indexed ranges
+from the primer's approved corpora (120 lines each, 6,000 characters total).
+Support confidence and background-only/explicit-support probabilities must all
+be >=0.9. `needs_review` or `review_unavailable` leaves the dossier and history
+unchanged; missing keys and failures never count as approval. A concurrent dossier
+edit/deletion returns `conflict` instead of overwriting the newer change.
+
+After independently verifying every assertion and background eligibility, an agent
+can supply a source-specific `manualVerification` explanation (up to 400 characters)
+for direct human corrections, non-indexed evidence or disabled/unavailable/incorrect
+reviews. This explicit path skips TypeSafe, records manual provenance in change
+history and keeps all structural limits. It is not a provider pass. Normal success
+returns `status: "ok"`, `saved: true` and `verification: "typesafe" | "manual"`.
+The skill documents when to use each path. Sources outside approved corpora are
+rejected before egress; no separate `evidenceReview` toggle is needed.
+
+For optional read-only diagnostics, `memory_people_prime({ personId, agentName?,
+draft: { blurb, citations: [{ path, from, lines }] } })` still reviews a snippet
+without writing. Agents do not need this extra call in the normal update workflow.
+
+Judgments are cached privately in `unblock-memory.sqlite` (maximum 2,000 entries), keyed
+by person, agent, exact evidence/context, questions,
+and judge version. No source text or credentials are stored in the cache.
+Retrieval reruns against the current index; unchanged judgments are reused.
+This is on-demand preparation, not a new scheduler or incremental session scanner.
+Use it from an existing People Whisperer maintenance cron. Refresh stale session
+indexes with `memory_sync_sessions` before priming when needed.
+
+## People store and maintenance
+
+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 an injection-enabled person record.
+Incomplete Slack identities create a bounded, deduplicated todo without storing
+message content. Other channels are ignored.
+
+PeopleSQL registers these tools when enabled:
+
+- `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;
+- `memory_people_prime` prepares evidence when the separately opted-in primer is
+  enabled, otherwise returns disabled; and
+- 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 through `tools.allow`. The sync is bounded to
+200 normalized directory entries per call and is safe to rerun. Unblock Memory
+keeps normalized ID, name, handle, avatar, bot and deactivation fields. Slack requires the
+`users:read` scope. Each invocation starts at the beginning of the directory;
+there is no caller-visible continuation cursor. Repeating a capped call does not
+guarantee coverage beyond 200 entries, and sync does not reactivate unavailable people.
+
+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. Dossier generation belongs to the agent; prompt injection
+performs no model call. The optional primer grades evidence and reviews draft snippets.
+The goal is recognition, not a behavioral profile: one short paragraph of at most
+70 words identifying the person and their enduring organization/agent relationship.
+New writes allow only `role`/`relationship` sections and explicit `observed`/`reported`
+claims; priorities, preferences and inferred profiles belong outside dossiers.
+Legacy dossiers remain readable, but must be deliberately rewritten by the agent
+before replacement. No automatic destructive migration or blanket deletion occurs.
+
+Every `replace_dossier` and `delete_dossier` action requires a concise `reason`
+(up to 500 characters for replacements, 1,000 for deletions). Replacement history
+also records whether TypeSafe checks passed or a manual attestation was used.
+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.
+
+## Injection and person state
+
+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:
+
+```text
+Use $people-whisperer to maintain this person's brief background snippet.
+```
+
+For an optional cron or isolated agent session, use this goal:
+
+```text
+Use $people-whisperer to maintain brief background snippets for people you interact
+with. Follow the packaged skill, including source verification and write results.
+Update only when useful; several people or nobody is fine. Report changes and gaps.
+```
+
+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.
+
+### Pause, correct, delete or restore
+
+| Action | Effect | Preserved / follow-up |
+| --- | --- | --- |
+| `set_injection` with `enabled:false` | Pause future injection for this person | Person, dossier and history remain |
+| `replace_dossier` | Save a verified full replacement | Prior snapshot/reason remain in history; existing thread receipts are not reset |
+| `delete_dossier` | Remove the current dossier | Person and transactional before/after history remain; no new blurb injection |
+| `soft_delete_person` | Mark unavailable and turn injection off | Identity/dossier/history remain; creates a review todo |
+| `restore_person` | Mark active again | Injection stays **off**; inspect and explicitly re-enable if appropriate |
+| `set_injection` with `enabled:true` | Enable the person-level injection gate | Still needs global whispering, host permissions, a dossier and an unserved thread |
+
+Slack deactivation marks the **whole linked person** unavailable and disables
+injection, even when other identities are linked. Directory sync skips unavailable
+people rather than automatically restoring them.
+
+Tool inputs for a deliberate pause and later restore/re-enable, using an actual ID:
+
+```json
+{ "action": "set_injection", "personId": "PERSON_ID", "enabled": false }
+```
+
+```json
+{ "action": "restore_person", "personId": "PERSON_ID" }
+```
+
+`restore_person` is for an unavailable person, not a paused active person. After
+inspection, use `set_injection` with `enabled:true` for either one when wanted.
+None of these operations erases raw memory or dossier history.
+
+`memory_people_inspect`'s `injectionEligible` and `contribution` are a
+**record-level preview**, not proof that a hook will inject: they do not account
+for the global whisperer switch, host permissions or an existing thread receipt.
+Changing a dossier or restarting the Gateway does not re-inject it in an already
+served thread. A same-run retry replays its saved contribution; a different thread
+can receive the current blurb. Do not delete receipts as routine troubleshooting.
+
+For agent research/write steps and the dossier schema, use the packaged
+[People Whisperer skill](../skills/people-whisperer/SKILL.md). If the agent has a
+skill allowlist, include `people-whisperer`. General [search and session filtering](retrieval.md)
+are shared memory features, not people-specific controls.