@unblocklabs/unblock-memory 0.2.6 → 0.3.0

package/dist/src/curation.js

@@ -0,0 +1,191 @@
+import { createHash, randomUUID } from "node:crypto";
+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_STATUSES = ["pending", "resolved", "deferred", "irrelevant"];
+function annotation(row) {
+    return {
+        corpus: row.corpus,
+        collection: row.collection,
+        path: row.path,
+        contentFingerprint: row.content_fingerprint,
+        eventTime: row.event_time,
+        basis: row.basis,
+        evidence: row.evidence,
+        qmdHash: row.qmd_hash,
+        qmdSeq: row.qmd_seq,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function task(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        corpus: row.corpus,
+        collection: row.collection,
+        path: row.path,
+        reason: row.reason,
+        contentFingerprint: row.content_fingerprint,
+        detail: row.detail,
+        resolutionNote: row.resolution_note,
+        status: row.status,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export function chunkFingerprint(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+export class CurationStore {
+    #db;
+    constructor(path) {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        this.#db = new DatabaseSync(path);
+        chmodSync(path, 0o600);
+        this.#db.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA busy_timeout = 5000;
+
+      CREATE TABLE IF NOT EXISTS temporal_annotations (
+        corpus TEXT NOT NULL,
+        collection TEXT NOT NULL,
+        path TEXT NOT NULL,
+        content_fingerprint TEXT NOT NULL DEFAULT '',
+        event_time TEXT NOT NULL,
+        basis TEXT NOT NULL CHECK (basis IN ('path', 'frontmatter', 'session', 'agent_verified')),
+        evidence TEXT NOT NULL,
+        qmd_hash TEXT,
+        qmd_seq INTEGER,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (corpus, collection, path, content_fingerprint)
+      );
+
+    `);
+        this.#ensureMaintenanceSchema();
+    }
+    #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')),
+        corpus TEXT NOT NULL,
+        collection TEXT NOT NULL,
+        path TEXT NOT NULL,
+        reason TEXT NOT NULL,
+        content_fingerprint TEXT NOT NULL,
+        detail TEXT,
+        resolution_note TEXT,
+        status TEXT NOT NULL CHECK (status IN ('pending', 'resolved', 'deferred', 'irrelevant')),
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE (type, corpus, collection, path, reason, content_fingerprint)
+      );
+    `);
+        this.#db.exec(`
+      CREATE INDEX IF NOT EXISTS maintenance_tasks_status_created
+        ON maintenance_tasks(status, created_at);
+    `);
+    }
+    close() {
+        this.#db.close();
+    }
+    annotations() {
+        return this.#db.prepare(`
+      SELECT * FROM temporal_annotations
+      ORDER BY collection, path, content_fingerprint
+    `).all().map((row) => annotation(row));
+    }
+    addTask(candidate) {
+        const now = new Date().toISOString();
+        this.#db.prepare(`
+      INSERT INTO maintenance_tasks
+        (id, type, corpus, collection, path, reason, content_fingerprint, detail, status, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)
+      ON CONFLICT(type, corpus, collection, path, reason, content_fingerprint) DO UPDATE SET
+        detail = CASE
+          WHEN maintenance_tasks.status = 'pending' THEN excluded.detail
+          ELSE maintenance_tasks.detail
+        END,
+        updated_at = CASE
+          WHEN maintenance_tasks.status = 'pending' THEN excluded.updated_at
+          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);
+    }
+    listTasks(params = {}) {
+        const status = params.status ?? "pending";
+        const limit = Math.max(1, Math.min(10, Math.floor(params.limit ?? 5)));
+        return this.#db.prepare(`
+      SELECT * FROM maintenance_tasks
+      WHERE status = ?
+      ORDER BY created_at, id
+      LIMIT ?
+    `).all(status, limit).map((row) => task(row));
+    }
+    updateTask(params) {
+        this.#db.exec("BEGIN IMMEDIATE");
+        try {
+            const row = this.#db.prepare("SELECT * FROM maintenance_tasks WHERE id = ?")
+                .get(params.id);
+            if (!row) {
+                this.#db.exec("COMMIT");
+                return undefined;
+            }
+            const now = new Date().toISOString();
+            if (row.type === "ambiguous_event_time" && params.status === "resolved" && !params.annotation) {
+                throw new Error("resolving an ambiguous event-time task requires a date annotation");
+            }
+            if (params.annotation) {
+                if (row.type !== "ambiguous_event_time") {
+                    throw new Error("date annotations can only resolve ambiguous event-time tasks");
+                }
+                if (params.status !== "resolved") {
+                    throw new Error("date annotations require resolved status");
+                }
+                if (!Number.isFinite(Date.parse(params.annotation.eventTime))) {
+                    throw new Error("date annotation eventTime must be an ISO 8601 timestamp");
+                }
+                const fingerprint = params.annotation.scope === "document" ? "" : row.content_fingerprint;
+                if (params.annotation.scope === "chunk" && !fingerprint) {
+                    throw new Error("chunk annotation requires a content fingerprint");
+                }
+                this.#db.prepare(`
+          INSERT INTO temporal_annotations
+            (corpus, collection, path, content_fingerprint, event_time, basis, evidence,
+             qmd_hash, qmd_seq, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?, ?)
+          ON CONFLICT(corpus, collection, path, content_fingerprint) DO UPDATE SET
+            event_time = excluded.event_time,
+            basis = excluded.basis,
+            evidence = excluded.evidence,
+            qmd_hash = NULL,
+            qmd_seq = NULL,
+            updated_at = excluded.updated_at
+        `).run(row.corpus, row.collection, row.path, fingerprint, params.annotation.eventTime, params.annotation.basis, params.annotation.evidence, now, now);
+            }
+            this.#db.prepare(`
+        UPDATE maintenance_tasks
+        SET status = ?, resolution_note = ?, updated_at = ?
+        WHERE id = ?
+      `).run(params.status, params.note ?? null, now, params.id);
+            const updated = task(this.#db.prepare("SELECT * FROM maintenance_tasks WHERE id = ?").get(params.id));
+            this.#db.exec("COMMIT");
+            return updated;
+        }
+        catch (error) {
+            this.#db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    updateAnnotationLocation(params) {
+        this.#db.prepare(`
+      UPDATE temporal_annotations
+      SET qmd_hash = ?, qmd_seq = ?
+      WHERE corpus = ? AND collection = ? AND path = ? AND content_fingerprint = ?
+    `).run(params.qmdHash, params.qmdSeq, params.annotation.corpus, params.annotation.collection, params.annotation.path, params.annotation.contentFingerprint);
+    }
+}

package/dist/src/manager.d.ts

@@ -2,6 +2,7 @@ import type { QMDStore } from "@unblocklabs/qmd";
 import { type AnalysisRunner, type MemoryAnalysisSummary, type MemoryClusterDetail, type MemoryClusterList, type MemoryClusterSort, type MemoryReclusterOptions } from "./analysis.js";
 import type { CorpusMemorySearchResult, CorpusSearchOptions, MemoryEmbeddingProbeResult, MemoryProviderStatus, MemoryReadResult, MemorySearchManagerContract, MemorySyncParams } from "./contracts.js";
 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";
 export type ManagerStore = Pick<QMDStore, "update" | "embed" | "getStatus" | "listCollections" | "searchLex" | "vsearch" | "get" | "getDocumentBody" | "close">;
@@ -15,6 +16,11 @@ export type ManagerSessionConfig = {
     outputDir: string;
     timezone: string;
 };
+export type SkillSearchCandidate = {
+    name: string;
+    path: string;
+    score: number;
+};
 export declare function enableSecureDelete(store: QMDStore): void;
 export declare function cleanupRemovedDocuments(store: QMDStore, changedDocuments?: number): number;
 export declare function pruneStaleCollections(store: QMDStore, configuredCollections: ReadonlySet<string>): Promise<number>;
@@ -28,6 +34,7 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
     #private;
     constructor(params: {
         dbPath: string;
+        curationPath?: string;
         workspaceDir: string;
         sources: readonly ResolvedSource[];
         storeFactory?: () => Promise<ManagerStore>;
@@ -47,7 +54,23 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         offset?: number;
         sort?: MemoryClusterSort;
     }): Promise<MemoryClusterDetail>;
+    listMaintenanceTasks(params?: {
+        status?: MaintenanceStatus;
+        limit?: number;
+    }): import("./curation.js").MaintenanceTask[];
+    updateMaintenanceTask(params: {
+        id: string;
+        status: Exclude<MaintenanceStatus, "pending">;
+        note?: string;
+        annotation?: {
+            scope: "chunk" | "document";
+            eventTime: string;
+            basis: TemporalBasis;
+            evidence: string;
+        };
+    }): import("./curation.js").MaintenanceTask | undefined;
     search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
+    searchSkills(query: string, minScore: number, limit: number): Promise<SkillSearchCandidate[]>;
     readFile(params: {
         relPath: string;
         from?: number;

package/dist/src/manager.js

@@ -1,13 +1,24 @@
+import { realpathSync } from "node:fs";
 import { mkdir, stat } from "node:fs/promises";
-import { dirname } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import chokidar from "chokidar";
-import { ensureMemoryAnalysisSchema, latestAnalysisRunId, markMemoryAnalysisStale, readAnalysisSummary, readCluster, readClusters, runAnalysisWorker, } from "./analysis.js";
+import { ensureMemoryAnalysisSchema, latestAnalysisCollections, latestAnalysisRunId, markMemoryAnalysisStale, readAnalysisSummary, readCluster, readClusters, runAnalysisWorker, } from "./analysis.js";
+import { CurationStore, chunkFingerprint, } from "./curation.js";
 import { readSessionManifest, sessionMetadataByPath, syncSessionProjections, } from "./session-sync.js";
 import { parseSafeVirtualPath } from "./sources.js";
 const DEFAULT_READ_LINES = 120;
 const MAX_READ_CHARS = 12_000;
 const WATCH_DEBOUNCE_MS = 250;
 const qmdModule = import("@unblocklabs/qmd");
+function markStaleForAnalysisCollectionChange(db, collections, hasSkills) {
+    const current = collections.toSorted();
+    const previous = latestAnalysisCollections(db)?.toSorted();
+    if (previous
+        ? previous.join("\0") !== current.join("\0")
+        : hasSkills && latestAnalysisRunId(db) !== undefined) {
+        markMemoryAnalysisStale(db);
+    }
+}
 function completedEmbeddingCount(result) {
     if (result.errors > 0) {
         throw new Error(`QMD failed to embed ${result.errors} chunk${result.errors === 1 ? "" : "s"}`);
@@ -135,6 +146,7 @@ function sessionAllowedPaths(metadataByPath, collection, filter) {
 export class QmdMemoryManager {
     #dbPath;
     #workspaceDir;
+    #curationPath;
     #sources;
     #storeFactory;
     #keepModelsWarm;
@@ -142,6 +154,7 @@ export class QmdMemoryManager {
     #analysisRunner;
     #sessions;
     #store;
+    #curation;
     #cleanupRemovedDocuments;
     #operationChain;
     #watcher;
@@ -155,6 +168,7 @@ export class QmdMemoryManager {
     #sessionManifestMtimeNs;
     constructor(params) {
         this.#dbPath = params.dbPath;
+        this.#curationPath = params.curationPath ?? `${params.dbPath}.curation.sqlite`;
         this.#workspaceDir = params.workspaceDir;
         this.#sources = new Map(params.sources.map((source) => [source.collection, source]));
         this.#storeFactory = params.storeFactory;
@@ -200,7 +214,7 @@ export class QmdMemoryManager {
     }
     #startWatcher() {
         const paths = [...new Set([...this.#sources.values()]
-                .filter((source) => source.kind === "files")
+                .filter((source) => source.kind !== "sessions")
                 .map((source) => source.watchPath))];
         if (paths.length === 0 || this.#watcher)
             return;
@@ -235,8 +249,10 @@ export class QmdMemoryManager {
         if (this.#storeFactory) {
             this.#store = await this.#storeFactory();
             const store = this.#store;
-            if (store.internal)
+            if (store.internal) {
                 ensureMemoryAnalysisSchema(store.internal.db);
+                markStaleForAnalysisCollectionChange(store.internal.db, this.#analysisCollectionNames(), this.#skillCollectionNames().length > 0);
+            }
             return this.#store;
         }
         const { createStore } = await qmdModule;
@@ -252,8 +268,26 @@ export class QmdMemoryManager {
         });
         enableSecureDelete(store);
         ensureMemoryAnalysisSchema(store.internal.db);
-        const prunedDocuments = await pruneStaleCollections(store, new Set(this.#collectionNames()));
-        if (prunedDocuments > 0)
+        markStaleForAnalysisCollectionChange(store.internal.db, this.#analysisCollectionNames(), this.#skillCollectionNames().length > 0);
+        const configuredCollections = new Set(this.#allCollectionNames());
+        const staleCollections = (await store.getStatus()).collections
+            .map((collection) => collection.name)
+            .filter((collection) => !configuredCollections.has(collection));
+        const appearsInAnalysis = store.internal.db.prepare(`
+      SELECT 1
+      FROM memory_analysis_memberships membership
+      JOIN documents document ON document.hash = membership.hash
+      WHERE membership.run_id = (
+        SELECT id FROM memory_analysis_runs
+        WHERE completed_at IS NOT NULL
+        ORDER BY completed_at DESC, created_at DESC, id DESC
+        LIMIT 1
+      ) AND document.collection = ?
+      LIMIT 1
+    `);
+        const prunedAnalysisInput = staleCollections.some((collection) => appearsInAnalysis.get(collection));
+        const prunedDocuments = await pruneStaleCollections(store, configuredCollections);
+        if (prunedDocuments > 0 && prunedAnalysisInput)
             markMemoryAnalysisStale(store.internal.db);
         try {
             await ensureSemanticChunking(store);
@@ -268,22 +302,36 @@ export class QmdMemoryManager {
         this.#store = store;
         return store;
     }
+    #allCollectionNames() {
+        return [...this.#sources.keys()];
+    }
+    #analysisCollectionNames() {
+        return [...this.#sources.values()]
+            .filter((source) => source.kind !== "skills")
+            .map((source) => source.collection);
+    }
+    #skillCollectionNames() {
+        return [...this.#sources.values()]
+            .filter((source) => source.kind === "skills")
+            .map((source) => source.collection);
+    }
     #collectionNames(corpora) {
+        const publicSources = [...this.#sources.values()].filter((source) => source.kind !== "skills");
         if (corpora === undefined)
-            return [...this.#sources.keys()];
+            return publicSources.map((source) => source.collection);
         if (corpora.length === 0)
             throw new Error("memory_search corpora must not be empty");
         const selected = new Set(corpora);
         if (selected.has("all")) {
             if (selected.size > 1)
                 throw new Error('memory_search corpus "all" must be used alone');
-            return [...this.#sources.keys()];
+            return publicSources.map((source) => source.collection);
         }
-        const known = new Set([...this.#sources.values()].map((source) => source.corpus));
+        const known = new Set(publicSources.map((source) => source.corpus));
         const unknown = [...selected].find((corpus) => !known.has(corpus));
         if (unknown)
             throw new Error(`memory_search unknown corpus: ${unknown}`);
-        return [...this.#sources.values()]
+        return publicSources
             .filter((source) => selected.has(source.corpus))
             .map((source) => source.collection);
     }
@@ -291,29 +339,39 @@ export class QmdMemoryManager {
         const run = async () => {
             const store = await this.#getStore();
             this.#dirty = true;
-            const collections = [...this.#sources.values()]
-                .filter((source) => source.kind === "files")
-                .map((source) => source.collection);
-            const update = await store.update({ collections });
-            this.#cleanupRemovedDocuments?.(update.updated + update.removed);
             const analysisStore = store;
-            const invalidatesAnalysis = update.indexed + update.updated + update.removed > 0 ||
-                update.needsEmbedding > 0 ||
-                params?.force === true;
-            if (invalidatesAnalysis && analysisStore.internal) {
+            const collections = [...this.#sources.values()].filter((source) => source.kind !== "sessions");
+            let analysisMarkedStale = false;
+            const markAnalysisStale = () => {
+                if (analysisMarkedStale || !analysisStore.internal)
+                    return;
                 markMemoryAnalysisStale(analysisStore.internal.db);
+                analysisMarkedStale = true;
+            };
+            if (collections.length === 0) {
+                const update = await store.update({ collections: [] });
+                this.#cleanupRemovedDocuments?.(update.updated + update.removed);
+                if (update.indexed + update.updated + update.removed > 0 ||
+                    update.needsEmbedding > 0 || params?.force === true) {
+                    markAnalysisStale();
+                }
+                const embed = await store.embed({ force: params?.force, chunkStrategy: "semantic" });
+                if (completedEmbeddingCount(embed) > 0)
+                    markAnalysisStale();
             }
-            let chunksEmbedded = 0;
-            for (const collection of collections.length > 0 ? collections : [undefined]) {
+            for (const source of collections) {
+                const update = await store.update({ collections: [source.collection] });
+                this.#cleanupRemovedDocuments?.(update.updated + update.removed);
+                const changed = update.indexed + update.updated + update.removed > 0 || update.needsEmbedding > 0;
+                if (source.kind !== "skills" && (changed || params?.force === true))
+                    markAnalysisStale();
                 const embed = await store.embed({
-                    ...(collection ? { collection } : {}),
+                    collection: source.collection,
                     force: params?.force,
                     chunkStrategy: "semantic",
                 });
-                chunksEmbedded += completedEmbeddingCount(embed);
-            }
-            if (!invalidatesAnalysis && chunksEmbedded > 0 && analysisStore.internal) {
-                markMemoryAnalysisStale(analysisStore.internal.db);
+                if (source.kind !== "skills" && completedEmbeddingCount(embed) > 0)
+                    markAnalysisStale();
             }
             const status = await store.getStatus();
             const indexedCollections = await store.listCollections();
@@ -377,6 +435,7 @@ export class QmdMemoryManager {
             await this.#analysisRunner({
                 executable: this.#analysisExecutable,
                 dbPath: this.#dbPath,
+                collections: this.#analysisCollectionNames(),
                 options,
                 signal,
             });
@@ -391,7 +450,126 @@ export class QmdMemoryManager {
         return this.#enqueue(async () => readClusters((await this.#getAnalysisStore()).internal.db, limit));
     }
     fetchCluster(params) {
-        return this.#enqueue(async () => readCluster((await this.#getAnalysisStore()).internal.db, params.clusterId, params.topK, params.offset, params.sort));
+        return this.#enqueue(async () => {
+            const db = (await this.#getAnalysisStore()).internal.db;
+            this.#loadTemporalAnnotations(db);
+            const detail = readCluster(db, params.clusterId, params.topK, params.offset, params.sort, { sessionCollection: this.#sessions?.collection });
+            if (params.sort === "date_asc" || params.sort === "date_desc") {
+                for (const member of detail.members ?? []) {
+                    if (member.eventTime !== null)
+                        continue;
+                    const safe = parseSafeVirtualPath(member.eventTimeSource, this.#sources);
+                    if (!safe)
+                        continue;
+                    this.#getCuration().addTask({
+                        type: "ambiguous_event_time",
+                        corpus: safe.source.corpus,
+                        collection: safe.source.collection,
+                        path: safe.relativePath,
+                        reason: "cluster chronology has no reliable event time",
+                        contentFingerprint: member.contentFingerprint,
+                        detail: "Inspect the document and relevant evidence; annotate a date only when one can be supported.",
+                    });
+                }
+            }
+            if (detail.runId && detail.members) {
+                this.#addDuplicateTasks(db, detail.runId, detail.members);
+            }
+            return detail;
+        });
+    }
+    listMaintenanceTasks(params = {}) {
+        return this.#getCuration().listTasks(params);
+    }
+    updateMaintenanceTask(params) {
+        return this.#getCuration().updateTask(params);
+    }
+    #getCuration() {
+        this.#curation ??= new CurationStore(this.#curationPath);
+        return this.#curation;
+    }
+    #loadTemporalAnnotations(db) {
+        db.exec("DELETE FROM memory_temporal_annotations");
+        const findChunks = db.prepare(`
+      SELECT d.hash, vectors.seq, vectors.pos, vectors.chunk_len, content.doc
+      FROM documents d
+      JOIN content ON content.hash = d.hash
+      JOIN content_vectors vectors ON vectors.hash = d.hash
+      WHERE d.collection = ? AND d.path = ? AND d.active = 1
+      ORDER BY vectors.seq
+    `);
+        const insert = db.prepare(`
+      INSERT OR REPLACE INTO memory_temporal_annotations
+        (collection, path, qmd_hash, qmd_seq, event_time, basis, document_wide)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+        const curation = this.#getCuration();
+        for (const annotation of curation.annotations()) {
+            if (!annotation.contentFingerprint) {
+                insert.run(annotation.collection, annotation.path, null, null, annotation.eventTime, annotation.basis, 1);
+                continue;
+            }
+            const rows = findChunks.all(annotation.collection, annotation.path);
+            const matched = rows.find((row) => chunkFingerprint(row.doc.slice(row.pos, row.pos + row.chunk_len)) === annotation.contentFingerprint);
+            curation.updateAnnotationLocation({
+                annotation,
+                qmdHash: matched?.hash ?? null,
+                qmdSeq: matched?.seq ?? null,
+            });
+            if (matched) {
+                insert.run(annotation.collection, annotation.path, matched.hash, matched.seq, annotation.eventTime, annotation.basis, 0);
+            }
+        }
+    }
+    #addDuplicateTasks(db, runId, members) {
+        if (members.length === 0)
+            return;
+        const pageMatch = members.map(() => "(duplicates.canonical_hash = ? AND duplicates.canonical_seq = ?) OR " +
+            "(duplicates.duplicate_hash = ? AND duplicates.duplicate_seq = ?)").join(" OR ");
+        const pageParams = members.flatMap((member) => [member.hash, member.seq, member.hash, member.seq]);
+        const sessionCollections = [...this.#sources.values()]
+            .filter((source) => source.kind === "sessions")
+            .map((source) => source.collection);
+        const excludeSessions = sessionCollections.length > 0
+            ? `duplicate_document.collection NOT IN (${sessionCollections.map(() => "?").join(", ")})`
+            : "1 = 1";
+        const rows = db.prepare(`
+      SELECT
+        duplicate_document.collection,
+        duplicate_document.path,
+        duplicates.content_fingerprint,
+        COUNT(*) AS occurrence_count
+      FROM memory_analysis_duplicate_occurrences duplicates
+      JOIN (SELECT DISTINCT hash FROM documents WHERE active = 1) canonical_document
+        ON canonical_document.hash = duplicates.canonical_hash
+      JOIN documents duplicate_document
+        ON duplicate_document.hash = duplicates.duplicate_hash
+       AND duplicate_document.active = 1
+      WHERE duplicates.run_id = ?
+        AND (${pageMatch})
+        AND ${excludeSessions}
+      GROUP BY duplicate_document.collection, duplicate_document.path,
+               duplicates.content_fingerprint
+      ORDER BY duplicate_document.collection, duplicate_document.path,
+               duplicates.content_fingerprint
+      LIMIT 10
+    `).all(runId, ...pageParams, ...sessionCollections);
+        const curation = this.#getCuration();
+        for (const row of rows) {
+            const source = this.#sources.get(row.collection);
+            if (!source || source.kind === "sessions")
+                continue;
+            curation.addTask({
+                type: "exact_duplicate",
+                corpus: source.corpus,
+                collection: row.collection,
+                path: row.path,
+                reason: "exact chunk content repeats in this source document",
+                contentFingerprint: row.content_fingerprint,
+                detail: `${row.occurrence_count} exact duplicate occurrence${row.occurrence_count === 1 ? "" : "s"}. ` +
+                    "Review the source and propose cleanup only if repetition is accidental.",
+            });
+        }
     }
     async #getAnalysisStore() {
         const store = await this.#getStore();
@@ -466,10 +644,54 @@ export class QmdMemoryManager {
                 }];
         });
     }
+    async searchSkills(query, minScore, limit) {
+        const collections = this.#skillCollectionNames();
+        if (collections.length === 0)
+            return [];
+        await this.#operationChain;
+        const hits = await (await this.#getStore()).vsearch(query, {
+            collection: collections,
+            limit,
+            minScore,
+            expand: false,
+        });
+        const sourceOrder = new Map([...this.#sources.keys()].map((collection, index) => [collection, index]));
+        const candidates = new Map();
+        for (const hit of hits) {
+            const safe = parseSafeVirtualPath(hit.file, this.#sources);
+            if (!safe || safe.source.kind !== "skills")
+                continue;
+            const path = realpathSync(resolve(safe.source.root, safe.relativePath));
+            if (basename(path).toLowerCase() !== "skill.md")
+                continue;
+            const frontmatter = /^---\s*\n([\s\S]*?)\n---(?:\n|$)/u.exec(hit.body)?.[1];
+            const configuredName = frontmatter?.split("\n")
+                .map((line) => /^name:\s*(.+?)\s*$/u.exec(line)?.[1])
+                .find((name) => name !== undefined)
+                ?.replace(/^(?:"(.*)"|'(.*)')$/u, "$1$2");
+            const candidate = {
+                name: configuredName?.trim() || basename(dirname(path)),
+                path,
+                score: hit.score,
+            };
+            const key = candidate.name.toLowerCase();
+            const order = sourceOrder.get(safe.source.collection) ?? Number.MAX_SAFE_INTEGER;
+            const current = candidates.get(key);
+            if (!current || order < current.sourceOrder ||
+                (order === current.sourceOrder && candidate.score > current.candidate.score)) {
+                candidates.set(key, { candidate, sourceOrder: order });
+            }
+        }
+        return [...candidates.values()]
+            .map(({ candidate }) => candidate)
+            .sort((left, right) => right.score - left.score)
+            .slice(0, limit);
+    }
     async readFile(params) {
         const safe = parseSafeVirtualPath(params.relPath, this.#sources);
-        if (!safe)
+        if (!safe || safe.source.kind === "skills") {
             return { status: "not_found", text: "", path: params.relPath };
+        }
         await this.#operationChain;
         const store = await this.#getStore();
         const doc = await store.get(safe.normalized);
@@ -505,7 +727,11 @@ export class QmdMemoryManager {
             custom: {
                 corpora: [...corpora].map(([name, sources]) => sources[0]?.kind === "sessions"
                     ? { name, kind: "sessions", chatTypes: sources[0].chatTypes }
-                    : { name, kind: "files", paths: sources.map((source) => source.configuredPath) }),
+                    : {
+                        name,
+                        kind: sources[0]?.kind === "skills" ? "skills" : "files",
+                        paths: sources.map((source) => source.configuredPath),
+                    }),
                 ...(this.#watchError ? { watchError: this.#watchError } : {}),
             },
         };
@@ -529,5 +755,7 @@ export class QmdMemoryManager {
         await this.#operationChain?.catch(() => undefined);
         await this.#store?.close();
         this.#store = undefined;
+        this.#curation?.close();
+        this.#curation = undefined;
     }
 }