@unblocklabs/unblock-memory 0.3.15 → 0.3.17

package/README.md

@@ -1,5 +1,203 @@
 # Unblock Memory
 
+## Response quality tracking (opt-in)
+
+`responseAudit` evaluates bounded human-agent exchanges in the background. It is
+separate from chunk-quality auditing and never changes memories or prompts. It
+creates private response-review tasks, not memory-curation tasks.
+Its primary purpose is tracking delivery quality over time: visible fulfillment,
+deliverable fit, clear underdelivery and its observable reason. Memory gaps are only
+an optional diagnostic lead, not a proxy for performance.
+Only approved Slack sender IDs with trusted `senderKind: human` or owner metadata
+qualify (older Slack records use unknown senderKind even for known owners).
+Explicit bots, unverified identities, internal messages, other senders and thread changes form
+hard boundaries. Synthetic delivery mirrors and gateway-injected answers are excluded.
+Assistant progress messages are grouped with the terminal answer.
+Recognized Slack envelopes are stripped even inside `upstreamUserText`; embedded
+history is not treated as current human text. Ambiguous envelopes are excluded.
+Removed history marks the context as limited; ordinary Markdown/JSON is preserved.
+Human feedback closes when the next assistant turn starts. Still-open feedback,
+no-response exchanges, incomplete/failed turns and oversized inputs are not graded.
+
+```json
+{
+  "responseAudit": {
+    "enabled": true,
+    "sentimentEnabled": true,
+    "senderIds": ["YOUR_SLACK_USER_ID"],
+    "chatTypes": ["direct"],
+    "historyMessages": 6,
+    "lookbackDays": 30,
+    "maxEpisodes": 20,
+    "intervalMinutes": 60,
+    "memoryCorpora": ["memory", "knowledge"]
+  }
+}
+```
+
+This is explicit approval to send those exchanges to TypeSafe. Sender IDs apply
+across the agent's Slack accounts; use only identities approved in all such accounts.
+`memoryCorpora` is optional and separately approves configured **file** corpora for
+memory-gap investigation. Leave it empty to send no indexed memory evidence.
+`typesafe.enabled: false` or missing credentials prevents evaluation. An interval
+of zero means manual-only. Defaults are disabled, no approved senders, direct chats,
+6 preceding visible messages, 30 days, 20 episodes per run and a 60-minute interval.
+`sentimentEnabled` defaults to **true within that opt-in audit**; it does not bypass
+approved senders or TypeSafe credentials. Set it false to omit polarity, annoyance,
+frustration and intensity questions while retaining quality/repair judgments.
+`intervalMinutes` controls their shared cadence; no second sentiment timer is needed.
+The Gateway checks a durable per-agent due time on startup and every minute (no
+agent-turn cron or separate launchd job). First enablement waits one interval;
+restarts preserve the due time and an overdue schedule gets one bounded catch-up,
+not one run per missed interval. Each attempt advances the due time before work,
+including missing-key skips, failures or interrupted runs, to prevent retry storms.
+Changing the interval recalculates the due time from the last scheduled attempt
+(or initial enablement). The Gateway must be running; manual audits do not change
+the automatic schedule. Missing/unreadable credentials skip all quality and sentiment
+inference without failing Gateway startup or normal memory functionality.
+Changing the interval does not invalidate cached results. Changing the sentiment
+toggle selects a separate reporting cohort, so older missing sentiment is not
+treated as neutral; unchanged quality/feedback stages are reused across the toggle.
+
+Operator commands (not agent tools):
+
+```sh
+openclaw memory-responses audit --agent main --dry-run
+openclaw memory-responses audit --agent main
+openclaw memory-responses report --agent main
+openclaw memory-responses report --agent main --episode EPISODE_ID
+openclaw memory-responses report --agent main --sender SLACK_USER_ID --account ACCOUNT_SCOPE --bucket day --since 2026-09-01 --until 2026-10-01
+openclaw memory-responses report --agent main --person PERSON_ID
+openclaw memory-responses tasks --agent main
+openclaw memory-responses review --agent main --id TASK_ID --status deferred --reviewer human --note "Review the linked exchanges before changing preferences"
+openclaw memory-responses annotate --agent main --date 2026-09-18 --kind prompt --note "Known prompt revision deployed"
+openclaw memory-responses retry-failed --agent main
+```
+
+Reports group by scoped human identity as well as task/model/time. Names are not
+identity keys. Existing active people-store links are resolved read-only at assessment
+time; missing links do not prevent analysis. Unknown account scopes stay isolated
+per session. No new identity fields are sent to TypeSafe. Date ranges are UTC with
+an inclusive start and exclusive end. `periodStart` identifies a day/week bucket;
+legacy `week`/`fromWeek`/`toWeek` fields remain aliases. `--task-type` and `--model`
+further narrow comparisons. Human-specific scores are not rankings of the humans:
+task difficulty, feedback habits and selection bias remain important.
+
+Session checkpoints hash bounded active source bytes; unchanged sessions skip
+extraction and all inference. Changed sessions are re-extracted within the existing
+budget, then stage hashes reuse unchanged quality, feedback, sentiment and later
+evidence judgments. Only hashes/counts are checkpointed, never a transcript copy.
+A persisted cursor rotates through discovery and tracked-session reconciliation;
+`deferredByLimit` includes known backlog and a lower-bound marker for unvisited
+sessions. `stages` exposes pending/failed/succeeded counts and exhausted retries
+for the cohort/date range, before person filters. `retry-failed` only resets failed
+work; successful stages remain cached. Source freshness is checked before activation.
+
+Review tasks distinguish concrete delivery shortfalls from high-intensity human
+experience complaints. Stable task keys include exchange, scoped human and issue
+family. Decisions survive rescoring; stale source evidence and superseded findings
+are labeled separately. Review status/provenance never changes the raw judgments.
+Tasks and change annotations are operator-only and stay out of memory/whisperer
+prompts. `--reviewer` records human/agent provenance, not authentication or a new
+permission grant. Task lists disclose their 1,000-item cap. There are no automatic
+dossier updates: review the evidence and approve any concrete preference separately.
+Old cohorts remain stored; the first staged-cohort run does not silently import
+unverified older rubric judgments. Audit-history retention is not automatic.
+
+Two separate TypeSafe requests prevent human feedback from influencing the original
+fulfillment/deliverable-fit grade. The feedback pass distinguishes acceptance,
+correction, continuation, unrelated replies, expressed sentiment, repeated constraints
+and avoidable rework. Current-index memory investigation runs only for a strong
+memory-gap signal: lexical retrieval selects up to three whole short documents from
+approved collections. This is an investigation lead, **not proof of historical
+availability, factual truth, or agent fault**. Tool-call counts do not establish what
+the model saw or whether it should have searched. Unseen artifacts are unassessable.
+
+Deliverable kind/format/scope has its own assessability gate, independent of whether
+execution or external facts can be verified. Feedback attribution distinguishes the
+current answer, earlier behavior, delivery, missing proactive action, external events,
+new work and mixed/unclear targets. A reported forgotten instruction does not prove
+searchable memory existed. A third, separate request examines the original exchange,
+human feedback and available next assistant block for specific reported shortfalls,
+acknowledgment, explicit factual corrections, delivery failures and regressions. These are
+retrospective signals, not independently verified facts and never inputs to the
+original grade. Clean text preceding a synthetic error/delivery notice can be assessed
+as **partial** evidence; the notice itself is excluded and no successful completion
+is inferred. Later evidence is capped at six messages/12K characters; incomplete,
+unsafe or oversized blocks stay explicitly pending/unavailable/oversized. New later
+evidence changes the input hash; only changed assessment stages are re-evaluated,
+within normal audit budgets. Successful stages survive failures in later stages.
+When the next block is unavailable, the third pass uses only the original exchange
+and feedback; it cannot infer a missing delivery from missing later evidence.
+
+Code combines narrow, confident evidence into an **observed outcome**, preserving
+its basis and reason. A concrete original-answer shortfall or later admission takes
+precedence over praise. Broad reported failures are used only when they do not
+depend on a newly introduced requirement. Accurate explanations of earlier mistakes,
+ordinary follow-ups, necessary clarification and unseen work are not automatically
+failures. Sentiment and earlier-workflow complaints remain separate review signals.
+Sentiment includes independent annoyance and frustration yes-probabilities (both
+can apply), plus an expressed-dissatisfaction intensity score from 0 to 3. Intensity
+means no expressed displeasure / restrained displeasure / pointed complaint /
+explicit rejection or loss of trust. It is **not confidence or failure severity**.
+External frustration, brevity and factual corrections alone do not establish
+annoyance or frustration; mixed praise and complaints can still carry both signals.
+Weekly reports show dissatisfaction, annoyance and frustration rates, intensity
+means, unknown counts and their own assessment denominators. Unassessed results
+are never counted as neutral. Sentiment deltas require 20 samples in both periods
+and matching assessment coverage; they remain descriptive, not causal evidence.
+Outcome, evidence basis and failure reasons remain distinct: a correction does not
+automatically mean `incorrect_claim`. Confident reason judgments and direct
+delivery/regression admissions supply reasons; otherwise `reasonStatus` is
+`uncertain`. `reasonDetails` retain each label's source and strength, distinguishing
+Choice confidence from Noul yes-probability. Multiple supported reasons can coexist.
+`reportVersion` identifies composition/reporting semantics independently of the
+judge rubric, allowing cached judgments to be re-reported without re-inference.
+
+Results live in the agent's private `unblock-memory/response-audit.sqlite`, outside
+the memory index. It stores judgments and source event references/hashes, not copies
+of conversations. Identical successful inputs are cached; source rewrites invalidate
+in-scope results on the next scan. Reports partition by fixed judge/rubric/context
+configuration, UTC week, task type and agent model. They expose eligible/assessed
+counts, excluded cases, confidence-qualified score means with per-dimension denominators, rework rates with Wilson
+intervals, and evidence IDs. Small groups (<20) are marked explicitly. Confidence
+thresholds are provisional, not calibrated guarantees. Human-reviewed evaluation
+data is still needed before drawing performance conclusions.
+Reports include dated clear-underdelivery examples and reason counts. Descriptive
+score deltas compare successive available UTC weeks within the same task type,
+agent model and rubric/configuration, with at least 20 confident scores per dimension
+in each period and unchanged scored coverage; changed coverage withholds the score
+delta. Outcome trends show acknowledgment, reported-shortfall and unknown rates
+against **all evaluated exchanges**, with at least 20 evaluated exchanges per period.
+Read the three rates together: fewer acknowledgments can mean more unknowns, not
+more failures. Every delta includes before/after values, sample counts, denominator
+and coverage-change flags. Unknown task types/models cannot produce deltas. These
+are not statistical change-point detections or proof of causality; model/version
+changes remain visible as separate groups rather than silently mixing cohorts.
+The legacy `observedSuccessRate` group field remains acknowledgment / known outcomes
+for compatibility, but is not used for trends. Unknowns are never successes.
+Coverage changes and threshold variability can move rates; acknowledgment is not
+factual verification. Week buckets
+may be partial, and several exchanges in one session are not independent. Wilson
+intervals are descriptive, not calibrated confidence about overall agent ability.
+
+Each run selects at most 100 recent sessions for inference, each at most 2,000 active events/2M
+characters; episodes must fit 24K characters and six feedback messages without
+truncating the answer. Coverage counts describe the scanned sessions; only episodes
+within `lookbackDays` are judged. Caps, failures and no-feedback cases remain visible.
+Saved sessions in the report window are also reconciled independently of that
+selection, so removing an entire active branch retires its scores. Oversized saved
+sessions defer reconciliation rather than being treated as deleted; the report
+exposes `reconciledSessions` and `reconciliationDeferred`. All reconciliation shares
+the run deadline. Freshness checks compare the assessed episode, not unrelated
+later session activity. Actual snapshot races do not exhaust provider retries.
+The whole run has a two-minute deadline, at most three provider attempts per input (ten-minute
+backoff), and a cross-process lease. Scheduling never starts inference on the agent
+turn path or boots a QMD manager. No model downloads or source re-indexing occur.
+The report is observational: different task mixes, selective human replies and judge
+changes can produce apparent trends. It does not automatically declare regressions,
+rewrite prompts, or treat silence as success.
+
 ## Review and diagnostics
 
 - `memory_diagnostics` reports credential **availability only**, per-agent process-local
@@ -326,18 +524,105 @@ directory.
 
 ### People Whisperer
 
+#### Optional People Dossier Primer
+
+`memory_people_prime({ personId, agentName? })` prepares evidence for an existing person;
+it does **not** generate claims, update dossiers, or inject context. With
+`people.enabled: true`, opt in separately:
+
+```json
+{
+  "peoplePrimer": {
+    "enabled": true,
+    "corpora": ["memory", "knowledge", "sessions"],
+    "hitsPerQuestion": 30,
+    "minScore": 0.35,
+    "minUsefulness": 0.8,
+    "maxEvidencePerQuestion": 3,
+    "timeoutMs": 30000
+  }
+}
+```
+
+List only configured, approved non-skill corpora. The feature is **off by
+default** and requires shared TypeSafe credentials. Disabled TypeSafe or missing/
+unreadable credentials safely skip the primer; agents can still research normally.
+Enabling it approves sending the person's identity, retrieved excerpts and optional
+draft snippet to TypeSafe. Existing dossiers are not sent as grading evidence.
+Sessions includes all indexed conversations;
+results are available to the agent's tool callers, so scope approval accordingly.
+
+Three default questions cover explicit role/organization, enduring organizational
+background, and the person's relationship to the agent (not its business mission).
+Preferences, working styles, priorities, feedback and task history are excluded.
+Each uses QMD vector search (no query expansion) for up to 30 hits, configurable
+up to 40. All unique eligible hits above the vector threshold are graded, not just
+the final top three. Complete excerpts over 6,000 characters are counted and skipped,
+not silently truncated. Duplicate source spans across questions share a request;
+Independent attribution, explicit-background, durability, recognition-value and
+question-usefulness judgments run together; every dimension must pass the threshold.
+Every candidate is graded against all three questions, regardless of which search
+found it. Mixed excerpts may supply a useful background fact without making their
+surrounding behavioral content eligible for the snippet.
+Provider concurrency is four, with a two-minute overall tool deadline.
+
+Supply the agent's human-facing name when no identity name is configured; otherwise
+questions use "the assistant", never an internal routing ID such as `main`.
+The output includes a deduplicated source-linked excerpt list referenced by each
+question's evidence IDs, a bounded uncertain-review shortlist,
+and retrieval/cache/failure counts. Coverage is `evidence_found`, `uncertain` or
+`unknown`, not a claim that a question has been definitively answered. Partial
+provider failures are explicit; absence of selected hits does not prove absence of
+evidence. The agent must verify dates, speakers and contradictions before writing.
+Memory evidence never grants permissions or establishes that an old request is
+still open.
+
+`memory_people_update({ action: "replace_dossier", personId, dossier, reason,
+agentName? })` automatically checks the proposed blurb before saving. Exact
+`qmd://path#Lstart-Lend` claim evidence locators supply up to three indexed ranges
+from the primer's approved corpora (120 lines each, 6,000 characters total).
+Support confidence and background-only/explicit-support probabilities must all
+be >=0.9. `needs_review` or `review_unavailable` leaves the dossier and history
+unchanged; missing keys and failures never count as approval. A concurrent dossier
+edit/deletion returns `conflict` instead of overwriting the newer change.
+
+After independently verifying every assertion and background eligibility, an agent
+can supply a source-specific `manualVerification` explanation (up to 400 characters)
+for direct human corrections, non-indexed evidence or disabled/unavailable/incorrect
+reviews. This explicit path skips TypeSafe, records manual provenance in change
+history and keeps all structural limits. It is not a provider pass. Normal success
+returns `status: "ok"`, `saved: true` and `verification: "typesafe" | "manual"`.
+The skill documents when to use each path. Sources outside approved corpora are
+rejected before egress; no separate `evidenceReview` toggle is needed.
+
+For optional read-only diagnostics, `memory_people_prime({ personId, agentName?,
+draft: { blurb, citations: [{ path, from, lines }] } })` still reviews a snippet
+without writing. Agents do not need this extra call in the normal update workflow.
+
+Judgments are cached privately in `people.sqlite` (maximum 2,000 entries), keyed
+by person, agent, exact evidence/context, questions,
+and judge version. No source text or credentials are stored in the cache.
+Retrieval reruns against the current index; unchanged judgments are reused.
+This is on-demand preparation, not a new scheduler or incremental session scanner.
+Use it from an existing People Whisperer maintenance cron. Refresh stale session
+indexes with `memory_sync_sessions` before priming when needed.
+
+#### People store and maintenance
+
 PeopleSQL is an optional agent-local people store. When `people.enabled` is
 true, incoming Slack messages with a canonical agent session key and exact
 account and sender IDs create or refresh an injection-enabled person record.
 Incomplete Slack identities create a bounded, deduplicated todo without storing
 message content. Other channels are ignored.
 
-PeopleSQL registers three tools when enabled:
+PeopleSQL registers these tools when enabled:
 
 - `memory_people_inspect` lists active people, reads one exact person, reads one
   person's dossier change history, or lists bounded actionable todos;
 - `memory_people_update` replaces or deletes dossiers, toggles one person's
-  injection, and manages company, todo, deletion, or restoration state; and
+  injection, and manages company, todo, deletion, or restoration state;
+- `memory_people_prime` prepares evidence when the separately opted-in primer is
+  enabled, otherwise returns disabled; and
 - the optional `memory_people_sync` enriches one active OpenClaw Slack account;
   its tool input accepts an account ID, not a token.
 
@@ -353,10 +638,18 @@ person's current dossier, search ordinary memory and sessions with
 `memory_search`/`memory_get`, and replace the dossier when that would improve a
 future conversation. The plugin owns no dossier-maintenance workflow or refresh
 schedule. A dossier's `reviewedAt` value records its last successful write; it
-is not scheduling state. The plugin performs no model call for dossier
-maintenance or prompt injection.
-
-Every `replace_dossier` and `delete_dossier` action requires a concise `reason`.
+is not scheduling state. Dossier generation belongs to the agent; prompt injection
+performs no model call. The optional primer grades evidence and reviews draft snippets.
+The goal is recognition, not a behavioral profile: one short paragraph of at most
+70 words identifying the person and their enduring organization/agent relationship.
+New writes allow only `role`/`relationship` sections and explicit `observed`/`reported`
+claims; priorities, preferences and inferred profiles belong outside dossiers.
+Legacy dossiers remain readable, but must be deliberately rewritten by the agent
+before replacement. No automatic destructive migration or blanket deletion occurs.
+
+Every `replace_dossier` and `delete_dossier` action requires a concise `reason`
+(up to 500 characters for replacements, 1,000 for deletions). Replacement history
+also records whether TypeSafe checks passed or a manual attestation was used.
 The plugin transactionally records that reason with its authoritative before and
 after dossier snapshots. List small newest-first summaries with
 `memory_people_inspect({ view: "dossier_changes", personId, limit?, offset? })`,
@@ -379,20 +672,15 @@ The package includes a `$people-whisperer` skill with the canonical agent
 procedure and dossier shape. For a manual refresh, ask:
 
 ```text
-Use $people-whisperer to improve your understanding of this person. Search memory
-and recent sessions, inspect their current PeopleSQL dossier, and update it only
-if the result would make future conversations meaningfully better.
+Use $people-whisperer to maintain this person's brief background snippet.
 ```
 
 For an optional cron or isolated agent session, use this goal:
 
 ```text
-Use $people-whisperer to improve your understanding of people you interact with.
-
-Search recent sessions and memory for meaningful information about people. Inspect
-their existing PeopleSQL dossiers when useful. Update a dossier only when doing so
-would make future conversations meaningfully better. Ignore routine conversation,
-repetition, and weak inference. You may update several people or nobody.
+Use $people-whisperer to maintain brief background snippets for people you interact
+with. Follow the packaged skill, including source verification and write results.
+Update only when useful; several people or nobody is fine. Report changes and gaps.
 ```
 
 Choose any cadence appropriate for the agent; the plugin does not require or

package/dist/src/config.d.ts

@@ -1,3 +1,5 @@
+import { type ResponseAuditConfig } from "./response-config.js";
+import { type PeoplePrimerConfig } from "./people-primer-config.js";
 export type FileCorpusConfig = {
     name: string;
     kind: "files";
@@ -40,6 +42,8 @@ export type UnblockMemoryConfig = {
         enabled: boolean;
         corpora: readonly string[];
     };
+    responseAudit: ResponseAuditConfig;
+    peoplePrimer: PeoplePrimerConfig;
     people: {
         enabled: boolean;
         whisperer: {

package/dist/src/config.js

@@ -1,4 +1,6 @@
 import { isAbsolute } from "node:path";
+import { resolveResponseAudit } from "./response-config.js";
+import { resolvePeoplePrimer } from "./people-primer-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;
@@ -262,6 +264,8 @@ export function resolveConfig(value) {
             typesafe: { ...DEFAULT_TYPESAFE_CONFIG },
             qualityAudit: { ...DEFAULT_QUALITY_AUDIT },
             evidenceReview: { enabled: false, corpora: [] },
+            responseAudit: resolveResponseAudit(undefined, DEFAULT_CORPORA),
+            peoplePrimer: resolvePeoplePrimer(undefined, DEFAULT_CORPORA, false),
             people: DEFAULT_PEOPLE_CONFIG,
             skillWhisperer: DEFAULT_SKILL_WHISPERER,
             memoryWhisperer: { ...DEFAULT_MEMORY_WHISPERER },
@@ -271,9 +275,10 @@ export function resolveConfig(value) {
         throw new Error("unblock-memory config must be an object");
     }
     const config = value;
-    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "skillWhisperer", "memoryWhisperer", "typesafe", "qualityAudit", "evidenceReview"], "config");
+    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "peoplePrimer", "skillWhisperer", "memoryWhisperer", "typesafe", "qualityAudit", "evidenceReview", "responseAudit"], "config");
     const corpora = resolveCorpora(config.corpora);
     const people = resolvePeople(config.people);
+    const peoplePrimer = resolvePeoplePrimer(config.peoplePrimer, corpora, people.enabled);
     let evidenceReview = { enabled: false, corpora: [] };
     if (config.evidenceReview !== undefined) {
         const value = config.evidenceReview;
@@ -344,8 +349,9 @@ export function resolveConfig(value) {
     if (skillWhisperer.enabled && !corpora.some((corpus) => corpus.kind === "skills")) {
         throw new Error('unblock-memory enabled skillWhisperer requires a corpus named "skills" with kind "skills"');
     }
-    return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, people, skillWhisperer,
+    return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, people, peoplePrimer, skillWhisperer,
         qualityAudit: resolveQualityAudit(config.qualityAudit, corpora),
         evidenceReview,
+        responseAudit: resolveResponseAudit(config.responseAudit, corpora),
         memoryWhisperer: resolveMemoryWhisperer(config.memoryWhisperer, corpora), typesafe: resolveTypeSafe(config.typesafe) };
 }

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

@@ -13,6 +13,10 @@ export declare function reviewIndexedClaim(params: {
     apiKey: string;
     timeoutMs: number;
     signal: AbortSignal;
+    personBackground?: {
+        name: string;
+        agentName: string;
+    };
     read?: <T>(run: () => T) => Promise<T>;
 }): Promise<{
     status: "unavailable";
@@ -29,6 +33,11 @@ export declare function reviewIndexedClaim(params: {
     }[];
     policy: string;
     scope: string;
+    needsReview: boolean;
+    background?: {
+        backgroundOnly: number;
+        explicitSupport: number;
+    } | undefined;
     verdict: "supports" | "contradicts" | "insufficient_evidence";
     confidence: number;
     probabilities: {
@@ -36,6 +45,5 @@ export declare function reviewIndexedClaim(params: {
         contradicts: number;
         insufficient_evidence: number;
     };
-    needsReview: boolean;
     status: "ok";
 }>;

package/dist/src/evidence-review.js

@@ -45,6 +45,7 @@ export async function reviewIndexedClaim(params) {
         }
         return { status: "ok", ...judgment,
             evidence: evidence.map(({ text: _text, ...citation }) => citation),
-            policy: "jev-1.13.0:claim-v1", scope: "Advisory support check against cited indexed excerpts only, not current truth or authorization to write. Verify original sources and identity before promotion." };
+            policy: params.personBackground ? "jev-1.13.0:person-background-v2" : "jev-1.13.0:claim-v1",
+            scope: "Advisory support check against cited indexed excerpts only, not current truth or authorization to write. Verify original sources and identity before promotion." };
     });
 }

package/dist/src/manager.d.ts

@@ -85,6 +85,11 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         }[];
         policy: string;
         scope: string;
+        needsReview: boolean;
+        background?: {
+            backgroundOnly: number;
+            explicitSupport: number;
+        } | undefined;
         verdict: "supports" | "contradicts" | "insufficient_evidence";
         confidence: number;
         probabilities: {
@@ -92,7 +97,6 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
             contradicts: number;
             insufficient_evidence: number;
         };
-        needsReview: boolean;
         status: "ok";
     }>;
     reviewCluster(params: Omit<Parameters<typeof reviewClusterIngestion>[0], "db" | "sources" | "read"> & {

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

@@ -0,0 +1,3 @@
+/** A recognition aid, never a behavioral profile. Existing records remain readable. */
+export declare const PEOPLE_BACKGROUND_MAX_WORDS = 70;
+export declare function backgroundWordCount(text: string): number;

package/dist/src/people-background.js

@@ -0,0 +1,5 @@
+/** A recognition aid, never a behavioral profile. Existing records remain readable. */
+export const PEOPLE_BACKGROUND_MAX_WORDS = 70;
+export function backgroundWordCount(text) {
+    return text.trim().split(/\s+/u).filter(Boolean).length;
+}

package/dist/src/people-dossier-review.d.ts

@@ -0,0 +1,41 @@
+import type { UnblockMemoryConfig } from "./config.js";
+import type { Person, PersonDossier } from "./people-store.js";
+import type { QmdMemoryRuntime } from "./runtime.js";
+import type { getContext } from "./tool-context.js";
+/** Review the injected blurb using only exact indexed references already on its claims. */
+export declare function reviewPersonDossier(params: {
+    config: UnblockMemoryConfig;
+    runtime: QmdMemoryRuntime;
+    active: NonNullable<ReturnType<typeof getContext>>;
+    person: Person;
+    dossier: PersonDossier;
+    agentName?: string;
+    signal?: AbortSignal;
+}): Promise<{
+    evidence: {
+        path: string;
+        from: number;
+        lines: number;
+        documentHash: string;
+        excerptHash: string;
+    }[];
+    policy: string;
+    scope: string;
+    needsReview: boolean;
+    background?: {
+        backgroundOnly: number;
+        explicitSupport: number;
+    } | undefined;
+    verdict: "supports" | "contradicts" | "insufficient_evidence";
+    confidence: number;
+    probabilities: {
+        supports: number;
+        contradicts: number;
+        insufficient_evidence: number;
+    };
+    status: "ok";
+} | {
+    status: "unavailable";
+    needsReview: boolean;
+    reason: string;
+}>;

package/dist/src/people-dossier-review.js

@@ -0,0 +1,47 @@
+import { resolveAgentIdentity } from "openclaw/plugin-sdk/agent-runtime";
+import { abortable } from "./abortable.js";
+import { resolveTypeSafeApiKey } from "./typesafe.js";
+/** Review the injected blurb using only exact indexed references already on its claims. */
+export async function reviewPersonDossier(params) {
+    const unavailable = (reason) => ({ status: "unavailable", needsReview: true, reason });
+    const { config, runtime, active, person, dossier } = params;
+    if (!config.peoplePrimer.enabled || !config.typesafe.enabled) {
+        return unavailable("TypeSafe background review is disabled; verify manually before saving");
+    }
+    const citations = new Map();
+    for (const section of dossier.sections)
+        for (const claim of section.claims)
+            for (const ref of claim.evidence) {
+                const match = /^(qmd:\/\/[^#]+)#L([1-9]\d*)(?:-L([1-9]\d*))?$/.exec(ref.locator);
+                if (!match)
+                    return unavailable("Evidence needs exact qmd://path#Lstart-Lend references or explicit manual verification");
+                const from = Number(match[2]), end = Number(match[3] ?? match[2]);
+                if (!Number.isSafeInteger(from) || !Number.isSafeInteger(end) || end < from || end - from >= 120) {
+                    return unavailable("Evidence ranges must contain 1–120 lines");
+                }
+                const citation = { path: match[1], from, lines: end - from + 1 };
+                citations.set(JSON.stringify(citation), citation);
+            }
+    if (!citations.size || citations.size > 3)
+        return unavailable("Choose 1–3 distinct indexed evidence ranges or verify manually");
+    const deadline = AbortSignal.timeout(120_000);
+    const signal = params.signal ? AbortSignal.any([params.signal, deadline]) : deadline;
+    try {
+        signal.throwIfAborted();
+        const apiKey = await abortable(resolveTypeSafeApiKey(config.typesafe), signal);
+        if (!apiKey)
+            return unavailable("TypeSafe API key not configured; verify manually before saving");
+        const { manager } = await abortable(runtime.getMemorySearchManager(active), signal);
+        if (!manager)
+            return unavailable("Memory index unavailable; verify manually before saving");
+        return await abortable(manager.reviewClaim({
+            claim: dossier.blurb, citations: [...citations.values()],
+            personBackground: { name: person.preferredName ?? person.displayName,
+                agentName: resolveAgentIdentity(active.cfg, active.agentId)?.name?.trim() || params.agentName?.trim() || "the assistant" },
+            corpora: config.peoplePrimer.corpora, apiKey, timeoutMs: config.peoplePrimer.timeoutMs, signal,
+        }), signal);
+    }
+    catch {
+        return unavailable("Background review failed or was cancelled; no dossier written");
+    }
+}

package/dist/src/people-primer-config.d.ts

@@ -0,0 +1,13 @@
+import { Type, type Static } from "typebox";
+import type { CorpusConfig } from "./config.js";
+export declare const peoplePrimerSchema: Type.TObject<{
+    enabled: Type.TBoolean;
+    corpora: Type.TArray<Type.TString>;
+    hitsPerQuestion: Type.TInteger;
+    minScore: Type.TNumber;
+    minUsefulness: Type.TNumber;
+    maxEvidencePerQuestion: Type.TInteger;
+    timeoutMs: Type.TInteger;
+}>;
+export type PeoplePrimerConfig = Static<typeof peoplePrimerSchema>;
+export declare function resolvePeoplePrimer(value: unknown, corpora: readonly CorpusConfig[], peopleEnabled: boolean): PeoplePrimerConfig;

package/dist/src/people-primer-config.js

@@ -0,0 +1,33 @@
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+export const peoplePrimerSchema = Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    corpora: Type.Array(Type.String({ minLength: 1 }), { default: [] }),
+    hitsPerQuestion: Type.Integer({ minimum: 1, maximum: 40, default: 30 }),
+    minScore: Type.Number({ minimum: 0, maximum: 1, default: 0.35 }),
+    minUsefulness: Type.Number({ minimum: 0.5, maximum: 1, default: 0.8 }),
+    maxEvidencePerQuestion: Type.Integer({ minimum: 1, maximum: 10, default: 3 }),
+    timeoutMs: Type.Integer({ minimum: 1, maximum: 60000, default: 30000 }),
+}, { additionalProperties: false });
+export function resolvePeoplePrimer(value, corpora, peopleEnabled) {
+    if (value === undefined)
+        return { enabled: false, corpora: [], hitsPerQuestion: 30,
+            minScore: 0.35, minUsefulness: 0.8, maxEvidencePerQuestion: 3, timeoutMs: 30000 };
+    let config;
+    try {
+        const withDefaults = Value.Default(peoplePrimerSchema, value);
+        if (!Value.Check(peoplePrimerSchema, withDefaults))
+            throw new Error("Invalid config");
+        config = withDefaults;
+    }
+    catch {
+        throw new Error("Invalid peoplePrimer configuration");
+    }
+    if (config.corpora.some(name => !corpora.some(c => c.name === name && c.kind !== "skills"))) {
+        throw new Error("peoplePrimer.corpora must list configured non-skill corpora");
+    }
+    if (config.enabled && (!peopleEnabled || !config.corpora.length)) {
+        throw new Error("peoplePrimer requires people.enabled and explicit approved corpora");
+    }
+    return { ...config, corpora: [...new Set(config.corpora)] };
+}

package/dist/src/people-primer-tool.d.ts

@@ -0,0 +1,5 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { UnblockMemoryConfig } from "./config.js";
+import type { PeopleStores } from "./people-store.js";
+import type { QmdMemoryRuntime } from "./runtime.js";
+export declare function registerPeoplePrimerTool(api: OpenClawPluginApi, runtime: QmdMemoryRuntime, stores: PeopleStores, config: UnblockMemoryConfig): void;