@unblocklabs/unblock-memory 0.3.16 → 0.3.17

package/README.md

@@ -524,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.
 
@@ -551,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? })`,
@@ -577,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,4 +1,5 @@
 import { type ResponseAuditConfig } from "./response-config.js";
+import { type PeoplePrimerConfig } from "./people-primer-config.js";
 export type FileCorpusConfig = {
     name: string;
     kind: "files";
@@ -42,6 +43,7 @@ export type UnblockMemoryConfig = {
         corpora: readonly string[];
     };
     responseAudit: ResponseAuditConfig;
+    peoplePrimer: PeoplePrimerConfig;
     people: {
         enabled: boolean;
         whisperer: {

package/dist/src/config.js

@@ -1,5 +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;
@@ -264,6 +265,7 @@ export function resolveConfig(value) {
             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 },
@@ -273,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", "responseAudit"], "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;
@@ -346,7 +349,7 @@ 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),

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;

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

@@ -0,0 +1,78 @@
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { jsonResult, resolveAgentIdentity } from "openclaw/plugin-sdk/agent-runtime";
+import { getContext } from "./tool-context.js";
+import { resolveTypeSafeApiKey } from "./typesafe.js";
+import { primePersonDossier } from "./people-primer.js";
+import { abortable } from "./abortable.js";
+import { backgroundWordCount, PEOPLE_BACKGROUND_MAX_WORDS } from "./people-background.js";
+const parameters = Type.Object({
+    personId: Type.String({ pattern: "\\S", maxLength: 1000 }),
+    agentName: Type.Optional(Type.String({ pattern: "\\S", maxLength: 100,
+        description: "Your human-facing name, e.g. Bill, when no agent identity name is configured. Never a person's name guessed from search results." })),
+    draft: Type.Optional(Type.Object({
+        blurb: Type.String({ pattern: "\\S", maxLength: 1200, description: "Final background-only snippet, at most 70 words. Supplying a draft reviews it instead of running searches." }),
+        citations: Type.Array(Type.Object({
+            path: Type.String({ pattern: "^qmd://", maxLength: 2000 }),
+            from: Type.Integer({ minimum: 1 }), lines: Type.Integer({ minimum: 1, maximum: 120 }),
+        }, { additionalProperties: false }), { minItems: 1, maxItems: 3 }),
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
+export function registerPeoplePrimerTool(api, runtime, stores, config) {
+    const running = new Set();
+    api.registerTool(ctx => {
+        const active = getContext(ctx);
+        if (!active)
+            return null;
+        return {
+            name: "memory_people_prime", label: "Prime Person Dossier",
+            description: "Prepare background-only evidence using three identity/organization/agent-relationship questions. Supply draft to review a final <=70-word snippet against indexed citations instead of searching. Requires peoplePrimer opt-in and approved corpora. Sends identity, approved excerpts and optional draft to TypeSafe, never the existing dossier. Advisory; never writes dossiers.",
+            parameters,
+            async execute(_id, params, signal) {
+                const { personId, agentName: suppliedName, draft } = Value.Parse(parameters, params);
+                if (!config.people.enabled || !config.peoplePrimer.enabled || !config.typesafe.enabled)
+                    return jsonResult({ status: "disabled" });
+                if (draft && backgroundWordCount(draft.blurb) > PEOPLE_BACKGROUND_MAX_WORDS) {
+                    return jsonResult({ status: "invalid", needsReview: true, reason: "Background snippet must not exceed 70 words" });
+                }
+                const key = JSON.stringify([active.agentId, personId]);
+                if (running.has(key))
+                    return jsonResult({ status: "busy" });
+                running.add(key);
+                const deadline = AbortSignal.timeout(120_000);
+                const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+                try {
+                    combined.throwIfAborted();
+                    const apiKey = await abortable(resolveTypeSafeApiKey(config.typesafe), combined);
+                    combined.throwIfAborted();
+                    if (!apiKey)
+                        return jsonResult({ status: "unavailable", reason: "TypeSafe API key not configured" });
+                    const store = stores.get(active.agentId);
+                    const person = store.getPerson(personId);
+                    if (!person || person.status !== "active")
+                        return jsonResult({ status: "not_found" });
+                    const identities = store.listIdentities(personId);
+                    if (identities.length && identities.every(i => i.isBot === true || i.isDeactivated))
+                        return jsonResult({ status: "unavailable", reason: "No active human identity" });
+                    const { manager } = await abortable(runtime.getMemorySearchManager(active), combined);
+                    combined.throwIfAborted();
+                    if (!manager)
+                        return jsonResult({ status: "unavailable", reason: "Memory unavailable" });
+                    const agentName = resolveAgentIdentity(active.cfg, active.agentId)?.name?.trim() || suppliedName?.trim() || "the assistant";
+                    if (draft)
+                        return jsonResult(await manager.reviewClaim({ claim: draft.blurb, citations: draft.citations,
+                            personBackground: { name: person.preferredName ?? person.displayName, agentName },
+                            corpora: config.peoplePrimer.corpora, apiKey, timeoutMs: config.peoplePrimer.timeoutMs, signal: combined }));
+                    return jsonResult(await primePersonDossier({ personId, agentName, store, config: config.peoplePrimer, apiKey, signal: combined,
+                        search: (query, options) => manager.search(query, { ...options, requestContext: active.requestContext }) }));
+                }
+                catch {
+                    return jsonResult({ status: "unavailable", needsReview: true, reason: "Primer failed or was cancelled; no dossier written" });
+                }
+                finally {
+                    running.delete(key);
+                }
+            },
+        };
+    }, { names: ["memory_people_prime"] });
+}

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

@@ -0,0 +1,94 @@
+import type { CorpusMemorySearchResult, CorpusSearchOptions } from "./contracts.js";
+import type { PeoplePrimerConfig } from "./people-primer-config.js";
+import type { PeopleStore } from "./people-store.js";
+/** Evidence preparation only. Search is local; approved excerpts go to TypeSafe.
+ * No identity inference, generated claims, dossier writes or automatic injection. */
+export declare function primePersonDossier(params: {
+    personId: string;
+    agentName: string;
+    store: Pick<PeopleStore, "getPerson" | "listIdentities" | "getPrimerJudgment" | "cachePrimerJudgment">;
+    search: (query: string, options: CorpusSearchOptions) => Promise<CorpusMemorySearchResult[]>;
+    config: PeoplePrimerConfig;
+    apiKey: string;
+    signal: AbortSignal;
+}): Promise<{
+    status: "disabled";
+    reason?: undefined;
+    personId?: undefined;
+    name?: undefined;
+    version?: undefined;
+    advisory?: undefined;
+    stats?: undefined;
+    questions?: undefined;
+    evidence?: undefined;
+} | {
+    status: "not_found";
+    reason?: undefined;
+    personId?: undefined;
+    name?: undefined;
+    version?: undefined;
+    advisory?: undefined;
+    stats?: undefined;
+    questions?: undefined;
+    evidence?: undefined;
+} | {
+    status: "unavailable";
+    reason: string;
+    personId?: undefined;
+    name?: undefined;
+    version?: undefined;
+    advisory?: undefined;
+    stats?: undefined;
+    questions?: undefined;
+    evidence?: undefined;
+} | {
+    status: "ok" | "partial";
+    personId: string;
+    name: string;
+    version: string;
+    advisory: string;
+    stats: {
+        uniqueCandidates: number;
+        requests: number;
+        cached: number;
+        failed: number;
+        elapsedMs: number;
+    };
+    questions: {
+        graded: number;
+        qualifying: number;
+        coverage: "unknown" | "evidence_found" | "uncertain";
+        evidence: {
+            evidenceId: string;
+            vectorScore: number;
+            usefulness: number;
+            aboutPerson: number;
+            explicitBackground: number;
+            enduring: number;
+            recognition: number;
+        }[];
+        review: {
+            evidenceId: string;
+            vectorScore: number;
+            usefulness: number;
+            aboutPerson: number;
+            explicitBackground: number;
+            enduring: number;
+            recognition: number;
+        }[];
+        retrieved?: number | undefined;
+        eligible?: number | undefined;
+        oversized?: number | undefined;
+        id: string;
+        question: string;
+    }[];
+    evidence: {
+        id: string;
+        path: string;
+        from: number;
+        lines: number;
+        excerpt: string;
+        corpus: string;
+    }[];
+    reason?: undefined;
+}>;