@unblocklabs/unblock-memory 0.2.5 → 0.2.6

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,12 +110,15 @@ 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
@@ -166,17 +164,26 @@ 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 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.
+
+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 +193,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 +237,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

@@ -30,9 +30,11 @@ type MemoryAnalysisMember = {
     x: number;
     y: number;
     representativeRank: number | null;
+    sourceDate: 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 +74,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 +94,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): MemoryClusterDetail;
 export {};

package/dist/src/analysis.js

@@ -208,8 +208,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) {
+    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 +217,40 @@ 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: "m.source_date DESC, m.hash, m.seq",
+        date_asc: "m.source_date 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 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)
+          FROM documents d
+          WHERE d.hash = m.hash AND d.active = 1
+        ) AS source_date
+      FROM memory_analysis_available_memberships m
+      WHERE m.run_id = ? AND m.cluster_id = ?
+    )
+    SELECT * FROM member_rows m
+    ORDER BY ${order}
+    LIMIT ? OFFSET ?
+  `).all(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 text = byteSlice(row.doc.slice(row.pos, row.pos + row.chunk_len), 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 +260,7 @@ function members(db, runId, clusterId, limit, maxExcerptBytes = MAX_EXCERPT_BYTE
             x: row.x,
             y: row.y,
             representativeRank: row.representative_rank,
+            sourceDate: row.source_date,
             text,
             sourcePaths: aliases,
         };
@@ -276,7 +294,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 +380,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") {
     const run = latestValidRun(db);
     if (!run) {
         return { status: "not_analyzed", ...readMetadata() };
@@ -388,6 +406,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);
+    const nextOffset = offset + pageMembers.length;
+    const hasMore = nextOffset < total;
     return {
         status: "ok",
         runId: run.id,
@@ -395,9 +418,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/manager.d.ts

@@ -1,5 +1,5 @@
 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 SessionSyncResult } from "./session-sync.js";
@@ -44,6 +44,8 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
     fetchCluster(params: {
         clusterId: string;
         topK?: number;
+        offset?: number;
+        sort?: MemoryClusterSort;
     }): Promise<MemoryClusterDetail>;
     search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
     readFile(params: {

package/dist/src/manager.js

@@ -391,7 +391,7 @@ 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 () => readCluster((await this.#getAnalysisStore()).internal.db, params.clusterId, params.topK, params.offset, params.sort));
     }
     async #getAnalysisStore() {
         const store = await this.#getStore();

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,14 @@ 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 }));
         },
     };
 }

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,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",

package/skills/memory-curator/SKILL.md

@@ -1,78 +1,75 @@
 ---
 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.
+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.
+- 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.