@unblocklabs/unblock-memory 0.2.5 → 0.2.7

package/README.md

@@ -53,14 +53,9 @@ directories, or globs into named corpora:
               chatTypes: ["channel", "group"],
             },
             {
-              name: "canon",
+              name: "knowledge",
               kind: "files",
-              paths: ["knowledge/canon/**/*.md"],
-            },
-            {
-              name: "reflections",
-              kind: "files",
-              paths: ["knowledge/reflections/**/*.md"],
+              paths: ["knowledge/**/*.md"],
             },
           ],
           // Optional: omit unless the local analysis worker is installed.
@@ -85,7 +80,7 @@ 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
-`corpora: ["canon"]` to search selected corpora or `corpora: ["all"]` to
+`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`.
 
@@ -115,18 +110,22 @@ The optional `sessions` corpus reads the current agent's normal OpenClaw SQLite
 store and indexes its active user/assistant transcript branch. It defaults to
 channel and group conversations; add `direct` explicitly to include DMs. Run
 `memory_sync_sessions` to start a refresh, then use `memory_sync_status` to
-check its progress or result. Projections are private derived Markdown
-under the agent's `unblock-memory/sessions` state directory and can be rebuilt
-from OpenClaw at any time. Session results include provider, chat type,
-conversation identity, and start time as an ISO 8601 timestamp. They participate
-in the same search and clustering index as file memory. This phase does not sync
-sessions at startup or on a schedule; refreshes are manual through
+check its progress or result. Projections are private derived Markdown under the
+agent's `unblock-memory/sessions` state directory and can be rebuilt from
+OpenClaw at any time. Their embedded text contains only `# Transcript` and
+timestamped speaker messages; filtering metadata remains in the session
+manifest. The projected file modification time matches the session start time
+for meaningful chronological cluster reads. Session results include provider,
+chat type, conversation identity, and start time as an ISO 8601 timestamp. They
+participate in the same search and clustering index as file memory. This phase
+does not sync sessions at startup or on a schedule; refreshes are manual through
 `memory_sync_sessions`.
 
 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
 
@@ -166,17 +165,38 @@ Unblock Memory exposes:
 - `memory_list_clusters` to cheaply list current clusters and report whether the
   retained analysis is stale
 - `memory_recluster` to explicitly rebuild clusters when the list is missing or stale
-- `memory_fetch_cluster` to return up to `topK` representative QMD chunks for a
-  short `clusterId` returned by `memory_list_clusters`
+- `memory_fetch_cluster` to return a sorted, paginated selection of QMD chunks
+  for a short `clusterId` returned by `memory_list_clusters`
 
 `memory_recluster` optionally accepts UMAP controls (`method`, components,
 neighbors, and minimum distance), HDBSCAN controls (minimum cluster size,
 minimum samples, selection method and epsilon, and single-cluster behavior),
 and a deterministic seed. Omitting them uses the worker's defaults.
 
-Cluster reads return at most 50 members. 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.
+`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 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
+are shared across the page so every returned member receives a useful excerpt
+and at least one source path, including a full 50-member page.
 
 If indexing changes content or vectors, the previous derived analysis is kept
 and marked stale. Cluster reads include the analysis timestamp, stale timestamp,
@@ -186,33 +206,37 @@ A failed rebuild leaves the stale result intact, while a successful rebuild
 atomically replaces it. Analysis is never scheduled automatically. If the worker
 is absent or fails, `memory_search` and `memory_get` continue to work.
 
-## Curating canon and reflections
+## Curating knowledge
 
 The plugin bundles the `memory-curator` skill for turning useful clusters into
 durable knowledge. It becomes available when the plugin is enabled. If the
 agent has an explicit skill allowlist, include `memory-curator`.
 
-Keep curated files outside `memory/**` so each file belongs to only one corpus:
+Keep maintained knowledge outside `memory/**` so each file belongs to only one
+corpus. Use stable topic files updated in place:
 
 ```text
 knowledge/
-├── canon/
-│   └── gateway-restarts.md
-└── reflections/
-    └── 2026-08-26.md
+├── fleet.md
+├── people/
+│   └── rico.md
+└── projects/
+    └── unblock-memory.md
 ```
 
-Canon files are stable topic files updated in place. Each one contains only the
-current affirmative rule or understanding, its update time, current rationale,
-and `qmd://` evidence links. Do not include old procedures, changelogs, or a
-`Supersedes` section: semantic chunking may retrieve those passages without the
-surrounding warning that they are obsolete.
+Knowledge is the agent's maintained, current understanding of its unique world:
+facts such as fleet membership, local decisions and preferences, assessments,
+and explicit uncertainty that would be expensive to reconstruct from scattered
+history. Each claim should carry its own epistemic qualification so it remains
+honest when semantic chunking retrieves it alone. Remove stale conclusions
+instead of preserving history, changelogs, or `Supersedes` passages in the same
+file; raw memory and sessions retain the evidence history.
 
-Reflection files are daily or timestamped and append-oriented. They hold useful
-patterns, hypotheses, contradictions, and uncertainty, but are not
-authoritative. Both corpora participate in later search and clustering, so a
-later run can reconsider prior reasoning. Repeated derived text is not
-independent corroboration; durable canon still needs underlying source evidence.
+Public or vendor-owned facts, generic command syntax, and behavior likely to
+change with third-party releases should normally be looked up from the current
+authoritative source. A local policy or deliberate divergence may belong in
+knowledge, but the local decision—not copied generic documentation—is the
+durable content.
 
 For a manual run, ask the agent:
 
@@ -226,10 +250,12 @@ For recurring curation, use an OpenClaw automation with the same thin message:
 Use $memory-curator to run the scheduled memory curation cycle.
 ```
 
-The skill lists current clusters, reclusters only when analysis is missing or
-stale, follows representative sources with `memory_get`, and may correctly
-write nothing. Its own writes are indexed for the next cycle; it does not
-recluster recursively in the same run.
+The skill treats a cluster as an incomplete attention signal. It frames the
+question raised, uses representative, score, and chronological views as useful,
+searches existing knowledge and adjacent corpora, and investigates live systems,
+files, documentation, or the web when those are better evidence. It then updates
+a stable knowledge topic or correctly writes nothing. Its own writes are indexed
+for the next cycle; it does not recluster recursively in the same run.
 
 Existing `unblock-qmd` indexes are derived caches and may be left in place;
 Unblock Memory rebuilds its own index from configured corpora.

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,9 +33,15 @@ type MemoryAnalysisMember = {
     x: number;
     y: number;
     representativeRank: number | null;
+    sourceModifiedAt: string;
+    eventTime: string | null;
+    eventTimeBasis: "path" | "frontmatter" | "session" | "agent_verified" | null;
+    eventTimeSource: string;
+    contentFingerprint: string;
     text: string;
     sourcePaths: string[];
 };
+export type MemoryClusterSort = "representative" | "score_desc" | "score_asc" | "date_desc" | "date_asc";
 export type MemoryAnalysisSummary = {
     status: "ok";
     runId: string;
@@ -72,6 +81,13 @@ export type MemoryClusterDetail = AnalysisReadMetadata & {
     runId?: string;
     cluster?: Omit<MemoryClusterSummary, "preview">;
     members?: MemoryAnalysisMember[];
+    page?: {
+        offset: number;
+        returned: number;
+        total: number;
+        hasMore: boolean;
+        nextOffset?: number;
+    };
 };
 export declare function ensureMemoryAnalysisSchema(db: AnalysisDatabase): void;
 export declare function markMemoryAnalysisStale(db: AnalysisDatabase): void;
@@ -85,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): 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,8 +231,8 @@ function byteSlice(text, maxBytes) {
         return "";
     return bytes.subarray(0, maxBytes - 3).toString("utf8").replace(/\uFFFD$/u, "") + "…";
 }
-function members(db, runId, clusterId, limit, maxExcerptBytes = MAX_EXCERPT_BYTES, maxTotalBytes = MAX_TOTAL_EXCERPT_BYTES, maxTotalAliases = MAX_TOTAL_ALIASES) {
-    const noiseOrder = clusterId === -1
+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,
        m.representative_rank,
@@ -217,23 +240,87 @@ function members(db, runId, clusterId, limit, maxExcerptBytes = MAX_EXCERPT_BYTE
        m.outlier_score,
        m.hash,
        m.seq`;
+    const score = clusterId === -1 ? "m.outlier_score" : "m.probability";
+    const order = {
+        representative: representativeOrder,
+        score_desc: `${score} DESC, m.hash, m.seq`,
+        score_asc: `${score} 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(`
-    SELECT
-      m.hash, m.seq, m.probability, m.outlier_score, m.x, m.y,
-      m.representative_rank, m.pos, m.chunk_len, m.doc
-    FROM memory_analysis_available_memberships m
-    WHERE m.run_id = ? AND m.cluster_id = ?
-    ORDER BY ${noiseOrder}
-    LIMIT ?
-  `).all(runId, clusterId, limit);
+    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 d.modified_at
+          FROM documents d
+          WHERE d.hash = m.hash AND d.active = 1
+          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(temporal.sessionCollection ?? "", temporal.sessionCollection ?? "", temporal.sessionCollection ?? "", runId, clusterId, runId, clusterId, limit, offset);
     let remaining = maxTotalBytes;
     let remainingAliases = maxTotalAliases;
-    return rows.map((row) => {
-        const text = remaining <= 0
-            ? ""
-            : byteSlice(row.doc.slice(row.pos, row.pos + row.chunk_len), Math.min(maxExcerptBytes, remaining));
+    return rows.map((row, index) => {
+        const remainingRows = rows.length - index;
+        const excerptBudget = Math.min(maxExcerptBytes, Math.floor(remaining / remainingRows));
+        const fullText = row.doc.slice(row.pos, row.pos + row.chunk_len);
+        const text = byteSlice(fullText, excerptBudget);
         remaining -= Buffer.byteLength(text);
-        const aliases = sourcePaths(db, row.hash, Math.min(MAX_ALIASES_PER_MEMBER, remainingAliases));
+        const aliasBudget = Math.min(MAX_ALIASES_PER_MEMBER, Math.floor(remainingAliases / remainingRows));
+        const aliases = sourcePaths(db, row.hash, aliasBudget);
         remainingAliases -= aliases.length;
         return {
             hash: row.hash,
@@ -243,6 +330,11 @@ function members(db, runId, clusterId, limit, maxExcerptBytes = MAX_EXCERPT_BYTE
             x: row.x,
             y: row.y,
             representativeRank: row.representative_rank,
+            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,
         };
@@ -276,7 +368,7 @@ function readMetadata(run) {
 }
 function toSummary(db, run, row, includePreview, previewBytes = 600, aliasLimit = MAX_TOTAL_ALIASES) {
     const preview = includePreview
-        ? members(db, run.id, row.cluster_id, 1, previewBytes, previewBytes, aliasLimit)[0]
+        ? members(db, run.id, row.cluster_id, 1, 0, "representative", previewBytes, previewBytes, aliasLimit)[0]
         : undefined;
     return {
         clusterId: clusterReference(run.id, row.cluster_id),
@@ -362,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) {
+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() };
@@ -388,6 +480,11 @@ export function readCluster(db, clusterReferenceId, requestedLimit = DEFAULT_MEM
         return { status: "not_found", runId: run.id, ...metadata };
     }
     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, MAX_EXCERPT_BYTES, MAX_TOTAL_EXCERPT_BYTES, MAX_TOTAL_ALIASES, temporal);
+    const nextOffset = offset + pageMembers.length;
+    const hasMore = nextOffset < total;
     return {
         status: "ok",
         runId: run.id,
@@ -395,9 +492,16 @@ export function readCluster(db, clusterReferenceId, requestedLimit = DEFAULT_MEM
         cluster: {
             clusterId: clusterReferenceId,
             size: row.size,
-            availableSize: availableSize(db, run.id, clusterId),
+            availableSize: total,
             meanProbability: row.mean_probability,
         },
-        members: members(db, run.id, clusterId, limit),
+        members: pageMembers,
+        page: {
+            offset,
+            returned: pageMembers.length,
+            total,
+            hasMore,
+            ...(hasMore ? { nextOffset } : {}),
+        },
     };
 }

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

@@ -1,7 +1,8 @@
 import type { QMDStore } from "@unblocklabs/qmd";
-import { type AnalysisRunner, type MemoryAnalysisSummary, type MemoryClusterDetail, type MemoryClusterList, type MemoryReclusterOptions } from "./analysis.js";
+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>;
@@ -44,7 +46,24 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
     fetchCluster(params: {
         clusterId: string;
         topK?: number;
+        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));
+        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

@@ -192,6 +192,14 @@ function createListClustersTool(runtime, ctx) {
 const fetchClusterParameters = Type.Object({
     clusterId: Type.String({ pattern: "^[0-9a-f]{10}$" }),
     topK: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+    offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    sort: Type.Optional(Type.Union([
+        Type.Literal("representative"),
+        Type.Literal("score_desc"),
+        Type.Literal("score_asc"),
+        Type.Literal("date_desc"),
+        Type.Literal("date_asc"),
+    ])),
 }, { additionalProperties: false });
 function createFetchClusterTool(runtime, ctx) {
     const active = getContext(ctx);
@@ -200,14 +208,89 @@ function createFetchClusterTool(runtime, ctx) {
     return {
         name: "memory_fetch_cluster",
         label: "Fetch Memory Cluster",
-        description: "Fetch the top representative QMD chunks for a clusterId returned by memory_list_clusters.",
+        description: "Fetch a sorted page of QMD chunks for a clusterId returned by memory_list_clusters.",
         parameters: fetchClusterParameters,
         async execute(_toolCallId, params) {
-            const { clusterId, topK } = Value.Parse(fetchClusterParameters, params);
+            const { clusterId, topK, offset, sort } = Value.Parse(fetchClusterParameters, params);
             const { manager, error } = await runtime.getMemorySearchManager(active);
             if (!manager)
                 return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });
-            return jsonResult(await manager.fetchCluster({ clusterId, topK }));
+            return jsonResult(await manager.fetchCluster({ clusterId, topK, offset, sort }));
+        },
+    };
+}
+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" });
         },
     };
 }
@@ -304,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/dist/src/session-projector.js

@@ -100,9 +100,6 @@ function formatTimestamp(value, timezone) {
     return `${part("year")}-${part("month")}-${part("day")} ` +
         `${part("hour")}:${part("minute")}:${part("second")} ${part("timeZoneName")}`.trim();
 }
-function inline(value) {
-    return value.replace(/[\r\n]+/gu, " ").replaceAll("`", "\\`");
-}
 export function projectSession(input) {
     const messages = input.events.flatMap((event) => {
         const projected = projectMessage(event, input);
@@ -110,22 +107,8 @@ export function projectSession(input) {
     });
     if (messages.length === 0)
         return undefined;
-    const provider = input.provider ?? "unknown";
-    const header = [
-        "# Session",
-        "",
-        `- Session ID: \`${inline(input.sessionId)}\``,
-        `- Provider: ${inline(provider)}`,
-        `- Chat type: ${input.chatType}`,
-        ...(input.label ? [`- Conversation: ${inline(input.label)}`] : []),
-        ...(input.conversationId ? [`- Conversation ID: \`${inline(input.conversationId)}\``] : []),
-        `- Started: ${new Date(input.startedAt).toISOString()}`,
-        "",
-        "## Transcript",
-        "",
-    ];
     const transcript = messages.map((message) => `${formatTimestamp(message.timestamp, input.timezone)} — ${message.speaker}: ${message.text}`);
-    return `${[...header, ...transcript].join("\n\n")}\n`;
+    return `# Transcript\n\n${transcript.join("\n\n")}\n`;
 }
 function hash(value) {
     return createHash("sha256").update(value).digest("hex").slice(0, 16);

package/dist/src/session-sync.js

@@ -1,11 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync } from "node:fs";
-import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rename, unlink, utimes, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { projectSession, sessionDocumentPath, } from "./session-projector.js";
 const MANIFEST_VERSION = 1;
-const PROJECTOR_VERSION = 1;
+const PROJECTOR_VERSION = 2;
 const SUPPORTED_SCHEMA_VERSION = 17;
 const REQUIRED_COLUMNS = {
     schema_meta: ["meta_key", "role", "schema_version", "agent_id", "app_version"],
@@ -261,6 +261,7 @@ export async function syncSessionProjections(params) {
         }
         const target = projectionPath(params.outputDir, documentPath);
         await atomicWrite(target, content, 0o600);
+        await utimes(target, new Date(), new Date(metadata.startedAt));
         if (previous?.documentPath && previous.documentPath !== documentPath) {
             await remove(projectionPath(params.outputDir, previous.documentPath));
         }

package/openclaw.plugin.json

@@ -1,18 +1,20 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.2.5",
+  "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.5",
+  "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

@@ -1,78 +1,84 @@
 ---
 name: memory-curator
-description: Review Unblock Memory clusters and turn supported current knowledge into canon or exploratory reasoning into reflections.
+description: Investigate Unblock Memory clusters and maintain supported, agent-specific knowledge that would otherwise be difficult to reconstruct.
 ---
 
 # Memory Curator
 
-Use Unblock Memory's semantic clusters to maintain durable workspace knowledge.
-Clusters show similarity, not truth or consensus. Prefer no write over a weak or
-duplicative artifact.
-
-## Review clusters
-
-1. Call `memory_list_clusters`.
-2. If analysis is missing or stale, call `memory_recluster`, then list again.
-3. Fetch useful clusters with `memory_fetch_cluster`. Treat noise as optional
-   review material, not automatically important content.
-4. Follow representative `qmd://` source paths with `memory_get` whenever the
-   excerpt lacks context or a conclusion could change durable knowledge.
-5. Distinguish underlying memory or session evidence from earlier canon and
-   reflections. Derived artifacts may help locate, challenge, or revise an
-   understanding, but repetition does not make them independent evidence.
-6. For each reviewed cluster, choose canon, reflection, or no write.
-
-## Write canon
-
-Use `knowledge/canon/<stable-topic>.md` for a supported, durable rule or current
-understanding. Update the topic file in place instead of creating dated copies.
-
-Every semantic chunk in canon must remain correct if retrieved alone:
-
-- State only the current affirmative truth.
-- Remove obsolete instructions rather than preserving them for comparison.
-- Never add `Supersedes`, history, changelog, old-process, or migration sections.
-- Include a human-readable `Updated` timestamp, the current rationale, and
-  `qmd://` evidence citations.
-- Preserve uncertainty in the claim itself. If the evidence does not support a
-  stable current claim, write a reflection or nothing.
-
-A concise shape is sufficient:
-
-```markdown
-# Topic
-
-Updated: 2026-08-26 14:30 EDT
-
-## Current understanding
-
-Present-tense rule or facts.
-
-## Rationale
-
-Why this is the current understanding.
-
-## Evidence
-
-- qmd://memory/...
-- qmd://sessions/...
-```
-
-## Write reflections
-
-Use `knowledge/reflections/YYYY-MM-DD.md` for patterns, hypotheses,
-contradictions, open questions, or reasoning worth revisiting. Append a
-timestamped section when the day's file already exists. Label uncertainty
-plainly and include the `qmd://` evidence examined. Reflections are not
-authoritative instructions.
+Use semantic clusters as attention signals for maintaining the agent's current
+understanding of its world. A cluster shows similarity, not a complete timeline,
+truth, or consensus. Do not write from a cluster alone, and prefer no write over
+weak, duplicative, or easily looked-up knowledge.
+
+## Investigate
+
+1. Call `memory_list_clusters`. If analysis is missing or stale, call
+   `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. 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
+   `corpora: ["knowledge"]`. If that corpus is not configured, report that and
+   do not create an unindexed file.
+5. Investigate the evidence needed to answer the question. Follow important
+   `qmd://` sources with `memory_get`, search adjacent memory or sessions, inspect
+   other clusters, and check live systems, local files, authoritative docs, or
+   the web when they are the right source. The selected cluster is not assumed
+   to contain the whole timeline or the current truth.
+6. Distinguish underlying evidence from earlier agent-created knowledge.
+   Derived repetition can locate or challenge a conclusion, but is not
+   independent corroboration.
+
+## Decide what belongs in knowledge
+
+Write knowledge when the result is agent-specific, evolving, and expensive to
+reconstruct, such as current fleet composition, relationships, preferences,
+project decisions, local conventions, or an assessment synthesized across
+time.
+
+Prefer a lookup for public or vendor-owned facts, generic command syntax, and
+behavior likely to change with a third-party release. Those sources may verify
+a local conclusion, but do not copy ordinary documentation into knowledge. A
+local policy or deliberate divergence can belong when its local meaning and
+rationale are the durable part.
+
+Choose one outcome: update knowledge or no write. No write is successful when
+the evidence is insufficient, the information is already accurate, or lookup
+is better than memory.
+
+## Maintain knowledge
+
+Use a stable `knowledge/<topic>.md` file and update it in place. Facts, agent
+assessments, and uncertainty may coexist. Qualify each claim where it appears so
+it remains honest if semantic chunking retrieves it alone:
+
+- identify what is verified and when or against which current source;
+- label an interpretation as the agent's assessment rather than a settled fact;
+- state uncertainty or an open question directly with the affected claim.
+
+Keep the file focused on current understanding. Remove stale conclusions rather
+than retaining `Supersedes`, history, changelog, migration, or old-process
+sections. Raw memory and sessions preserve the evidence history. Include a
+human-readable update time and useful evidence citations, but do not force a
+rigid document template.
 
 ## Finish the cycle
 
 - Do not rewrite raw memory or session projections.
-- Avoid restating knowledge already captured accurately.
-- Verify new or updated knowledge with `memory_search`, selecting `canon` or
-  `reflections` when useful.
-- Report clusters reviewed, files changed, evidence used, uncertainties, and
-  intentional skips.
+- 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,
+  files changed, current uncertainties, and intentional no-write decisions.
 - Do not recluster again after this cycle's writes. Let them enter the next
   scheduled cycle so the run cannot recursively react to its own output.