@unblocklabs/unblock-memory 0.2.6 → 0.3.0

package/README.md

@@ -38,6 +38,10 @@ directories, or globs into named corpora:
     slots: { memory: "unblock-memory" },
     entries: {
       "unblock-memory": {
+        hooks: {
+          // Required only when skillWhisperer.enabled is true.
+          allowConversationAccess: true,
+        },
         config: {
           // Default: avoid repeated model cold starts after idle periods.
           keepEmbeddingModelWarm: true,
@@ -57,7 +61,24 @@ directories, or globs into named corpora:
               kind: "files",
               paths: ["knowledge/**/*.md"],
             },
+            {
+              name: "skills",
+              kind: "skills",
+              paths: [
+                "skills/**/SKILL.md",
+                ".agents/skills/**/SKILL.md",
+                "~/.agents/skills/**/SKILL.md",
+                "~/.openclaw/skills/**/SKILL.md",
+                "~/.openclaw/plugin-skills/**/SKILL.md",
+              ],
+            },
           ],
+          skillWhisperer: {
+            enabled: false,
+            historyMessages: 5,
+            minScore: 0.4,
+            cooldownTurns: 10,
+          },
           // Optional: omit unless the local analysis worker is installed.
           analysis: {
             executable: "/absolute/path/to/unblock-cluster/bin/unblock-memory-analysis",
@@ -79,11 +100,34 @@ corpus; other unique names may be added for custom material.
 context resident after first use. Set it to `false` to restore QMD's five-minute
 idle unload behavior.
 
-`memory_search` searches every configured corpus by default. Pass
+`memory_search` searches every configured non-skill corpus by default. Pass
 `corpora: ["knowledge"]` to search selected corpora or `corpora: ["all"]` to
 request all of them explicitly. Search results include their corpus name and
 remain readable by passing the returned `qmd://` path to `memory_get`.
 
+### Skill Whisperer
+
+Skill Whisperer is an optional semantic reminder for user turns. Configure one
+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, searches only skill files, and prepends at most one name/path hint
+when the best eligible match reaches `minScore`. It never opens or invokes a
+skill automatically.
+
+The defaults use five prior messages, a calibrated score threshold of `0.4`,
+and a ten-turn cooldown. A skill is cooling down after either a suggestion or a
+successful direct `read` of its indexed `SKILL.md`; the next result is eligible
+only when it independently meets the same score threshold. Cooldown state is
+per session and intentionally resets with the Gateway. Shell-command reads are
+not tracked.
+
+The `skills` corpus shares the existing QMD store and warm embedding model but
+is private to Skill Whisperer: it is excluded from ordinary `memory_search`
+(including `corpora: ["all"]`), `memory_get`, clustering, and memory-maintenance
+tasks. Paths are explicit by design; the plugin does not reconstruct
+OpenClaw's effective skill inventory from `openclaw.json`.
+
 Use `sessionFilter` to restrict session results by metadata while leaving file
 corpora searchable. Supported fields are `startedFrom` and `startedTo`
 (inclusive ISO 8601 timestamps), `provider`, `chatType`, `accountId`, and
@@ -122,9 +166,10 @@ does not sync sessions at startup or on a schedule; refreshes are manual through
 `memory_sync_sessions`.
 
 Indexes live at `~/.openclaw/agents/<agentId>/unblock-memory/index.sqlite` (or the
-equivalent configured OpenClaw state directory). The first lookup builds the
-index; Markdown filesystem changes queue a debounced, serialized background
-refresh.
+equivalent configured OpenClaw state directory). Durable agent-supplied event
+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 analysis
 
@@ -144,9 +189,10 @@ python3 -m venv .venv
 Set `analysis.executable` to the absolute path of
 `bin/unblock-memory-analysis` in that checkout. One worker installation can
 serve every agent on the host. The plugin invokes it directly with
-`--db <the agent's known index path>` and, when requested, a validated
-`--config-json <clustering options>` payload. Agents cannot choose a database,
-executable, shell command, or arbitrary arguments.
+`--db <the agent's known index path>`, the plugin's non-skill collection IDs,
+and, when requested, a validated `--config-json <clustering options>` payload.
+Agents cannot choose a database, executable, collection, shell command, or
+arbitrary arguments.
 
 Without the worker, `memory_list_clusters` reports that memory has not been
 analyzed and `memory_recluster` reports that analysis is unavailable. Ordinary
@@ -175,10 +221,24 @@ and a deterministic seed. Omitting them uses the worker's defaults.
 `memory_fetch_cluster` accepts `topK` (1–50), a zero-based `offset`, and
 `sort`: `representative` (the default), `score_desc`, `score_asc`, `date_desc`,
 or `date_asc`. Score is cluster membership probability for normal clusters and
-outlier score for noise. Each member includes `sourceDate`, the latest
-modification time among its active source aliases. For projected sessions that
-date is the session start time. Responses include page totals and the next
-offset when more members remain.
+outlier score for noise. Each member reports raw `sourceModifiedAt` separately
+from `eventTime` and `eventTimeBasis`. Session start times and dated memory paths
+resolve programmatically; reviewed annotations resolve otherwise ambiguous
+chunks or whole documents. Date sorting uses resolved event time when available
+and the clearly labeled source modification time only as a fallback. Responses
+include page totals and the next offset when more members remain.
+
+A chronological cluster read creates a coalesced maintenance proposal only for
+returned documents whose event time remains ambiguous; it does not scan the
+whole corpus for chores. Persisted exact-duplicate analysis can likewise create
+review proposals for non-session Markdown. `memory_list_maintenance_tasks`
+returns at most ten tasks, while `memory_update_maintenance_task` can resolve,
+defer, or mark one irrelevant and optionally attach a supported event date.
+For duplicate proposals, defer confirmed cleanup until the source change is
+complete, mark intentional repetition irrelevant, and resolve only completed
+work. These tools never edit or delete source Markdown. Duplicate cleanup
+remains a reviewed source change outside the maintenance tool, and generated
+session projections must never be edited directly.
 
 Member excerpts are capped at 2 KB each and 12 KB across a response; source
 aliases are capped at five per member and 50 across a response. These budgets

package/dist/src/analysis.d.ts

@@ -1,5 +1,8 @@
 import type { QMDStore } from "@unblocklabs/qmd";
 type AnalysisDatabase = QMDStore["internal"]["db"];
+export type TemporalReadOptions = {
+    sessionCollection?: string;
+};
 export type MemoryReclusterOptions = {
     space?: {
         method?: "umap" | "none";
@@ -19,6 +22,7 @@ export type MemoryReclusterOptions = {
 export type AnalysisRunner = (params: {
     executable: string;
     dbPath: string;
+    collections: readonly string[];
     options?: MemoryReclusterOptions;
     signal?: AbortSignal;
 }) => Promise<void>;
@@ -30,7 +34,11 @@ type MemoryAnalysisMember = {
     x: number;
     y: number;
     representativeRank: number | null;
-    sourceDate: string;
+    sourceModifiedAt: string;
+    eventTime: string | null;
+    eventTimeBasis: "path" | "frontmatter" | "session" | "agent_verified" | null;
+    eventTimeSource: string;
+    contentFingerprint: string;
     text: string;
     sourcePaths: string[];
 };
@@ -88,11 +96,13 @@ export declare function clusterReference(runId: string, clusterId: number): stri
 export declare function runAnalysisWorker(params: {
     executable: string;
     dbPath: string;
+    collections: readonly string[];
     options?: MemoryReclusterOptions;
     signal?: AbortSignal;
 }): Promise<void>;
 export declare function latestAnalysisRunId(db: AnalysisDatabase): string | undefined;
+export declare function latestAnalysisCollections(db: AnalysisDatabase): readonly string[] | undefined;
 export declare function readAnalysisSummary(db: AnalysisDatabase): MemoryAnalysisSummary | undefined;
 export declare function readClusters(db: AnalysisDatabase, requestedLimit?: number): MemoryClusterList;
-export declare function readCluster(db: AnalysisDatabase, clusterReferenceId: string, requestedLimit?: number, requestedOffset?: number, sort?: MemoryClusterSort): MemoryClusterDetail;
+export declare function readCluster(db: AnalysisDatabase, clusterReferenceId: string, requestedLimit?: number, requestedOffset?: number, sort?: MemoryClusterSort, temporal?: TemporalReadOptions): MemoryClusterDetail;
 export {};

package/dist/src/analysis.js

@@ -48,6 +48,17 @@ export function ensureMemoryAnalysisSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_memory_analysis_memberships_cluster
       ON memory_analysis_memberships(run_id, cluster_id, representative_rank);
 
+    CREATE TABLE IF NOT EXISTS memory_analysis_duplicate_occurrences (
+      run_id TEXT NOT NULL,
+      content_fingerprint TEXT NOT NULL,
+      canonical_hash TEXT NOT NULL,
+      canonical_seq INTEGER NOT NULL,
+      duplicate_hash TEXT NOT NULL,
+      duplicate_seq INTEGER NOT NULL,
+      PRIMARY KEY (run_id, duplicate_hash, duplicate_seq),
+      FOREIGN KEY (run_id) REFERENCES memory_analysis_runs(id) ON DELETE CASCADE
+    );
+
     CREATE VIEW IF NOT EXISTS memory_analysis_available_memberships AS
     SELECT
       m.run_id, m.hash, m.seq, m.cluster_id, m.probability, m.outlier_score,
@@ -61,6 +72,18 @@ export function ensureMemoryAnalysisSchema(db) {
       WHERE d.hash = m.hash AND d.active = 1
     );
   `);
+    db.exec(`
+    CREATE TEMP TABLE IF NOT EXISTS memory_temporal_annotations (
+      collection TEXT NOT NULL,
+      path TEXT NOT NULL,
+      qmd_hash TEXT,
+      qmd_seq INTEGER,
+      event_time TEXT NOT NULL,
+      basis TEXT NOT NULL,
+      document_wide INTEGER NOT NULL,
+      PRIMARY KEY (collection, path, qmd_hash, qmd_seq, document_wide)
+    );
+  `);
 }
 export function markMemoryAnalysisStale(db) {
     db.prepare(`
@@ -81,7 +104,7 @@ export function clusterReference(runId, clusterId) {
 export function runAnalysisWorker(params) {
     return new Promise((resolve, reject) => {
         params.signal?.throwIfAborted();
-        const args = ["--db", params.dbPath];
+        const args = ["--db", params.dbPath, "--collections-json", JSON.stringify(params.collections)];
         if (params.options && Object.keys(params.options).length > 0) {
             args.push("--config-json", JSON.stringify(params.options));
         }
@@ -147,6 +170,26 @@ function latestRun(db) {
 export function latestAnalysisRunId(db) {
     return latestRun(db)?.id;
 }
+export function latestAnalysisCollections(db) {
+    const row = db.prepare(`
+    SELECT params_json
+    FROM memory_analysis_runs
+    WHERE completed_at IS NOT NULL
+    ORDER BY completed_at DESC, created_at DESC, id DESC
+    LIMIT 1
+  `).get();
+    if (!row)
+        return undefined;
+    try {
+        const collections = JSON.parse(row.params_json).collections;
+        return Array.isArray(collections) && collections.every((value) => typeof value === "string")
+            ? collections
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function count(db, sql, runId) {
     return db.prepare(sql).get(runId)?.count ?? 0;
 }
@@ -208,7 +251,7 @@ function byteSlice(text, maxBytes) {
         return "";
     return bytes.subarray(0, maxBytes - 3).toString("utf8").replace(/\uFFFD$/u, "") + "…";
 }
-function members(db, runId, clusterId, limit, offset = 0, sort = "representative", maxExcerptBytes = MAX_EXCERPT_BYTES, maxTotalBytes = MAX_TOTAL_EXCERPT_BYTES, maxTotalAliases = MAX_TOTAL_ALIASES) {
+function members(db, runId, clusterId, limit, offset = 0, sort = "representative", maxExcerptBytes = MAX_EXCERPT_BYTES, maxTotalBytes = MAX_TOTAL_EXCERPT_BYTES, maxTotalAliases = MAX_TOTAL_ALIASES, temporal = {}) {
     const representativeOrder = clusterId === -1
         ? "m.outlier_score DESC, m.hash, m.seq"
         : `CASE WHEN m.representative_rank IS NULL THEN 1 ELSE 0 END,
@@ -222,32 +265,79 @@ function members(db, runId, clusterId, limit, offset = 0, sort = "representative
         representative: representativeOrder,
         score_desc: `${score} DESC, m.hash, m.seq`,
         score_asc: `${score} ASC, m.hash, m.seq`,
-        date_desc: "m.source_date DESC, m.hash, m.seq",
-        date_asc: "m.source_date ASC, m.hash, m.seq",
+        date_desc: "julianday(COALESCE(m.event_time, m.source_modified_at)) DESC, m.hash, m.seq",
+        date_asc: "julianday(COALESCE(m.event_time, m.source_modified_at)) ASC, m.hash, m.seq",
     }[sort];
     const rows = db.prepare(`
-    WITH member_rows AS (
+    WITH candidate_times AS (
+      SELECT
+        m.hash,
+        m.seq,
+        d.collection,
+        d.path,
+        d.modified_at AS source_modified_at,
+        CASE
+          WHEN d.collection = ? THEN d.modified_at
+          WHEN d.path GLOB '*[12][0-9][0-9][0-9]-[01][0-9]-[0-3][0-9].md'
+            THEN substr(d.path, length(d.path) - 12, 10) || 'T00:00:00.000Z'
+          ELSE annotation.event_time
+        END AS event_time,
+        CASE
+          WHEN d.collection = ? THEN 'session'
+          WHEN d.path GLOB '*[12][0-9][0-9][0-9]-[01][0-9]-[0-3][0-9].md' THEN 'path'
+          ELSE annotation.basis
+        END AS event_time_basis,
+        CASE
+          WHEN d.collection = ? THEN 1
+          WHEN d.path GLOB '*[12][0-9][0-9][0-9]-[01][0-9]-[0-3][0-9].md' THEN 2
+          WHEN annotation.event_time IS NOT NULL THEN 3
+          ELSE 4
+        END AS priority
+      FROM memory_analysis_available_memberships m
+      JOIN documents d ON d.hash = m.hash AND d.active = 1
+      LEFT JOIN memory_temporal_annotations annotation
+        ON annotation.collection = d.collection
+       AND annotation.path = d.path
+       AND (annotation.document_wide = 1 OR
+            (annotation.qmd_hash = m.hash AND annotation.qmd_seq = m.seq))
+      WHERE m.run_id = ? AND m.cluster_id = ?
+    ), ranked_times AS (
+      SELECT *, ROW_NUMBER() OVER (
+        PARTITION BY hash, seq
+        ORDER BY priority, julianday(COALESCE(event_time, source_modified_at)) DESC, collection, path
+      ) AS rank
+      FROM candidate_times
+    ), member_rows AS (
       SELECT
         m.hash, m.seq, m.probability, m.outlier_score, m.x, m.y,
         m.representative_rank, m.pos, m.chunk_len, m.doc,
         (
-          SELECT MAX(d.modified_at)
+          SELECT d.modified_at
           FROM documents d
           WHERE d.hash = m.hash AND d.active = 1
-        ) AS source_date
+          ORDER BY julianday(d.modified_at) DESC, d.collection, d.path
+          LIMIT 1
+        ) AS source_modified_at,
+        temporal.event_time,
+        temporal.event_time_basis,
+        temporal.collection AS event_collection,
+        temporal.path AS event_path
       FROM memory_analysis_available_memberships m
+      JOIN ranked_times temporal
+        ON temporal.hash = m.hash AND temporal.seq = m.seq AND temporal.rank = 1
       WHERE m.run_id = ? AND m.cluster_id = ?
     )
     SELECT * FROM member_rows m
     ORDER BY ${order}
     LIMIT ? OFFSET ?
-  `).all(runId, clusterId, limit, offset);
+  `).all(temporal.sessionCollection ?? "", temporal.sessionCollection ?? "", temporal.sessionCollection ?? "", runId, clusterId, runId, clusterId, limit, offset);
     let remaining = maxTotalBytes;
     let remainingAliases = maxTotalAliases;
     return rows.map((row, index) => {
         const remainingRows = rows.length - index;
         const excerptBudget = Math.min(maxExcerptBytes, Math.floor(remaining / remainingRows));
-        const text = byteSlice(row.doc.slice(row.pos, row.pos + row.chunk_len), excerptBudget);
+        const fullText = row.doc.slice(row.pos, row.pos + row.chunk_len);
+        const text = byteSlice(fullText, excerptBudget);
         remaining -= Buffer.byteLength(text);
         const aliasBudget = Math.min(MAX_ALIASES_PER_MEMBER, Math.floor(remainingAliases / remainingRows));
         const aliases = sourcePaths(db, row.hash, aliasBudget);
@@ -260,7 +350,11 @@ function members(db, runId, clusterId, limit, offset = 0, sort = "representative
             x: row.x,
             y: row.y,
             representativeRank: row.representative_rank,
-            sourceDate: row.source_date,
+            sourceModifiedAt: row.source_modified_at,
+            eventTime: row.event_time,
+            eventTimeBasis: row.event_time_basis,
+            eventTimeSource: `qmd://${row.event_collection}/${row.event_path}`,
+            contentFingerprint: createHash("sha256").update(fullText).digest("hex"),
             text,
             sourcePaths: aliases,
         };
@@ -380,7 +474,7 @@ function resolveClusterId(db, runId, reference) {
   `).all(runId, runId);
     return clusterIds.find((row) => clusterReference(runId, row.cluster_id) === reference)?.cluster_id;
 }
-export function readCluster(db, clusterReferenceId, requestedLimit = DEFAULT_MEMBER_LIMIT, requestedOffset = 0, sort = "representative") {
+export function readCluster(db, clusterReferenceId, requestedLimit = DEFAULT_MEMBER_LIMIT, requestedOffset = 0, sort = "representative", temporal = {}) {
     const run = latestValidRun(db);
     if (!run) {
         return { status: "not_analyzed", ...readMetadata() };
@@ -408,7 +502,7 @@ export function readCluster(db, clusterReferenceId, requestedLimit = DEFAULT_MEM
     const limit = Math.max(1, Math.min(MAX_MEMBER_LIMIT, Math.floor(requestedLimit)));
     const offset = Math.max(0, Math.floor(requestedOffset));
     const total = availableSize(db, run.id, clusterId);
-    const pageMembers = members(db, run.id, clusterId, limit, offset, sort);
+    const pageMembers = members(db, run.id, clusterId, limit, offset, sort, MAX_EXCERPT_BYTES, MAX_TOTAL_EXCERPT_BYTES, MAX_TOTAL_ALIASES, temporal);
     const nextOffset = offset + pageMembers.length;
     const hasMore = nextOffset < total;
     return {

package/dist/src/config.d.ts

@@ -3,6 +3,11 @@ export type FileCorpusConfig = {
     kind: "files";
     paths: readonly string[];
 };
+export type SkillCorpusConfig = {
+    name: "skills";
+    kind: "skills";
+    paths: readonly string[];
+};
 declare const CHAT_TYPES: readonly ["channel", "group", "direct"];
 export type ChatType = typeof CHAT_TYPES[number];
 type SessionCorpusConfig = {
@@ -10,7 +15,7 @@ type SessionCorpusConfig = {
     kind: "sessions";
     chatTypes: readonly ChatType[];
 };
-export type CorpusConfig = FileCorpusConfig | SessionCorpusConfig;
+export type CorpusConfig = FileCorpusConfig | SkillCorpusConfig | SessionCorpusConfig;
 export declare const DEFAULT_CORPORA: readonly FileCorpusConfig[];
 export type UnblockMemoryConfig = {
     corpora: readonly CorpusConfig[];
@@ -18,6 +23,12 @@ export type UnblockMemoryConfig = {
     analysis: {
         executable?: string;
     };
+    skillWhisperer: {
+        enabled: boolean;
+        historyMessages: number;
+        minScore: number;
+        cooldownTurns: number;
+    };
 };
 export declare function resolveConfig(value: unknown): UnblockMemoryConfig;
 export {};

package/dist/src/config.js

@@ -6,6 +6,12 @@ export const DEFAULT_CORPORA = [{
         kind: "files",
         paths: DEFAULT_PATHS,
     }];
+const DEFAULT_SKILL_WHISPERER = {
+    enabled: false,
+    historyMessages: 5,
+    minScore: 0.4,
+    cooldownTurns: 10,
+};
 function assertOnlyKeys(value, allowed, label) {
     const unknown = Object.keys(value).find((key) => !allowed.includes(key));
     if (unknown)
@@ -33,6 +39,17 @@ function resolveCorpora(value) {
         if (names.has(name))
             throw new Error(`unblock-memory corpus names must be unique: ${name}`);
         names.add(name);
+        if (corpus.kind === "skills") {
+            assertOnlyKeys(corpus, ["name", "kind", "paths"], `corpora[${index}]`);
+            if (name !== "skills") {
+                throw new Error('unblock-memory skills corpus must be named "skills"');
+            }
+            if (!Array.isArray(corpus.paths) || corpus.paths.length === 0 ||
+                !corpus.paths.every((path) => typeof path === "string" && path.trim())) {
+                throw new Error("unblock-memory corpus skills paths must be a non-empty array of non-empty strings");
+            }
+            return { name: "skills", kind: "skills", paths: corpus.paths.map((path) => path.trim()) };
+        }
         if (corpus.kind === "sessions") {
             assertOnlyKeys(corpus, ["name", "kind", "chatTypes"], `corpora[${index}]`);
             if (name !== "sessions") {
@@ -49,8 +66,11 @@ function resolveCorpora(value) {
         if (name === "sessions") {
             throw new Error('unblock-memory corpus named "sessions" must have kind "sessions"');
         }
+        if (name === "skills") {
+            throw new Error('unblock-memory corpus named "skills" must have kind "skills"');
+        }
         if (corpus.kind !== "files") {
-            throw new Error(`unblock-memory corpus ${name} must have kind "files" or "sessions"`);
+            throw new Error(`unblock-memory corpus ${name} must have kind "files", "skills", or "sessions"`);
         }
         if (!Array.isArray(corpus.paths) || corpus.paths.length === 0 ||
             !corpus.paths.every((path) => typeof path === "string" && path.trim())) {
@@ -65,30 +85,64 @@ function resolveCorpora(value) {
 }
 export function resolveConfig(value) {
     if (value === undefined || value === null) {
-        return { corpora: DEFAULT_CORPORA, keepEmbeddingModelWarm: true, analysis: {} };
+        return {
+            corpora: DEFAULT_CORPORA,
+            keepEmbeddingModelWarm: true,
+            analysis: {},
+            skillWhisperer: DEFAULT_SKILL_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"], "config");
+    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "skillWhisperer"], "config");
     const corpora = resolveCorpora(config.corpora);
     if (config.keepEmbeddingModelWarm !== undefined && typeof config.keepEmbeddingModelWarm !== "boolean") {
         throw new Error("unblock-memory keepEmbeddingModelWarm must be a boolean");
     }
     const keepEmbeddingModelWarm = config.keepEmbeddingModelWarm ?? true;
-    if (config.analysis === undefined)
-        return { corpora, keepEmbeddingModelWarm, analysis: {} };
-    if (!config.analysis || typeof config.analysis !== "object" || Array.isArray(config.analysis)) {
-        throw new Error("unblock-memory analysis must be an object");
+    let analysisConfig = {};
+    if (config.analysis !== undefined) {
+        if (!config.analysis || typeof config.analysis !== "object" || Array.isArray(config.analysis)) {
+            throw new Error("unblock-memory analysis must be an object");
+        }
+        const analysis = config.analysis;
+        assertOnlyKeys(analysis, ["executable"], "analysis");
+        const configured = analysis.executable;
+        if (configured !== undefined) {
+            if (typeof configured !== "string" || !configured.trim() || !isAbsolute(configured.trim())) {
+                throw new Error("unblock-memory analysis.executable must be an absolute non-empty path");
+            }
+            analysisConfig = { executable: configured.trim() };
+        }
+    }
+    let skillWhisperer = DEFAULT_SKILL_WHISPERER;
+    if (config.skillWhisperer !== undefined) {
+        if (!config.skillWhisperer || typeof config.skillWhisperer !== "object" || Array.isArray(config.skillWhisperer)) {
+            throw new Error("unblock-memory skillWhisperer must be an object");
+        }
+        const value = config.skillWhisperer;
+        assertOnlyKeys(value, ["enabled", "historyMessages", "minScore", "cooldownTurns"], "skillWhisperer");
+        const enabled = value.enabled ?? false;
+        const historyMessages = value.historyMessages ?? 5;
+        const minScore = value.minScore ?? 0.4;
+        const cooldownTurns = value.cooldownTurns ?? 10;
+        if (typeof enabled !== "boolean")
+            throw new Error("unblock-memory skillWhisperer.enabled must be a boolean");
+        if (typeof historyMessages !== "number" || !Number.isInteger(historyMessages) || historyMessages < 0) {
+            throw new Error("unblock-memory skillWhisperer.historyMessages must be a non-negative integer");
+        }
+        if (typeof minScore !== "number" || !Number.isFinite(minScore) || minScore < 0 || minScore > 1) {
+            throw new Error("unblock-memory skillWhisperer.minScore must be between 0 and 1");
+        }
+        if (typeof cooldownTurns !== "number" || !Number.isInteger(cooldownTurns) || cooldownTurns < 0) {
+            throw new Error("unblock-memory skillWhisperer.cooldownTurns must be a non-negative integer");
+        }
+        skillWhisperer = { enabled, historyMessages, minScore, cooldownTurns };
     }
-    const analysis = config.analysis;
-    assertOnlyKeys(analysis, ["executable"], "analysis");
-    const configured = analysis.executable;
-    if (configured === undefined)
-        return { corpora, keepEmbeddingModelWarm, analysis: {} };
-    if (typeof configured !== "string" || !configured.trim() || !isAbsolute(configured.trim())) {
-        throw new Error("unblock-memory analysis.executable must be an absolute non-empty path");
+    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: { executable: configured.trim() } };
+    return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, skillWhisperer };
 }

package/dist/src/curation.d.ts

@@ -0,0 +1,70 @@
+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"];
+export type MaintenanceTaskType = typeof MAINTENANCE_TASK_TYPES[number];
+declare const MAINTENANCE_STATUSES: readonly ["pending", "resolved", "deferred", "irrelevant"];
+export type MaintenanceStatus = typeof MAINTENANCE_STATUSES[number];
+export type TemporalAnnotation = {
+    corpus: string;
+    collection: string;
+    path: string;
+    contentFingerprint: string;
+    eventTime: string;
+    basis: TemporalBasis;
+    evidence: string;
+    qmdHash: string | null;
+    qmdSeq: number | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type MaintenanceTask = {
+    id: string;
+    type: MaintenanceTaskType;
+    corpus: string;
+    collection: string;
+    path: string;
+    reason: string;
+    contentFingerprint: string;
+    detail: string | null;
+    resolutionNote: string | null;
+    status: MaintenanceStatus;
+    createdAt: string;
+    updatedAt: string;
+};
+export declare function chunkFingerprint(text: string): string;
+export declare class CurationStore {
+    #private;
+    constructor(path: string);
+    close(): void;
+    annotations(): TemporalAnnotation[];
+    addTask(candidate: {
+        type: MaintenanceTaskType;
+        corpus: string;
+        collection: string;
+        path: string;
+        reason: string;
+        contentFingerprint?: string;
+        detail?: string;
+    }): void;
+    listTasks(params?: {
+        status?: MaintenanceStatus;
+        limit?: number;
+    }): MaintenanceTask[];
+    updateTask(params: {
+        id: string;
+        status: Exclude<MaintenanceStatus, "pending">;
+        note?: string;
+        annotation?: {
+            scope: "chunk" | "document";
+            eventTime: string;
+            basis: TemporalBasis;
+            evidence: string;
+        };
+    }): MaintenanceTask | undefined;
+    updateAnnotationLocation(params: {
+        annotation: TemporalAnnotation;
+        qmdHash: string | null;
+        qmdSeq: number | null;
+    }): void;
+}
+export {};