@unblocklabs/unblock-memory 0.8.3 → 0.10.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. Turns on when you add a `skills` corpus; 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, compared with each person's own weekly baseline, 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;
@@ -77,7 +78,7 @@ function resolveTypeSafe(value) {
     };
 }
 const DEFAULT_SKILL_WHISPERER = {
-    enabled: false,
+    enabled: true,
     historyMessages: 5,
     minScore: 0.5,
     cooldownTurns: 10,
@@ -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);
@@ -344,7 +345,7 @@ export function resolveConfig(value) {
         }
         const value = config.skillWhisperer;
         assertOnlyKeys(value, ["enabled", "historyMessages", "minScore", "cooldownTurns"], "skillWhisperer");
-        const enabled = value.enabled ?? false;
+        const enabled = value.enabled ?? DEFAULT_SKILL_WHISPERER.enabled;
         const historyMessages = value.historyMessages ?? 5;
         const minScore = value.minScore ?? 0.5;
         const cooldownTurns = value.cooldownTurns ?? 10;
@@ -368,8 +369,11 @@ export function resolveConfig(value) {
         }
         skillWhisperer = { enabled, historyMessages, minScore, cooldownTurns };
     }
+    // Default-on means "on once skills exist": without a skills corpus it could never
+    // hint, so it registers no prompt hook and reports inactive. Host-applied schema
+    // defaults are indistinguishable from an explicit true, so this never throws.
     if (skillWhisperer.enabled && !corpora.some((corpus) => corpus.kind === "skills")) {
-        throw new Error('unblock-memory enabled skillWhisperer requires a corpus named "skills" with kind "skills"');
+        skillWhisperer = { ...skillWhisperer, enabled: false };
     }
     return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, people, peoplePrimer, skillWhisperer,
         extraction: resolveExtraction(config.extraction, corpora),
@@ -377,5 +381,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;
@@ -51,8 +95,8 @@ export declare class WhispererDiagnostics {
                 [k: string]: {
                     calls: number;
                     outcomes: {
-                        ok?: number | undefined;
                         cancelled?: number | undefined;
+                        ok?: number | undefined;
                         partial?: number | undefined;
                         skipped?: number | undefined;
                         failed?: number | undefined;
@@ -60,7 +104,7 @@ export declare class WhispererDiagnostics {
                         timed_out?: number | undefined;
                     };
                     slowestRecent: {
-                        outcome: "ok" | "cancelled" | "partial" | "skipped" | "failed" | "empty" | "timed_out";
+                        outcome: "cancelled" | "ok" | "partial" | "skipped" | "failed" | "empty" | "timed_out";
                         setupMs?: number | undefined;
                         queueWaitMs?: number | undefined;
                         metadataMs?: number | undefined;

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/emotion-baselines.d.ts

@@ -0,0 +1,120 @@
+import type { DatabaseSync, SQLOutputValue } from "node:sqlite";
+export declare const INSIDE_OUT_EMOTIONS: readonly ["joy", "sadness", "fear", "anger", "disgust", "surprise"];
+/** Erased by an operator purge: never retried, linked, aggregated or compared. */
+export declare const PURGED_GRADE = "Purged by operator";
+type Emotion = typeof INSIDE_OUT_EMOTIONS[number];
+type Row = Record<string, SQLOutputValue>;
+type Statistics = {
+    count: number;
+    mean: number | null;
+    min: number | null;
+    p10: number | null;
+    median: number | null;
+    p90: number | null;
+    max: number | null;
+    distribution: [number, number][];
+};
+type Summary = Record<Emotion, Statistics>;
+type Deviation = {
+    delta: number;
+    percentile: number;
+    unusualness: number;
+};
+type Comparison = {
+    status: "ok" | "insufficient_history";
+    count: number;
+    emotions: Record<Emotion, Deviation> | null;
+};
+type PersonalDeviation = {
+    version: string;
+    status: "ok" | "insufficient_history" | "unlinked_person" | "missing_time" | "future_time" | "grade_failed";
+    personId: string | null;
+    baselineId: string | null;
+    baselineEnd: number | null;
+    assessedAt: number;
+    minInteractions: number;
+    cumulative: Comparison | null;
+    weekly: Comparison | null;
+};
+/**
+ * One current, content-addressed snapshot per person, rubric, model and completed week.
+ * Reads finish before each batch commits, so the shared store is never held for a whole pass.
+ * No inference and no changes to raw grades.
+ */
+export declare function refreshEmotionBaselines(db: DatabaseSync, options: {
+    minInteractions: number;
+    now?: number;
+    recompare?: boolean;
+}): {
+    snapshots: number;
+    comparisons: number;
+};
+/** Prepared once per export, not per row. */
+export declare function deviationReader(db: DatabaseSync): (row: Row, history?: boolean) => PersonalDeviation | {
+    status: string;
+} | {
+    history: {
+        currentGrade: boolean;
+        version: string;
+        status: "ok" | "insufficient_history" | "unlinked_person" | "missing_time" | "future_time" | "grade_failed";
+        personId: string | null;
+        baselineId: string | null;
+        baselineEnd: number | null;
+        assessedAt: number;
+        minInteractions: number;
+        cumulative: Comparison | null;
+        weekly: Comparison | null;
+    }[];
+    version: string;
+    status: "ok" | "insufficient_history" | "unlinked_person" | "missing_time" | "future_time" | "grade_failed";
+    personId: string | null;
+    baselineId: string | null;
+    baselineEnd: number | null;
+    assessedAt: number;
+    minInteractions: number;
+    cumulative: Comparison | null;
+    weekly: Comparison | null;
+} | {
+    history: {
+        currentGrade: boolean;
+        version: string;
+        status: "ok" | "insufficient_history" | "unlinked_person" | "missing_time" | "future_time" | "grade_failed";
+        personId: string | null;
+        baselineId: string | null;
+        baselineEnd: number | null;
+        assessedAt: number;
+        minInteractions: number;
+        cumulative: Comparison | null;
+        weekly: Comparison | null;
+    }[];
+    status: "not_compared";
+};
+/** Weekly snapshots, newest first; cumulative statistics are prefix sums of each population's stored weeks. */
+export declare function emotionBaselineHistory(db: DatabaseSync, options?: {
+    personId?: string;
+    since?: number;
+    limit?: number;
+}): {
+    id: string;
+    person_id: string;
+    rubric: string;
+    model: string;
+    version: string;
+    week_start: number;
+    week_end: number;
+    computed_at: number;
+    weekly: Summary;
+    cumulative: Summary;
+}[];
+/**
+ * Delete one person's baselines and assessment history. With `grades`, also erase their six
+ * probabilities and person link, keeping a tombstone so the reply is never sent to Jev again.
+ */
+export declare function purgeEmotionProfile(db: DatabaseSync, personId: string, options?: {
+    grades?: boolean;
+}): {
+    baselines: number;
+    assessments: number;
+    grades: number;
+};
+export {};