@unblocklabs/unblock-memory 0.3.12 → 0.3.13

package/README.md

@@ -80,6 +80,12 @@ directories, or globs into named corpora:
             minScore: 0.5,
             cooldownTurns: 10,
           },
+          typesafe: {
+            enabled: true, // Default; shared by enabled Skill and Memory Whisperers.
+            // Alternatively set TYPESAFE_API_KEY in the Gateway environment.
+            apiKeyFile: "/absolute/path/to/.env",
+            timeoutMs: 1500,
+          },
           people: {
             enabled: false,
             whisperer: { enabled: false, maxChars: 1200 },
@@ -110,6 +116,68 @@ idle unload behavior.
 request all of them explicitly. Search results include their corpus name and
 remain readable by passing the returned `qmd://` path to `memory_get`.
 
+### Memory Whisperer
+
+Memory Whisperer is optional and **off by default**. It proactively retrieves
+historical context before user-triggered turns, without changing `memory_search`
+or `memory_get`. Enable it in the plugin config with an explicit corpus allowlist:
+
+```json5
+memoryWhisperer: {
+  enabled: true,
+  corpora: ["knowledge"], // Must exist in corpora; approve its contents for all agent audiences.
+  historyMessages: 5,
+  minUsefulness: 0.9,
+  maxHints: 2,
+  cooldownTurns: 10,
+  timeoutMs: 3000,
+},
+```
+
+Requires `hooks.allowConversationAccess: true` on the plugin entry, prompt
+injection permission, and the shared TypeSafe credentials described below.
+An empty allowlist is invalid when enabled; `all`, unknown names, and `skills`
+are not accepted. File corpora are approved for **every audience using the agent**:
+do not allowlist private dossiers for an agent that also serves shared channels.
+If `sessions` is allowlisted, only the exact current session is searched, including
+its older indexed messages. Missing session identity excludes that corpus. Other
+sessions, even in the same channel, are excluded before sending excerpts to TypeSafe.
+Session availability still depends on the normal indexing/sync schedule.
+
+QMD searches the current request plus the last N user/assistant messages (at most
+12,000 characters), retrieving up to eight vector candidates without query expansion,
+the local reranker, or a similarity-score cutoff. TypeSafe evaluates one independent
+Noul question per candidate in a single request: does the excerpt add material value
+beyond what the conversation already contains? Merely related, redundant,
+wrong-person/project, and clearly superseded information should be rejected;
+useful contradictory evidence can qualify. `minUsefulness` thresholds the probability
+of yes, not a calibrated guarantee of accuracy. Evaluate it on your own conversations.
+
+**Privacy and budgets:** this feature sends up to 16,000 characters of the available
+user/assistant conversation, prioritizing the current request and recent messages,
+plus up to eight 1,200-character excerpts, corpus names, and session dates to
+`api.typesafe.ai`. Session excerpts retain a complete turn or message when it fits,
+otherwise the complete matched chunk. Chunks exceeding the excerpt budget are
+skipped, never sliced; ordinary `memory_search` is unchanged.
+It does not fetch a complete historical transcript; the host may
+already have compacted the available context. Truncation is marked in the judge's
+input. System messages, thinking blocks, images, and tool-result messages are omitted;
+anything quoted in ordinary user/assistant text can still be transmitted.
+
+At most two qualifying excerpts are injected verbatim with source references and
+historical/untrusted-data framing. Excerpts are deduplicated by normalized content
+and overlapping source lines; recently injected content has a ten-user-turn cooldown
+by default. Cooldown state is in memory and resets on session end or Gateway restart.
+The complete hint payload is capped at 5,000 characters plus a short framing paragraph.
+
+Unlike Skill Whisperer, **disabled TypeSafe, a missing key, no qualifying hits, or any
+failure means no memory hint**—there is no vector-only fallback. The overall process
+has a 3-second deadline, with the shared 1.5-second TypeSafe request deadline inside it;
+neither performs retries. Timed-out or superseded runs cannot inject late hints.
+Already-running local QMD work may finish in the background, but does not keep the
+agent waiting beyond the deadline. No new indexing, clustering, or summarization runs
+are triggered by this feature beyond the memory manager's normal initialization.
+
 ### Skill Whisperer
 
 Skill Whisperer is an optional semantic reminder for user turns. Configure one
@@ -117,13 +185,40 @@ isolated `skills` corpus, set `skillWhisperer.enabled` to `true`, and authorize
 `plugins.entries.unblock-memory.hooks.allowConversationAccess`. The feature
 embeds the current prompt plus the configured number of prior user/assistant
 messages, compares it with each configured skill's frontmatter `name` and
-`description`, and prepends at most one name/path hint when the best match
-reaches `minScore`. Full skill procedures do not influence routing. The plugin
-never opens or invokes a skill automatically.
-
-The defaults use five prior messages, a calibrated score threshold of `0.5`,
+`description`. With TypeSafe enabled and a key available, the top three valid
+candidates are sent to TypeSafe, without a vector-score cutoff. TypeSafe chooses
+one skill or none. A "none" decision never falls back to a vector hint. Full skill
+procedures do not influence routing; no skill is invoked automatically.
+
+The shared `typesafe` configuration defaults to `enabled: true` and
+`timeoutMs: 1500`. Skill and Memory Whisperers share it. Credentials come from
+`typesafe.apiKey`, an absolute `typesafe.apiKeyFile`, or (when neither is set)
+the Gateway's `TYPESAFE_API_KEY` environment variable. Configure at most one of
+`apiKey` and `apiKeyFile`. A key file may contain just the key or dotenv entries
+including `TYPESAFE_API_KEY`; it is reread each turn to support rotation. A dotenv
+file is not sourced as shell code and does not change the process environment.
+Missing/empty files or dotenv files without that variable count as no key;
+an explicit file never falls back to an unrelated environment key. Protect key
+files with owner-only permissions. Workspace `.env` files are not auto-discovered:
+point `apiKeyFile` at the intended file or load the variable into the Gateway.
+
+If TypeSafe is disabled or no key is found, selection uses the original local
+vector process and `skillWhisperer.minScore`. With a key present, an API error,
+invalid response, or timeout emits no hint and logs a sanitized warning; it does
+not switch to vector-only selection. There are no automatic HTTP retries. Other
+credential-file read errors likewise produce a warning and no hint.
+
+**Privacy:** enabled TypeSafe selection sends up to 12,000 characters of current
+prompt/recent user-assistant text, plus the shortlisted names/descriptions, to
+`api.typesafe.ai`. Source-path fields, full skill procedures, tool-result messages,
+and system messages are excluded; dossiers and ordinary memory files are not read
+for this call. Material already quoted in user/assistant text can still be included.
+Disable `typesafe.enabled` to keep Skill Whisperer entirely local. The pinned model
+is `jev-1.13.0`.
+
+The defaults use five prior messages, a vector-only score threshold of `0.5`,
 and a ten-turn cooldown. A skill is cooling down after either a suggestion or a
-successful direct `read` of its indexed `SKILL.md`. When the best qualifying
+successful direct `read` of its indexed `SKILL.md`. When the selected
 skill is cooling down, no hint is emitted; Skill Whisperer does not fall through
 to a weaker match. Cooldown state is per session and intentionally resets with
 the Gateway. Shell-command reads are not tracked.
@@ -275,6 +370,60 @@ dates and maintenance proposals live separately in `curation.sqlite`, so a QMD
 index rebuild does not discard them. The first lookup builds the index;
 Markdown filesystem changes queue a debounced, serialized background refresh.
 
+## Memory quality audit
+
+`memory_audit_quality` is an on-demand, source-read-only audit. TypeSafe flags likely
+ingestion noise for agent investigation; it never deletes, rewrites, or suppresses
+memory. Enable it with explicit approval for the corpora sent to TypeSafe:
+
+```json5
+qualityAudit: {
+  enabled: true,
+  corpora: ["memory", "knowledge"], // Must be configured non-skill corpora.
+  minNoise: 0.8,
+},
+```
+
+Off by default. Uses the shared TypeSafe credentials and request timeout. Missing
+credentials or disabled TypeSafe produces no audit. Approval includes transmission
+of full eligible chunks and visibility of findings to all audiences using the agent.
+Unlike Memory Whisperer, approving `sessions` includes **all indexed sessions** in
+that corpus, including configured direct conversations. Only approve that when intended.
+
+Call with `{ "limit": 10 }` (maximum 20 indexed chunk occurrences per page), then
+pass the returned `next` as `after` until `done` is true. A `partial` result preserves
+the completed cursor; retry there, or from the beginning if no cursor exists. This
+is not a full-document audit: unindexed content is not scanned. Chunks over 6,000
+characters are counted as skipped, not silently truncated. No clustering is required.
+
+Two independent Noul questions distinguish ingestion noise from identifiable useful
+evidence. High values for both can indicate valuable content trapped in a wrapper.
+Low evidence alone does not create a junk finding. JSON, logs, code, terse facts,
+historical records, and missing context are not automatically defects. Empty chunks
+are detected locally. A JSON string that decodes to a message envelope is also
+flagged as a possible double-encoding defect, even when its content is useful.
+An ordinary JSON message object is not flagged from its shape alone. These are
+review clues, never verdicts about whether the information should be kept.
+
+At most four unique chunks (24,000 characters) and their source kinds are sent in
+one request, without conversation context or source paths. Requests do not retry
+automatically and stop starting new work after a 30-second audit deadline; existing
+manager initialization/indexing may finish later. Judgments are cached in the
+curation database by content, source kind, model and question version. A rescan from
+the beginning reuses cached results, including after corpus/index changes. Changes
+behind a page cursor are picked up on the next rescan.
+
+Suspect chunks become `quality_review` tasks in `memory_list_maintenance_tasks`.
+The audit returns page-local groups by configured source and suspected issue,
+with up to three examples each, not a claim that a whole cluster is defective.
+Findings include source references, bounded previews, probabilities and content
+fingerprints. Reviewed tasks are not reopened for unchanged content. The curator
+inspects the original source and ingestion path, proposes or performs authorized
+repairs, and verifies the resulting source/index before resolving with a required
+note. Prefer repairing a common extractor or inclusion rule over many symptoms;
+never manually edit generated session projections. Thresholds need evaluation on
+your data; model probability is not proof of a defect.
+
 ## Memory analysis
 
 Analysis is opt-in. Core indexing, `memory_search`, and `memory_get` need only

package/dist/src/config.d.ts

@@ -25,6 +25,17 @@ export type UnblockMemoryConfig = {
     analysis: {
         executable?: string;
     };
+    typesafe: {
+        enabled: boolean;
+        apiKey?: string;
+        apiKeyFile?: string;
+        timeoutMs: number;
+    };
+    qualityAudit: {
+        enabled: boolean;
+        corpora: readonly string[];
+        minNoise: number;
+    };
     people: {
         enabled: boolean;
         whisperer: {
@@ -41,6 +52,15 @@ export type UnblockMemoryConfig = {
         minScore: number;
         cooldownTurns: number;
     };
+    memoryWhisperer: {
+        enabled: boolean;
+        corpora: readonly string[];
+        historyMessages: number;
+        minUsefulness: number;
+        maxHints: number;
+        cooldownTurns: number;
+        timeoutMs: number;
+    };
 };
 export declare const DEFAULT_PEOPLE_CONFIG: UnblockMemoryConfig["people"];
 export declare function resolveConfig(value: unknown): UnblockMemoryConfig;

package/dist/src/config.js

@@ -15,12 +15,108 @@ export const DEFAULT_PEOPLE_CONFIG = {
     whisperer: { enabled: false, maxChars: 1200 },
     todos: { maxOpen: 1000 },
 };
+const DEFAULT_TYPESAFE_CONFIG = {
+    enabled: true,
+    timeoutMs: 1500,
+};
+const DEFAULT_QUALITY_AUDIT = {
+    enabled: false, corpora: [], minNoise: 0.8,
+};
+function resolveQualityAudit(value, corpora) {
+    if (value === undefined)
+        return { ...DEFAULT_QUALITY_AUDIT };
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("qualityAudit must be an object");
+    const config = value;
+    assertOnlyKeys(config, ["enabled", "corpora", "minNoise"], "qualityAudit");
+    const enabled = config.enabled ?? false;
+    const selected = config.corpora ?? [];
+    const minNoise = config.minNoise ?? DEFAULT_QUALITY_AUDIT.minNoise;
+    if (typeof enabled !== "boolean")
+        throw new Error("qualityAudit.enabled must be a boolean");
+    if (!Array.isArray(selected) || !selected.every((name) => typeof name === "string" && corpora.some(corpus => corpus.name === name && corpus.kind !== "skills"))) {
+        throw new Error("qualityAudit.corpora must list configured non-skill corpora");
+    }
+    if (enabled && !selected.length)
+        throw new Error("enabled qualityAudit requires explicit corpora");
+    if (typeof minNoise !== "number" || !Number.isFinite(minNoise) || minNoise < 0 || minNoise > 1) {
+        throw new Error("qualityAudit.minNoise must be between 0 and 1");
+    }
+    return { enabled, corpora: [...new Set(selected)], minNoise };
+}
+function resolveTypeSafe(value) {
+    if (value === undefined)
+        return { ...DEFAULT_TYPESAFE_CONFIG };
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("unblock-memory typesafe must be an object");
+    }
+    const config = value;
+    assertOnlyKeys(config, ["enabled", "apiKey", "apiKeyFile", "timeoutMs"], "typesafe");
+    const enabled = config.enabled ?? true;
+    if (typeof enabled !== "boolean")
+        throw new Error("unblock-memory typesafe.enabled must be a boolean");
+    for (const key of ["apiKey", "apiKeyFile"]) {
+        if (config[key] !== undefined && (typeof config[key] !== "string" || !config[key].trim())) {
+            throw new Error(`unblock-memory typesafe.${key} must be a non-empty string`);
+        }
+    }
+    const apiKey = typeof config.apiKey === "string" ? config.apiKey.trim() : undefined;
+    const apiKeyFile = typeof config.apiKeyFile === "string" ? config.apiKeyFile.trim() : undefined;
+    if (apiKey && apiKeyFile)
+        throw new Error("unblock-memory typesafe accepts apiKey or apiKeyFile, not both");
+    if (apiKeyFile && !isAbsolute(apiKeyFile)) {
+        throw new Error("unblock-memory typesafe.apiKeyFile must be an absolute path");
+    }
+    return {
+        enabled, ...(apiKey ? { apiKey } : {}), ...(apiKeyFile ? { apiKeyFile } : {}),
+        timeoutMs: positiveInteger(config.timeoutMs, DEFAULT_TYPESAFE_CONFIG.timeoutMs, "typesafe.timeoutMs", 10_000),
+    };
+}
 const DEFAULT_SKILL_WHISPERER = {
     enabled: false,
     historyMessages: 5,
     minScore: 0.5,
     cooldownTurns: 10,
 };
+const DEFAULT_MEMORY_WHISPERER = {
+    enabled: false, corpora: [], historyMessages: 5, minUsefulness: 0.9,
+    maxHints: 2, cooldownTurns: 10, timeoutMs: 3000,
+};
+function resolveMemoryWhisperer(value, corpora) {
+    if (value === undefined)
+        return { ...DEFAULT_MEMORY_WHISPERER };
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("unblock-memory memoryWhisperer must be an object");
+    }
+    const config = value;
+    assertOnlyKeys(config, Object.keys(DEFAULT_MEMORY_WHISPERER), "memoryWhisperer");
+    const enabled = config.enabled ?? false;
+    if (typeof enabled !== "boolean")
+        throw new Error("unblock-memory memoryWhisperer.enabled must be a boolean");
+    const selected = config.corpora ?? [];
+    if (!Array.isArray(selected) || !selected.every((name) => typeof name === "string" && corpora.some(corpus => corpus.name === name && corpus.kind !== "skills"))) {
+        throw new Error("unblock-memory memoryWhisperer.corpora must list configured non-skill corpora");
+    }
+    if (enabled && !selected.length)
+        throw new Error("unblock-memory enabled memoryWhisperer requires explicit corpora");
+    const historyMessages = config.historyMessages ?? 5;
+    const cooldownTurns = config.cooldownTurns ?? 10;
+    if (typeof historyMessages !== "number" || !Number.isInteger(historyMessages) || historyMessages < 0 || historyMessages > 50) {
+        throw new Error("unblock-memory memoryWhisperer.historyMessages must be an integer between 0 and 50");
+    }
+    if (typeof cooldownTurns !== "number" || !Number.isInteger(cooldownTurns) || cooldownTurns < 0 || cooldownTurns > 1000) {
+        throw new Error("unblock-memory memoryWhisperer.cooldownTurns must be an integer between 0 and 1000");
+    }
+    const minUsefulness = config.minUsefulness ?? 0.9;
+    if (typeof minUsefulness !== "number" || !Number.isFinite(minUsefulness) || minUsefulness < 0 || minUsefulness > 1) {
+        throw new Error("unblock-memory memoryWhisperer.minUsefulness must be between 0 and 1");
+    }
+    return {
+        enabled, corpora: [...new Set(selected)], historyMessages, cooldownTurns, minUsefulness,
+        maxHints: positiveInteger(config.maxHints, 2, "memoryWhisperer.maxHints", 2),
+        timeoutMs: positiveInteger(config.timeoutMs, 3000, "memoryWhisperer.timeoutMs", 10_000),
+    };
+}
 function assertOnlyKeys(value, allowed, label) {
     const unknown = Object.keys(value).find((key) => !allowed.includes(key));
     if (unknown)
@@ -160,15 +256,18 @@ export function resolveConfig(value) {
             corpora: DEFAULT_CORPORA,
             keepEmbeddingModelWarm: true,
             analysis: {},
+            typesafe: { ...DEFAULT_TYPESAFE_CONFIG },
+            qualityAudit: { ...DEFAULT_QUALITY_AUDIT },
             people: DEFAULT_PEOPLE_CONFIG,
             skillWhisperer: DEFAULT_SKILL_WHISPERER,
+            memoryWhisperer: { ...DEFAULT_MEMORY_WHISPERER },
         };
     }
     if (typeof value !== "object" || Array.isArray(value)) {
         throw new Error("unblock-memory config must be an object");
     }
     const config = value;
-    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "skillWhisperer"], "config");
+    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "skillWhisperer", "memoryWhisperer", "typesafe", "qualityAudit"], "config");
     const corpora = resolveCorpora(config.corpora);
     const people = resolvePeople(config.people);
     if (config.keepEmbeddingModelWarm !== undefined &&
@@ -227,5 +326,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, skillWhisperer,
+        qualityAudit: resolveQualityAudit(config.qualityAudit, corpora),
+        memoryWhisperer: resolveMemoryWhisperer(config.memoryWhisperer, corpora), typesafe: resolveTypeSafe(config.typesafe) };
 }

package/dist/src/contracts.d.ts

@@ -12,6 +12,8 @@ export type CorpusMemorySearchResult = MemorySearchResult & {
     session?: SessionMetadata;
 };
 export type SessionSearchFilter = {
+    /** Internal exact-session scope used by proactive hints; not exposed by the search tool. */
+    sessionId?: string;
     startedFrom?: string;
     startedTo?: string;
     provider?: string;
@@ -22,6 +24,8 @@ export type SessionSearchFilter = {
 export type MemoryRequestContext = Pick<OpenClawPluginToolContext, "sessionKey" | "sessionId" | "messageChannel" | "agentAccountId" | "nativeChannelId" | "deliveryContext">;
 export type CorpusSearchOptions = NonNullable<Parameters<MemorySearchManagerContract["search"]>[1]> & {
     corpora?: readonly string[];
+    /** Internal vector-hint budget; oversized matched chunks are omitted, never sliced. */
+    maxSnippetChars?: number;
     sessionFilter?: SessionSearchFilter;
     requestContext?: MemoryRequestContext;
 };

package/dist/src/curation.d.ts

@@ -1,6 +1,7 @@
+import type { QualityJudgment } from "./typesafe.js";
 declare const TEMPORAL_BASES: readonly ["path", "frontmatter", "session", "agent_verified"];
 export type TemporalBasis = typeof TEMPORAL_BASES[number];
-declare const MAINTENANCE_TASK_TYPES: readonly ["ambiguous_event_time", "exact_duplicate"];
+declare const MAINTENANCE_TASK_TYPES: readonly ["ambiguous_event_time", "exact_duplicate", "quality_review"];
 export type MaintenanceTaskType = typeof MAINTENANCE_TASK_TYPES[number];
 declare const MAINTENANCE_STATUSES: readonly ["pending", "resolved", "deferred", "irrelevant"];
 export type MaintenanceStatus = typeof MAINTENANCE_STATUSES[number];
@@ -36,6 +37,8 @@ export declare class CurationStore {
     #private;
     constructor(path: string);
     close(): void;
+    qualityJudgment(key: string): QualityJudgment | undefined;
+    cacheQualityJudgment(key: string, judgment: QualityJudgment): void;
     annotations(): TemporalAnnotation[];
     addTask(candidate: {
         type: MaintenanceTaskType;
@@ -45,7 +48,7 @@ export declare class CurationStore {
         reason: string;
         contentFingerprint?: string;
         detail?: string;
-    }): void;
+    }): MaintenanceTask;
     listTasks(params?: {
         status?: MaintenanceStatus;
         limit?: number;

package/dist/src/curation.js

@@ -3,7 +3,7 @@ import { chmodSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 const TEMPORAL_BASES = ["path", "frontmatter", "session", "agent_verified"];
-const MAINTENANCE_TASK_TYPES = ["ambiguous_event_time", "exact_duplicate"];
+const MAINTENANCE_TASK_TYPES = ["ambiguous_event_time", "exact_duplicate", "quality_review"];
 const MAINTENANCE_STATUSES = ["pending", "resolved", "deferred", "irrelevant"];
 function annotation(row) {
     return {
@@ -66,12 +66,17 @@ export class CurationStore {
 
     `);
         this.#ensureMaintenanceSchema();
+        this.#db.exec(`CREATE TABLE IF NOT EXISTS quality_judgments (
+      cache_key TEXT PRIMARY KEY,
+      noise REAL NOT NULL CHECK (noise BETWEEN 0 AND 1),
+      evidence REAL NOT NULL CHECK (evidence BETWEEN 0 AND 1)
+    )`);
     }
     #ensureMaintenanceSchema() {
         this.#db.exec(`
       CREATE TABLE IF NOT EXISTS maintenance_tasks (
         id TEXT PRIMARY KEY,
-        type TEXT NOT NULL CHECK (type IN ('ambiguous_event_time', 'exact_duplicate')),
+        type TEXT NOT NULL CHECK (type IN ('ambiguous_event_time', 'exact_duplicate', 'quality_review')),
         corpus TEXT NOT NULL,
         collection TEXT NOT NULL,
         path TEXT NOT NULL,
@@ -85,6 +90,23 @@ export class CurationStore {
         UNIQUE (type, corpus, collection, path, reason, content_fingerprint)
       );
     `);
+        const schema = this.#db.prepare("SELECT sql FROM sqlite_master WHERE name = 'maintenance_tasks'")
+            .get();
+        if (!schema.sql.includes("'quality_review'")) {
+            this.#db.exec("BEGIN IMMEDIATE");
+            try {
+                this.#db.exec(schema.sql.replace("maintenance_tasks", "maintenance_tasks_quality")
+                    .replace("'exact_duplicate'", "'exact_duplicate', 'quality_review'"));
+                this.#db.exec(`INSERT INTO maintenance_tasks_quality SELECT * FROM maintenance_tasks;
+          DROP TABLE maintenance_tasks;
+          ALTER TABLE maintenance_tasks_quality RENAME TO maintenance_tasks;`);
+                this.#db.exec("COMMIT");
+            }
+            catch (error) {
+                this.#db.exec("ROLLBACK");
+                throw error;
+            }
+        }
         this.#db.exec(`
       CREATE INDEX IF NOT EXISTS maintenance_tasks_status_created
         ON maintenance_tasks(status, created_at);
@@ -93,6 +115,14 @@ export class CurationStore {
     close() {
         this.#db.close();
     }
+    qualityJudgment(key) {
+        return this.#db.prepare("SELECT noise, evidence FROM quality_judgments WHERE cache_key = ?")
+            .get(key);
+    }
+    cacheQualityJudgment(key, judgment) {
+        this.#db.prepare("INSERT OR REPLACE INTO quality_judgments(cache_key, noise, evidence) VALUES (?, ?, ?)")
+            .run(key, judgment.noise, judgment.evidence);
+    }
     annotations() {
         return this.#db.prepare(`
       SELECT * FROM temporal_annotations
@@ -115,6 +145,9 @@ export class CurationStore {
           ELSE maintenance_tasks.updated_at
         END
     `).run(randomUUID(), candidate.type, candidate.corpus, candidate.collection, candidate.path, candidate.reason, candidate.contentFingerprint ?? "", candidate.detail ?? null, now, now);
+        return task(this.#db.prepare(`SELECT * FROM maintenance_tasks
+      WHERE type = ? AND corpus = ? AND collection = ? AND path = ? AND reason = ? AND content_fingerprint = ?`)
+            .get(candidate.type, candidate.corpus, candidate.collection, candidate.path, candidate.reason, candidate.contentFingerprint ?? ""));
     }
     listTasks(params = {}) {
         const status = params.status ?? "pending";
@@ -136,6 +169,9 @@ export class CurationStore {
                 return undefined;
             }
             const now = new Date().toISOString();
+            if (row.type === "quality_review" && params.status === "resolved" && !params.note?.trim()) {
+                throw new Error("resolving a quality review requires a note describing source/index verification");
+            }
             if (row.type === "ambiguous_event_time" && params.status === "resolved" && !params.annotation) {
                 throw new Error("resolving an ambiguous event-time task requires a date annotation");
             }

package/dist/src/manager.d.ts

@@ -5,6 +5,7 @@ import type { ChatType } from "./config.js";
 import { type MaintenanceStatus, type TemporalBasis } from "./curation.js";
 import { type SessionSyncResult } from "./session-sync.js";
 import { type ResolvedSource } from "./sources.js";
+import { type QualityCursor } from "./quality-audit.js";
 export type ManagerStore = Pick<QMDStore, "update" | "embed" | "getStatus" | "listCollections" | "searchLex" | "vsearch" | "get" | "getDocumentBody" | "close">;
 export type ManagerSessionConfig = {
     agentId: string;
@@ -19,6 +20,7 @@ export type ManagerSessionConfig = {
 };
 export type SkillSearchCandidate = {
     name: string;
+    description: string;
     path: string;
     score: number;
 };
@@ -31,7 +33,7 @@ export declare function buildReadResult(params: {
     from?: number;
     lines?: number;
 }): MemoryReadResult;
-export declare function expandSessionSearchHit(result: Pick<VectorSearchResult, "body" | "bestChunk" | "chunkPos" | "chunkLen">, maxTokens: number, countTokens: (text: string) => Promise<number>): Promise<{
+export declare function expandSessionSearchHit(result: Pick<VectorSearchResult, "body" | "bestChunk" | "chunkPos" | "chunkLen">, maxTokens: number, countTokens: (text: string) => Promise<number>, maxChars?: number): Promise<{
     text: string;
     position: number;
 }>;
@@ -63,6 +65,38 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         status?: MaintenanceStatus;
         limit?: number;
     }): import("./curation.js").MaintenanceTask[];
+    auditQuality(params: {
+        corpora: readonly string[];
+        apiKey: string;
+        timeoutMs: number;
+        minNoise: number;
+        limit?: number;
+        after?: QualityCursor;
+        signal: AbortSignal;
+    }): Promise<{
+        status: "ok" | "partial";
+        done: boolean;
+        next: QualityCursor | undefined;
+        scanned: number;
+        judged: number;
+        cached: number;
+        skippedOversized: number;
+        skippedStale: number;
+        flagged: number;
+        groups: {
+            corpus: string;
+            source: string;
+            reason: string;
+            pending: number;
+            examples: import("./curation.js").MaintenanceTask[];
+        }[];
+        policy: string;
+        scope: string;
+    } | {
+        status: "busy";
+    } | {
+        status: "unavailable";
+    }>;
     updateMaintenanceTask(params: {
         id: string;
         status: Exclude<MaintenanceStatus, "pending">;