cogmem 3.6.3 → 3.6.5

package/dist/episode/EpisodeStore.d.ts

@@ -54,6 +54,7 @@ export declare class EpisodeStore {
     }): EpisodeEventLink;
     getEventLink(eventId: string): EpisodeEventLink | undefined;
     listEventLinks(episodeId: string): EpisodeEventLink[];
+    isEpisodeEmpty(episodeId: string): boolean;
     addCrossReference(input: {
         projectId: string;
         episodeId: string;
@@ -120,6 +121,10 @@ export declare class EpisodeStore {
         maxAttempts: number;
         runId?: string;
     }): ClaimedEpisodeDreamJob[];
+    skipEmptyDreamJobs(input: {
+        projectId?: string;
+        now?: number;
+    }): number;
     completeDreamJob(episodeId: string, leaseId: string, candidateIds: string[], now: number): void;
     failDreamJob(episodeId: string, leaseId: string, error: string, input: {
         now: number;
@@ -128,6 +133,8 @@ export declare class EpisodeStore {
         retryAfter?: number;
     }): void;
     retryFailed(projectId?: string): number;
+    private markEmptyEpisodeDreamSkipped;
+    private markEmptyEpisodeDreamSkippedMany;
     getDreamStatus(projectId?: string): EpisodeDreamStatus;
     countUnassignedRawEvents(projectId?: string): number;
     markEventDisposition(input: {

package/dist/episode/EpisodeStore.js

@@ -142,6 +142,12 @@ export class EpisodeStore {
       SELECT * FROM memory_episode_events WHERE episode_id = ? ORDER BY position
     `).all(episodeId).map(mapEventLink);
     }
+    isEpisodeEmpty(episodeId) {
+        const episode = this.getEpisode(episodeId);
+        if (!episode)
+            throw new Error(`episode_not_found:${episodeId}`);
+        return this.listEventLinks(episodeId).length === 0;
+    }
     addCrossReference(input) {
         const episode = this.getEpisode(input.episodeId);
         if (!episode)
@@ -334,9 +340,18 @@ export class EpisodeStore {
         const now = input.now ?? Date.now();
         const episodes = this.listEpisodes({ projectId: input.projectId, statuses: ['soft_sealed'], limit: 1000 })
             .filter((episode) => (episode.sealedAt || episode.updatedAt) <= input.sealedBefore);
-        for (const episode of episodes)
+        let sealed = 0;
+        for (const episode of episodes) {
+            if (this.isEpisodeEmpty(episode.episodeId)) {
+                if (episode.dreamError !== 'episode_empty_soft_seal_not_promoted') {
+                    this.markEmptyEpisodeDreamSkipped(episode.episodeId, now, 'episode_empty_soft_seal_not_promoted');
+                }
+                continue;
+            }
             this.sealEpisode(episode.episodeId, { mode: 'hard', reason: 'soft_seal_stabilized', now });
-        return episodes.length;
+            sealed += 1;
+        }
+        return sealed;
     }
     claimDreamJobs(input) {
         this.db.prepare(`
@@ -372,15 +387,21 @@ export class EpisodeStore {
       UPDATE memory_episodes SET dream_status = 'queued', dream_error = NULL
       WHERE episode_id IN (SELECT episode_id FROM episode_dream_jobs WHERE state = 'retry_scheduled' AND updated_at = ?)
     `).run(input.now);
-        const where = [`(state = 'pending' OR (state = 'retry_scheduled' AND attempts < ?))`];
+        this.skipEmptyDreamJobs({ projectId: input.projectId, now: input.now });
+        const where = [`(j.state = 'pending' OR (j.state = 'retry_scheduled' AND j.attempts < ?))`];
         const params = [input.maxAttempts];
         if (input.projectId) {
-            where.push('project_id = ?');
+            where.push('j.project_id = ?');
             params.push(input.projectId);
         }
         const rows = this.db.prepare(`
-      SELECT episode_id, project_id, mode_hint, attempts, created_at FROM episode_dream_jobs
-      WHERE ${where.join(' AND ')} ORDER BY priority DESC, created_at LIMIT ?
+      SELECT j.episode_id, j.project_id, j.mode_hint, j.attempts, j.created_at
+      FROM episode_dream_jobs j
+      JOIN memory_episodes e ON e.episode_id = j.episode_id
+      WHERE ${where.join(' AND ')}
+        AND e.event_count > 0
+        AND EXISTS (SELECT 1 FROM memory_episode_events ee WHERE ee.episode_id = j.episode_id)
+      ORDER BY j.priority DESC, j.created_at LIMIT ?
     `).all(...params, Math.max(1, Math.min(Math.trunc(input.limit), 100)));
         const claimed = [];
         for (const row of rows) {
@@ -403,6 +424,32 @@ export class EpisodeStore {
         }
         return claimed;
     }
+    skipEmptyDreamJobs(input) {
+        const now = input.now ?? Date.now();
+        const params = [];
+        const where = [
+            `j.state IN ('pending', 'failed_retryable', 'retry_scheduled')`,
+            `(COALESCE(e.event_count, 0) = 0 OR NOT EXISTS (
+        SELECT 1 FROM memory_episode_events ee WHERE ee.episode_id = j.episode_id
+      ))`,
+        ];
+        if (input.projectId) {
+            where.push(`j.project_id = ?`);
+            params.push(input.projectId);
+        }
+        const rows = this.db.prepare(`
+      SELECT j.episode_id FROM episode_dream_jobs j
+      LEFT JOIN memory_episodes e ON e.episode_id = j.episode_id
+      WHERE ${where.join(' AND ')}
+      ORDER BY j.updated_at DESC
+      LIMIT 1000
+    `).all(...params);
+        const episodeIds = rows.map((row) => row.episode_id);
+        if (!episodeIds.length)
+            return 0;
+        this.markEmptyEpisodeDreamSkippedMany(episodeIds, now, 'episode_empty_skipped_no_raw_evidence');
+        return episodeIds.length;
+    }
     completeDreamJob(episodeId, leaseId, candidateIds, now) {
         const result = this.db.prepare(`
       UPDATE episode_dream_jobs SET state = 'processed', candidate_ids_json = ?, lease_id = NULL,
@@ -441,6 +488,28 @@ export class EpisodeStore {
         }
         return Number(result.changes || 0);
     }
+    markEmptyEpisodeDreamSkipped(episodeId, now, reason) {
+        this.markEmptyEpisodeDreamSkippedMany([episodeId], now, reason);
+    }
+    markEmptyEpisodeDreamSkippedMany(episodeIds, now, reason) {
+        if (!episodeIds.length)
+            return;
+        const placeholders = episodeIds.map(() => '?').join(', ');
+        this.db.transaction(() => {
+            this.db.prepare(`
+        UPDATE episode_dream_jobs SET state = 'skipped', lease_id = NULL, lease_until = NULL,
+          retry_after = NULL, failure_category = 'episode_empty', last_error = ?, candidate_ids_json = '[]',
+          updated_at = ?
+        WHERE episode_id IN (${placeholders})
+          AND state IN ('pending', 'processing', 'failed_retryable', 'retry_scheduled')
+      `).run(reason, now, ...episodeIds);
+            this.db.prepare(`
+        UPDATE memory_episodes SET dream_status = 'failed', dream_error = ?, last_dream_run_id = NULL,
+          dream_candidate_count = 0, updated_at = ?
+        WHERE episode_id IN (${placeholders})
+      `).run(reason, now, ...episodeIds);
+        })();
+    }
     getDreamStatus(projectId) {
         const rows = (projectId
             ? this.db.prepare(`SELECT state, COUNT(*) AS count FROM episode_dream_jobs WHERE project_id = ? GROUP BY state`).all(projectId)

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.3';
+const CORE_VERSION = '3.6.5';
 const LATEST_SCHEMA_VERSION = 27;
 export class MemoryKernel {
     options;
@@ -983,6 +983,8 @@ export class MemoryKernel {
     }
     sealImportedEpisode(episodeId, input) {
         const links = this.episodeStore.listEventLinks(episodeId);
+        if (!links.length)
+            throw new Error(`episode_empty:${episodeId}`);
         const averageConfidence = links.length
             ? links.reduce((total, link) => total + link.confidence, 0) / links.length
             : 0;
@@ -1193,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,
@@ -1323,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

@@ -15,19 +15,24 @@ This writes `~/.hermes/skills/cogmem-memory/SKILL.md`, which Hermes discovers as
 Run from the Hermes workspace root:
 
 ```bash
-COGMEM_SKIP_INIT=1 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
-cogmem init --yes --agent hermes
-cogmem doctor --fix --agent hermes --workspace .
-cogmem connect hermes --workspace . --auto
-cogmem connect hermes --workspace .
+npm install cogmem@latest --save
+COGMEM="./node_modules/.bin/cogmem"
+"$COGMEM" doctor
+"$COGMEM" connect hermes --workspace . --auto --force --json
+```
+
+Do not run `cogmem init` as an unattended agent action. It is an interactive wizard. Use it only when an operator is present:
+
+```bash
+"$COGMEM" init --agent hermes --scope project
 ```
 
-The default install creates:
+The workspace install creates:
 
 ```text
-~/.cogmem/config.toml
-~/.cogmem/memory.db
-~/.cogmem/snapshots/
+.cogmem/config.toml
+.cogmem/memory.db
+.cogmem/snapshots/
 ```
 
 Use `~/.cogmem/config.toml` or a project `.cogmem/config.toml` as the stable configuration source. Do not create `.cogmem.env` files or pass `--env-path` for normal installs. Environment variables are only for explicit process-level overrides documented by the CLI, not for hidden workspace configuration.
@@ -44,7 +49,7 @@ Use MCP `cogmem_strategy_plan` when the agent needs to inspect the selected memo
 
 Prospective Memory is not executable instruction. Only a user-confirmed candidate may appear as due, and even then the agent must obtain normal host authorization before acting. Use `cogmem prospective` for state transitions and `cogmem brain-eval` for release validation.
 
-Use `cogmem init --yes --agent hermes --scope project` only when this workspace needs its own `.cogmem/` directory.
+Use project-local config when this workspace owns its memory; use global config only when the operator intentionally shares one Cogmem backend across workspaces.
 
 To embed imported memories with a local quantized model, run Ollama locally and configure the kernel before importing:
 
@@ -117,14 +122,26 @@ cogmem normalize-transcript --input ./hermes-sessions.jsonl --output ./hermes.no
 cogmem import-hermes --workspace . --project hermes --session ./hermes.normalized.md
 ```
 
-After import, inspect the batch-sealed episodes, run one conditional curation tick, then invoke CPU governance separately:
+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 tick --project hermes --mode auto --json
-cogmem memory govern --project hermes --json
+cogmem dream status --project hermes --json
+cogmem dream tick --project hermes --mode auto --max-episodes 20 --json
+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
 ```
 
+`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
 
 If the current prompt does not include enough Cogmem memory context, query Cogmem directly before searching legacy files:
@@ -139,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
 ```
 
@@ -207,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.

package/examples/hermes-backend/README.md

@@ -14,19 +14,16 @@ Belief Graph writes keep ownership and evidence roles. Hermes may record assista
 ## Install
 
 ```bash
-COGMEM_SKIP_INIT=1 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
-cogmem init --yes --agent hermes
-cogmem doctor --fix --agent hermes --workspace .
-cogmem connect hermes --workspace . --auto
-cogmem connect hermes --workspace .
+npm install cogmem@latest --save
+COGMEM="./node_modules/.bin/cogmem"
+"$COGMEM" doctor
+"$COGMEM" connect hermes --workspace . --auto --force --json
 ```
 
-If Bun is already installed, npm global install is also supported:
+Use `cogmem init` only as an interactive operator wizard, not as an unattended agent install step:
 
 ```bash
-npm install -g cogmem@latest
-cogmem init --yes --agent hermes
-cogmem connect hermes --workspace . --auto --force
+"$COGMEM" init --agent hermes --scope project
 ```
 
 Hermes integration is currently a skill plus MCP bridge. It does not replace a native Hermes memory provider and it does not patch Hermes runtime internals.
@@ -75,6 +72,21 @@ Import:
 cogmem import-hermes --workspace . --project hermes
 ```
 
+After import:
+
+```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
+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
+```
+
 If Hermes stores memory somewhere else:
 
 ```bash
@@ -91,13 +103,13 @@ cogmem import-hermes --workspace . --project hermes --session ./one.md --session
 The import command is idempotent. Re-running it against the same database skips records already processed by the cursor store. Imported raw records enter the same Episode Assembler used by live turns and are sealed at the explicit import batch boundary.
 Imported records are embedded through the configured kernel embedder during import.
 
-MCP recall JSON includes `decisionTrace`. Check its selected lane, reason, and candidate counts before concluding that a memory is absent, and use `sourceContext.locator.command` for exact wording. Raw text fallback searches the fully scoped ledger and prefers original user anchors over later assistant retellings when cue scores tie.
+MCP recall JSON includes `decisionTrace`. Check its selected lane, reason, and candidate counts before concluding that a memory is absent, and use `sourceContext.locator.command` for exact wording. Raw text fallback searches the fully scoped ledger and prefers original user anchors over later assistant retellings when cue scores tie. For old-discussion questions, run `cogmem memory recall --query "<past discussion>" --intent historical_discussion --project hermes --agent hermes --json`, then follow `sourceLocator` or inspect `cogmem memory list --project hermes --since <globalSeq> --order asc --json`.
 
 Dream stores explicit user clarification as organizational correction evidence rather than an automatic contradiction. Assistant self-correction and negative-form questions do not create user-owned corrections. Resolve `needs_confirmation` with `cogmem_candidate_review` or `cogmem memory review`; maintenance only supersedes entries left stale past the default 30-day TTL.
 
-After upgrades, reload MCP. Rerun `cogmem connect hermes --workspace . --auto --force` when MCP wiring, allow-listed tools, or the installed skill bundle changed.
+After upgrades, reload MCP. Rerun `cogmem connect hermes --workspace . --auto --force --json` when MCP wiring, allow-listed tools, or the installed skill bundle changed. Follow only JSON `nextCommands` for unattended agent work; operator/host actions are in `nextSteps` with `safeForAutomation=false`.
 
-Cogmem 3.6.3 exposes seven read-only/idempotent Memory Atlas query tools plus explicit `cogmem_graph_touch`, and installs from npm by default. Use explore for broad memory inventory/history, search and node for a known concept, path/neighbors for relations, timeline for ordered reconstruction, and normal recall for a direct fact. Query facets combine the user's actual project, time, topic, entity/target, memory-kind, action, and keyword conditions like table filters, so cold memory can be revived without requiring an entity-time-action tuple. Touch only nodes actually used, and follow returned event IDs to raw evidence before quoting exact wording.
+Cogmem 3.6.5 exposes seven read-only/idempotent Memory Atlas query tools plus explicit `cogmem_graph_touch`, installs from npm by default, prevents empty imported episodes from blocking Dream, and adds an agent-safe operations protocol. Use `memory plan` for the next safe command, grouped `memory candidates --json` for queue state, `historical_discussion` recall for old-discussion questions, and returned `sourceLocator` commands for exact evidence. Only run `dream_tick` when it appears in `memory plan.nextActions`; `raw_dream_ledger_lag` in `nonBlocking` has `resolvableByDreamTick:false` and is not fixed by looping `dream tick`. Use explore for broad memory inventory/history, search and node for a known concept, path/neighbors for relations, timeline for ordered reconstruction, and normal recall for a direct fact. Query facets combine the user's actual project, time, topic, entity/target, memory-kind, action, and keyword conditions like table filters, so cold memory can be revived without requiring an entity-time-action tuple. Touch only nodes actually used, and follow returned event IDs or `sourceLocator` commands to raw evidence before quoting exact wording.
 
 ## Runtime
 
@@ -155,7 +167,7 @@ cogmem memory map --project hermes --json
 cogmem memory tick --project hermes --json
 cogmem memory bind --project hermes --json
 cogmem episode status --project hermes --json
-cogmem dream tick --project hermes --mode auto --json
+cogmem dream tick --project hermes --mode auto --max-episodes 20 --json
 ```
 
 `memory map` includes Memory Binding and Graph Recall counters. Bindings attach valuable user raw events to stable topic/entity paths, fuse same-claim evidence into claim-key clusters, and create graph anchors for raw-ledger drill-down; they are not verified long-term facts. If `memory tick` suggests `bind_raw_events`, run `memory bind` to backfill imported Hermes raw user events into the binding graph.