cogmem 3.6.4 → 3.6.5

package/dist/bin/memory.js

@@ -55,6 +55,8 @@ function readArgs(argv) {
         before: numberArg(values, 'before'),
         after: numberArg(values, 'after'),
         sinceGlobalSeq: numberArg(values, 'since') ?? numberArg(values, 'since-global-seq'),
+        untilGlobalSeq: numberArg(values, 'until') ?? numberArg(values, 'until-global-seq'),
+        order: orderArg(values, 'order'),
         intervalMs: numberArg(values, 'interval-ms'),
         maxRuns: numberArg(values, 'max-runs'),
         promoteLimit: numberArg(values, 'promote-limit'),
@@ -75,6 +77,7 @@ function usage() {
         '',
         'Commands:',
         '  status               summarize raw ledger, vector, and dream backlog state',
+        '  plan                 summarize status as agent-safe next actions',
         '  list                 list raw ledger events with source anchors',
         '  search --query <q>   search raw ledger text without requiring hot vectors',
         '  recall --query <q>   run agent-facing governed recall with source context',
@@ -101,7 +104,9 @@ function usage() {
         '  --thread <id>        scope to one thread',
         '  --session <id>       scope to one session',
         '  --limit <n>          result limit, default 20',
-        '  --since <globalSeq>  for bind, scan raw events at or after a global sequence',
+        '  --since <globalSeq>  list/bind events at or after a global sequence',
+        '  --until <globalSeq>  list events at or before a global sequence',
+        '  --order <asc|desc>   list raw ledger order, default desc',
         '  --status <status>    candidate queue status, default candidate',
         '  --id <candidate>     candidate id for review',
         '  --action <action>    review action: approve, reject, defer, supersede, or relink',
@@ -117,7 +122,7 @@ function usage() {
         '  --interval-ms <n>    watch sleep interval, default 300000',
         '  --max-runs <n>       stop watch after n iterations; omit for long-running worker',
         '  --agent <id>         agent id for governed recall, default openclaw',
-        '  --intent <intent>    memory_recall, previous_session_summary, or forensic_quote',
+        '  --intent <intent>    memory_recall, previous_session_summary, forensic_quote, or historical_discussion',
         '  --db <memory.db>     open an explicit database path',
         '  --config <toml>      open a cogmem TOML config',
         '  --include-evidence   include bounded raw excerpts; event ids are always returned',
@@ -135,6 +140,7 @@ function usage() {
 }
 function isMemoryCommand(value) {
     return value === 'status'
+        || value === 'plan'
         || value === 'list'
         || value === 'search'
         || value === 'recall'
@@ -166,9 +172,17 @@ function recallIntentArg(values, key) {
     const raw = stringArg(values, key);
     if (!raw)
         return undefined;
-    if (raw === 'memory_recall' || raw === 'previous_session_summary' || raw === 'forensic_quote')
+    if (raw === 'memory_recall' || raw === 'previous_session_summary' || raw === 'forensic_quote' || raw === 'historical_discussion')
         return raw;
-    throw new Error(`--${key} must be one of memory_recall, previous_session_summary, forensic_quote`);
+    throw new Error(`--${key} must be one of memory_recall, previous_session_summary, forensic_quote, historical_discussion`);
+}
+function orderArg(values, key) {
+    const raw = stringArg(values, key);
+    if (!raw)
+        return undefined;
+    if (raw === 'asc' || raw === 'desc')
+        return raw;
+    throw new Error(`--${key} must be one of asc, desc`);
 }
 function stringArg(values, key) {
     const value = values[key];
@@ -219,30 +233,32 @@ function inspectionDbPath(args) {
 function runReadOnlyInspection(args) {
     const inspection = new MemoryInspectionStore(inspectionDbPath(args));
     try {
-        if (args.command === 'status') {
+        if (args.command === 'status' || args.command === 'plan') {
             const payload = inspection.status({
                 projectId: args.projectId, workspaceId: args.workspaceId,
                 threadId: args.threadId, sessionId: args.sessionId,
             });
+            const queueSummary = buildCandidateQueueSummary(inspection, args.projectId, args.limit || 5000);
+            const plan = buildMemoryPlan(payload, queueSummary, args.projectId);
+            const enrichedPayload = args.command === 'plan'
+                ? plan
+                : { ...payload, queueSummary, nextActions: plan.nextActions, blocking: plan.blocking, nonBlocking: plan.nonBlocking };
             if (args.json) {
-                printCliJson('memory.status', payload, {
+                printCliJson(`memory.${args.command}`, enrichedPayload, {
                     queue: payload.dreamCandidateQueue,
                     beliefs: payload.activeBeliefs,
                 });
             }
             else
-                printHuman('status', payload);
+                printHuman(args.command, enrichedPayload);
             return;
         }
-        const status = args.status || 'candidate';
-        const candidates = inspection.listCandidates({
-            projectId: args.projectId,
-            status,
-            limit: args.limit || 50,
-        });
-        const payload = { total: candidates.length, status, candidates: candidates.map(candidateToJson) };
+        const queueSummary = buildCandidateQueueSummary(inspection, args.projectId, args.limit || 50);
+        const payload = args.status
+            ? buildSpecificCandidatePayload(inspection, args.projectId, args.status, args.limit || 50, queueSummary)
+            : buildGroupedCandidatePayload(queueSummary);
         if (args.json)
-            printCliJson('memory.candidates', payload);
+            printCliJson('memory.candidates', payload, { queue: queueSummary });
         else
             printHuman('candidates', payload);
     }
@@ -262,6 +278,7 @@ function eventText(event) {
 }
 function eventToJson(event) {
     const text = eventText(event);
+    const locator = eventSourceLocator(event, 2, 2);
     return {
         eventId: event.eventId,
         label: memoryEventLabel(event),
@@ -294,6 +311,21 @@ function eventToJson(event) {
             causalityType: event.causalityType,
             orderingConfidence: event.orderingConfidence,
         },
+        sourceLocator: locator,
+    };
+}
+function eventSourceLocator(event, before, after) {
+    const projectArg = event.projectId ? ` --project ${cliArg(event.projectId)}` : '';
+    const base = `cogmem memory show --event ${cliArg(event.eventId)}${projectArg}`;
+    return {
+        eventId: event.eventId,
+        globalSeq: event.globalSeq,
+        projectId: event.projectId,
+        threadId: event.threadId,
+        sessionId: event.sessionId,
+        localDate: event.localDate,
+        command: `${base} --before ${before} --after ${after} --json`,
+        contextCommand: `${base} --before 3 --after 3 --json`,
     };
 }
 function candidateToJson(candidate) {
@@ -313,6 +345,141 @@ function candidateToJson(candidate) {
         updatedAt: candidate.updatedAt,
     };
 }
+function buildCandidateQueueSummary(inspection, projectId, limit) {
+    const status = inspection.status({ projectId });
+    const queue = status.dreamCandidateQueue;
+    const candidateRows = inspection.listCandidates({ projectId, status: 'candidate', limit });
+    const needsRows = inspection.listCandidates({ projectId, status: 'needs_confirmation', limit: Math.max(limit, 5000) });
+    const now = Date.now();
+    const deferredRows = needsRows.filter((candidate) => candidate.reviewAfter !== undefined && candidate.reviewAfter > now);
+    const activeNeedsRows = needsRows.filter((candidate) => !(candidate.reviewAfter !== undefined && candidate.reviewAfter > now));
+    return {
+        candidate: queue.candidate,
+        needs_confirmation: queue.needsConfirmation,
+        activeNeedsConfirmation: Math.max(0, queue.needsConfirmation - deferredRows.length),
+        deferredNeedsConfirmation: deferredRows.length,
+        promoted: queue.promoted,
+        rejected: queue.rejected,
+        superseded: queue.superseded,
+        shadow: queue.shadow,
+        groups: {
+            candidate: candidateRows.slice(0, limit).map(candidateToJson),
+            needs_confirmation: activeNeedsRows.slice(0, limit).map(candidateToJson),
+            deferred: deferredRows.slice(0, limit).map(candidateToJson),
+        },
+    };
+}
+function buildSpecificCandidatePayload(inspection, projectId, status, limit, queueSummary) {
+    const candidates = inspection.listCandidates({ projectId, status, limit });
+    const payload = {
+        total: candidates.length,
+        status,
+        candidates: candidates.map(candidateToJson),
+        queueSummary,
+    };
+    if (status === 'candidate') {
+        payload.warning = 'This lists only status=candidate. Use memory candidates without --status for grouped candidate and needs_confirmation queues.';
+    }
+    else if (status === 'needs_confirmation') {
+        payload.warning = 'memory govern does not process needs_confirmation. Use memory review with explicit user evidence, or defer with review_after.';
+    }
+    return payload;
+}
+function buildGroupedCandidatePayload(queueSummary) {
+    return {
+        total: queueSummary.groups.candidate.length + queueSummary.groups.needs_confirmation.length + queueSummary.groups.deferred.length,
+        status: 'grouped',
+        queueSummary,
+        groups: queueSummary.groups,
+        nextActions: candidateNextActions(queueSummary, undefined),
+    };
+}
+function buildMemoryPlan(status, queueSummary, projectId) {
+    const nextActions = [];
+    const blocking = [];
+    const nonBlocking = [];
+    const projectArg = projectId ? ` --project ${cliArg(projectId)}` : '';
+    const episodeDream = status.episodeDream;
+    const pendingEpisodes = asCount(episodeDream.pending) + asCount(episodeDream.retryScheduled);
+    const undreamedRawCount = asCount(status.undreamedRawCount);
+    if (pendingEpisodes > 0) {
+        nextActions.push({
+            priority: 'high',
+            type: 'dream_tick',
+            safeForAutomation: true,
+            reason: `${pendingEpisodes} sealed episode Dream jobs can be processed`,
+            command: `cogmem dream tick${projectArg} --mode auto --max-episodes 20 --json`,
+        });
+    }
+    if (undreamedRawCount > 0) {
+        nonBlocking.push({
+            type: 'raw_dream_ledger_lag',
+            count: undreamedRawCount,
+            episodeDreamPending: pendingEpisodes,
+            resolvableByDreamTick: false,
+            safeForAutomation: false,
+            reason: pendingEpisodes > 0
+                ? 'Raw ledger dream coverage is tracked separately from sealed episode Dream jobs; dream tick may process episodes but does not guarantee this counter will clear.'
+                : 'Raw ledger dream coverage is behind, but there are no sealed episode Dream jobs. Do not run dream tick for this signal alone.',
+            command: `cogmem memory list${projectArg} --order asc --limit 20 --json`,
+        });
+    }
+    nextActions.push(...candidateNextActions(queueSummary, projectId));
+    if (queueSummary.activeNeedsConfirmation > 0) {
+        blocking.push({
+            type: 'needs_confirmation',
+            count: queueSummary.activeNeedsConfirmation,
+            reason: 'Manual review requires explicit user evidence; memory govern will not process these candidates.',
+            command: `cogmem memory candidates${projectArg} --status needs_confirmation --json`,
+        });
+    }
+    if (queueSummary.deferredNeedsConfirmation > 0) {
+        nonBlocking.push({
+            type: 'deferred_confirmation',
+            count: queueSummary.deferredNeedsConfirmation,
+            reason: 'Deferred needs_confirmation remains in the review queue until review_after.',
+            command: `cogmem memory candidates${projectArg} --json`,
+        });
+    }
+    return {
+        healthy: nextActions.length === 0 && blocking.length === 0,
+        projectId,
+        queueSummary,
+        dreamBacklog: status.dreamBacklog,
+        episodeDream: status.episodeDream,
+        vectorState: status.vectorState,
+        nextActions,
+        blocking,
+        nonBlocking,
+    };
+}
+function candidateNextActions(queueSummary, projectId) {
+    const projectArg = projectId ? ` --project ${cliArg(projectId)}` : '';
+    const actions = [];
+    if (queueSummary.candidate > 0) {
+        actions.push({
+            priority: 'high',
+            type: 'govern',
+            safeForAutomation: true,
+            reason: `${queueSummary.candidate} ordinary candidates are ready for deterministic governance`,
+            command: `cogmem memory govern${projectArg} --limit 100 --json`,
+        });
+    }
+    if (queueSummary.activeNeedsConfirmation > 0) {
+        actions.push({
+            priority: 'medium',
+            type: 'review_needs_confirmation',
+            safeForAutomation: false,
+            reason: `${queueSummary.activeNeedsConfirmation} candidates need explicit operator/user confirmation`,
+            command: `cogmem memory candidates${projectArg} --status needs_confirmation --json`,
+            reviewCommand: `cogmem memory review${projectArg} --id <candidate-id> --action <approve|reject|defer|supersede|relink> --actor <operator> --reason <reason> --json`,
+        });
+    }
+    return actions;
+}
+function asCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
 function runStatus(kernel, args) {
     const page = kernel.eventStore.queryEvents(1, 1, {
         projectId: args.projectId ? [args.projectId] : undefined,
@@ -344,9 +511,15 @@ function runList(kernel, args) {
         workspaceId: args.workspaceId ? [args.workspaceId] : undefined,
         threadId: args.threadId ? [args.threadId] : undefined,
         sessionId: args.sessionId ? [args.sessionId] : undefined,
+        sinceGlobalSeq: args.sinceGlobalSeq,
+        untilGlobalSeq: args.untilGlobalSeq,
+        order: args.order,
     });
     return {
         total: page.total,
+        sinceGlobalSeq: args.sinceGlobalSeq,
+        untilGlobalSeq: args.untilGlobalSeq,
+        order: args.order || 'desc',
         events: page.records.map(eventToJson),
     };
 }
@@ -607,12 +780,24 @@ function runCandidates(kernel, args) {
     };
 }
 function printHuman(command, payload) {
-    if (command === 'status') {
+    if (command === 'status' || command === 'plan') {
+        if (command === 'plan') {
+            console.log(`healthy: ${payload.healthy}`);
+            console.log(`queueSummary: ${JSON.stringify(payload.queueSummary)}`);
+            console.log(`nextActions: ${JSON.stringify(payload.nextActions)}`);
+            console.log(`blocking: ${JSON.stringify(payload.blocking)}`);
+            console.log(`nonBlocking: ${JSON.stringify(payload.nonBlocking)}`);
+            return;
+        }
         console.log(`rawEvents: ${payload.rawEventCount}`);
         console.log(`vectors: ${payload.vectorCount}`);
         console.log(`dreamBacklog: ${JSON.stringify(payload.dreamBacklog)}`);
         console.log(`episodeDream: ${JSON.stringify(payload.episodeDream)}`);
         console.log(`dreamCandidateQueue: ${JSON.stringify(payload.dreamCandidateQueue)}`);
+        if (payload.queueSummary)
+            console.log(`queueSummary: ${JSON.stringify(payload.queueSummary)}`);
+        if (payload.nextActions)
+            console.log(`nextActions: ${JSON.stringify(payload.nextActions)}`);
         return;
     }
     if (command === 'dream') {
@@ -646,6 +831,18 @@ function printHuman(command, payload) {
         return;
     }
     if (command === 'candidates') {
+        if (payload.queueSummary)
+            console.log(`queueSummary: ${JSON.stringify(payload.queueSummary)}`);
+        const groups = payload.groups;
+        if (groups) {
+            for (const [group, values] of Object.entries(groups)) {
+                console.log(`${group}: ${values.length}`);
+                for (const candidate of values) {
+                    console.log(`- ${candidate.candidateId} ${candidate.candidateType} ${candidate.status} confidence=${candidate.confidence}`);
+                }
+            }
+            return;
+        }
         const candidates = Array.isArray(payload.candidates) ? payload.candidates : [];
         for (const candidate of candidates) {
             console.log(`- ${candidate.candidateId} ${candidate.candidateType} ${candidate.status} confidence=${candidate.confidence}`);
@@ -741,7 +938,7 @@ async function main() {
         console.log(usage());
         return;
     }
-    if (args.command === 'status' || args.command === 'candidates') {
+    if (args.command === 'status' || args.command === 'plan' || args.command === 'candidates') {
         runReadOnlyInspection(args);
         return;
     }
@@ -801,3 +998,6 @@ main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
 });
+function cliArg(value) {
+    return /^[A-Za-z0-9._:/=@+-]+$/u.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/factory.d.ts

@@ -138,6 +138,8 @@ export interface MemoryBindingBackfillOptions {
 export interface MemoryBindingBackfillResult {
     projectId?: string;
     sinceGlobalSeq?: number;
+    nextGlobalSeq?: number;
+    hasMore: boolean;
     scannedEvents: number;
     bindableEvents: number;
     boundEvents: number;

package/dist/factory.js

@@ -83,7 +83,7 @@ import { SqliteVecStore } from './store/SqliteVecStore.js';
 import { VectorStore } from './store/VectorStore.js';
 import { config } from './utils/Config.js';
 import { KernelRunningError, SnapshotExporter, SnapshotImporter, } from './snapshot/index.js';
-const CORE_VERSION = '3.6.4';
+const CORE_VERSION = '3.6.5';
 const LATEST_SCHEMA_VERSION = 27;
 export class MemoryKernel {
     options;
@@ -1195,18 +1195,22 @@ export class MemoryKernel {
     }
     bindRawEvents(options = {}) {
         const limit = Math.max(1, Math.min(options.limit ?? 500, 5000));
-        const page = this.eventStore.queryEvents(1, limit, {
-            projectId: options.projectId ? [options.projectId] : undefined,
-            workspaceId: options.workspaceId ? [options.workspaceId] : undefined,
-            threadId: options.threadId ? [options.threadId] : undefined,
-            sessionId: options.sessionId ? [options.sessionId] : undefined,
+        const afterGlobalSeq = options.sinceGlobalSeq === undefined
+            ? undefined
+            : Math.max(-1, options.sinceGlobalSeq - 1);
+        const records = this.eventStore.listRawEventsAfterGlobalSeq({
+            projectId: options.projectId,
+            workspaceId: options.workspaceId,
+            threadId: options.threadId,
+            sessionId: options.sessionId,
+            afterGlobalSeq,
+            limit,
         });
-        const records = page.records
-            .filter((event) => options.sinceGlobalSeq === undefined || (event.globalSeq || 0) >= options.sinceGlobalSeq)
-            .sort((a, b) => (a.globalSeq || 0) - (b.globalSeq || 0));
         const result = {
             projectId: options.projectId,
             sinceGlobalSeq: options.sinceGlobalSeq,
+            nextGlobalSeq: records.at(-1)?.globalSeq,
+            hasMore: records.length >= limit,
             scannedEvents: records.length,
             bindableEvents: 0,
             boundEvents: 0,
@@ -1325,16 +1329,30 @@ export class MemoryKernel {
         return { touched: this.memoryAtlasStore.recordAccess(input.projectId, valid, input.reason, input.query, input.now) };
     }
     countUnboundBindableRawEvents(projectId, limit = 1000) {
-        const page = this.eventStore.queryEvents(1, Math.max(1, limit), {
-            projectId: projectId ? [projectId] : undefined,
-        });
+        const max = Math.max(1, limit);
+        let afterGlobalSeq;
         let count = 0;
-        for (const event of page.records) {
-            if (!this.memoryBindingService.isBindableRawEvent(event))
-                continue;
-            if (this.memoryBindingStore.listBindings({ eventId: event.eventId, limit: 1 }).length > 0)
-                continue;
-            count += 1;
+        while (count < max) {
+            const batchLimit = Math.min(500, max);
+            const events = this.eventStore.listRawEventsAfterGlobalSeq({
+                projectId,
+                afterGlobalSeq,
+                limit: batchLimit,
+            });
+            if (events.length === 0)
+                break;
+            afterGlobalSeq = events.at(-1)?.globalSeq ?? afterGlobalSeq;
+            for (const event of events) {
+                if (!this.memoryBindingService.isBindableRawEvent(event))
+                    continue;
+                if (this.memoryBindingStore.listBindings({ eventId: event.eventId, limit: 1 }).length > 0)
+                    continue;
+                count += 1;
+                if (count >= max)
+                    break;
+            }
+            if (events.length < batchLimit)
+                break;
         }
         return count;
     }

package/dist/host/openclaw/AutoMemoryPluginInstaller.js

@@ -26,7 +26,7 @@ export function installOpenClawAutoMemoryPlugin(options) {
         ? { kind: 'toml', path: resolve(options.configPath) }
         : resolveCogmemConfigPath({ cwd: workspaceRoot });
     if (configResolution.kind !== 'toml') {
-        throw new Error(`Missing cogmem config at ${configResolution.path}. Run cogmem-init --agent openclaw --scope project first.`);
+        throw new Error(`Missing cogmem config at ${configResolution.path}. Ask an operator to run the interactive setup: cogmem init --agent openclaw --scope project.`);
     }
     const configPath = configResolution.path;
     const pluginDir = resolve(options.pluginDir || defaultOpenClawAutoMemoryPluginDir(workspaceRoot));
@@ -663,6 +663,9 @@ function classifyRecallIntent(query) {
   if (/原话|怎么说的|完整对话|上一句|下一句|exact quote|verbatim/.test(text)) {
     return 'forensic_quote';
   }
+  if (/记得.{0,12}(聊过|讨论过|说过)|还记得|之前.{0,12}(聊过|讨论过|说过)|以前.{0,12}(聊过|讨论过|说过)|(过去|几个月前|半年前|上个月|前几天|昨天|上次|上个).{0,20}(聊过|讨论过|说过)|当时.{0,12}(聊|说|问)|那次.{0,12}(聊|说|问)|有没有.{0,12}(记录|聊过|讨论过)|have we discussed|did we talk about|previously discussed/.test(text)) {
+    return 'historical_discussion';
+  }
   return 'memory_recall';
 }
 
@@ -1754,7 +1757,8 @@ function formatRecallContext(result, config) {
       if (item.sourceContext.locator && item.sourceContext.locator.command) {
         lines.push('  sourceLocator=' + item.sourceContext.locator.command);
       } else if (item.sourceContext.event.eventId) {
-        lines.push('  sourceLocator=cogmem memory show --event ' + item.sourceContext.event.eventId + ' --before 2 --after 2');
+        const project = item.sourceContext.event.projectId ? ' --project ' + item.sourceContext.event.projectId : '';
+        lines.push('  sourceLocator=cogmem memory show --event ' + item.sourceContext.event.eventId + project + ' --before 2 --after 2 --json');
       }
       const seenEventIds = new Set([anchorEvent.eventId].filter(Boolean));
       const before = uniqueWindowEvents(Array.isArray(item.sourceContext.before) ? item.sourceContext.before : [], seenEventIds).slice(-2);

package/dist/mcp/server.js

@@ -5,7 +5,7 @@ import { callCogmemMcpTool, listCogmemMcpTools, } from './CoreMcpTools.js';
 export function createCogmemMcpServer(runtime = {}) {
     const server = new Server({
         name: 'cogmem-core',
-        version: '3.6.1',
+        version: '3.6.5',
     }, {
         capabilities: {
             tools: {},

package/dist/store/EventStore.d.ts

@@ -61,6 +61,9 @@ export declare class EventStore {
     getLatestEvent(): MemoryEvent | null;
     listRawEventsAfterGlobalSeq(options?: {
         projectId?: string;
+        workspaceId?: string;
+        threadId?: string;
+        sessionId?: string;
         afterGlobalSeq?: number;
         limit?: number;
     }): MemoryEvent[];
@@ -78,6 +81,9 @@ export declare class EventStore {
         sessionId?: string[];
         startTime?: number;
         endTime?: number;
+        sinceGlobalSeq?: number;
+        untilGlobalSeq?: number;
+        order?: 'asc' | 'desc';
     }): EventAuditPage;
     getEvent(eventId: string): MemoryEvent | null;
     getThreadEvents(threadId: string, options?: {

package/dist/store/EventStore.js

@@ -270,6 +270,18 @@ export class EventStore {
             conditions.push('project_id = ?');
             params.push(options.projectId);
         }
+        if (options.workspaceId) {
+            conditions.push('workspace_id = ?');
+            params.push(options.workspaceId);
+        }
+        if (options.threadId) {
+            conditions.push('thread_id = ?');
+            params.push(options.threadId);
+        }
+        if (options.sessionId) {
+            conditions.push('session_id = ?');
+            params.push(options.sessionId);
+        }
         if (options.afterGlobalSeq !== undefined) {
             conditions.push('COALESCE(global_seq, 0) > ?');
             params.push(options.afterGlobalSeq);
@@ -347,7 +359,18 @@ export class EventStore {
             conditions.push('occurred_at <= ?');
             params.push(filters.endTime);
         }
+        if (filters?.sinceGlobalSeq !== undefined) {
+            conditions.push('COALESCE(global_seq, 0) >= ?');
+            params.push(filters.sinceGlobalSeq);
+        }
+        if (filters?.untilGlobalSeq !== undefined) {
+            conditions.push('COALESCE(global_seq, 0) <= ?');
+            params.push(filters.untilGlobalSeq);
+        }
         const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+        const orderSql = filters?.order === 'asc'
+            ? 'COALESCE(global_seq, 0) ASC, occurred_at ASC, event_id ASC'
+            : 'COALESCE(global_seq, 0) DESC, occurred_at DESC, event_id DESC';
         const totalRow = this.db.prepare(`
       SELECT COUNT(*) AS count FROM memory_events ${where}
     `).get(...params);
@@ -355,7 +378,7 @@ export class EventStore {
       SELECT ${MEMORY_EVENT_COLUMNS}
       FROM memory_events
       ${where}
-      ORDER BY COALESCE(global_seq, 0) DESC, occurred_at DESC, event_id DESC
+      ORDER BY ${orderSql}
       LIMIT ? OFFSET ?
     `).all(...params, safePageSize, offset);
         return {
@@ -375,7 +398,10 @@ export class EventStore {
                 threadId: filters?.threadId,
                 sessionId: filters?.sessionId,
                 startTime: filters?.startTime,
-                endTime: filters?.endTime
+                endTime: filters?.endTime,
+                sinceGlobalSeq: filters?.sinceGlobalSeq,
+                untilGlobalSeq: filters?.untilGlobalSeq,
+                order: filters?.order,
             }
         };
     }

package/dist/types/index.d.ts

@@ -850,6 +850,9 @@ export interface EventAuditPage {
         sessionId?: string[];
         startTime?: number;
         endTime?: number;
+        sinceGlobalSeq?: number;
+        untilGlobalSeq?: number;
+        order?: 'asc' | 'desc';
     };
 }
 //# sourceMappingURL=index.d.ts.map

package/examples/hermes-backend/AGENTS.md

@@ -122,12 +122,14 @@ cogmem normalize-transcript --input ./hermes-sessions.jsonl --output ./hermes.no
 cogmem import-hermes --workspace . --project hermes --session ./hermes.normalized.md
 ```
 
-Cogmem 3.6.4 skips import batch sealing for empty episode boundaries and skips legacy empty Dream jobs so one bad imported episode cannot block the queue.
+Cogmem 3.6.4 and later skip import batch sealing for empty episode boundaries and skip legacy empty Dream jobs so one bad imported episode cannot block the queue.
 
 After import, use this order:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory status --project hermes --json
+cogmem memory candidates --project hermes --json
 cogmem episode status --project hermes --json
 cogmem dream status --project hermes --json
 cogmem dream tick --project hermes --mode auto --max-episodes 20 --json
@@ -135,9 +137,10 @@ cogmem memory candidates --project hermes --status candidate --json
 cogmem memory govern --project hermes --limit 100 --json
 cogmem memory candidates --project hermes --status needs_confirmation --json
 cogmem memory review --project hermes --id <candidate-id> --action approve --actor <operator> --reason "confirmed by user" --confirmation-event <user-event-id> --json
+cogmem memory recall --query "<verification question>" --project hermes --agent hermes --json
 ```
 
-`needs_confirmation` is not the Dream backlog. `memory govern` does not approve it; use `memory review` with explicit evidence.
+`memory plan` is the first agent-safe health and next-action command. Only run `dream_tick` when it appears in `nextActions`; if `nonBlocking` contains `raw_dream_ledger_lag` with `resolvableByDreamTick:false`, inspect raw sources or episode/import boundaries instead of retrying `dream tick`. Default `memory candidates --json` groups ordinary, `needs_confirmation`, and deferred review queues; use `--status` only when a human asks for one queue. `needs_confirmation` is not the Dream backlog. `memory govern` does not approve it; use `memory review` with explicit evidence.
 
 ## Active Memory Search
 
@@ -153,15 +156,18 @@ For inventory or product questions, use recall first and raw search as a forensi
 cogmem memory recall --query "我们记录过哪些库存" --project hermes --agent hermes --json
 cogmem memory search --query "エルビ 库存" --project hermes --json
 cogmem memory show --event <event-id> --before 2 --after 2 --json
+cogmem memory recall --query "几个月前我们是不是讨论过 Cogmem 的记忆黑盒" --intent historical_discussion --project hermes --agent hermes --json
+cogmem memory list --project hermes --since <globalSeq> --order asc --json
 ```
 
 `vectors: 0` does not mean Cogmem has no memory. It means the dense vector index has no hot vectors yet. `memory recall` still falls back to governed raw ledger search and returns `sourceContext` locators. Broad inventory questions are expanded into structured cues such as `库存管理`, `在库`, `产品コード`, and `数量`; if compiled-memory candidates miss those cues, raw ledger evidence is preferred.
 
-`sourceContext` and `memory show --json` now share the same replay contract: each event has a `label`, optional `charRange` / `sourceRange`, and `sourceContext.window` / `window` metadata with requested counts, actual counts, `excludesAnchor`, `ordering`, `roleFilter`, and `overlapHandling`. Use those fields before quoting exact wording or explaining what happened before/after a recalled point.
+`sourceContext` and `memory show --json` now share the same replay contract: each event has a `label`, optional `charRange` / `sourceRange`, and `sourceContext.window` / `window` metadata with requested counts, actual counts, `excludesAnchor`, `ordering`, `roleFilter`, and `overlapHandling`. Use those fields before quoting exact wording or explaining what happened before/after a recalled point. In 3.6.5, Raw Ledger list rows and Atlas search/explore evidence include `sourceLocator.command` and `sourceLocator.contextCommand`; run those commands before saying the source event is unavailable.
 
 Check status with:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory status --project hermes --json
 ```
 
@@ -221,12 +227,12 @@ Hermes has no automatic observation path in this integration. Use `cogmem_episod
 
 Use `cogmem_topic_operate` with actor `user_explicit` only for explicit user naming/organization instructions. Model suggestions use `model_candidate` and remain reviewable; alias collisions fail closed. Use `cogmem_episode_repair` for split/merge/move/reclassify/requeue work so receipts, stale candidates, cross-references, Dream jobs, and audit records stay synchronized. Do not hand-edit the database.
 
-Use `cogmem memory map --project hermes --json` or MCP `cogmem_memory_map` to inspect Memory Binding and Graph Recall counters. Bindings attach high-value user raw events to stable topic/entity paths, fuse same-claim evidence into claim-key clusters, and create graph anchors for source drill-down only; they are not verified facts, user preferences, or instructions. Correction bindings expose review flags and correction edges. If `cogmem memory tick --project hermes --json` suggests `bind_raw_events`, run `cogmem memory bind --project hermes --json`. Re-run `cogmem connect hermes --workspace . --auto` after upgrades to patch existing MCP allow-lists with new Cogmem tools.
+Use `cogmem memory map --project hermes --json` or MCP `cogmem_memory_map` to inspect Memory Binding and Graph Recall counters. Bindings attach high-value user raw events to stable topic/entity paths, fuse same-claim evidence into claim-key clusters, and create graph anchors for source drill-down only; they are not verified facts, user preferences, or instructions. Correction bindings expose review flags and correction edges. If `cogmem memory tick --project hermes --json` suggests `bind_raw_events`, run `cogmem memory bind --project hermes --json`; in 3.6.5 it scans the historical ledger by cursor and can resume with `--since <globalSeq>`. Re-run `cogmem connect hermes --workspace . --auto --force --json` after upgrades to patch existing MCP allow-lists with new Cogmem tools. Follow only `nextCommands` for unattended agent work; operator/host actions are in `nextSteps` with `safeForAutomation=false`.
 
 Dream correction records require explicit user clarification; assistant self-correction and questions containing `是不是` are not user-owned contradictions. Invalid provider output is a rejected diagnostic. Maintenance ticks supersede `needs_confirmation` entries older than the default 30-day TTL and retain their evidence rows.
 
 ## Memory Atlas navigation
 
-For broad inventory or historical questions call `cogmem_graph_explore`. Use `cogmem_graph_search` and `cogmem_graph_node` for known concepts, `cogmem_graph_neighbors`/`cogmem_graph_path` for relations, and `cogmem_graph_timeline` for ordered reconstruction. Use `cogmem_recall` for a direct fact and follow event IDs to `cogmem memory show` for exact wording.
+For broad inventory or historical questions call `cogmem_graph_explore`. Use `cogmem_graph_search` and `cogmem_graph_node` for known concepts, `cogmem_graph_neighbors`/`cogmem_graph_path` for relations, and `cogmem_graph_timeline` for ordered reconstruction. Use `cogmem_recall` for a direct fact and follow event IDs or returned `sourceLocator` commands to `cogmem memory show` for exact wording.
 
 Combine the filters present in the user's message, including project, time, topic, entity/target, memory kind, and ordinary cues. Do not force an entity + time + action tuple. A cold result is newly visible, not newly verified or promoted.