@unblocklabs/unblock-memory 0.3.11 → 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.
@@ -254,9 +349,20 @@ role-labeled, timestamped speaker messages; filtering metadata remains in the
 session manifest. The projected file modification time matches the session
 start time for meaningful chronological cluster reads. Session results include
 provider, chat type, conversation identity, and start time as an ISO 8601 timestamp. They
-participate in the same search and clustering index as file memory. This phase
-does not sync sessions at startup or on a schedule; refreshes are manual through
-`memory_sync_sessions`.
+participate in the same search and clustering index as file memory. The plugin
+automatically refreshes each configured agent's sessions every 15 minutes while
+the Gateway runs. Set `syncIntervalMinutes` on the `sessions` corpus to an integer
+from `1` to `1440`, or `0` for manual-only syncing. For example:
+
+```json
+{ "name": "sessions", "kind": "sessions", "syncIntervalMinutes": 15 }
+```
+
+The first refresh runs after one interval, not during startup. Restart the
+Gateway after changing the interval. Refreshes are incremental; an already-running
+sync is skipped, and failures are visible through `memory_sync_status` and retried
+at the next interval. `memory_sync_sessions` still provides an immediate manual
+refresh. Syncing and embedding run inside the Gateway process, without an LLM turn.
 
 Indexes live at `~/.openclaw/agents/<agentId>/unblock-memory/index.sqlite` (or the
 equivalent configured OpenClaw state directory). Durable agent-supplied event
@@ -264,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

@@ -15,6 +15,7 @@ type SessionCorpusConfig = {
     kind: "sessions";
     chatTypes: readonly ChatType[];
     maxExpandedTokens: number;
+    syncIntervalMinutes: number;
 };
 export type CorpusConfig = FileCorpusConfig | SkillCorpusConfig | SessionCorpusConfig;
 export declare const DEFAULT_CORPORA: readonly FileCorpusConfig[];
@@ -24,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: {
@@ -40,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)
@@ -61,7 +157,7 @@ function resolveCorpora(value) {
             return { name: "skills", kind: "skills", paths: corpus.paths.map((path) => path.trim()) };
         }
         if (corpus.kind === "sessions") {
-            assertOnlyKeys(corpus, ["name", "kind", "chatTypes", "maxExpandedTokens"], `corpora[${index}]`);
+            assertOnlyKeys(corpus, ["name", "kind", "chatTypes", "maxExpandedTokens", "syncIntervalMinutes"], `corpora[${index}]`);
             if (name !== "sessions") {
                 throw new Error('unblock-memory session corpus must be named "sessions"');
             }
@@ -71,8 +167,14 @@ function resolveCorpora(value) {
                 !chatTypes.every((chatType) => CHAT_TYPES.includes(chatType))) {
                 throw new Error(`unblock-memory corpus sessions chatTypes must contain channel, group, or direct`);
             }
+            const syncIntervalMinutes = corpus.syncIntervalMinutes ?? 15;
+            if (typeof syncIntervalMinutes !== "number" || !Number.isInteger(syncIntervalMinutes) ||
+                syncIntervalMinutes < 0 || syncIntervalMinutes > 1440) {
+                throw new Error("unblock-memory corpus sessions syncIntervalMinutes must be an integer between 0 and 1440");
+            }
             return {
                 name: "sessions",
+                syncIntervalMinutes,
                 kind: "sessions",
                 chatTypes: [...new Set(chatTypes)],
                 maxExpandedTokens: positiveInteger(corpus.maxExpandedTokens, DEFAULT_SESSION_MAX_EXPANDED_TOKENS, "corpus sessions maxExpandedTokens", MAX_SESSION_MAX_EXPANDED_TOKENS),
@@ -154,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 &&
@@ -221,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">;