cogmem 3.6.2 → 3.6.4

package/examples/hermes-backend/README.md

@@ -14,11 +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
+```
+
+Use `cogmem init` only as an interactive operator wizard, not as an unattended agent install step:
+
+```bash
+"$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.
@@ -67,6 +72,19 @@ Import:
 cogmem import-hermes --workspace . --project hermes
 ```
 
+After import:
+
+```bash
+cogmem memory status --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
@@ -89,7 +107,7 @@ Dream stores explicit user clarification as organizational correction evidence r
 
 After upgrades, reload MCP. Rerun `cogmem connect hermes --workspace . --auto --force` when MCP wiring, allow-listed tools, or the installed skill bundle changed.
 
-Cogmem 3.6.2 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.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.
 
 ## Runtime
 
@@ -147,7 +165,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.

package/examples/hermes-backend/SKILL.md

@@ -31,27 +31,56 @@ cogmem prospective due --project <projectId>
 
 ## Install
 
-Run from the Hermes workspace root:
+Run from the Hermes workspace root. Prefer a workspace-local npm dependency so Hermes and Cogmem upgrade together:
+
+```bash
+npm install cogmem@latest --save
+COGMEM="./node_modules/.bin/cogmem"
+"$COGMEM" doctor
+"$COGMEM" connect hermes --workspace . --auto --force --json
+```
+
+If the workspace already has Cogmem installed locally, keep using the local binary. If there is no local binary but a global install exists, use global. If neither exists, install first:
+
+```bash
+if [ -x ./node_modules/.bin/cogmem ]; then
+  COGMEM="./node_modules/.bin/cogmem"
+elif command -v cogmem >/dev/null 2>&1; then
+  COGMEM="cogmem"
+else
+  npm install cogmem@latest --save
+  COGMEM="./node_modules/.bin/cogmem"
+fi
+```
+
+Global npm is also supported when the operator wants one CLI for every workspace:
+
+```bash
+npm install -g cogmem@latest
+COGMEM="cogmem"
+"$COGMEM" connect hermes --workspace . --auto --force --json
+```
+
+The one-line installer remains available for machines that do not already have Bun. Use `COGMEM_SKIP_INIT=1` for agent-run installs so the installer does not start the interactive wizard:
 
 ```bash
 COGMEM_SKIP_INIT=1 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
-cogmem init --yes --agent hermes
-cogmem doctor
-cogmem connect hermes --workspace . --auto --force
+COGMEM="cogmem"
+"$COGMEM" connect hermes --workspace . --auto --force --json
 ```
 
-Use project-local config only when this workspace needs isolation:
+Do not run `cogmem init` as an unattended agent action. `cogmem init` is an interactive configuration wizard. Use it only when an operator is present or explicitly asks for a guided setup:
 
 ```bash
-cogmem init --yes --agent hermes --scope project
+"$COGMEM" init --agent hermes --scope project
 ```
 
-The default install creates:
+Hermes workspaces should normally use project-local config when the workspace owns its memory:
 
 ```text
-~/.cogmem/config.toml
-~/.cogmem/memory.db
-~/.cogmem/snapshots/
+.cogmem/config.toml
+.cogmem/memory.db
+.cogmem/snapshots/
 ```
 
 To embed imported memories with a local quantized model, run Ollama locally and configure the kernel before importing:
@@ -98,7 +127,7 @@ cogmem update --yes
 # Manual equivalent: cogmem migrate --yes --backup
 ```
 
-`cogmem update --yes` installs `cogmem@latest` from npm, runs the newly installed backed-up migration with the resolved config, and then reports that the Hermes MCP server or agent host must be reloaded. Agents should inspect `cogmem update --dry-run --json` or `cogmem migrate --dry-run --json` when an operator wants a preview. Schema migration preserves Raw Ledger events; it updates governed projections and indexes only.
+`cogmem update --yes` installs `cogmem@latest` from npm, runs the newly installed backed-up migration with the resolved config, and then reports that the Hermes MCP server or agent host must be reloaded. For npm global installs, `cogmem update --yes` resolves to `npm install -g cogmem@latest` instead of writing into the current directory. Agents should inspect `cogmem update --dry-run --json` or `cogmem migrate --dry-run --json` when an operator wants a preview. Schema migration preserves Raw Ledger events; dry-run is read-only and updates governed projections and indexes only during apply.
 
 Default Hermes memory contract:
 
@@ -151,12 +180,20 @@ 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.
 
-Run the curator/governance loop under host supervision after import and during normal use:
+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.
+
+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 status --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 <distinct-user-event-id> --json
+cogmem memory recall --query "<verification question>" --project hermes --agent hermes --json
 ```
 
 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.
@@ -296,8 +333,8 @@ Do not edit `~/.hermes/config.yaml` to point `memory.provider` at `cogmem` until
 ```yaml
 mcp_servers:
   cogmem:
-    command: "/resolved/path/to/cogmem-mcp"
-    args: []
+    command: "/resolved/path/to/cogmem"
+    args: ["mcp"]
     enabled: true
     tools:
       include:
@@ -329,7 +366,7 @@ mcp_servers:
         - cogmem_prospective
 ```
 
-The command path is resolved by `cogmem connect hermes`: it uses `COGMEM_MCP_BIN` when explicitly set, then a workspace-local `node_modules/.bin/cogmem-mcp` when present, then the globally linked `cogmem-mcp` from the one-line installer.
+The command path is resolved by `cogmem connect hermes`: it uses `COGMEM_BIN` when explicitly set, then a workspace-local `node_modules/.bin/cogmem`, then global `cogmem`, and passes `mcp` as the first argument. `COGMEM_MCP_BIN` and `cogmem-mcp` remain compatibility paths for existing host configs.
 
 When Hermes calls `cogmem_recall`, it should pass `projectId: "hermes"` and may omit `agentId`; the MCP bridge infers `agentId` from `projectId`. The returned `items` use the same shape as `cogmem memory recall --project hermes --agent hermes --json`, including `raw_ledger` items, labeled `sourceContext` events, `sourceContext.window`, and `sourceContext.locator.command` when vectors are empty or compiled evidence misses.
 

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

@@ -1,4 +1,4 @@
-# Cogmem 3.6.2 Operations Reference for Hermes
+# Cogmem 3.6.4 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.
 
@@ -21,14 +21,35 @@ Read this file when installing, upgrading, importing, repairing, or operating Co
 
 ## Install, connect, and reload
 
+Recommended workspace-local npm 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
-cogmem connect hermes --workspace . --auto --force --json
+npm install cogmem@latest --save
+COGMEM="./node_modules/.bin/cogmem"
+"$COGMEM" doctor
+"$COGMEM" connect hermes --workspace . --auto --force --json
+```
+
+Use this resolver in agent-run scripts:
+
+```bash
+if [ -x ./node_modules/.bin/cogmem ]; then
+  COGMEM="./node_modules/.bin/cogmem"
+elif command -v cogmem >/dev/null 2>&1; then
+  COGMEM="cogmem"
+else
+  npm install cogmem@latest --save
+  COGMEM="./node_modules/.bin/cogmem"
+fi
+```
+
+Use `npm install -g cogmem@latest` only when the operator wants a global CLI. The one-line installer is still supported with `COGMEM_SKIP_INIT=1`, but do not run `cogmem init` unattended. `cogmem init` is an interactive wizard; run it only with an operator present:
+
+```bash
+"$COGMEM" init --agent hermes --scope project
 ```
 
-Then run `/reload-mcp` inside Hermes. `connect --auto` installs this skill bundle and updates the Hermes MCP allow-list; it does not claim a native `memory.provider` integration.
+Then run `/reload-mcp` inside Hermes. `connect --auto` installs this skill bundle and updates the Hermes MCP allow-list; it does not claim a native `memory.provider` integration. New configs start the bridge as `cogmem mcp`; `cogmem-mcp` remains a compatibility bin for older host configs.
 
 ## Upgrade and migrate
 
@@ -38,7 +59,7 @@ For normal upgrades, use one command:
 cogmem update --yes
 ```
 
-`cogmem update --yes` installs `cogmem@latest` from npm, then runs post-install work through the newly installed local CLI. With a valid config it runs `cogmem migrate --yes --backup --config <config>` and reports that the Hermes MCP server or agent host must be reloaded.
+`cogmem update --yes` installs `cogmem@latest` from npm, then runs post-install work through the newly installed CLI. For npm global installs it uses `npm install -g cogmem@latest`; for the one-line installer it updates `~/.cogmem/pkg`; for a workspace dependency it updates that workspace. With a valid config it runs `cogmem migrate --yes --backup --config <config>` and reports that the Hermes MCP server or agent host must be reloaded.
 
 Preview the package and migration plan without writing:
 
@@ -53,7 +74,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.2 schema-27 state in one run and preserves Raw Ledger evidence. 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.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.
 
 ## Import Hermes memory
 
@@ -90,6 +111,22 @@ cogmem episode import --project hermes --session import-2026 --source-agent herm
 
 Use stable `externalMessageId` values for MCP append/import. If an MCP batch warns `auto_identity_not_safe_across_split_batches`, assign IDs before splitting or retrying.
 
+After import, verify semantic maintenance in this exact order:
+
+```bash
+cogmem memory status --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 <distinct-user-event-id> --json
+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.
+
 ## Inspect, recall, and drill down
 
 ```bash

package/examples/openclaw-backend/AGENTS.md

@@ -15,12 +15,17 @@ This writes `<workspace>/skills/cogmem-memory/SKILL.md`, which OpenClaw discover
 Run from the OpenClaw workspace root:
 
 ```bash
-COGMEM_SKIP_INIT=1 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
-cogmem init --yes --agent openclaw --scope project
-cogmem doctor --fix --agent openclaw --workspace .
-cogmem connect openclaw --workspace .
-cogmem connect openclaw --workspace . --auto --force
-cogmem openclaw diagnose --workspace . --json
+npm install cogmem@latest --save
+COGMEM="./node_modules/.bin/cogmem"
+"$COGMEM" doctor
+"$COGMEM" connect openclaw --workspace . --auto --force --json
+"$COGMEM" openclaw diagnose --workspace . --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 openclaw --scope project
 ```
 
 The OpenClaw workspace install creates:
@@ -92,6 +97,22 @@ 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.
+
+After import, use this order:
+
+```bash
+cogmem memory status --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
+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
+```
+
+`needs_confirmation` is not the Dream backlog. `memory govern` does not approve it; use `memory review` with explicit evidence.
 
 Import scope:
 

package/examples/openclaw-backend/README.md

@@ -9,11 +9,16 @@ Belief Graph writes keep ownership and evidence roles. OpenClaw may record assis
 ## Install
 
 ```bash
-COGMEM_SKIP_INIT=1 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
-cogmem init --yes --agent openclaw --scope project
-cogmem doctor --fix --agent openclaw --workspace .
-cogmem connect openclaw --workspace .
-cogmem connect openclaw --workspace . --auto --force
+npm install cogmem@latest --save
+COGMEM="./node_modules/.bin/cogmem"
+"$COGMEM" doctor
+"$COGMEM" connect openclaw --workspace . --auto --force --json
+```
+
+Use `cogmem init` only as an interactive operator wizard, not as an unattended agent install step:
+
+```bash
+"$COGMEM" init --agent openclaw --scope project
 ```
 
 ## Local Quantized Embeddings
@@ -53,7 +58,7 @@ Then run:
 
 ```bash
 cogmem episode status --project openclaw --json
-cogmem dream tick --project openclaw --mode auto --json
+cogmem dream tick --project openclaw --mode auto --max-episodes 20 --json
 cogmem memory govern --project openclaw --json
 cogmem memory candidates --project openclaw --status candidate --json
 ```
@@ -78,7 +83,7 @@ cogmem memory tick --project openclaw --json
 cogmem memory bind --project openclaw --json
 ```
 
-Cogmem 3.6.2 keeps the 3.6.x Memory Atlas and OpenClaw reliability work, then makes npm the default install and update channel. 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.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.
 
 ```bash
 cogmem memory graph-explore --project openclaw --query "去年与 Hermes 有关的决定" --json
@@ -118,6 +123,19 @@ Import:
 cogmem import-openclaw --workspace . --project openclaw
 ```
 
+After import:
+
+```bash
+cogmem memory status --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
+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
+```
+
 Single source files and batches can be imported explicitly:
 
 ```bash
@@ -206,7 +224,7 @@ To make future OpenClaw turns automatically recall and record memory, run:
 cogmem connect openclaw --workspace . --auto --force
 ```
 
-`--auto` installs `<workspace>/extensions/cogmem-auto-memory/`, patches OpenClaw `plugins.load.paths`, and enables a local plugin wrapper with `before_prompt_build` and `agent_end` hooks. The wrapper calls `KernelAgentMemoryBackend` through the public `cogmem` API via a Bun bridge; core still does not import OpenClaw. Plugin 0.6.2 uses singleton queue/spawn locks, stale-lock recovery, and bounded remember batches so queued `agent_end` recording does not hold SQLite open longer than necessary.
+`--auto` installs `<workspace>/extensions/cogmem-auto-memory/`, patches OpenClaw `plugins.load.paths`, and enables a local plugin wrapper with `before_prompt_build` and `agent_end` hooks. The wrapper calls `KernelAgentMemoryBackend` through the public `cogmem` API via a Bun bridge; core still does not import OpenClaw. Plugin 0.6.3 uses singleton queue/spawn locks, stale-lock and stale-processing recovery, and bounded remember batches so queued `agent_end` recording does not hold SQLite open longer than necessary.
 
 The wrapper does not rewrite OpenClaw's native prompt, tool instructions, skills, or conversation order. It only prepends Cogmem-owned blocks:
 

package/examples/openclaw-backend/SKILL.md

@@ -31,22 +31,51 @@ cogmem prospective due --project <projectId>
 
 ## Install
 
-Run from the OpenClaw workspace root:
+Run from the OpenClaw workspace root. Prefer a workspace-local npm dependency so OpenClaw and Cogmem upgrade together:
+
+```bash
+npm install cogmem@latest --save
+COGMEM="./node_modules/.bin/cogmem"
+"$COGMEM" doctor
+"$COGMEM" connect openclaw --workspace . --auto --force --json
+```
+
+If the workspace already has Cogmem installed locally, keep using the local binary. If there is no local binary but a global install exists, use global. If neither exists, install first:
+
+```bash
+if [ -x ./node_modules/.bin/cogmem ]; then
+  COGMEM="./node_modules/.bin/cogmem"
+elif command -v cogmem >/dev/null 2>&1; then
+  COGMEM="cogmem"
+else
+  npm install cogmem@latest --save
+  COGMEM="./node_modules/.bin/cogmem"
+fi
+```
+
+Global npm is also supported when the operator wants one CLI for every workspace:
+
+```bash
+npm install -g cogmem@latest
+COGMEM="cogmem"
+"$COGMEM" connect openclaw --workspace . --auto --force --json
+```
+
+The one-line installer remains available for machines that do not already have Bun. Use `COGMEM_SKIP_INIT=1` for agent-run installs so the installer does not start the interactive wizard:
 
 ```bash
 COGMEM_SKIP_INIT=1 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
-cogmem init --yes --agent openclaw --scope project
-cogmem doctor
-cogmem connect openclaw --workspace . --auto --force
+COGMEM="cogmem"
+"$COGMEM" connect openclaw --workspace . --auto --force --json
 ```
 
-This creates project-local kernel config and storage under `.cogmem/`, which is the recommended OpenClaw workspace setup.
+Do not run `cogmem init` as an unattended agent action. `cogmem init` is an interactive configuration wizard. Use it only when an operator is present or explicitly asks for a guided setup:
 
 ```bash
-cogmem init --yes --agent openclaw --scope project
+"$COGMEM" init --agent openclaw --scope project
 ```
 
-The install creates:
+OpenClaw workspaces should normally use project-local kernel config and storage:
 
 ```text
 .cogmem/config.toml
@@ -98,7 +127,7 @@ cogmem update --yes
 # Manual equivalent: cogmem migrate --yes --backup && cogmem doctor --fix --agent openclaw --workspace . --plugin-only
 ```
 
-`cogmem update --yes` installs `cogmem@latest` from npm, runs the newly installed backed-up migration with the resolved config, refreshes OpenClaw's generated plugin files when the integration is configured, and then reports that the OpenClaw gateway or agent host must be restarted. Agents should inspect `cogmem update --dry-run --json` or `cogmem migrate --dry-run --json` when an operator wants a preview. Schema migration preserves Raw Ledger events; it updates governed projections and indexes only.
+`cogmem update --yes` installs `cogmem@latest` from npm, runs the newly installed backed-up migration with the resolved config, refreshes OpenClaw's generated plugin files when the integration is configured, and then reports that the OpenClaw gateway or agent host must be restarted. For npm global installs, `cogmem update --yes` resolves to `npm install -g cogmem@latest` instead of writing into the current directory. Agents should inspect `cogmem update --dry-run --json` or `cogmem migrate --dry-run --json` when an operator wants a preview. Schema migration preserves Raw Ledger events; dry-run is read-only and updates governed projections and indexes only during apply.
 
 After any 3.5.2 -> 3.6.x OpenClaw upgrade, refresh the generated OpenClaw plugin files. Use the plugin-only path first when OpenClaw is misbehaving, because it does not open the Cogmem database:
 
@@ -147,6 +176,21 @@ 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.
+
+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 status --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
+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 <distinct-user-event-id> --json
+cogmem memory recall --query "<verification question>" --project openclaw --agent openclaw --json
+```
 
 Imported sources:
 
@@ -298,7 +342,7 @@ 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.
 
-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.2 acquires the queue lock before opening Cogmem, recovers stale lock directories 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.
+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.
 
 When automatic memory recording looks stuck, do not delete queue files first. Diagnose the plugin and locks:
 
@@ -309,6 +353,8 @@ cat .cogmem/queue/openclaw-remember.jsonl.lock/owner.json 2>/dev/null || true
 cat .cogmem/queue/openclaw-remember.jsonl.spawn.lock/owner.json 2>/dev/null || true
 ```
 
+`openclaw diagnose` reports pending queue lines, dead-letter lines, active lock metadata, spawn-lock metadata, and stale `.processing` files. Use that JSON before deleting anything manually.
+
 If `plugin.current=false`, refresh without opening the database:
 
 ```bash
@@ -349,7 +395,7 @@ Run curation manually or from a host-owned schedule:
 
 ```bash
 cogmem episode status --project openclaw --json
-cogmem dream tick --project openclaw --mode auto --json
+cogmem dream tick --project openclaw --mode auto --max-episodes 20 --json
 cogmem memory govern --project openclaw --json
 cogmem memory candidates --project openclaw --status candidate --json
 ```
@@ -385,7 +431,7 @@ Explicit user clarification may create an organizational `correction` record. Do
 
 OpenClaw session exports may place the body below an empty `user:` or `assistant:` header and may repeat an assistant block exactly. Import accepts that layout, collapses only adjacent exact export duplicates, and uses the `# Session: ... UTC` heading as the chronological timestamp base. Do not rewrite the file solely to make it importable.
 
-If rejected provider diagnostics mention invalid memory-model output but later curation works, seal or repair the affected episode, run `cogmem dream tick --project openclaw --mode auto --json`, then run `cogmem memory govern --project openclaw --json`; recovered provider runs mark older provider diagnostics as `superseded`.
+If rejected provider diagnostics mention invalid memory-model output but later curation works, seal or repair the affected episode, run `cogmem dream tick --project openclaw --mode auto --max-episodes 20 --json`, then run `cogmem memory govern --project openclaw --json`; recovered provider runs mark older provider diagnostics as `superseded`.
 
 After package updates or config drift, repair the host wiring:
 
@@ -431,9 +477,11 @@ openclaw gateway restart
 If the OpenClaw environment exposes an MCP client, use the core MCP bridge instead of writing a native plugin first:
 
 ```bash
-cogmem-mcp
+cogmem mcp
 ```
 
+`cogmem-mcp` remains a compatibility bin for older host configs.
+
 Expose these tools to the agent:
 
 - `cogmem_remember_turn`

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

@@ -1,4 +1,4 @@
-# Cogmem 3.6.2 Operations Reference for OpenClaw
+# Cogmem 3.6.4 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.
 
@@ -26,11 +26,32 @@ Read this file when installing, upgrading, importing, repairing, or operating Co
 
 ## Install and connect
 
+Recommended workspace-local npm install:
+
 ```bash
-COGMEM_SKIP_INIT=1 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
-cogmem init --yes --agent openclaw --scope project
-cogmem doctor
-cogmem connect openclaw --workspace . --auto --force --json
+npm install cogmem@latest --save
+COGMEM="./node_modules/.bin/cogmem"
+"$COGMEM" doctor
+"$COGMEM" connect openclaw --workspace . --auto --force --json
+```
+
+Use this resolver in agent-run scripts:
+
+```bash
+if [ -x ./node_modules/.bin/cogmem ]; then
+  COGMEM="./node_modules/.bin/cogmem"
+elif command -v cogmem >/dev/null 2>&1; then
+  COGMEM="cogmem"
+else
+  npm install cogmem@latest --save
+  COGMEM="./node_modules/.bin/cogmem"
+fi
+```
+
+Use `npm install -g cogmem@latest` only when the operator wants a global CLI. The one-line installer is still supported with `COGMEM_SKIP_INIT=1`, but do not run `cogmem init` unattended. `cogmem init` is an interactive wizard; run it only with an operator present:
+
+```bash
+"$COGMEM" init --agent openclaw --scope project
 ```
 
 Restart the OpenClaw Gateway after plugin or config changes. `connect --auto` installs the direct OpenClaw hook bridge; OpenClaw does not need MCP for automatic recall, recording, or Atlas navigation.
@@ -44,7 +65,7 @@ cogmem update --yes
 openclaw gateway restart
 ```
 
-`cogmem update --yes` installs `cogmem@latest` from npm, then runs post-install work through the newly installed local CLI. With a valid config it runs `cogmem migrate --yes --backup --config <config>`. When OpenClaw integration is enabled, it also runs `cogmem doctor --fix --agent openclaw --plugin-only --config <config> --workspace <workspace>` so stale generated plugin files are replaced before restart.
+`cogmem update --yes` installs `cogmem@latest` from npm, then runs post-install work through the newly installed CLI. For npm global installs it uses `npm install -g cogmem@latest`; for the one-line installer it updates `~/.cogmem/pkg`; for a workspace dependency it updates that workspace. With a valid config it runs `cogmem migrate --yes --backup --config <config>`. When OpenClaw integration is enabled, it also runs `cogmem doctor --fix --agent openclaw --plugin-only --config <config> --workspace <workspace>` so stale generated plugin files are replaced before restart.
 
 Preview the package, migration, and plugin-refresh plan without writing:
 
@@ -62,7 +83,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.2 schema-27 state in one run. It preserves Raw Ledger evidence. Keep the returned `backupPath` until verification passes.
+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`.
 
 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:
 
@@ -75,15 +96,16 @@ Use `cogmem openclaw diagnose --workspace . --json` when automatic memory blocks
 - `plugin.current=false`: generated files are stale; run plugin-only fix and restart gateway.
 - no `audit.lastBeforePromptBuild`: plugin is not loaded or the hook did not fire.
 - `audit.lastBeforePromptBuild.action=error`: bridge or DB failure; inspect `reason`, `bridgeCommand`, and `dbLocked`.
-- `action=inject` but no visible block: inspect `returnedInjectionShape`. Plugin 0.6.2 returns `prependContext`, `context`, and `promptPrefix`; if OpenClaw still ignores all three, the host hook contract changed and the OpenClaw plugin API must be checked before blaming recall.
+- `action=inject` but no visible block: inspect `returnedInjectionShape`. Plugin 0.6.3 returns `prependContext`, `context`, and `promptPrefix`; if OpenClaw still ignores all three, the host hook contract changed and the OpenClaw plugin API must be checked before blaming recall.
 
-Plugin 0.6.2 queue behavior:
+Plugin 0.6.3 queue behavior:
 
 - `agent_end` only appends durable JSONL jobs, then starts at most one drainer through queue/spawn locks.
 - `drain-remember-queue` acquires the queue lock before opening Cogmem or SQLite. A second drainer exits without opening the DB.
-- Stale `.cogmem/queue/openclaw-remember.jsonl.lock` and `.spawn.lock` directories older than `rememberDrainTimeoutMs` are recovered automatically and carry `owner.json` metadata for diagnosis.
+- Stale `.cogmem/queue/openclaw-remember.jsonl.lock`, `.spawn.lock`, and `.processing` files older than `rememberDrainTimeoutMs` are recovered automatically and carry enough metadata for diagnosis.
 - `rememberDrainBatchSize` defaults to `20`, so a busy workspace drains bounded batches and releases DB handles quickly. Lower it temporarily if OpenClaw shares a slow SQLite disk.
 - Failed jobs retry up to `rememberMaxAttempts`; exhausted jobs move to `.dead.jsonl`.
+- `cogmem openclaw diagnose --workspace . --json` reports pending queue lines, dead-letter lines, lock owners, spawn-lock owners, and `.processing` files.
 
 If the queue is not draining, diagnose before deleting files:
 
@@ -112,6 +134,22 @@ cogmem import-openclaw --workspace . --project openclaw --dry-run --json
 cogmem import-openclaw --workspace . --project openclaw --json
 ```
 
+After import, verify semantic maintenance in this exact order:
+
+```bash
+cogmem memory status --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
+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 <distinct-user-event-id> --json
+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.
+
 Pass explicit sources when discovery is not enough:
 
 ```bash
@@ -257,6 +295,7 @@ cogmem prospective confirm --project openclaw --id <candidate-id> --evidence <us
 ## MCP and direct-plugin choice
 
 - OpenClaw automatic hooks use the direct bridge installed by `connect --auto`.
+- Start the MCP bridge with `cogmem mcp`; `cogmem-mcp` remains a compatibility bin for older host configs.
 - Use MCP tools when an agent host supports MCP and needs explicit graph/review operations.
 - Broad inventory/history: `cogmem_graph_explore`.
 - Known node: `cogmem_graph_search`, then `cogmem_graph_node`.