cogmem 3.6.4 → 3.6.5

package/examples/hermes-backend/README.md

@@ -75,7 +75,9 @@ 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
@@ -101,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.4 exposes seven read-only/idempotent Memory Atlas query tools plus explicit `cogmem_graph_touch`, installs from npm by default, and prevents empty imported episodes from blocking Dream. 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
 

package/examples/hermes-backend/SKILL.md

@@ -180,12 +180,14 @@ cogmem import-hermes --workspace . --project hermes --session ./hermes.normalize
 
 The importer is idempotent. Re-running it skips records already imported into the same memory database.
 
-Cogmem 3.6.4 skips import batch sealing for empty episode boundaries and Dream skips legacy empty episode jobs instead of blocking the whole queue. If `episode status` shows `dreamError` beginning with `episode_empty`, inspect the source events and use episode repair instead of editing SQLite rows.
+Cogmem 3.6.4 and later skip import batch sealing for empty episode boundaries and Dream skips legacy empty episode jobs instead of blocking the whole queue. If `episode status` shows `dreamError` beginning with `episode_empty`, inspect the source events and use episode repair instead of editing SQLite rows.
 
 Run the maintenance loop under host supervision after import and during normal use. `needs_confirmation` is a human review queue, not the Dream backlog, and `memory govern` promotes only ordinary `candidate` rows:
 
 ```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
@@ -196,6 +198,8 @@ cogmem memory review --project hermes --id <candidate-id> --action approve --act
 cogmem memory recall --query "<verification question>" --project hermes --agent hermes --json
 ```
 
+`memory plan` is the first agent-safe health and next-action command. It explains which queues block release, which work is non-blocking, whether vectors are empty but fallback recall is available, and what command should run next. 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 candidates, `needs_confirmation`, and deferred review entries; use `--status` only when the operator asks for one queue.
+
 A host timer may run this bounded tick periodically. The tick exits after inspecting the backlog and performs no work when no sealed episode is ready.
 
 ## Active Memory Search
@@ -233,9 +237,25 @@ cogmem memory show --event <event-id> --before 2 --after 2 --json
 
 `sourceContext` entries include stable `label` values, optional `charRange` / `sourceRange`, and `sourceContext.window` metadata. Use `window.before.requestedCount`, `window.before.count`, `window.after.requestedCount`, `window.after.count`, `excludesAnchor`, `ordering`, `roleFilter`, and `overlapHandling` to understand the before/after replay. `memory show --json` returns the same contract, so the labels in MCP recall can be matched to the local CLI output.
 
+For “did we discuss this before?”, “几个月前是不是聊过…”, “记忆黑盒”, MCP memory gaps, or other old-discussion questions, force the historical-discussion lane before saying memory is absent:
+
+```bash
+cogmem memory recall --query "<past discussion question>" --intent historical_discussion --project hermes --agent hermes --json
+```
+
+If the answer depends on exact wording or nearby context, run the returned `sourceLocator` or use a Raw Ledger cursor:
+
+```bash
+cogmem memory show --event <eventId> --project hermes --before 2 --after 2 --json
+cogmem memory list --project hermes --since <globalSeq> --order asc --json
+```
+
+In 3.6.5, raw list rows and Atlas search/explore evidence include `sourceLocator.command` and a deeper `sourceLocator.contextCommand`. Use those commands before claiming an event ID is missing, before quoting exact words, or before treating an Atlas summary as the source.
+
 `vectors: 0` does not mean memory is unavailable. It means dense vector search has no hot index yet; `memory recall` still has governed raw-ledger fallback. Broad inventory questions are expanded into structured cues such as `库存管理`, `在库`, `产品コード`, and `数量`; when compiled candidates miss those cues, prefer the raw ledger result and use its `sourceContext` for details. Check status with:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory status --project hermes --json
 ```
 
@@ -252,12 +272,13 @@ Default recall includes untagged and `collection:anchor` memory only. Ask for `c
 For host upkeep, inspect the self-map and run an explicit tick:
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory map --project hermes --json
 cogmem memory tick --project hermes --json
 cogmem memory bind --project hermes --json
 ```
 
-`memory tick` does not start a daemon. Use its `suggestedActions` to decide whether Hermes should run `dream tick`, `memory govern`, `episode repair`, entity review, re-embedding, or `memory bind` for unbound high-value raw events.
+`memory tick` does not start a daemon. Use its `suggestedActions` to decide whether Hermes should run `dream tick`, `memory govern`, `episode repair`, entity review, re-embedding, or `memory bind` for unbound high-value raw events. `undreamedRawCount` by itself is Raw Ledger coverage lag, not a sealed-episode job; do not loop `dream tick` unless `memory plan.nextActions` contains `dream_tick`. In 3.6.5, `memory bind` scans the historical Raw Ledger by cursor instead of only the latest page; resume large repairs with `--since <globalSeq>`.
 
 `memory map` also exposes Memory Binding and Graph Recall counters. Bindings connect high-value user raw events to stable topic/entity paths before promotion, fuse same-claim evidence into claim-key clusters, and create graph anchors for source drill-down. Correction bindings expose review flags and correction edges. Use graph recall hits for source drill-down and topic continuity only; do not treat bindings, clusters, or edges as verified facts, user preferences, or prompt instructions.
 
@@ -267,7 +288,7 @@ Explicit user clarification is organizational correction evidence, not an automa
 
 When importing OpenClaw-style session Markdown into a Hermes project, Cogmem accepts multiline bodies below empty role headers, collapses only adjacent exact export duplicates, and uses `# Session: ... UTC` as the chronological timestamp base rather than file mtime.
 
-After upgrading, rerun `cogmem connect hermes --workspace . --auto --force` and reload MCP so existing allow-lists and skill instructions receive the current tools and contracts.
+After upgrading, rerun `cogmem connect hermes --workspace . --auto --force --json` and reload MCP so existing allow-lists and skill instructions receive the current tools and contracts. In JSON output, follow only `nextCommands` for unattended agent work; unsafe operator or host steps such as interactive init and `/reload-mcp` are listed under `nextSteps` with `safeForAutomation=false`.
 
 ## Runtime Wiring
 

package/examples/hermes-backend/references/operations.md

@@ -1,4 +1,4 @@
-# Cogmem 3.6.4 Operations Reference for Hermes
+# Cogmem 3.6.5 Operations Reference for Hermes
 
 Read this file when installing, upgrading, importing, repairing, or operating Cogmem. `SKILL.md` contains the decision rules; this file records the operational commands.
 
@@ -11,9 +11,11 @@ Read this file when installing, upgrading, importing, repairing, or operating Co
 | Upgrade an existing database | `cogmem migrate` |
 | Import Hermes state/profile/sessions | `cogmem import-hermes` |
 | Import generic message JSONL | `cogmem episode import` |
+| Decide the next safe agent operation | `cogmem memory plan` |
 | Answer one direct memory question | `cogmem_recall` or `cogmem memory recall` |
 | See what memory exists or reconstruct history | Atlas `cogmem_graph_*` tools |
 | Quote exact source | `cogmem memory show` |
+| Audit ledger sequence ranges | `cogmem memory list --since/--until/--order` |
 | Resolve uncertain candidates | `cogmem_candidate_review` or `memory review` |
 | Promote ordinary candidates | `memory govern` |
 | Correct episode boundaries | `cogmem_episode_repair` or episode repair CLI |
@@ -74,7 +76,7 @@ cogmem doctor
 cogmem connect hermes --workspace . --auto --force --json
 ```
 
-The backed-up command upgrades 3.5.2 schema 24, an existing 3.6.0 schema-26 database, or a pre-release schema-25 test database to the 3.6.4 schema-27 state in one run and preserves Raw Ledger evidence. `--dry-run` is read-only and does not create `_schema_migrations`. Reload MCP after reconnecting.
+The backed-up command upgrades 3.5.2 schema 24, an existing 3.6.0 schema-26 database, or a pre-release schema-25 test database to the 3.6.5 schema-27 state in one run and preserves Raw Ledger evidence. `--dry-run` is read-only and does not create `_schema_migrations`. Reload MCP after reconnecting.
 
 ## Import Hermes memory
 
@@ -114,7 +116,9 @@ Use stable `externalMessageId` values for MCP append/import. If an MCP batch war
 After import, verify semantic maintenance in this exact 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
@@ -125,23 +129,27 @@ cogmem memory review --project hermes --id <candidate-id> --action approve --act
 cogmem memory recall --query "<verification question>" --project hermes --agent hermes --json
 ```
 
-`needs_confirmation` is not a Dream backlog. `memory govern` does not approve it. Use `memory review` with explicit evidence. Cogmem 3.6.4 skips import batch sealing for empty episode boundaries and marks legacy empty Dream jobs as skipped so one bad imported episode cannot block the queue. If `episode status` reports `episode_empty_*`, inspect the episode and repair boundaries with the audited episode repair commands.
+`memory plan` is the first agent-safe health and next-action command. It reports queue state, blocking and non-blocking actions, Dream backlog hints, vector fallback state, and safe commands. 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 candidates, `needs_confirmation`, and deferred review entries; use `--status` only for one explicit queue. `needs_confirmation` is not a Dream backlog. `memory govern` does not approve it. Use `memory review` with explicit evidence. Cogmem 3.6.4 and later skip import batch sealing for empty episode boundaries and mark legacy empty Dream jobs as skipped so one bad imported episode cannot block the queue. If `episode status` reports `episode_empty_*`, inspect the episode and repair boundaries with the audited episode repair commands.
 
 ## Inspect, recall, and drill down
 
 ```bash
+cogmem memory plan --project hermes --json
 cogmem memory status --project hermes --json
+cogmem memory candidates --project hermes --json
 cogmem memory candidates --project hermes --status needs_confirmation --json
 cogmem episode status --project hermes --json
 cogmem dream status --project hermes --json
 cogmem memory recall --query "<question>" --project hermes --agent hermes --json
+cogmem memory recall --query "<past discussion question>" --intent historical_discussion --project hermes --agent hermes --json
 cogmem explain-recall --query "<question>" --project hermes --agent hermes --json
 cogmem memory show --event <event-id> --before 2 --after 2 --json
+cogmem memory list --project hermes --since <globalSeq> --order asc --json
 ```
 
 JSON uses `cogmem.cli.v1`: object fields are top-level, arrays use `items`, and queue counters remain top-level. `vectors: 0` is not a recall failure; inspect `vectorState`.
 
-Read-only status/candidates use a lightweight SQLite path and should not require stopping the MCP server.
+Use `historical_discussion` for “did we discuss this before?”, “几个月前是不是聊过…”, “记忆黑盒”, and missing MCP memory cases. Raw list rows include `sourceLocator`; run the locator before quoting exact words or saying the event cannot be found. Read-only plan/status/candidates use a lightweight SQLite path and should not require stopping the MCP server.
 
 ## Memory Atlas as composable filters
 
@@ -166,7 +174,7 @@ Use MCP by question shape:
 - Direct fact: `cogmem_recall`.
 - Exact source: follow `evidenceEventIds` with `memory show`.
 
-Graph reads are pure and declared read-only/idempotent. Call `cogmem_graph_touch` only after using selected nodes. Overview display alone must not change future ranking. `evidenceTotal` is all known evidence; `evidenceReturned` is the bounded payload.
+Graph reads are pure and declared read-only/idempotent. Call `cogmem_graph_touch` only after using selected nodes. Overview display alone must not change future ranking. `evidenceTotal` is all known evidence; `evidenceReturned` is the bounded payload. Search/explore evidence includes `sourceLocator.command` and `sourceLocator.contextCommand`; use those locators before treating an Atlas summary as evidence.
 
 ## Candidate governance and review
 

package/examples/openclaw-backend/AGENTS.md

@@ -97,12 +97,14 @@ cogmem import-openclaw --workspace . --project openclaw --json
 ```
 
 Real non-JSON imports print source-level and embedding+ingest progress to stderr. Use `--json --progress` to keep JSON on stdout while streaming progress to stderr, or `--no-progress` when a wrapper needs quiet stderr.
-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 openclaw --json
 cogmem memory status --project openclaw --json
+cogmem memory candidates --project openclaw --json
 cogmem episode status --project openclaw --json
 cogmem dream status --project openclaw --json
 cogmem dream tick --project openclaw --mode auto --max-episodes 20 --json
@@ -110,9 +112,10 @@ cogmem memory candidates --project openclaw --status candidate --json
 cogmem memory govern --project openclaw --limit 100 --json
 cogmem memory candidates --project openclaw --status needs_confirmation --json
 cogmem memory review --project openclaw --id <candidate-id> --action approve --actor <operator> --reason "confirmed by user" --confirmation-event <user-event-id> --json
+cogmem memory recall --query "<verification question>" --project openclaw --agent openclaw --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.
 
 Import scope:
 
@@ -180,6 +183,8 @@ Recall behavior:
 - For each item with `sourceContext`, use event `label` values, optional `charRange` / `sourceRange`, and `sourceContext.window` to understand before/after semantics. Windows are chronological, exclude the anchor, and report overlap handling instead of relying on guesswork.
 - Use `cogmem memory map --project openclaw --json` 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 `CORRECTS` / `CONTRADICTS` edges; inspect the raw ledger before relying on them.
 - If `cogmem memory tick --project openclaw --json` suggests `bind_raw_events`, run `cogmem memory bind --project openclaw --json` to backfill imported or adapter-written raw user events into the binding graph.
+- For “did we discuss this before?”, “几个月前是不是聊过…”, “记忆黑盒”, or missing injection cases, run `cogmem memory recall --query "<past discussion question>" --intent historical_discussion --project openclaw --agent openclaw --json` before claiming no memory.
+- For ledger audits or resumable checks, use `cogmem memory list --project openclaw --since <globalSeq> --order asc --json`; list rows and Atlas search/explore evidence include `sourceLocator` commands in 3.6.5.
 
 Installing the workspace skill makes the kernel procedure discoverable to OpenClaw agents. Installing the local auto wrapper makes future turns call the memory kernel automatically:
 
@@ -187,7 +192,7 @@ Installing the workspace skill makes the kernel procedure discoverable to OpenCl
 cogmem connect openclaw --workspace . --auto --force
 ```
 
-This writes `<workspace>/extensions/cogmem-auto-memory/`, patches OpenClaw `plugins.load.paths`, and enables `before_prompt_build` and `agent_end` hooks. The wrapper calls `KernelAgentMemoryBackend` through `cogmem` public API via a Bun bridge; core does not import OpenClaw.
+This writes `<workspace>/extensions/cogmem-auto-memory/`, patches OpenClaw `plugins.load.paths`, and enables `before_prompt_build` and `agent_end` hooks. The wrapper calls `KernelAgentMemoryBackend` through `cogmem` public API via a Bun bridge; core does not import OpenClaw. In JSON output, follow only `nextCommands` for unattended agent work; unsafe operator or host steps such as interactive init and gateway restart are listed under `nextSteps` with `safeForAutomation=false`.
 
 The auto wrapper keeps OpenClaw native prompt/tool/skill context untouched. It prepends only Cogmem-owned context blocks:
 

package/examples/openclaw-backend/README.md

@@ -78,20 +78,23 @@ The Dream Worker processes sealed episodes and proposes candidate memories only.
 For host-owned inspection and upkeep:
 
 ```bash
+cogmem memory plan --project openclaw --json
 cogmem memory map --project openclaw --json
 cogmem memory tick --project openclaw --json
 cogmem memory bind --project openclaw --json
 ```
 
-Cogmem 3.6.4 keeps the 3.6.x Memory Atlas and OpenClaw reliability work, makes npm the default install and update channel, and prevents empty imported episodes from blocking Dream. The auto plugin uses one shared bridge/kernel lifecycle for graph exploration, evidence-bearing node/timeline drill-down, and recall, so OpenClaw does not need MCP for broad inventory/history questions. Atlas combines the query's actual project, time, topic, entity/target, memory-kind, action, and keyword conditions like table filters; no fixed entity-time-action tuple is required.
+Cogmem 3.6.5 keeps the 3.6.x Memory Atlas and OpenClaw reliability work, makes npm the default install and update channel, 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`. The auto plugin uses one shared bridge/kernel lifecycle for graph exploration, evidence-bearing node/timeline drill-down, and recall, so OpenClaw does not need MCP for broad inventory/history questions. Atlas combines the query's actual project, time, topic, entity/target, memory-kind, action, and keyword conditions like table filters; no fixed entity-time-action tuple is required.
 
 ```bash
+cogmem memory plan --project openclaw --json
 cogmem memory graph-explore --project openclaw --query "去年与 Hermes 有关的决定" --json
 cogmem memory graph-node --project openclaw --id <node-id> --include-evidence --json
 cogmem memory graph-path --project openclaw --from <node-id> --to <node-id> --json
+cogmem memory recall --query "几个月前我们是不是讨论过 Cogmem 的记忆黑盒" --intent historical_discussion --project openclaw --agent openclaw --json
 ```
 
-Use Atlas to locate a bounded source-backed slice, then use `memory show` for exact evidence. Graph reads do not change activation; explicitly touch only nodes the agent actually uses. Activation controls default visibility and decays during explicit maintenance; exact scoped facets can still revive cold memory without promoting or rewriting it.
+Use Atlas to locate a bounded source-backed slice, then use `memory show` or the returned `sourceLocator` for exact evidence. Graph reads do not change activation; explicitly touch only nodes the agent actually uses. Activation controls default visibility and decays during explicit maintenance; exact scoped facets can still revive cold memory without promoting or rewriting it.
 
 `memory tick` returns activation decay results and `suggestedActions`; it does not start a hidden daemon. If it reports `bind_raw_events`, run `memory bind` to attach imported or adapter-written raw user events to Memory Binding.
 
@@ -126,7 +129,9 @@ cogmem import-openclaw --workspace . --project openclaw
 After import:
 
 ```bash
+cogmem memory plan --project openclaw --json
 cogmem memory status --project openclaw --json
+cogmem memory candidates --project openclaw --json
 cogmem episode status --project openclaw --json
 cogmem dream status --project openclaw --json
 cogmem dream tick --project openclaw --mode auto --max-episodes 20 --json

package/examples/openclaw-backend/SKILL.md

@@ -176,12 +176,14 @@ cogmem import-openclaw --workspace . --project openclaw --json
 
 The importer is idempotent. Re-running it skips records already imported into the same memory database.
 Real non-JSON imports print source-level and embedding+ingest progress to stderr. Use `--json --progress` to keep JSON on stdout while streaming progress to stderr, or `--no-progress` when a wrapper needs quiet stderr.
-Cogmem 3.6.4 skips import batch sealing for empty episode boundaries and Dream skips legacy empty episode jobs instead of blocking the whole queue. If `episode status` shows `dreamError` beginning with `episode_empty`, inspect the source events and use episode repair instead of editing SQLite rows.
+Cogmem 3.6.4 and later skip import batch sealing for empty episode boundaries and Dream skips legacy empty episode jobs instead of blocking the whole queue. If `episode status` shows `dreamError` beginning with `episode_empty`, inspect the source events and use episode repair instead of editing SQLite rows.
 
 After import, run the maintenance loop in this order. `needs_confirmation` is a human review queue, not the Dream backlog, and `memory govern` promotes only ordinary `candidate` rows:
 
 ```bash
+cogmem memory plan --project openclaw --json
 cogmem memory status --project openclaw --json
+cogmem memory candidates --project openclaw --json
 cogmem episode status --project openclaw --json
 cogmem dream status --project openclaw --json
 cogmem dream tick --project openclaw --mode auto --max-episodes 20 --json
@@ -192,6 +194,8 @@ cogmem memory review --project openclaw --id <candidate-id> --action approve --a
 cogmem memory recall --query "<verification question>" --project openclaw --agent openclaw --json
 ```
 
+`memory plan` is the first agent-safe health and next-action command. It explains which queues block release, which work is non-blocking, whether vectors are empty but fallback recall is available, and what command should run next. 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 candidates, `needs_confirmation`, and deferred review entries; use `--status` only when the operator asks for one queue.
+
 Imported sources:
 
 - `USER.md` as user profile memory.
@@ -288,15 +292,17 @@ Useful intents:
 ```bash
 cogmem memory recall --query "上个会话我们聊了什么" --intent previous_session_summary --project openclaw --agent openclaw --session "$OPENCLAW_SESSION_ID" --exclude-session "$OPENCLAW_SESSION_ID" --json
 cogmem memory recall --query "我关于记忆黑盒问题的原话是什么" --intent forensic_quote --project openclaw --agent openclaw --json
+cogmem memory recall --query "几个月前我们是不是讨论过 Cogmem 的记忆黑盒" --intent historical_discussion --project openclaw --agent openclaw --json
 ```
 
 Use `items[].sourceContext` to understand what the user asked, how the agent answered, and nearby context. If the item has `sourceContext.locator.command`, run that command for a fuller local replay:
 
 ```bash
 cogmem memory show --event <eventId> --before 2 --after 2 --json
+cogmem memory list --project openclaw --since <globalSeq> --order asc --json
 ```
 
-For old memories, a `raw_ledger` result may come from full scoped ledger text fallback even when Chinese FTS has no direct hit. Equal matches prefer the original user event; use `sourceContext.after` to inspect the paired assistant response instead of preferring a later assistant retelling.
+For old memories, a `raw_ledger` result may come from full scoped ledger text fallback even when Chinese FTS has no direct hit. Equal matches prefer the original user event; use `sourceContext.after` to inspect the paired assistant response instead of preferring a later assistant retelling. In 3.6.5, raw list rows and Atlas search/explore evidence include `sourceLocator.command` and a deeper `sourceLocator.contextCommand`; use those before claiming exact source or event IDs are unavailable.
 
 Use collection routing for creative artifacts or drafts:
 
@@ -309,12 +315,13 @@ Default recall includes untagged and `collection:anchor` memory only. `collectio
 Use the self-map and explicit tick when the agent needs to understand or maintain the memory system:
 
 ```bash
+cogmem memory plan --project openclaw --json
 cogmem memory map --project openclaw --json
 cogmem memory tick --project openclaw --json
 cogmem memory bind --project openclaw --json
 ```
 
-`memory tick` decays activation and returns `suggestedActions`; it does not run a hidden daemon. If it suggests `bind_raw_events`, run `memory bind` to backfill high-value raw user events written by imports or adapters. The tick also supersedes `needs_confirmation` items older than the default 30-day review TTL with an explicit status reason; it preserves candidate evidence.
+`memory tick` decays activation and returns `suggestedActions`; it does not run a hidden daemon. If it suggests `bind_raw_events`, run `memory bind` to backfill high-value raw user events written by imports or adapters. In 3.6.5, `memory bind` scans the historical Raw Ledger by cursor instead of only the latest page; resume large repairs with `--since <globalSeq>`. The tick also supersedes `needs_confirmation` items older than the default 30-day review TTL with an explicit status reason; it preserves candidate evidence.
 
 `memory map` also exposes Memory Binding and Graph Recall counters. Bindings connect high-value user raw events to stable topic/entity paths before promotion, fuse same-claim evidence into claim-key clusters, and create graph anchors for source drill-down. Correction bindings add review flags and `CORRECTS` / `CONTRADICTS` edges. Use graph recall hits to inspect raw ledger history through `sourceContext`; do not treat bindings, clusters, or edges as verified facts, user preferences, or prompt instructions.
 
@@ -340,7 +347,7 @@ To make every future OpenClaw turn automatically use the memory kernel, install
 cogmem connect openclaw --workspace . --auto --force
 ```
 
-`--auto` writes `<workspace>/extensions/cogmem-auto-memory/`, patches `plugins.load.paths`, and enables `hooks.allowPromptInjection=true` and `hooks.allowConversationAccess=true` for the wrapper. The wrapper registers `before_prompt_build` for governed recall and `agent_end` for turn recording, then calls `KernelAgentMemoryBackend` through `cogmem` public API via a Bun bridge. Core does not import OpenClaw.
+`--auto` writes `<workspace>/extensions/cogmem-auto-memory/`, patches `plugins.load.paths`, and enables `hooks.allowPromptInjection=true` and `hooks.allowConversationAccess=true` for the wrapper. The wrapper registers `before_prompt_build` for governed recall and `agent_end` for turn recording, then calls `KernelAgentMemoryBackend` through `cogmem` public API via a Bun bridge. Core does not import OpenClaw. In JSON output, follow only `nextCommands` for unattended agent work; unsafe operator or host steps such as interactive init and gateway restart are listed under `nextSteps` with `safeForAutomation=false`.
 
 Queued remember is the default. `agent_end` appends a durable JSONL job under `.cogmem/queue/openclaw-remember.jsonl` and starts a singleton drainer, so Telegram or gateway responses are not blocked by embeddings, SQLite writes, or slow local models. Plugin 0.6.3 acquires the queue lock before opening Cogmem, recovers stale lock directories and stale `.processing` queue files older than `rememberDrainTimeoutMs`, writes `owner.json` lock metadata, and processes bounded batches controlled by `rememberDrainBatchSize` (default `20`). If a drain fails, the job is retried and then moved to a dead-letter file instead of being silently discarded.
 
@@ -409,7 +416,7 @@ For periodic curation, let the host timer wake one bounded tick:
 cogmem dream tick --project openclaw --mode auto --max-episodes 10 --json
 ```
 
-The timer does not force a full Dream run. `dream tick` inspects sealed episode jobs, chooses no work, micro, normal, or deep mode, then exits. Run `cogmem memory govern` separately; candidates stay pending until governance evaluates them.
+The timer does not force a full Dream run. `dream tick` inspects sealed episode jobs, chooses no work, micro, normal, or deep mode, then exits. `undreamedRawCount` by itself is Raw Ledger coverage lag, not a sealed-episode job; do not loop `dream tick` unless `memory plan.nextActions` contains `dream_tick`. Run `cogmem memory govern` separately; candidates stay pending until governance evaluates them.
 
 Episode classification is contextual but remains CPU-owned in the live hook. Short user replies are interpreted against whether the previous assistant turn was a proposal, question, or factual statement. Unknown turns default to an ambiguous review boundary; continuation needs explicit continuation language or topic/entity/project overlap. Background import or repair may use hybrid review, but normalized reviewer fields are allow-listed and cannot write belief, entity, temporal, prospective, topic, or governance state.
 
@@ -437,7 +444,8 @@ After package updates or config drift, repair the host wiring:
 
 ```bash
 cogmem connect openclaw --workspace . --auto --force
-cogmem doctor --fix --agent openclaw --workspace .
+cogmem doctor --fix --agent openclaw --workspace . --plugin-only --json
+openclaw gateway restart
 ```
 
 The wrapper maps OpenClaw behavior to core like this:

package/examples/openclaw-backend/references/operations.md

@@ -1,4 +1,4 @@
-# Cogmem 3.6.4 Operations Reference for OpenClaw
+# Cogmem 3.6.5 Operations Reference for OpenClaw
 
 Read this file when installing, upgrading, importing, repairing, or operating Cogmem. `SKILL.md` contains the decision rules; this file is the command reference.
 
@@ -14,9 +14,11 @@ Read this file when installing, upgrading, importing, repairing, or operating Co
 | Repair empty project scope from old imports | `cogmem repair project-scope` |
 | Import OpenClaw files | `cogmem import-openclaw` |
 | Import generic message JSONL | `cogmem episode import` |
+| Decide the next safe agent operation | `cogmem memory plan` |
 | Answer one direct memory question | `cogmem memory recall` or `cogmem_recall` |
 | See what memory exists or reconstruct history | Atlas `graph-*` commands/tools |
 | Quote exact source | `cogmem memory show` |
+| Audit ledger sequence ranges | `cogmem memory list --since/--until/--order` |
 | Inspect or resolve uncertain candidates | `memory candidates` then `memory review` |
 | Promote ordinary candidates | `memory govern` |
 | Inspect/process sealed episodes | `episode status`, `dream status`, `dream tick` |
@@ -83,7 +85,7 @@ openclaw gateway restart
 cogmem openclaw diagnose --workspace . --json
 ```
 
-The second command upgrades 3.5.2 schema 24, an existing 3.6.0 schema-26 database, or a pre-release schema-25 test database to the 3.6.4 schema-27 state in one run. It preserves Raw Ledger evidence. Keep the returned `backupPath` until verification passes. `--dry-run` is read-only and does not create `_schema_migrations`.
+The second command upgrades 3.5.2 schema 24, an existing 3.6.0 schema-26 database, or a pre-release schema-25 test database to the 3.6.5 schema-27 state in one run. It preserves Raw Ledger evidence. Keep the returned `backupPath` until verification passes. `--dry-run` is read-only and does not create `_schema_migrations`.
 
 After upgrading the package/database, refresh OpenClaw's generated plugin files. `doctor --plugin-only` avoids opening the Cogmem kernel, so it can repair stale `extensions/cogmem-auto-memory/index.js` and `bridge.mjs` even when an old drainer has SQLite busy. Use `connect --auto --force` when intentionally reinstalling the full integration and patching OpenClaw config:
 
@@ -137,7 +139,9 @@ cogmem import-openclaw --workspace . --project openclaw --json
 After import, verify semantic maintenance in this exact order:
 
 ```bash
+cogmem memory plan --project openclaw --json
 cogmem memory status --project openclaw --json
+cogmem memory candidates --project openclaw --json
 cogmem episode status --project openclaw --json
 cogmem dream status --project openclaw --json
 cogmem dream tick --project openclaw --mode auto --max-episodes 20 --json
@@ -148,7 +152,7 @@ cogmem memory review --project openclaw --id <candidate-id> --action approve --a
 cogmem memory recall --query "<verification question>" --project openclaw --agent openclaw --json
 ```
 
-`needs_confirmation` is not a Dream backlog. `memory govern` does not approve it. Use `memory review` with explicit evidence. Cogmem 3.6.4 skips import batch sealing for empty episode boundaries and marks legacy empty Dream jobs as skipped so one bad imported episode cannot block the queue. If `episode status` reports `episode_empty_*`, inspect the episode and repair boundaries with the audited episode repair commands.
+`memory plan` is the first agent-safe health and next-action command. It reports queue state, blocking and non-blocking actions, Dream backlog hints, vector fallback state, and safe commands. 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 candidates, `needs_confirmation`, and deferred review entries; use `--status` only for one explicit queue. `needs_confirmation` is not a Dream backlog. `memory govern` does not approve it. Use `memory review` with explicit evidence. Cogmem 3.6.4 and later skip import batch sealing for empty episode boundaries and mark legacy empty Dream jobs as skipped so one bad imported episode cannot block the queue. If `episode status` reports `episode_empty_*`, inspect the episode and repair boundaries with the audited episode repair commands.
 
 Pass explicit sources when discovery is not enough:
 
@@ -169,7 +173,9 @@ Use `--start-line`, `--end-line`, or `--max-lines` to split controlled runs. Pre
 ## Read-only inspection and JSON
 
 ```bash
+cogmem memory plan --project openclaw --json
 cogmem memory status --project openclaw --json
+cogmem memory candidates --project openclaw --json
 cogmem memory candidates --project openclaw --status needs_confirmation --json
 cogmem episode status --project openclaw --json
 cogmem dream status --project openclaw --json
@@ -177,7 +183,7 @@ cogmem dream status --project openclaw --json
 
 All documented JSON commands emit `schemaVersion: "cogmem.cli.v1"`. Object payload fields are top-level; arrays use `items`. Queue counters `candidate`, `promoted`, `needs_confirmation`, and `beliefs` are top-level. `memory status` explains whether recall remains available when `vectors` is zero.
 
-`memory status` and `memory candidates` use a lightweight read-only SQLite connection. They should remain usable while the OpenClaw plugin has a long-lived connection.
+`memory plan`, `memory status`, and `memory candidates` use a lightweight read-only SQLite connection. They should remain usable while the OpenClaw plugin has a long-lived connection.
 
 ## Recall and source drill-down
 
@@ -185,6 +191,7 @@ Use recall for a direct factual question:
 
 ```bash
 cogmem memory recall --query "<question>" --project openclaw --agent openclaw --json
+cogmem memory recall --query "<past discussion question>" --intent historical_discussion --project openclaw --agent openclaw --json
 cogmem explain-recall --query "<question>" --project openclaw --agent openclaw --json
 ```
 
@@ -192,8 +199,12 @@ Follow returned evidence, never a summary alone:
 
 ```bash
 cogmem memory show --event <event-id> --before 2 --after 2 --json
+cogmem memory list --project openclaw --since <globalSeq> --order asc --json
+cogmem memory list --project openclaw --since <globalSeq> --until <globalSeq> --order asc --json
 ```
 
+Use `historical_discussion` for “did we discuss this before?”, “几个月前是不是聊过…”, “记忆黑盒”, and missing prompt-injection cases. Raw list rows include `sourceLocator`; run the locator before quoting exact words or saying the event cannot be found.
+
 ## Memory Atlas
 
 Atlas combines whichever facets the question supplies, like table filters. Supported constraints include project, time range, topic, entity/target, memory kind, action, and ordinary text cues. Do not require a fixed entity + time + action tuple.
@@ -219,7 +230,7 @@ Use `--no-refresh` during lock incidents and `--refresh` when the operator wants
 
 Graph reads are pure: overview/search/explore do not brighten what they display. In MCP, call `cogmem_graph_touch` only after the agent actually selects or uses nodes. Activation changes visibility, never evidence or truth. Exact scoped facets may revive cold nodes.
 
-Every evidence result distinguishes `evidenceTotal` from `evidenceReturned` and includes an event ID plus a `memory show` drill-down command.
+Every evidence result distinguishes `evidenceTotal` from `evidenceReturned` and includes an event ID plus `sourceLocator.command` and `sourceLocator.contextCommand` drill-down commands. Use those locators before treating an Atlas summary as evidence.
 
 ## Candidate governance and review
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cogmem",
 
-  "version": "3.6.4",
+  "version": "3.6.5",
 
   "type": "module",
   "description": "cogmem — agent-native memory kernel for a single local-first AI agent",