@unblocklabs/unblock-memory 0.8.3 → 0.10.0

package/docs/configuration.md

@@ -16,6 +16,7 @@ settings; a rotated credential file is reread without a restart.
 | Skill Whisperer | `skillWhisperer.enabled`, skills corpus, host hooks | Best local vector candidate meeting `minScore` | Exclude failed candidates; successful siblings may qualify; no vector fallback |
 | Memory Whisperer | `memoryWhisperer.enabled`, explicit approved corpora, host hooks | No hints | Exclude failed candidates; recall/deadline failures still suppress the turn |
 | Complementary hints | Enabled Memory Whisperer + `complementaryHints` | No additional judgment; base hints also require a key | Keep baseline hints unless the total deadline expires |
+| Safety Whisperer | `safetyWhisperer.enabled`, at least one scenario, host hooks (conversation access and prompt injection) | Could not check: the turn proceeds without safety prompts (fails open) | Fails open; recorded as could-not-check, never as no match |
 | 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 |
@@ -25,8 +26,11 @@ settings; a rotated credential file is reread without a restart.
 | Inside Out | `insideOut.enabled`; opts in all retained channels | No inference | Failed reviews are recorded and retried; successes 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
+Skill Whisperer turns on by default once a `skills` corpus is configured; without
+one it registers no hook and reports inactive.
+Memory/People Whisperers, people storage, the primer and audits default off.
+`typesafe.enabled` defaults true but does not enable those opt-in features;
+`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.
@@ -215,8 +219,8 @@ contract; these tables explain their effects.
 | `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; fixed 3-second total deadline |
+| `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` and Safety Whisperer uses `safetyWhisperer.timeoutMs` instead** |
+| `skillWhisperer.enabled` | `true` | Active only with a `skills` corpus (otherwise resolved to `false`, with no hook or host warning) and appropriate host hook access; fixed 3-second total deadline; `false` opts out |
 | `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 |
@@ -230,6 +234,18 @@ contract; these tables explain their effects.
 | `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 |
+| `safetyWhisperer.enabled` | `false` | Requires at least one scenario, a TypeSafe key and host hooks; see [Safety Whisperer](#safety-whisperer) |
+| `safetyWhisperer.historyMessages` | `6` | 0–20 earlier visible messages, whole messages only, for resolving follow-ups |
+| `safetyWhisperer.timeoutMs` | `3000` | 1–10,000 total deadline (credential and request); the host hook timeout must exceed the slowest enabled whisperer |
+| `safetyWhisperer.excludedChannels` | `[]` | Up to 500 `{ provider, accountId, channelId, name? }`, matched case-insensitively; skips every scenario there |
+| `safetyWhisperer.scenarios` | `[]` | Up to 20; unique `id` of letters, digits, `.`, `_` or `-` |
+| `safetyWhisperer.scenarios[].instructions` | Required | Up to 2,000 characters: what the scenario covers, with exclusions; sent to TypeSafe |
+| `safetyWhisperer.scenarios[].flaggedPrompt` | Required | Up to 2,000 characters, appended for matching unapproved requests; never sent to TypeSafe |
+| `safetyWhisperer.scenarios[].minProbability` | `0.4` | 0–1 minimum yes-probability that the current request is covered |
+| `safetyWhisperer.scenarios[].approvedRequestors` | `[]` | Up to 500 `{ provider, accountId, senderId, name? }`; `senderId` must match exactly; skip this scenario for them |
+| `safetyWhisperer.scenarios[].excludedChannels` | `[]` | Up to 500 channels where only this scenario is skipped |
+| `safetyWhisperer.scenarios[].agentIds` | Unset (every agent) | Non-empty list limits the scenario to these agents when one config serves several; normalized like OpenClaw agent IDs (lowercase) |
+| `safetyWhisperer.scenarios[].enabled` | `true` | Disabled scenarios are never sent to TypeSafe |
 
 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
@@ -364,6 +380,7 @@ boundary, not multi-tenant authorization. Approve sources for the agent's audien
 | 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 |
 | Inside Out | Target human reply, nearest assistant text and bounded preceding visible history; channel-scoped speaker identity keys |
+| Safety check | The complete current human message without OpenClaw's conversation-info header; the thread starter, replied-to message and channel messages since the last reply that arrived with it, which can include other people's names and message IDs; up to `historyMessages` earlier visible messages; and each eligible scenario's `instructions`. No sender, account or channel IDs from that header, approval lists or flagged prompts. A message wrapper Safety Whisperer does not recognize (anything other than Slack's) is sent whole, minus that header. |
 | 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
@@ -371,6 +388,157 @@ was quoted in ordinary visible text. Provider judgments are advisory; probabilit
 or score is not proof. Enabling a feature approves only that feature's documented processing.
 
 
+## Safety Whisperer
+
+An optional, interim guardrail for agents that serve several people. Before the
+main model runs on a human turn, it checks the current message against scenarios
+you define, such as questions about one person's salary. When a requestor who is
+not approved for a scenario asks something it covers, that scenario's
+`flaggedPrompt` is appended next to their message for that turn.
+
+**This is a prompt-level guardrail, not access control.** The classifier can miss
+a request and the agent can ignore an injected instruction. It does not remove
+sensitive information already available in context, memory or tools. An approved
+requestor is not an approved audience: asking in a shared channel can still expose
+an answer to everyone there. Use separate agents and real data-access controls for
+hard boundaries.
+
+```json
+{
+  "safetyWhisperer": {
+    "enabled": true,
+    "excludedChannels": [
+      { "name": "#leadership", "provider": "slack", "accountId": "work", "channelId": "C_LEADERSHIP" }
+    ],
+    "scenarios": [
+      {
+        "id": "individual-salaries",
+        "instructions": "Requests about a specific individual employee's salary, pay or compensation, including colloquial phrasing such as how much someone makes or earns. Exclude vendors and contractors.",
+        "approvedRequestors": [
+          { "name": "Dani", "provider": "slack", "accountId": "work", "senderId": "U_DANI" }
+        ],
+        "excludedChannels": [
+          { "name": "#people-ops", "provider": "slack", "accountId": "work", "channelId": "C_PEOPLE_OPS" }
+        ],
+        "flaggedPrompt": "This requestor is not approved to access this information. Kindly tell them that; do not disclose the requested information."
+      }
+    ]
+  }
+}
+```
+
+The plugin entry also needs `hooks.allowConversationAccess: true`, and
+`allowPromptInjection` must not be `false`; see [host controls](#host-controls).
+
+### How each turn is checked
+
+1. Only user-triggered turns are checked, every time: there is no cooldown. A
+   prompt rebuild for the same run reuses that run's result. Messages steered
+   into a run that is already working are not checked; see
+   [messages sent while the agent works](#messages-sent-while-the-agent-works).
+2. A global `excludedChannels` match skips every scenario. A scenario's own
+   `excludedChannels` skip only that scenario. Thread replies and forum topics
+   use their channel.
+3. Disabled scenarios, scenarios limited to other `agentIds`, and scenarios that
+   approve this requestor are dropped.
+4. If none remain, no request is made. Otherwise one TypeSafe request asks one
+   independent yes/no question per remaining scenario. It includes the complete
+   current message, the channel context that arrived with it (thread starter,
+   replied-to message, chat history since the agent's last reply) and up to
+   `historyMessages` earlier visible messages. A follow-up like "What about
+   Sally?" or "answer the question above" is therefore judged in context, while
+   the current message is judged, not whether an earlier one mentioned the topic.
+5. Every scenario scoring at least its `minProbability` adds its `flaggedPrompt`
+   in `<safety>` tags, last in the shared `<unblock_memory>` block after the
+   human message.
+
+### Messages sent while the agent works
+
+OpenClaw's default queue mode, `steer`, adds a message sent during an active run
+to that run without building a new prompt, so the message is never checked. The
+same applies when a person types `/queue steer` in a session. For agents that
+rely on Safety Whisperer, set `messages.queue.mode` (and any
+`messages.queue.byChannel` entries) to `followup` or `collect`; `memory_diagnostics`
+and the Gateway log warn with `queue_mode_steer` until then. In `collect` mode,
+queued messages from different people carry no single sender, so none of them is
+approved.
+
+### Identity
+
+Approval and exclusions compare `provider`, `accountId`, and `senderId` or
+`channelId` values from the host's trusted turn metadata. `senderId` must match
+exactly. `provider`, `accountId` and `channelId` match case-insensitively, because
+OpenClaw lowercases them in places. Names are labels only; display names, message
+text and identity claims never count. Missing identity never approves anyone and
+never excludes a channel, so turns without a sender ID, such as CLI or webchat,
+are treated as unapproved. Email-based approval is not supported.
+
+For Slack:
+
+- `provider` is `slack`.
+- `accountId` is the OpenClaw Slack account key, or `default` when the channel
+  has one account.
+- `senderId` is the person's member ID (`U…`): in their Slack profile, choose
+  **Copy member ID**.
+- `channelId` is the channel's ID (`C…` or `G…`), shown at the bottom of the
+  channel details.
+
+Some runtimes do not pass sender identity to plugins; OpenClaw's Codex
+app-server harness is one. There, every requestor is treated as unapproved,
+exclusions may not apply, and `memory_diagnostics` counts `missing_identity`;
+the first such turn is also logged.
+
+### When the check cannot run
+
+Safety Whisperer **fails open**: if the check cannot complete, the turn proceeds
+with no safety prompt. A TypeSafe outage or missing key therefore turns the
+guardrail off. The exception is a message too large to check: the requestor
+controls its size, so every eligible scenario's `flaggedPrompt` is added instead.
+`memory_diagnostics` reports each outcome under `whisperers.safety`, keeping
+could-not-check separate from no match:
+
+| Outcome | Meaning |
+| --- | --- |
+| `flagged` | At least one scenario matched; `matchedScenarios` counts matches by scenario ID |
+| `no_match` | Checked; no scenario matched |
+| `excluded` / `no_scenarios` | Skipped by a global exclusion, or nothing remained after filtering; no request |
+| `empty_request` | The current message had no text, such as an attachment alone; not checked |
+| `missing_key` / `typesafe_disabled` | Could not check: no credential, or TypeSafe disabled |
+| `input_too_large` | Not checked: the current message exceeds the roughly 24k-token budget. It is never truncated; every eligible `flaggedPrompt` is added |
+| `timed_out` / `failed` | Could not check: deadline, provider error or no usable answer |
+| `partial_response` | Counted with `flagged`: some answers were unusable, and the confident matches were still added |
+| `missing_identity` | Counted with the turn's outcome: the host passed no provider, account or sender ID |
+| `cancelled` | The session ended or the Gateway stopped during the check |
+
+Warnings include the outcome, error code, HTTP status and scenario count, never
+message text; a missing key is logged once until it returns.
+`memory_diagnostics` also reports `safety.active: false` with a `reason` when
+settings or host controls prevent checks (`typesafe_disabled`,
+`conversation_access_not_allowed`, `prompt_injection_not_allowed`,
+`no_enabled_scenarios`), and a `warnings` list:
+
+- `host_hook_timeout_below_whisperer_timeouts`: the host's `before_prompt_build`
+  timeout is shorter than the slowest enabled whisperer (`slowestWhispererMs`).
+  The host times out the plugin's whole contribution, so a slow Memory Whisperer
+  turn can drop a safety prompt even after diagnostics counted it as `flagged`.
+- `queue_mode_steer`: see
+  [messages sent while the agent works](#messages-sent-while-the-agent-works).
+
+The Gateway logs this status at startup when the feature is inactive or has a
+warning.
+
+### Writing scenarios
+
+`instructions` are the classifier's entire definition of a scenario. Name the
+subject, its synonyms and colloquial phrasing, and what is excluded. In the
+source checkout's `eval/safety-whisperer/` cases, adding "pay … including how much
+someone makes or earns" raised a compound request ("What does Bob make, and is he
+on medical leave?") from 0.06 to 0.45–0.48 and lowered "When is payday?" from 0.45
+to 0.18–0.21. With that wording, the 0.4 default `minProbability` made no errors
+across 22 cases, while 0.5 missed the compound request. Lower it to catch more
+borderline requests, or raise it for fewer false refusals. Test your own scenarios
+there before relying on them.
+
 ## Inside Out
 
 Inside Out records six independent emotion-presence probabilities for each human
@@ -384,15 +552,18 @@ change memories, retrieval, prompts, or dossiers.
     "enabled": true,
     "intervalMinutes": 1440,
     "maxInteractions": 100,
-    "maxContextTokens": 30000
+    "maxContextTokens": 30000,
+    "baselineMinInteractions": 20
   }
 }
 ```
 
 Defaults: disabled; daily cadence; at most 100 attempted reviews per run; estimated
 30,000-token context budget, leaving room for questions under Jev's 32k
-state-plus-longest-question limit. `intervalMinutes: 0` is manual-only. The shared
-`typesafe` settings supply Jev credentials and request timeout.
+state-plus-longest-question limit. `intervalMinutes: 0` makes inference manual-only;
+local baselines still refresh daily and on Gateway startup when Inside Out is enabled.
+`baselineMinInteractions` defaults to 20 (1–10,000) for each comparison population.
+The shared `typesafe` settings supply Jev credentials and request timeout.
 
 **Enabling this approves sending visible human/assistant conversation text across
 all retained channels to TypeSafe.** System messages, tool bodies, thinking blocks,
@@ -417,11 +588,15 @@ openclaw memory-emotions link-people --agent main
 openclaw memory-emotions link-people --agent main --repair-identities
 openclaw memory-emotions run --agent main --session SESSION_ID
 openclaw memory-emotions export --agent main --session SESSION_ID
+openclaw memory-emotions baseline-refresh --agent main
+openclaw memory-emotions baselines --agent main --person PERSON_ID
+openclaw memory-emotions export --agent main --person PERSON_ID --deviation-history
+openclaw memory-emotions baseline-refresh --agent main --recompare
 ```
 
 `run` handles backfill and new interactions through the same bounded pass. Repeat
-it until `reviewed` and `failed` are zero to finish backfill. Gateway startup also
-runs one pass, then repeats at the configured interval. Successful results are
+it until `reviewed` and `failed` are zero to finish backfill. With automatic inference
+enabled, Gateway startup also runs one pass, then repeats at the configured interval. Successful results are
 cached; new interactions take priority over retries. Request failures retry after
 an hour when the pass has remaining capacity, or immediately with `--retry`.
 Oversized context failures require explicit `--retry`, for example after increasing
@@ -480,13 +655,109 @@ changed or removed mappings; by default it never reads transcripts. Its explicit
 `--repair-identities` option reads sources owning unlinked reviews and repairs
 their channel, sender ID and human key from persisted metadata before linking.
 Neither mode calls Jev or changes scores, timestamps, review IDs or checkpoints.
-Unmatched identities stay null. Exports include `person_id`.
+Unmatched identities stay null. Exports include `person_id` and `personal_deviation`.
 `export` emits all matching rows as JSON, including errors. `report` averages
 successful rows by human, UTC day/week, rubric, and model; counts are the denominator.
-Both accept `--session`, `--sender`, `--since YYYY-MM-DD`, `--emotion`, and `--min`. `--sender`
+Both accept `--person`, `--session`, `--sender`, `--since YYYY-MM-DD`, `--emotion`, and `--min`. `--sender`
 matches exact sender IDs across channels; use exported `human_key` for precise
 account-specific analysis. These commands are read-only and never invoke Jev.
 
+### Person-relative baselines and deviations
+
+Inside Out keeps analytics beside PeopleSQL in the same `unblock-memory.sqlite`,
+linked by its existing `person_id`. `person_emotion_baselines` holds one snapshot
+per person, rubric, model and completed week; `inside_out_deviations` holds
+individual assessments. They are separate from dossier fields, recognition blurbs
+and searchable memory. PeopleSQL identities must already exist; Inside Out does not
+create people or guess links. Statistics are per agent's retained grades, not
+fleet-wide aggregates.
+
+Weeks run Monday 00:00 UTC to the next Monday, with an exclusive end. Each stored
+week keeps, per emotion, the exact sample count, sum, minimum and maximum, plus the
+distribution in 0.01-wide bins (at most 101 values), so a snapshot stays small
+however much history accumulates. Reports show weekly and cumulative sample counts,
+mean, minimum, maximum, p10, median, p90 and the binned distribution; cumulative
+values are computed from all earlier stored weeks when read. Means, minimums and
+maximums are exact; quantiles use bin values. Completed empty weeks are logged with
+zero weekly observations. Rubrics and models have separate populations.
+
+For each graded reply, `personal_deviation` compares its raw probabilities to that
+person's **preceding completed weeks**, excluding the reply's entire current week
+and future interactions. Both cumulative history and the immediately preceding
+week are reported. Each emotion includes:
+
+- `delta`: signed difference from the person's exact baseline mean.
+- `percentile`: empirical rank from 0 to 1 within 0.01-wide bins; grades in the
+  same bin are ties and take the midpoint.
+- `unusualness`: `abs(2 * percentile - 1)`, from 0 at the middle to 1 at the extremes.
+  This is a rank-derived signal, **not a probability or emotional intensity**.
+
+For example, a joy probability of 0.8 can be routine for someone whose prior grades
+are consistently 0.8, and unusual for someone whose prior grades are 0.1. This does
+not establish their personality, mental state, or the agent's quality. Counts below
+`baselineMinInteractions` produce `insufficient_history` with null emotion metrics,
+independently for weekly and cumulative comparisons. Unlinked people, missing or
+future timestamps and failed grades have explicit statuses; they are never neutral
+scores. Exports before the first local assessment show `not_compared`.
+
+`run` refreshes snapshots after grading new replies. Both grading and daily local
+refreshes update exact PeopleSQL links before aggregating or assessing new replies.
+Historical aggregation runs in a worker thread and commits in short batches, so the
+Gateway event loop stays responsive and other writers to `unblock-memory.sqlite`
+wait for one batch at most, never a whole refresh. Gateway shutdown cancels an
+active refresh; the next one resumes, and repeating a refresh never duplicates
+records. If the refresh after grading fails, `run` still returns its counts with a
+`baselineError` (the Gateway logs a warning); saved grades are unaffected.
+`link-people` also refreshes analytics. `baseline-refresh` does this without loading
+transcripts, calling Jev, or requiring TypeSafe credentials. `baselines` reads
+weekly snapshots, newest first, with optional `--person`, `--since YYYY-MM-DD`
+(inclusive UTC week-end) and `--limit` (1–1,000 weeks, default 100).
+
+Snapshots always reflect the currently linked grades. A late historical grade, a
+retry, a relink or removed identity evidence rewrites the affected week and every
+later week of that population in place, and a population with no linked grades left
+loses its snapshots; earlier revisions are not kept. A snapshot `id` addresses its
+whole cumulative population, so returning to an earlier population restores the
+earlier `id`.
+
+Normal refreshes preserve an existing assessment of the same grade. Late historical
+grades change snapshots but do not silently rewrite earlier comparisons.
+Use `baseline-refresh --recompare` to append changed assessments after backfill,
+identity or sample-policy changes; `export --deviation-history` includes the earlier
+results and marks which match the current grade. Repeating an unchanged refresh
+adds no duplicate records. Previously sparse or future-dated assessments also need
+explicit re-comparison when their circumstances change.
+
+`computed_at` and `assessedAt` record when these calculations actually occurred.
+A backfilled comparison uses retained evidence from earlier interaction weeks, but
+does not pretend that evidence had already been graded at the historical send time.
+Baseline calculation requires no additional model calls and changes no raw emotion
+judgments, dossiers, prompt injection, clustering or memory creation.
+
+### Deleting a person's emotion data
+
+```bash
+openclaw memory-emotions purge --agent main --person PERSON_ID
+openclaw memory-emotions purge --agent main --person PERSON_ID --grades
+```
+
+`purge` deletes one person's weekly snapshots and their whole assessment history,
+including assessments recorded while a reply was linked to them, and prints what it
+removed. It makes no Jev calls.
+
+- **Without `--grades`**, their raw grades stay, so the next refresh rebuilds
+  current snapshots and assessments from replies still linked to them. Use this
+  after correcting a misattributed identity.
+- **With `--grades`**, it also erases the six probabilities of every reply currently
+  linked to that person and unlinks it. Each row stays as a tombstone with the error
+  `Purged by operator`, so `run` (including `--retry`) never sends that reply to Jev
+  again, `link-people` never relinks it, and refreshes skip it. This cannot be
+  undone; run `link-people` first so every reply from that person is linked.
+
+Purging removes existing data only. While Inside Out stays enabled and the person's
+identity remains in PeopleSQL, their new replies are graded and start a new
+baseline. Soft-deleting a person in PeopleSQL does not remove Inside Out data.
+
 ## Storage, upgrades and recovery
 
 Each agent's state lives under the configured OpenClaw state directory, normally

package/docs/peoplesql.md

@@ -9,6 +9,13 @@ store with `people.enabled`; enable injection separately with
 and automatic save review, not a maintenance scheduler. For independent setup
 examples, see the [configuration profiles](configuration.md#example-profiles).
 
+[Inside Out baselines](configuration.md#person-relative-baselines-and-deviations)
+reuse PeopleSQL's person IDs in separate analytics tables in the same database.
+They retain weekly emotion-grade distributions and interaction deviations; none of
+this analytics is written into dossiers or injected by People Whisperer. Deleting a
+dossier or soft-deleting a person leaves it in place; use
+[`memory-emotions purge`](configuration.md#deleting-a-persons-emotion-data).
+
 ## Optional People Dossier Primer
 
 `memory_people_prime({ personId, agentName? })` prepares evidence for an existing person;

package/docs/retrieval.md

@@ -468,9 +468,11 @@ or raw exceptions; exact query text is not retained by this telemetry.
 ## Skill Whisperer
 
 
-Skill Whisperer is an optional semantic reminder for user turns. Configure one
-isolated `skills` corpus, set `skillWhisperer.enabled` to `true`, and authorize
-`plugins.entries.unblock-memory.hooks.allowConversationAccess`. The feature
+Skill Whisperer is a semantic reminder for user turns. It turns on by default once
+you configure one isolated `skills` corpus and authorize
+`plugins.entries.unblock-memory.hooks.allowConversationAccess`. Without a skills
+corpus it stays inactive: no prompt hook is registered and diagnostics report it
+disabled. Set `skillWhisperer.enabled` to `false` to opt out. It
 embeds the current prompt plus the configured number of prior user/assistant
 messages, compares it with each configured skill's frontmatter `name` and
 `description`. With TypeSafe enabled and a key available, the top three valid

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.8.3",
+  "version": "0.10.0",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": true },
@@ -92,6 +92,14 @@
       "label": "Approved Hint Corpora",
       "help": "Explicit non-skill corpus allowlist for automatic recall and TypeSafe processing. Session recall spans this agent's indexed sessions; the sessions corpus chatTypes setting controls direct-message inclusion."
     },
+    "safetyWhisperer.enabled": {
+      "label": "Safety Whisperer",
+      "help": "Prompt-level guardrail, not access control. Sends every checked human message and bounded recent history to TypeSafe and appends a scenario's flaggedPrompt when an unapproved requestor's message matches. Fails open: if the check cannot run, the turn proceeds without it. Requires hook conversation access and prompt injection. Disabled by default."
+    },
+    "safetyWhisperer.scenarios": {
+      "label": "Safety Scenarios",
+      "help": "Each scenario is judged independently. Approval and exclusions match exact provider/account/sender or channel IDs from trusted channel metadata, never names or message text."
+    },
     "people.enabled": {
       "label": "PeopleSQL",
       "help": "Enable the agent-local people store, Slack identity observation and people tools. Disabled by default; whispering and TypeSafe primer/review are separate opt-ins."
@@ -116,7 +124,8 @@
           "enabled": { "type": "boolean", "default": false },
           "intervalMinutes": { "type": "integer", "minimum": 0, "maximum": 10080, "default": 1440 },
           "maxInteractions": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 100 },
-          "maxContextTokens": { "type": "integer", "minimum": 256, "maximum": 30000, "default": 30000 }
+          "maxContextTokens": { "type": "integer", "minimum": 256, "maximum": 30000, "default": 30000 },
+          "baselineMinInteractions": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 20 }
         }
       },
       "extraction": {
@@ -340,17 +349,103 @@
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "enabled": { "type": "boolean", "default": false },
+          "enabled": { "type": "boolean", "default": true, "description": "Takes effect only when a corpus with kind \"skills\" is configured." },
           "historyMessages": { "type": "integer", "minimum": 0, "default": 5 },
           "minScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 },
           "cooldownTurns": { "type": "integer", "minimum": 0, "default": 10 }
         },
         "default": {
-          "enabled": false,
+          "enabled": true,
           "historyMessages": 5,
           "minScore": 0.5,
           "cooldownTurns": 10
         }
+      },
+      "safetyWhisperer": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "Optional prompt-level guardrail for sensitive request scenarios. Fails open when the check cannot run.",
+        "properties": {
+          "enabled": { "type": "boolean", "default": false },
+          "historyMessages": { "type": "integer", "minimum": 0, "maximum": 20, "default": 6 },
+          "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 3000 },
+          "excludedChannels": {
+            "type": "array",
+            "maxItems": 500,
+            "description": "Channels where every safety scenario is skipped. Threads inherit their channel.",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["provider", "accountId", "channelId"],
+              "properties": {
+                "name": { "type": "string", "pattern": "\\S", "maxLength": 256 },
+                "provider": { "type": "string", "pattern": "\\S", "maxLength": 256 },
+                "accountId": { "type": "string", "pattern": "\\S", "maxLength": 256 },
+                "channelId": { "type": "string", "pattern": "\\S", "maxLength": 256 }
+              }
+            }
+          },
+          "scenarios": {
+            "type": "array",
+            "maxItems": 20,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "instructions", "flaggedPrompt"],
+              "properties": {
+                "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+                "enabled": { "type": "boolean", "default": true },
+                "instructions": { "type": "string", "pattern": "\\S", "maxLength": 2000, "description": "What requests this scenario covers, including exclusions." },
+                "flaggedPrompt": { "type": "string", "pattern": "\\S", "maxLength": 2000, "description": "Appended next to the human message when an unapproved requestor's message matches." },
+                "minProbability": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.4, "description": "Minimum TypeSafe yes-probability that the current request is covered." },
+                "agentIds": {
+                  "type": "array",
+                  "minItems": 1,
+                  "maxItems": 500,
+                  "description": "Limit the scenario to these agents; omit for every agent.",
+                  "items": { "type": "string", "pattern": "\\S", "maxLength": 256 }
+                },
+                "approvedRequestors": {
+                  "type": "array",
+                  "maxItems": 500,
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["provider", "accountId", "senderId"],
+                    "properties": {
+                      "name": { "type": "string", "pattern": "\\S", "maxLength": 256 },
+                      "provider": { "type": "string", "pattern": "\\S", "maxLength": 256 },
+                      "accountId": { "type": "string", "pattern": "\\S", "maxLength": 256 },
+                      "senderId": { "type": "string", "pattern": "\\S", "maxLength": 256 }
+                    }
+                  }
+                },
+                "excludedChannels": {
+                  "type": "array",
+                  "maxItems": 500,
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["provider", "accountId", "channelId"],
+                    "properties": {
+                      "name": { "type": "string", "pattern": "\\S", "maxLength": 256 },
+                      "provider": { "type": "string", "pattern": "\\S", "maxLength": 256 },
+                      "accountId": { "type": "string", "pattern": "\\S", "maxLength": 256 },
+                      "channelId": { "type": "string", "pattern": "\\S", "maxLength": 256 }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "default": {
+          "enabled": false,
+          "historyMessages": 6,
+          "timeoutMs": 3000,
+          "excludedChannels": [],
+          "scenarios": []
+        }
       }
     }
   }

package/package.json

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