@unblocklabs/unblock-memory 0.8.3 → 0.9.0

package/README.md

@@ -1,109 +1,209 @@
 # Unblock Memory
 
-Workspace-native memory for OpenClaw, powered internally by `@unblocklabs/qmd`.
-It keeps one warm QMD store per agent and exposes `memory_search` and `memory_get`.
-Recall combines BM25 and vector candidates, then independently ranks complete
-passages with TypeSafe. The agent supplies both queries; no query generation or
-"do we need memory?" gate runs for explicit search. A TypeSafe key is required.
+Long-term memory for OpenClaw agents. Unblock Memory indexes each agent's
+workspace Markdown, and optionally its past conversations, so the agent can find
+what it already knows with `memory_search` and check the source with `memory_get`.
+Results are ranked by how useful each passage is for the question, not only by
+keyword or vector similarity.
+
+## Quick start
+
+**Requirements:** Node.js 22+, OpenClaw 2026.8.1-beta.3 or later, and a
+[TypeSafe](https://docs.typesafe.ai) API key. Search uses TypeSafe to rank results.
+
+1. Install once per OpenClaw host, not once per agent:
+
+   ```sh
+   openclaw plugins install npm:@unblocklabs/unblock-memory
+   ```
+
+2. Save your TypeSafe key in a private file (`chmod 600`), for example
+   `~/.openclaw/secrets/unblock-memory-typesafe.env`:
+
+   ```dotenv
+   TYPESAFE_API_KEY="your-key"
+   ```
+
+3. Merge this into `~/.openclaw/openclaw.json`, keeping your other settings.
+   `apiKeyFile` must be an absolute path.
+
+   ```json
+   {
+     "plugins": {
+       "slots": { "memory": "unblock-memory" },
+       "entries": {
+         "unblock-memory": {
+           "enabled": true,
+           "config": {
+             "typesafe": { "apiKeyFile": "/home/you/.openclaw/secrets/unblock-memory-typesafe.env" }
+           }
+         }
+       }
+     }
+   }
+   ```
+
+4. Restart the Gateway, then ask an agent to run `memory_diagnostics`:
+
+   ```sh
+   openclaw gateway restart
+   ```
+
+   `"credential": "available"` means the key was found. It does not check that
+   TypeSafe accepts the key; a test search does.
+
+By default each agent indexes `MEMORY.md`, `USER.md` and `memory/**/*.md` in its
+workspace. The index is built on first use and refreshes in the background when
+those files change. QMD, the local search engine, ships inside the package, so
+there is nothing else to install or run.
+
+To install from source instead:
+`openclaw plugins install git:github.com/unblocklabs-ai/unblock-memory`.
 
-## Start here
+## How it works
 
-Install once per OpenClaw host, not once per agent:
+The agent writes two queries: keywords for BM25 search and a plain-language
+question for vector search. Each returns up to ten candidate passages. TypeSafe
+scores how useful each complete passage is for the question, and the best ones
+come back with their source location.
 
-```sh
-openclaw plugins install npm:@unblocklabs/unblock-memory
+```json
+{ "bm25Query": "staging rollout approval", "vectorQuery": "Who approved the staging rollout?" }
 ```
 
-Merge this into your OpenClaw configuration, preserving other plugins/settings:
-
 ```json
 {
-  "plugins": {
-    "slots": { "memory": "unblock-memory" },
-    "entries": {
-      "unblock-memory": { "enabled": true, "config": {} }
+  "results": [
+    {
+      "path": "qmd://source-3f9a1c2b7d4e/memory/2026-09-14.md",
+      "startLine": 12,
+      "endLine": 15,
+      "snippet": "Priya approved the staging rollout after the load test passed.",
+      "corpus": "memory",
+      "score": 0.93
     }
-  }
+  ]
 }
 ```
 
-The default `memory` corpus contains `MEMORY.md`, `USER.md` and
-`memory/**/*.md`, relative to each agent's workspace. The first use builds its
-index; Markdown changes refresh it in the background. QMD is installed as a
-pinned dependency, not a separate service. A global QMD CLI is not required.
+The agent then calls `memory_get` with that `path` to read the surrounding
+context, attribution and dates. Search defaults to 5 results with a usefulness
+score of at least 0.7. See [search and read](docs/retrieval.md#search-and-read)
+for every parameter.
+
+**What leaves your machine:** indexing, embeddings, storage and `memory_get` run
+locally. `memory_search` sends the search question and candidate passages, with
+their paths and dates, to TypeSafe for scoring. Optional TypeSafe features send
+only what their own settings approve; see
+[TypeSafe data scope](docs/configuration.md#typesafe-data-scope).
+
+**On by default:** search and read over the `memory` corpus, and a
+[compaction memory flush](docs/configuration.md#compaction-memory-writes): before
+OpenClaw compacts a long conversation, the agent is prompted to append lasting
+notes to `memory/YYYY-MM-DD.md`. Turn the flush off with the host's
+`agents.defaults.compaction.memoryFlush.enabled` setting.
+
+## Optional features
+
+Everything below is off until you configure it.
+
+| Feature | What it does |
+| --- | --- |
+| [Session indexing](docs/retrieval.md#sessions) | Makes past conversations searchable. Group and channel chats by default; DMs only if you add them. |
+| [Skill Whisperer](docs/retrieval.md#skill-whisperer) | Suggests one relevant skill for a user message. Never runs it. Works without TypeSafe. |
+| [Memory Whisperer](docs/retrieval.md#memory-whisperer) | Adds up to two relevant past excerpts before the agent replies. Needs TypeSafe and a self-hosted query-generation API. |
+| [Safety Whisperer](docs/configuration.md#safety-whisperer) | Reminds the agent not to share sensitive topics, such as one person's salary, with requestors you haven't approved. A prompt-level guardrail, not access control; fails open if TypeSafe is unavailable. |
+| [People dossiers](docs/peoplesql.md) | Lets the agent keep a short, evidence-backed note about each person it works with. |
+| [People Whisperer](docs/peoplesql.md#injection-and-person-state) | Shows the agent its note about a person once per Slack thread. Local lookup, no model call. |
+| [People Primer](docs/peoplesql.md#optional-people-dossier-primer) | Gathers evidence for a person's note and reviews proposed notes before they are saved. |
+| [Session memory extraction](docs/extraction.md) | Pulls lasting facts from past conversations, checks each against exact quotes, and can make them searchable. Starts in shadow mode. |
+| [Clustering and curation](docs/retrieval.md#memory-analysis) | Groups related memories so the agent can spot duplicates and maintain its knowledge. Needs a local analysis worker. |
+| [Quality and claim review](docs/retrieval.md#review-and-diagnostics) | Flags noisy indexed content and checks whether a claim is supported by its sources. Advisory only. |
+| [Response audit](docs/response-audit.md) | Operator-only grading of reply quality and sentiment in approved Slack conversations. |
+| [Inside Out](docs/configuration.md#inside-out) | Operator-only scores for six emotions in human replies, with reports. Never changes memory or prompts. |
+
+Whisperers also need conversation-hook and prompt-injection permissions on the
+plugin entry; see [host controls](docs/configuration.md#host-controls). Each
+feature's requirements and failure behavior are listed in
+[feature gates and fallbacks](docs/configuration.md#feature-gates-and-fallbacks).
+
+<details>
+<summary>All agent tools</summary>
+
+| Area | Tools |
+| --- | --- |
+| Search and read | `memory_search`, `memory_get` |
+| Sessions | `memory_sync_sessions`, `memory_sync_status` |
+| Diagnostics | `memory_diagnostics` |
+| Clusters | `memory_recluster`, `memory_list_clusters`, `memory_fetch_cluster` |
+| Maintenance | `memory_list_maintenance_tasks`, `memory_update_maintenance_task` |
+| Review | `memory_audit_quality`, `memory_review_claim`, `memory_review_cluster` |
+| People (with `people.enabled`) | `memory_people_inspect`, `memory_people_update`, `memory_people_sync`, `memory_people_prime` |
+
+</details>
+
+## Using memory well
+
+- Search, then read. Check context, attribution and dates with `memory_get`
+  before relying on a snippet.
+- Empty results do not prove something never happened. The corpus may not be
+  selected, the threshold may be too high, or sessions may not have synced yet.
+- Old memory is not current permission to act.
+- Corpora are not access controls. Anyone who can use this agent's tools can
+  search everything indexed for it, so index only what they may all see.
+
+Two skills ship with the package:
+[people-whisperer](skills/people-whisperer/SKILL.md) and
+[memory-curator](skills/memory-curator/SKILL.md). Add them to any explicit agent
+skill allowlist.
+
+## Documentation
 
-Optional installation from source:
-`openclaw plugins install git:github.com/unblocklabs-ai/unblock-memory`.
+- [Configuration](docs/configuration.md): every setting and default,
+  credentials, host permissions, storage and upgrades.
+- [Retrieval](docs/retrieval.md): search and read, sessions, whisperers,
+  diagnostics, clustering and curation.
+- [People](docs/peoplesql.md): dossiers, primer, injection, and
+  pause/delete/restore.
+- [Session extraction](docs/extraction.md): shadow mode, backfill, thresholds
+  and publishing facts to search.
+- [Response audit](docs/response-audit.md): operator commands, cadence and
+  reports.
+- [Memory training](docs/memory-training.md): operator-only collection of
+  training data for Memory Whisperer's query model.
 
-## What does what?
-
-| Capability | What it does | Default / prerequisite |
-| --- | --- | --- |
-| [Search and reads](docs/retrieval.md#search-and-read) | BM25 + vector recall with TypeSafe ranking, then exact indexed reads | Search requires TypeSafe; reads stay local; files only unless more corpora are configured |
-| [Session indexing](docs/retrieval.md#sessions) | Makes past user/assistant exchanges searchable | Opt-in corpus; channel/group by default, DMs explicitly included |
-| [Skill Whisperer](docs/retrieval.md#skill-whisperer) | Suggests one relevant skill; never invokes it | Off; explicit skills corpus; TypeSafe optional |
-| [Memory Whisperer](docs/retrieval.md#memory-whisperer) | Injects up to two useful historical excerpts; query generation via resident API | Off; approved corpora + TypeSafe + query API credential |
-| [People dossiers](docs/peoplesql.md) | Stores agent-authored, evidence-backed recognition snippets | Off; `people.enabled` |
-| [People Primer](docs/peoplesql.md#optional-people-dossier-primer) | Selects evidence and reviews proposed blurbs; never generates/saves dossiers itself | Off; people + approved corpora + TypeSafe |
-| [People Whisperer](docs/peoplesql.md#injection-and-person-state) | Injects a saved blurb for an exact Slack identity | Off; separate global/per-person gates; no model call |
-| [Analysis and curation](docs/retrieval.md#memory-analysis) | Clusters existing vectors; agent maintains useful knowledge | Optional local analysis worker; no plugin-owned curation schedule |
-| [Quality and evidence review](docs/retrieval.md#review-and-diagnostics) | Advisory ingestion/claim checks and maintenance leads | Off; feature-specific corpora + TypeSafe |
-| [Response quality/sentiment](docs/response-audit.md) | Operator-only evaluation of approved Slack exchanges | Off; approved humans + TypeSafe; no memory/dossier updates |
-| [Inside Out](docs/configuration.md#inside-out) | Six emotion probabilities per human reply, with backfill and operator reports | Off; TypeSafe; channel agnostic; no memory or prompt changes |
-| [Session memory extraction](docs/extraction.md) | Luna proposes lasting facts; Jev verifies them; optional QMD search | Off; approved session types + TypeSafe + host LLM permission; shadow-only by default |
-| [Compaction memory flush](docs/configuration.md#compaction-memory-writes) | Supplies the host an append-only daily-memory write plan | Offered unless the host's memory-flush setting is false; separate from whisperers |
-
-**One agent search pipeline:** `memory_search` and Memory Whisperer share
-candidate discovery, passage rendering, deduplication and TypeSafe ranking.
-Whisperer additionally generates queries and applies its automatic recall/delivery policy.
-
-## Configuration and operating guides
-
-- [Configuration](docs/configuration.md): every setting/default, feature dependencies,
-  TypeSafe credentials/data scopes, host permissions and compaction.
-- [Retrieval](docs/retrieval.md): search/read workflow, sessions, whisperers,
-  indexing, diagnostics, clustering and curation.
-- [People](docs/peoplesql.md): dossier workflow, primer/save review, injection and
-  pause/delete/restore semantics.
-- [Response audit](docs/response-audit.md): operator commands, cadence, sentiment,
-  evidence-linked reports and their limits.
-- [Memory training](docs/memory-training.md): resumable, operator-only conversation
-  collection, TypeSafe recall gating, independent lex/vector Luna candidates, one
-  score-feedback revision, and the runtime's shared passage grader for LFM targets.
-- [Session extraction](docs/extraction.md): incremental/backfill runs, configurable
-  acceptance thresholds, shadow evaluation, and publishing lasting facts to search.
-
-The shared TypeSafe integration defaults on. Ordinary search requires a key;
-other TypeSafe features remain opt-in. People Whisperer's injection stays local;
-Skill Whisperer has a local fallback.
-[Provider gates and failure behavior](docs/configuration.md#feature-gates-and-fallbacks)
-differ by feature.
-
-## For agents
-
-Use `memory_search` to locate evidence, then `memory_get` to inspect context,
-attribution and dates. Follow bounded-read continuation when present. Empty search
-results are not proof of absence; old memory is not current authorization.
-
-The package includes two focused procedures:
-[people-whisperer](skills/people-whisperer/SKILL.md) and
-[memory-curator](skills/memory-curator/SKILL.md).
-Include them in any explicit agent skill allowlist. Read their longer references
-only when needed; Skill Whisperer does not install or authorize skills.
-
-## Storage and development
-
-Each agent has a rebuildable `index.sqlite` and durable `unblock-memory.sqlite`.
-The latter holds people/dossiers/history, curation and private response audits;
-sharing a file does not make audit data searchable or prompt-visible.
-Read [migration, backup and rollback](docs/configuration.md#durable-database-migration)
-before upgrading from the former separate databases.
-
-Source-checkout-only fleet key tooling, when present, is documented in
-`scripts/TYPESAFE-FLEET.md` and run through `scripts/typesafe-fleet.mjs`.
-It is not part of the npm package; keep populated key files private.
-
-[Release instructions](https://github.com/unblocklabs-ai/unblock-memory/blob/main/docs/RELEASE.md)
-and [product direction](https://github.com/unblocklabs-ai/unblock-memory/blob/main/docs/vision.md)
-are source-repository references. Planning documents describe historical or future
-designs, not the installed runtime contract.
+[Vision](https://github.com/unblocklabs-ai/unblock-memory/blob/main/docs/vision.md)
+describes where the project is headed. Documents in `docs/planning/` are
+historical or future designs, not current behavior.
+
+## Storage
+
+Each agent's state lives under `~/.openclaw/agents/<agentId>/unblock-memory/`:
+
+- `index.sqlite`: the search index. Safe to delete; it rebuilds.
+- `unblock-memory.sqlite`: people, dossiers, curation and audit history. Back
+  this up.
+
+Upgrading from a version with separate `people.sqlite`, `curation.sqlite` or
+`response-audit.sqlite` files? Stop the Gateway and read
+[migration, backup and rollback](docs/configuration.md#durable-database-migration)
+first.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test            # Node and Python 3 tests
+npm run preflight   # full pre-release check
+```
+
+Releases publish to npm from GitHub Releases; see
+[RELEASE.md](https://github.com/unblocklabs-ai/unblock-memory/blob/main/docs/RELEASE.md).
+Fleet TypeSafe key tooling for source checkouts is described in
+[TYPESAFE-FLEET.md](https://github.com/unblocklabs-ai/unblock-memory/blob/main/scripts/TYPESAFE-FLEET.md);
+keep populated key files private.
+
+## License
+
+[MIT](https://github.com/unblocklabs-ai/unblock-memory/blob/main/LICENSE)

package/dist/src/config.d.ts

@@ -2,6 +2,7 @@ import { type ExtractionConfig } from "./extraction-config.js";
 import { type ResponseAuditConfig } from "./response-config.js";
 import { type PeoplePrimerConfig } from "./people-primer-config.js";
 import { type InsideOutConfig } from "./inside-out.js";
+import { type SafetyWhispererConfig } from "./safety-config.js";
 export type FileCorpusConfig = {
     name: string;
     kind: "files";
@@ -77,6 +78,7 @@ export type UnblockMemoryConfig = {
             apiKeyFile?: string;
         };
     };
+    safetyWhisperer: SafetyWhispererConfig;
 };
 export declare const DEFAULT_PEOPLE_CONFIG: UnblockMemoryConfig["people"];
 export declare function resolveConfig(value: unknown): UnblockMemoryConfig;

package/dist/src/config.js

@@ -3,6 +3,7 @@ import { resolveExtraction } from "./extraction-config.js";
 import { resolveResponseAudit } from "./response-config.js";
 import { resolvePeoplePrimer } from "./people-primer-config.js";
 import { resolveInsideOut } from "./inside-out.js";
+import { resolveSafetyWhisperer } from "./safety-config.js";
 const DEFAULT_PATHS = ["MEMORY.md", "USER.md", "memory/**/*.md"];
 const DEFAULT_SESSION_MAX_EXPANDED_TOKENS = 500;
 const MAX_SESSION_MAX_EXPANDED_TOKENS = 10_000;
@@ -297,7 +298,7 @@ export function resolveConfig(value) {
         throw new Error("unblock-memory config must be an object");
     }
     const config = value;
-    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "peoplePrimer", "skillWhisperer", "memoryWhisperer", "typesafe", "qualityAudit", "evidenceReview", "responseAudit", "insideOut", "extraction"], "config");
+    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "peoplePrimer", "skillWhisperer", "memoryWhisperer", "safetyWhisperer", "typesafe", "qualityAudit", "evidenceReview", "responseAudit", "insideOut", "extraction"], "config");
     const corpora = resolveCorpora(config.corpora);
     const people = resolvePeople(config.people);
     const peoplePrimer = resolvePeoplePrimer(config.peoplePrimer, corpora, people.enabled);
@@ -377,5 +378,6 @@ export function resolveConfig(value) {
         evidenceReview,
         responseAudit: resolveResponseAudit(config.responseAudit, corpora),
         insideOut: resolveInsideOut(config.insideOut),
-        memoryWhisperer: resolveMemoryWhisperer(config.memoryWhisperer, corpora), typesafe: resolveTypeSafe(config.typesafe) };
+        memoryWhisperer: resolveMemoryWhisperer(config.memoryWhisperer, corpora),
+        safetyWhisperer: resolveSafetyWhisperer(config.safetyWhisperer), typesafe: resolveTypeSafe(config.typesafe) };
 }

package/dist/src/diagnostics.d.ts

@@ -1,11 +1,13 @@
 import { RetrievalTelemetry } from "./retrieval-telemetry.js";
-type Whisperer = "skill" | "memory";
-type Outcome = "missing_key" | "typesafe_disabled" | "no_candidates" | "rejected" | "cooldown" | "emitted" | "failed" | "timed_out" | "cancelled" | "unavailable" | "payload_limit" | "redundancy_unavailable" | "recall_not_needed" | "queries_generated" | "judge_candidate_failed" | "input_too_large";
+type Whisperer = "skill" | "memory" | "safety";
+type Outcome = "missing_key" | "typesafe_disabled" | "no_candidates" | "rejected" | "cooldown" | "emitted" | "failed" | "timed_out" | "cancelled" | "unavailable" | "payload_limit" | "redundancy_unavailable" | "recall_not_needed" | "queries_generated" | "judge_candidate_failed" | "input_too_large" | "excluded" | "no_scenarios" | "empty_request" | "no_match" | "flagged" | "missing_identity" | "partial_response";
 /** Process-local, content-free and bounded. Agent IDs are keys, never included in snapshots. */
 export declare class WhispererDiagnostics {
     #private;
     static shared(): WhispererDiagnostics;
     record(agentId: string, whisperer: Whisperer, outcome: Outcome): void;
+    /** Scenario IDs are operator configuration, not conversation content. */
+    recordSafetyMatch(agentId: string, scenarioId: string): void;
     measureMemory(agentId: string, observation: Parameters<RetrievalTelemetry["record"]>[1]): void;
     measureSearch(agentId: string, observation: Parameters<RetrievalTelemetry["record"]>[1]): void;
     snapshot(agentId: string): {
@@ -26,6 +28,13 @@ export declare class WhispererDiagnostics {
             queries_generated?: number | undefined;
             judge_candidate_failed?: number | undefined;
             input_too_large?: number | undefined;
+            excluded?: number | undefined;
+            no_scenarios?: number | undefined;
+            empty_request?: number | undefined;
+            no_match?: number | undefined;
+            flagged?: number | undefined;
+            missing_identity?: number | undefined;
+            partial_response?: number | undefined;
         };
         memory: {
             cancelled?: number | undefined;
@@ -44,6 +53,41 @@ export declare class WhispererDiagnostics {
             queries_generated?: number | undefined;
             judge_candidate_failed?: number | undefined;
             input_too_large?: number | undefined;
+            excluded?: number | undefined;
+            no_scenarios?: number | undefined;
+            empty_request?: number | undefined;
+            no_match?: number | undefined;
+            flagged?: number | undefined;
+            missing_identity?: number | undefined;
+            partial_response?: number | undefined;
+        };
+        safety: {
+            matchedScenarios: {
+                [k: string]: number;
+            };
+            cancelled?: number | undefined;
+            unavailable?: number | undefined;
+            rejected?: number | undefined;
+            failed?: number | undefined;
+            timed_out?: number | undefined;
+            missing_key?: number | undefined;
+            typesafe_disabled?: number | undefined;
+            no_candidates?: number | undefined;
+            cooldown?: number | undefined;
+            emitted?: number | undefined;
+            payload_limit?: number | undefined;
+            redundancy_unavailable?: number | undefined;
+            recall_not_needed?: number | undefined;
+            queries_generated?: number | undefined;
+            judge_candidate_failed?: number | undefined;
+            input_too_large?: number | undefined;
+            excluded?: number | undefined;
+            no_scenarios?: number | undefined;
+            empty_request?: number | undefined;
+            no_match?: number | undefined;
+            flagged?: number | undefined;
+            missing_identity?: number | undefined;
+            partial_response?: number | undefined;
         };
         telemetry: {
             scope: string;

package/dist/src/diagnostics.js

@@ -3,7 +3,8 @@ import { RetrievalTelemetry } from "./retrieval-telemetry.js";
 export class WhispererDiagnostics {
     static shared() {
         const scope = globalThis;
-        const symbol = Symbol.for("unblock-memory.whisperer-diagnostics.v1");
+        // Bump the version whenever the shape changes so an older loaded copy is never reused.
+        const symbol = Symbol.for("unblock-memory.whisperer-diagnostics.v2");
         return (scope[symbol] ??= new WhispererDiagnostics());
     }
     #agents = new Map();
@@ -12,7 +13,7 @@ export class WhispererDiagnostics {
         if (!entry) {
             if (this.#agents.size >= 100)
                 this.#agents.delete(this.#agents.keys().next().value);
-            entry = { counts: { skill: {}, memory: {} }, telemetry: new RetrievalTelemetry() };
+            entry = { counts: { skill: {}, memory: {}, safety: {} }, safetyScenarios: new Map(), telemetry: new RetrievalTelemetry() };
             this.#agents.set(agentId, entry);
         }
         return entry;
@@ -21,6 +22,13 @@ export class WhispererDiagnostics {
         const entry = this.#entry(agentId).counts;
         entry[whisperer][outcome] = Math.min(Number.MAX_SAFE_INTEGER, (entry[whisperer][outcome] ?? 0) + 1);
     }
+    /** Scenario IDs are operator configuration, not conversation content. */
+    recordSafetyMatch(agentId, scenarioId) {
+        const matches = this.#entry(agentId).safetyScenarios;
+        if (!matches.has(scenarioId) && matches.size >= 20)
+            return;
+        matches.set(scenarioId, Math.min(Number.MAX_SAFE_INTEGER, (matches.get(scenarioId) ?? 0) + 1));
+    }
     measureMemory(agentId, observation) {
         this.#entry(agentId).telemetry.record("memoryWhisperer", observation);
     }
@@ -30,6 +38,7 @@ export class WhispererDiagnostics {
     snapshot(agentId) {
         const entry = this.#agents.get(agentId);
         return { skill: { ...entry?.counts.skill }, memory: { ...entry?.counts.memory },
+            safety: { ...entry?.counts.safety, matchedScenarios: Object.fromEntries(entry?.safetyScenarios ?? []) },
             telemetry: entry?.telemetry.snapshot() ?? new RetrievalTelemetry().snapshot(),
             scope: "process lifetime; up to 100 agents" };
     }

package/dist/src/inside-out.js

@@ -5,7 +5,7 @@ import { stripReasoningTagsFromText } from "openclaw/plugin-sdk/text-chunking";
 import { openMemoryDatabase } from "./memory-database.js";
 import { messageText } from "./whisperer-context.js";
 import { conversationUserText } from "./response-text.js";
-import { requestTypeSafe, resolveTypeSafeApiKey, TYPESAFE_MODEL } from "./typesafe-client.js";
+import { estimateJevTokens, requestTypeSafe, resolveTypeSafeApiKey, TYPESAFE_MODEL } from "./typesafe-client.js";
 import { readInsideOutSources } from "./inside-out-sources.js";
 const INSIDE_OUT_EMOTIONS = ["joy", "sadness", "fear", "anger", "disgust", "surprise"];
 const RUBRIC = "emotion-presence-v2";
@@ -52,13 +52,6 @@ export function resolveInsideOut(value) {
         maxContextTokens: integer("maxContextTokens", 256, 30000) };
 }
 const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-// An estimate, not Jev's tokenizer. Non-ASCII is budgeted separately; whole messages stay intact.
-function tokens(value) {
-    let n = 0;
-    for (const c of JSON.stringify(value))
-        n += c.codePointAt(0) < 128 ? 1 / 3 : 2;
-    return Math.ceil(n);
-}
 function humanIdentity(source, message) {
     const meta = message.__openclaw, identity = meta?.senderIdentity;
     const channel = meta?.transport?.channel ?? identity?.pluginId ?? message.sourceChannel ?? source.channel;
@@ -113,12 +106,12 @@ function* interactions(source, budget, cached, after) {
         const id = assistant >= 0 ? hash([source.sessionId, message.id]) : "";
         if (assistant >= 0 && !cached(id)) {
             const selected = [{ message: history[assistant], position: assistant }];
-            let size = tokens({ history: selected.map(s => s.message), target: message });
+            let size = estimateJevTokens({ history: selected.map(s => s.message), target: message });
             const oversized = size > budget;
             for (let i = history.length - 1; !oversized && i >= 0; i--) {
                 if (i === assistant)
                     continue;
-                const cost = tokens(history[i]) + 2;
+                const cost = estimateJevTokens(history[i]) + 2;
                 if (size + cost > budget)
                     break;
                 selected.push({ message: history[i], position: i });

package/dist/src/plugin.js

@@ -8,6 +8,7 @@ import { registerPeopleTools } from "./people-tools.js";
 import { registerPeoplePrimerTool } from "./people-primer-tool.js";
 import { QmdMemoryRuntime } from "./runtime.js";
 import { registerSkillWhisperer } from "./skill-whisperer.js";
+import { registerSafetyWhisperer } from "./safety-whisperer.js";
 import { registerMemoryWhisperer } from "./memory-whisperer.js";
 import { registerWhispererPrompt } from "./whisperer-prompt.js";
 import { getContext } from "./tool-context.js";
@@ -497,6 +498,7 @@ export function registerUnblockMemory(api) {
         memory: registerMemoryWhisperer(api, runtime, config.memoryWhisperer, config.typesafe, diagnostics),
         skill: registerSkillWhisperer(api, runtime, config.skillWhisperer, config.typesafe, diagnostics),
         people: peopleWhisperer,
+        safety: registerSafetyWhisperer(api, config, diagnostics),
     });
     api.registerTool((ctx) => createSearchTool(runtime, ctx, config.typesafe, diagnostics), { names: ["memory_search"] });
     api.registerTool((ctx) => createGetTool(runtime, ctx), { names: ["memory_get"] });

package/dist/src/response-judge.d.ts

@@ -12,7 +12,7 @@ declare const qualitySchema: Type.TObject<{
     answers: Type.TObject<{
         taskType: Type.TObject<{
             type: Type.TLiteral<"choice">;
-            choice: Type.TEnum<("action" | "question" | "artifact" | "discussion" | "other")[]>;
+            choice: Type.TEnum<("action" | "question" | "other" | "artifact" | "discussion")[]>;
             confidence: Type.TNumber;
             probabilities: Type.TObject<{
                 [k: string]: Type.TNumber;

package/dist/src/response-stages.d.ts

@@ -51,7 +51,7 @@ export declare function assessResponseStages(store: ResponseAuditStore, cohort:
         taskType: {
             type: "choice";
             confidence: number;
-            choice: "action" | "question" | "artifact" | "discussion" | "other";
+            choice: "action" | "question" | "other" | "artifact" | "discussion";
             probabilities: {
                 [x: string]: number;
                 [x: number]: number;

package/dist/src/response-text.d.ts

@@ -3,6 +3,13 @@ export declare function conversationUserText(raw: string, sender?: unknown): {
     text: string;
     contextLimited: boolean;
 } | undefined;
+/** Like conversationUserText, plus the untrusted inbound context (thread starter, reply target,
+ * chat history) that a recognized envelope carries before the current message. */
+export declare function conversationEnvelope(raw: string, sender?: unknown): {
+    text: string;
+    contextLimited: boolean;
+    context?: string;
+} | undefined;
 /** Parse only recognized transport envelopes. Ambiguous wrappers are excluded,
  * never flattened into a human's request or used to approve embedded speakers. */
 export declare function responseUserText(input: string, senderId: string): {

package/dist/src/response-text.js

@@ -1,5 +1,11 @@
 /** Infer legacy transport sender metadata only to unwrap visible conversation text. */
 export function conversationUserText(raw, sender) {
+    const parsed = conversationEnvelope(raw, sender);
+    return parsed && { text: parsed.text, contextLimited: parsed.contextLimited };
+}
+/** Like conversationUserText, plus the untrusted inbound context (thread starter, reply target,
+ * chat history) that a recognized envelope carries before the current message. */
+export function conversationEnvelope(raw, sender) {
     let senderId = typeof sender === "string" ? sender : undefined;
     if (senderId === undefined) {
         const header = /^Conversation info: ⟦openclaw:ctx⟧\r?\n```json\r?\n([^]*?)\r?\n```\r?\n/.exec(raw.trim());
@@ -18,13 +24,18 @@ export function conversationUserText(raw, sender) {
         }
         senderId ??= /^From: [^\r\n]+ \(([^()\r\n]+)\)\r?\n/.exec(raw.trim())?.[1];
     }
-    return responseUserText(raw, senderId ?? "");
+    return userEnvelope(raw, senderId ?? "");
 }
 /** Parse only recognized transport envelopes. Ambiguous wrappers are excluded,
  * never flattened into a human's request or used to approve embedded speakers. */
 export function responseUserText(input, senderId) {
+    const parsed = userEnvelope(input, senderId);
+    return parsed && { text: parsed.text, contextLimited: parsed.contextLimited };
+}
+function userEnvelope(input, senderId) {
     let text = input.trim();
     let contextLimited = false;
+    let context;
     const header = /^Conversation info: ⟦openclaw:ctx⟧\r?\n```json\r?\n([^]*?)\r?\n```\r?\n/.exec(text);
     if (header) {
         let meta;
@@ -41,6 +52,7 @@ export function responseUserText(input, senderId) {
         if (markers.length !== 1 || markers[0][1] !== meta.sender.name)
             return undefined;
         const marker = markers[0];
+        context = rest.slice(0, marker.index).trim() || undefined;
         contextLimited = meta.history_truncated === true || rest.slice(0, marker.index).includes("Chat history since last reply:");
         text = rest.slice(marker.index + marker[0].length).trim();
         // OpenClaw appends channel metadata after the current Slack message. Only
@@ -68,5 +80,5 @@ export function responseUserText(input, senderId) {
     // Unrecognized/nested envelopes cannot safely supply the current human text.
     if (!text || text.includes("⟦openclaw:ctx⟧") || /^Chat history since last reply:/m.test(text))
         return undefined;
-    return { text, contextLimited };
+    return { text, contextLimited, ...(context ? { context } : {}) };
 }

package/dist/src/review-tools.js

@@ -3,6 +3,7 @@ import { Value } from "typebox/value";
 import { jsonResult } from "openclaw/plugin-sdk/agent-runtime";
 import { getContext } from "./tool-context.js";
 import { resolveTypeSafeApiKey } from "./typesafe-client.js";
+import { safetyStatus } from "./safety-whisperer.js";
 import { abortable } from "./abortable.js";
 const claimParameters = Type.Object({
     claim: Type.String({ pattern: "\\S", maxLength: 2000 }),
@@ -47,7 +48,9 @@ export function registerReviewTools(api, runtime, config, diagnostics) {
                 }
                 const result = { status: "ok", credential,
                     enabled: { skill: config.skillWhisperer.enabled, memory: config.memoryWhisperer.enabled && config.typesafe.enabled,
-                        complementaryHints: config.memoryWhisperer.complementaryHints, qualityAudit: config.qualityAudit.enabled, evidenceReview: config.evidenceReview.enabled },
+                        complementaryHints: config.memoryWhisperer.complementaryHints, qualityAudit: config.qualityAudit.enabled, evidenceReview: config.evidenceReview.enabled,
+                        safety: config.safetyWhisperer.enabled },
+                    safety: safetyStatus(api.config, config),
                     whisperers: diagnostics.snapshot(active.agentId) };
                 try {
                     const { manager } = await runtime.getMemorySearchManager(active);