@unblocklabs/unblock-memory 0.2.6 → 0.2.7

package/README.md

@@ -122,9 +122,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
 
@@ -175,10 +176,22 @@ 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.
+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";
@@ -30,7 +33,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[];
 };
@@ -94,5 +101,5 @@ export declare function runAnalysisWorker(params: {
 export declare function latestAnalysisRunId(db: AnalysisDatabase): 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(`
@@ -208,7 +231,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 +245,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 +330,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 +454,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 +482,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/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 {};

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">;
@@ -28,6 +29,7 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
     #private;
     constructor(params: {
         dbPath: string;
+        curationPath?: string;
         workspaceDir: string;
         sources: readonly ResolvedSource[];
         storeFactory?: () => Promise<ManagerStore>;
@@ -47,6 +49,21 @@ 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[]>;
     readFile(params: {
         relPath: string;

package/dist/src/manager.js

@@ -2,6 +2,7 @@ import { mkdir, stat } from "node:fs/promises";
 import { dirname } from "node:path";
 import chokidar from "chokidar";
 import { ensureMemoryAnalysisSchema, 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;
@@ -135,6 +136,7 @@ function sessionAllowedPaths(metadataByPath, collection, filter) {
 export class QmdMemoryManager {
     #dbPath;
     #workspaceDir;
+    #curationPath;
     #sources;
     #storeFactory;
     #keepModelsWarm;
@@ -142,6 +144,7 @@ export class QmdMemoryManager {
     #analysisRunner;
     #sessions;
     #store;
+    #curation;
     #cleanupRemovedDocuments;
     #operationChain;
     #watcher;
@@ -155,6 +158,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;
@@ -391,7 +395,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();
@@ -529,5 +652,7 @@ export class QmdMemoryManager {
         await this.#operationChain?.catch(() => undefined);
         await this.#store?.close();
         this.#store = undefined;
+        this.#curation?.close();
+        this.#curation = undefined;
     }
 }

package/dist/src/plugin.js

@@ -219,6 +219,81 @@ function createFetchClusterTool(runtime, ctx) {
         },
     };
 }
+const maintenanceStatus = Type.Union([
+    Type.Literal("pending"),
+    Type.Literal("resolved"),
+    Type.Literal("deferred"),
+    Type.Literal("irrelevant"),
+]);
+const listMaintenanceParameters = Type.Object({
+    status: Type.Optional(maintenanceStatus),
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
+}, { additionalProperties: false });
+function createListMaintenanceTool(runtime, ctx) {
+    const active = getContext(ctx);
+    if (!active)
+        return null;
+    return {
+        name: "memory_list_maintenance_tasks",
+        label: "List Memory Maintenance Tasks",
+        description: "List a bounded curation inbox of memory chronology and duplicate-review proposals.",
+        parameters: listMaintenanceParameters,
+        async execute(_toolCallId, params) {
+            const options = Value.Parse(listMaintenanceParameters, params);
+            const { manager, error } = await runtime.getMemorySearchManager(active);
+            if (!manager)
+                return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });
+            return jsonResult({ status: "ok", tasks: manager.listMaintenanceTasks(options) });
+        },
+    };
+}
+const isoTimestamp = Type.String({
+    pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?(?:Z|[+-]\\d{2}:\\d{2})$",
+});
+const updateMaintenanceParameters = Type.Object({
+    taskId: Type.String({ pattern: "\\S" }),
+    action: Type.Union([
+        Type.Literal("resolve"),
+        Type.Literal("defer"),
+        Type.Literal("irrelevant"),
+    ]),
+    note: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+    annotation: Type.Optional(Type.Object({
+        scope: Type.Optional(Type.Union([Type.Literal("chunk"), Type.Literal("document")])),
+        eventTime: isoTimestamp,
+        basis: Type.Union([
+            Type.Literal("path"),
+            Type.Literal("frontmatter"),
+            Type.Literal("session"),
+            Type.Literal("agent_verified"),
+        ]),
+        evidence: Type.String({ minLength: 1, maxLength: 500 }),
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
+function createUpdateMaintenanceTool(runtime, ctx) {
+    const active = getContext(ctx);
+    if (!active)
+        return null;
+    return {
+        name: "memory_update_maintenance_task",
+        label: "Update Memory Maintenance Task",
+        description: "Resolve, defer, or dismiss a memory-maintenance proposal. This tool never edits source Markdown.",
+        parameters: updateMaintenanceParameters,
+        async execute(_toolCallId, params) {
+            const { taskId, action, note, annotation } = Value.Parse(updateMaintenanceParameters, params);
+            const { manager, error } = await runtime.getMemorySearchManager(active);
+            if (!manager)
+                return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });
+            const updated = manager.updateMaintenanceTask({
+                id: taskId,
+                status: action === "resolve" ? "resolved" : action === "defer" ? "deferred" : "irrelevant",
+                note,
+                ...(annotation ? { annotation: { ...annotation, scope: annotation.scope ?? "chunk" } } : {}),
+            });
+            return jsonResult(updated ? { status: "ok", task: updated } : { status: "not_found" });
+        },
+    };
+}
 function formatDateInTimezone(timestamp, timezone) {
     const parts = new Intl.DateTimeFormat("en-US", {
         timeZone: timezone,
@@ -312,4 +387,6 @@ export function registerUnblockMemory(api) {
     api.registerTool((ctx) => createReclusterTool(runtime, ctx), { names: ["memory_recluster"] });
     api.registerTool((ctx) => createListClustersTool(runtime, ctx), { names: ["memory_list_clusters"] });
     api.registerTool((ctx) => createFetchClusterTool(runtime, ctx), { names: ["memory_fetch_cluster"] });
+    api.registerTool((ctx) => createListMaintenanceTool(runtime, ctx), { names: ["memory_list_maintenance_tasks"] });
+    api.registerTool((ctx) => createUpdateMaintenanceTool(runtime, ctx), { names: ["memory_update_maintenance_task"] });
 }

package/dist/src/runtime.js

@@ -204,6 +204,7 @@ export class QmdMemoryRuntime {
         const manager = new QmdMemoryManager({
             workspaceDir,
             dbPath: join(stateDir, "index.sqlite"),
+            curationPath: join(stateDir, "curation.sqlite"),
             sources,
             keepModelsWarm: this.#keepEmbeddingModelWarm,
             analysisExecutable: this.#analysisExecutable,

package/openclaw.plugin.json

@@ -1,18 +1,20 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },
   "skills": ["./skills"],
-  "contracts": { "tools": ["memory_search", "memory_get", "memory_sync_sessions", "memory_sync_status", "memory_recluster", "memory_list_clusters", "memory_fetch_cluster"] },
+  "contracts": { "tools": ["memory_search", "memory_get", "memory_sync_sessions", "memory_sync_status", "memory_recluster", "memory_list_clusters", "memory_fetch_cluster", "memory_list_maintenance_tasks", "memory_update_maintenance_task"] },
   "toolMetadata": {
     "memory_sync_sessions": { "sideEffecting": true },
     "memory_sync_status": { "replaySafe": true },
     "memory_recluster": { "sideEffecting": true },
     "memory_list_clusters": { "replaySafe": true },
-    "memory_fetch_cluster": { "replaySafe": true }
+    "memory_fetch_cluster": { "replaySafe": true },
+    "memory_list_maintenance_tasks": { "replaySafe": true },
+    "memory_update_maintenance_task": { "sideEffecting": true }
   },
   "uiHints": {
     "keepEmbeddingModelWarm": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "preflight": "npm run knip && npm run build && npm run typecheck && npm test && npm run plugin:inspect && npm run plugin:inspect:runtime && npm pack --dry-run"
   },
   "dependencies": {
-    "@unblocklabs/qmd": "https://github.com/unblocklabs-ai/qmd/releases/download/v2.9.2/unblocklabs-qmd-2.9.2.tgz",
+    "@unblocklabs/qmd": "https://github.com/unblocklabs-ai/qmd/releases/download/v2.9.3/unblocklabs-qmd-2.9.3.tgz",
     "chokidar": "5.0.0",
     "picomatch": "^4.0.5",
     "typebox": "1.3.6"

package/skills/memory-curator/SKILL.md

@@ -16,7 +16,9 @@ weak, duplicative, or easily looked-up knowledge.
    `memory_recluster`, then list again.
 2. Fetch a useful cluster with `memory_fetch_cluster`. Start with
    `sort: "representative"`; use `score_desc`, `date_asc`, or `date_desc` and
-   pagination when relevance, evolution, or recent state matters.
+   pagination when relevance, evolution, or recent state matters. Treat
+   `eventTime` as event chronology; `sourceModifiedAt` is only a labeled
+   fallback when `eventTime` is unresolved.
 3. State the question the cluster raises: what may be repeated, contradictory,
    changing, or worth understanding?
 4. Search existing knowledge with `memory_search`, using
@@ -67,6 +69,13 @@ rigid document template.
 ## Finish the cycle
 
 - Do not rewrite raw memory or session projections.
+- Review a small page from `memory_list_maintenance_tasks`. For ambiguous dates,
+  investigate supporting evidence and use `memory_update_maintenance_task` to
+  attach a chunk or document date only when supported; otherwise defer or mark
+  it irrelevant. For exact-duplicate proposals, decide whether cleanup should
+  be proposed, but do not treat repetition across historical files as an error.
+  The maintenance tools never change source Markdown, and generated session
+  projections must never be manually cleaned.
 - Verify an updated file with `memory_search`, using
   `corpora: ["knowledge"]`, and check all-corpora ranking when useful.
 - Report the questions investigated, evidence consulted beyond each cluster,