cogmem 3.6.3 → 3.6.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 3.6.4
+
+- Fixed OpenClaw/Hermes imports so empty imported episode boundaries are not batch-sealed into Dream work, and mature empty soft seals no longer abort `dream tick`.
+- Added Dream queue cleanup for legacy empty episode jobs so one bad upgraded/imported episode is marked skipped and does not consume maintenance batch slots.
+- Updated OpenClaw and Hermes auto-installed skills, runbooks, and README examples to prefer npm workspace-local installs, reserve `cogmem init` for interactive operator setup, and document the full import -> dream -> candidate governance -> `needs_confirmation` review flow.
+- Standardized MCP guidance on `cogmem mcp` for new Hermes/OpenClaw host configs while keeping `cogmem-mcp` as a compatibility bin for existing configs.
+
 ## 3.6.3
 
 - Added a GitHub Release `published` workflow for npm Trusted Publishing with OIDC provenance, full tests, build, version-tag validation, and package dry-run verification before `npm publish`.

package/README.md

@@ -11,15 +11,24 @@ It is not a knowledge-base app, a note-taking app, a vector RAG wrapper, an Obsi
 
 ## Status
 
-Current version: `3.6.3`
+Current version: `3.6.4`
 
 Distribution: npm registry. GitHub remains the source mirror and hosts this installer, but package install and upgrade resolve `cogmem` from npm by default.
 
+Default workspace install:
+
+```bash
+npm install cogmem@latest --save
+./node_modules/.bin/cogmem doctor
+```
+
+One-line installer for machines that need Bun bootstrapping:
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
 ```
 
-The installer:
+The one-line installer:
 
 1. Ensures Bun is available.
 2. Installs `cogmem@latest` from the npm registry into `~/.cogmem/pkg`.
@@ -158,10 +167,11 @@ High-dimensional vectors grow quickly. Prefer `raw_then_dream` or `selective_com
 
 ## Quick Start
 
-Install globally:
+Install into an agent workspace with npm:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
+npm install cogmem@latest --save
+./node_modules/.bin/cogmem doctor
 ```
 
 Or install into an existing Bun workspace:
@@ -185,6 +195,19 @@ npm install -g cogmem@latest
 cogmem init
 ```
 
+Or use the one-line installer for machines that do not already have Bun:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
+```
+
+For agent-run installs, skip the interactive wizard and connect the host explicitly:
+
+```bash
+COGMEM_SKIP_INIT=1 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
+cogmem doctor
+```
+
 Validate configuration:
 
 ```bash
@@ -206,7 +229,7 @@ cogmem migrate --dry-run --json
 
 For a manual migration, run `cogmem migrate --yes --backup`. The migration runner adopts the existing `_meta.schema_version`, applies only later idempotent migrations, preserves Raw Ledger rows, and creates a timestamped, transaction-consistent standalone database backup before changing an on-disk database. The backup includes committed SQLite WAL pages instead of copying only the main database file.
 
-Upgrade a 3.5.2 database, a 3.6.0 database, or a pre-release schema-25 test database into the 3.6.3 schema set with one command:
+Upgrade a 3.5.2 database, a 3.6.0 database, or a pre-release schema-25 test database into the 3.6.4 schema set with one command:
 
 ```bash
 cogmem migrate --yes --backup --json
@@ -237,9 +260,14 @@ cogmem repair project-scope --from "" --to openclaw --apply --json
 Inspect and conditionally process sealed conversation episodes:
 
 ```bash
+cogmem memory status --project my-agent --json
 cogmem episode status --project my-agent --json
-cogmem dream tick --project my-agent --mode auto --json
+cogmem dream status --project my-agent --json
+cogmem dream tick --project my-agent --mode auto --max-episodes 20 --json
+cogmem memory candidates --project my-agent --status candidate --json
 cogmem memory govern --project my-agent --json
+cogmem memory candidates --project my-agent --status needs_confirmation --json
+cogmem memory review --project my-agent --id <candidate-id> --action approve --actor <operator> --reason "confirmed" --confirmation-event <user-event-id> --json
 ```
 
 For a host timer, call `dream tick`; the timer only wakes the scheduler. An empty backlog performs no Dream work:
@@ -250,7 +278,7 @@ cogmem dream tick --project my-agent --mode auto --max-episodes 10 --json
 
 Raw events are always written first. `KernelAgentMemoryBackend` and OpenClaw plugin 0.6.3 assemble live turns automatically. The foreground hook uses deterministic rules and previous assistant/user context; background import and repair paths may use the advisory hybrid classifier. Advisory output is allow-listed and cannot directly mutate durable memory. Unknown turns now fail closed as ambiguous. Continuation requires explicit continuation language or project/topic/entity/semantic overlap; Cogmem does not route domains with an expanding hard-coded keyword dictionary.
 
-Hookless MCP agents can call `cogmem_episode_append` or bounded `cogmem_episode_import`. Existing OpenClaw/Hermes import commands use stable content identities and the same episode schema. Low-confidence imported groups soft-seal for review unless an operator explicitly forces sealing. Episode semantic summaries and closure receipts are control hints, never durable evidence; every Dream candidate must cite a non-empty subset of the episode's raw event IDs and still pass CPU governance.
+Hookless MCP agents can call `cogmem_episode_append` or bounded `cogmem_episode_import`. Existing OpenClaw/Hermes import commands use stable content identities and the same episode schema. Low-confidence imported groups soft-seal for review unless an operator explicitly forces sealing. 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. Episode semantic summaries and closure receipts are control hints, never durable evidence; every Dream candidate must cite a non-empty subset of the episode's raw event IDs and still pass CPU governance.
 
 User-shaped topic state is project-scoped. Explicit user operations become active and auditable; model-proposed topics, aliases, and relations remain candidates. Use MCP `cogmem_topic_list` to inspect nodes, `cogmem_topic_operate` to create, rename, alias, move, merge, split, or relate topics, and `cogmem_topic_rollback` to reverse an audited operation. Alias collisions fail closed as `needs_review`; applications can also call `TopicGovernance.rollback()` through the public API.
 
@@ -482,8 +510,8 @@ Hermes integration is MCP-based in this release. cogmem does not claim to be a n
 Install the skill and patch Hermes MCP config:
 
 ```bash
-cogmem init --agent hermes
-cogmem connect hermes --workspace /path/to/hermes/workspace --auto --force
+npm install cogmem@latest --save
+./node_modules/.bin/cogmem connect hermes --workspace /path/to/hermes/workspace --auto --force
 ```
 
 This installs the agent-facing skill bundle at:
@@ -501,6 +529,8 @@ With `--auto`, it adds or updates a `cogmem` MCP server entry in:
 ~/.hermes/config.yaml
 ```
 
+New Hermes configs start the server with `cogmem mcp`. Existing `cogmem-mcp` entries remain supported and are updated in place for tool allow-list changes.
+
 Then reload MCP inside Hermes:
 
 ```text
@@ -688,7 +718,7 @@ For Hermes after an update, reload the MCP server or restart the agent host. If
 cogmem connect hermes --workspace /path/to/hermes/workspace --auto --force
 ```
 
-This also updates existing Hermes `cogmem-mcp` blocks with missing strategy, episode, Dream, memory-map, maintenance, and prospective tools.
+This also updates existing Hermes MCP blocks with missing strategy, episode, Dream, memory-map, maintenance, and prospective tools. New configs use `cogmem mcp`; `cogmem-mcp` remains a compatibility bin.
 
 ## Documentation
 
@@ -710,6 +740,7 @@ Installed OpenClaw and Hermes skills include their own `references/operations.md
 cogmem init
 cogmem doctor
 cogmem connect openclaw|hermes
+cogmem mcp
 cogmem update
 cogmem memory recall|search|show|dream|govern|candidates|review|status|map|tick|bind
 cogmem memory graph|graph-search|graph-explore|graph-node|graph-neighbors|graph-path|graph-timeline
@@ -739,7 +770,7 @@ npm pack --dry-run --json
 npm publish --dry-run --access public
 ```
 
-Create a GitHub Release from the matching version tag, for example `v3.6.3`. The `.github/workflows/publish.yml` workflow publishes to npm only when the release is published, not when a tag is pushed. The npm Trusted Publisher entry must match repository `liuqin164/cogmem`, workflow file `publish.yml`, and environment `npm publish`.
+Create a GitHub Release from the matching version tag, for example `v3.6.4`. The `.github/workflows/publish.yml` workflow publishes to npm only when the release is published, not when a tag is pushed. The npm Trusted Publisher entry must match repository `liuqin164/cogmem`, workflow file `publish.yml`, and environment `npm publish`.
 
 Publish manually only for emergency fallback:
 

package/RELEASE_CHECKLIST.md

@@ -1,11 +1,11 @@
-# cogmem 3.6.3 Release Checklist
+# cogmem 3.6.4 Release Checklist
 
 This release is distributed through the npm registry. GitHub remains the source and review mirror.
 
 ## Required Metadata
 
 - `package.json` name is `cogmem`.
-- `package.json` version is `3.6.3`.
+- `package.json` version is `3.6.4`.
 - `package.json` has `publishConfig.access = public`.
 - Public export `.` points to `dist/public.js` and `dist/public.d.ts`.
 - Internal subpath `./internal` exists only as an explicit advanced subpath.
@@ -19,12 +19,13 @@ This release is distributed through the npm registry. GitHub remains the source
 - `cogmem doctor`
 - `cogmem connect`
 - `cogmem update`
+- `cogmem mcp`
 - `cogmem openclaw diagnose`
 - `cogmem-compact`
 - `cogmem memory`
 - `cogmem repair`
 - `cogmem explain-recall`
-- `cogmem-mcp`
+- `cogmem-mcp` compatibility bin for existing host configs
 - `cogmem import-openclaw`
 - `cogmem import-hermes`
 - `cogmem normalize-transcript`
@@ -43,6 +44,8 @@ MCP `tools/list` includes strategy, episode append/import/status/seal/repair, to
 ## Required Documentation
 
 - README explains the vision, architecture, limits, and one-line install command.
+- README and skills document npm as the default install path: workspace-local `npm install cogmem@latest --save` for OpenClaw/Hermes projects, global npm only when the operator wants one shared CLI, and the one-line installer as compatibility.
+- README and skills state that `cogmem init` is an interactive operator wizard and must not be scripted by an unattended agent; agents should use resolved `cogmem` commands, `cogmem doctor`, and `cogmem connect <agent>`.
 - README says this is a single-agent memory kernel, not an agent team shared brain.
 - README distinguishes embedding models from Dream Curator memory-model LLMs.
 - README and integration docs explain labeled `sourceContext`, strict before/after window metadata, `charRange` / `sourceRange`, and OpenClaw `sourceWindow` / `sourceTruncation` injection.
@@ -56,6 +59,9 @@ MCP `tools/list` includes strategy, episode append/import/status/seal/repair, to
 - README and skills explain that Prospective Memory is confirmed-only state with no task execution capability, and how to use BrainEval as a release gate.
 - README and skills explain Strategy Cortex templates, no-instruction-authority lifecycle, one-retry replanning, strategy-conditioned retrieval, offline-only rollout comparison, and read-only MemoryUseJudge telemetry.
 - README and skills explain Raw Ledger-first episode assembly, soft/hard sealing, explicit conditional Dream ticks, raw-event evidence grounding, repair/retry, and hookless Hermes MCP/import usage.
+- README and skills give the full post-import maintenance sequence: status, episode status, Dream status, bounded Dream tick, candidate listing, govern candidate, needs-confirmation listing, explicit review, and recall verification.
+- README and skills explain that 3.6.4 skips empty imported episode boundaries and legacy empty Dream jobs instead of letting them abort `dream tick`.
+- README and skills document `cogmem mcp` as the preferred MCP server command for new configs while preserving `cogmem-mcp` as a compatibility bin.
 - README and skills explain CPU foreground versus hybrid background classification, contextual short replies, registry-aware topic boundaries, safe reopen, semantic-summary non-evidence status, per-job Dream modes/failures, stable import identity, and schema migration 24.
 - README and skills explain user-shaped topic operations, user-explicit versus model-candidate authority, alias collision review, operation rollback, and project isolation.
 - README, `MEMORY_ATLAS.md`, and skills distinguish the system anatomy map from the content Atlas; explain graph overview/search/explore/node/neighbors/path/timeline, generic multi-facet cold-memory resurrection, activation visibility, source drill-down, and project isolation.
@@ -85,7 +91,7 @@ npm publish --dry-run --access public
 
 The pack dry-run must include built public API files, CLI files, examples, docs, and `install.sh`. It must not include local databases or machine-specific files.
 
-After verification, create a GitHub Release from the matching version tag, for example `v3.6.3`. The release workflow publishes through npm Trusted Publishing when the release is published. It must not publish on tag push alone.
+After verification, create a GitHub Release from the matching version tag, for example `v3.6.4`. The release workflow publishes through npm Trusted Publishing when the release is published. It must not publish on tag push alone.
 
 Emergency manual fallback:
 

package/dist/bin/connect.js

@@ -92,19 +92,18 @@ function defaultSkillPath(agent, workspaceRoot) {
 function nextCommands(agent) {
     if (agent === 'openclaw') {
         return [
-            './node_modules/.bin/cogmem-init --agent openclaw --scope project',
-            './node_modules/.bin/cogmem-doctor',
-            './node_modules/.bin/cogmem-import-openclaw --workspace . --project openclaw --dry-run',
-            './node_modules/.bin/cogmem-import-openclaw --workspace . --project openclaw',
-            './node_modules/.bin/cogmem-connect openclaw --workspace . --auto --force',
+            './node_modules/.bin/cogmem doctor',
+            './node_modules/.bin/cogmem openclaw diagnose --workspace . --json',
+            './node_modules/.bin/cogmem import-openclaw --workspace . --project openclaw --dry-run',
+            './node_modules/.bin/cogmem import-openclaw --workspace . --project openclaw',
+            './node_modules/.bin/cogmem memory status --project openclaw --json',
         ];
     }
     return [
-        './node_modules/.bin/cogmem-init --agent hermes',
-        './node_modules/.bin/cogmem-doctor',
-        './node_modules/.bin/cogmem-connect hermes --workspace . --auto --force',
-        './node_modules/.bin/cogmem-import-hermes --workspace . --project hermes --dry-run',
-        './node_modules/.bin/cogmem-import-hermes --workspace . --project hermes',
+        './node_modules/.bin/cogmem doctor',
+        './node_modules/.bin/cogmem import-hermes --workspace . --project hermes --dry-run',
+        './node_modules/.bin/cogmem import-hermes --workspace . --project hermes',
+        './node_modules/.bin/cogmem memory status --project hermes --json',
     ];
 }
 function usage() {
@@ -138,33 +137,45 @@ function hostConfigSnippet(agent, workspaceRoot, auto) {
             '// Add host config only after installing a real OpenClaw plugin wrapper with a valid manifest/schema.',
         ].join('\n');
     }
-    const mcpBin = resolveCogmemMcpCommand(workspaceRoot);
+    const mcpServer = resolveCogmemMcpServer(workspaceRoot);
     return [
         'mcp_servers:',
         '  cogmem:',
-        `    command: "${mcpBin}"`,
-        '    args: []',
+        `    command: "${mcpServer.command}"`,
+        `    args: ${JSON.stringify(mcpServer.args)}`,
         '    enabled: true',
         '    tools:',
         '      include:',
         ...HERMES_COGMEM_TOOLS.map((tool) => `        - ${tool}`),
     ].join('\n');
 }
-function resolveCogmemMcpCommand(workspaceRoot) {
+function resolveCogmemMcpServer(workspaceRoot) {
     if (process.env.COGMEM_MCP_BIN)
-        return process.env.COGMEM_MCP_BIN;
-    const workspaceBin = join(workspaceRoot, 'node_modules', '.bin', 'cogmem-mcp');
-    if (existsSync(workspaceBin))
-        return workspaceBin;
+        return { command: process.env.COGMEM_MCP_BIN, args: [] };
+    if (process.env.COGMEM_BIN)
+        return { command: process.env.COGMEM_BIN, args: ['mcp'] };
+    const workspaceCli = join(workspaceRoot, 'node_modules', '.bin', 'cogmem');
+    if (existsSync(workspaceCli))
+        return { command: workspaceCli, args: ['mcp'] };
     const pathValue = process.env.PATH || '';
+    for (const segment of pathValue.split(':')) {
+        if (!segment)
+            continue;
+        const candidate = join(segment, 'cogmem');
+        if (existsSync(candidate))
+            return { command: candidate, args: ['mcp'] };
+    }
+    const workspaceMcp = join(workspaceRoot, 'node_modules', '.bin', 'cogmem-mcp');
+    if (existsSync(workspaceMcp))
+        return { command: workspaceMcp, args: [] };
     for (const segment of pathValue.split(':')) {
         if (!segment)
             continue;
         const candidate = join(segment, 'cogmem-mcp');
         if (existsSync(candidate))
-            return candidate;
+            return { command: candidate, args: [] };
     }
-    return 'cogmem-mcp';
+    return { command: 'cogmem', args: ['mcp'] };
 }
 function installSkill(args) {
     if (!args.agent)
@@ -237,9 +248,9 @@ function defaultHermesConfigPath(env = process.env) {
 }
 function installHermesMcpConfig(input) {
     const configPath = resolve(input.configPath || defaultHermesConfigPath());
-    const serverCommand = resolveCogmemMcpCommand(resolve(input.workspaceRoot));
+    const server = resolveCogmemMcpServer(resolve(input.workspaceRoot));
     const original = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
-    const patched = patchHermesMcpConfig(original, serverCommand);
+    const patched = patchHermesMcpConfig(original, server.command, server.args);
     const changed = patched !== original;
     let backupPath;
     if (!input.dryRun && (changed || input.force)) {
@@ -253,21 +264,22 @@ function installHermesMcpConfig(input) {
     return {
         enabled: true,
         configPath,
-        serverCommand,
+        serverCommand: server.command,
+        serverArgs: server.args,
         dryRun: input.dryRun,
         configUpdated: changed || input.force,
         backupPath,
     };
 }
-function patchHermesMcpConfig(original, serverCommand) {
-    if (/^\s+cogmem\s*:/m.test(original) && original.includes('cogmem-mcp')) {
+function patchHermesMcpConfig(original, serverCommand, serverArgs) {
+    if (/^\s+cogmem\s*:/m.test(original)) {
         return patchExistingHermesCogmemConfig(original);
     }
     const lines = original.replace(/\r\n/g, '\n').split('\n');
     const serverBlock = [
         '  cogmem:',
         `    command: "${serverCommand}"`,
-        '    args: []',
+        `    args: ${JSON.stringify(serverArgs)}`,
         '    enabled: true',
         '    tools:',
         '      include:',
@@ -366,7 +378,7 @@ function printHuman(result) {
         console.log('');
         console.log('Hermes MCP integration:');
         console.log(`  config: ${result.hermesMcp.configPath}`);
-        console.log(`  command: ${result.hermesMcp.serverCommand}`);
+        console.log(`  command: ${result.hermesMcp.serverCommand} ${result.hermesMcp.serverArgs.join(' ')}`.trimEnd());
         if (result.hermesMcp.backupPath)
             console.log(`  backup: ${result.hermesMcp.backupPath}`);
         console.log('  reload: /reload-mcp');

package/dist/bin/import-support.d.ts

@@ -22,6 +22,7 @@ export interface AgentImportResult {
     recordsIngested: number;
     skippedRecords: number;
     rawRecordsAnchored?: number;
+    emptyEpisodesSkipped?: number;
     reindexRaw?: boolean;
     processedSourceIds: string[];
     diagnostics: SourceAdapterDiagnostic[];

package/dist/bin/import-support.js

@@ -152,6 +152,7 @@ function previewSources(input) {
         recordsIngested: 0,
         skippedRecords: 0,
         rawRecordsAnchored: 0,
+        emptyEpisodesSkipped: 0,
         reindexRaw: false,
         processedSourceIds: [],
         diagnostics,
@@ -161,6 +162,7 @@ function previewSources(input) {
 async function importSources(input) {
     const opened = openKernel(input.args, input.workspaceRoot);
     const importedEpisodeIds = new Set();
+    let emptyEpisodesSkipped = 0;
     const processor = new InstalledBatchProcessor({
         cursorStore: opened.kernel.cursorStore,
         ingestBatch: async (items) => {
@@ -190,7 +192,7 @@ async function importSources(input) {
         for (const episodeId of importedEpisodeIds) {
             const episode = opened.kernel.getEpisode(episodeId);
             if (episode?.status !== 'sealed') {
-                opened.kernel.sealImportedEpisode(episodeId, { reason: `${input.agent}_import_batch_boundary` });
+                emptyEpisodesSkipped += sealImportedEpisodeIfReady(opened.kernel, episodeId, `${input.agent}_import_batch_boundary`) ? 0 : 1;
             }
         }
         return {
@@ -207,6 +209,7 @@ async function importSources(input) {
             recordsIngested: summary.recordsIngested,
             skippedRecords: summary.skippedRecords,
             rawRecordsAnchored: summary.recordsIngested,
+            emptyEpisodesSkipped,
             reindexRaw: false,
             processedSourceIds: summary.processedSourceIds,
             diagnostics: summary.adapterDiagnostics,
@@ -238,6 +241,7 @@ async function reindexRawSources(input) {
     let rawRecordsAnchored = 0;
     let skippedRecords = 0;
     const importedEpisodeIds = new Set();
+    let emptyEpisodesSkipped = 0;
     try {
         for (const source of input.sources) {
             const adapter = adapters.get(source.adapterKind);
@@ -279,7 +283,7 @@ async function reindexRawSources(input) {
         for (const episodeId of importedEpisodeIds) {
             const episode = opened.kernel.getEpisode(episodeId);
             if (episode?.status !== 'sealed') {
-                opened.kernel.sealImportedEpisode(episodeId, { reason: `${input.agent}_reindex_batch_boundary` });
+                emptyEpisodesSkipped += sealImportedEpisodeIfReady(opened.kernel, episodeId, `${input.agent}_reindex_batch_boundary`) ? 0 : 1;
             }
         }
         return {
@@ -297,6 +301,7 @@ async function reindexRawSources(input) {
             recordsIngested: rawRecordsAnchored,
             skippedRecords,
             rawRecordsAnchored,
+            emptyEpisodesSkipped,
             processedSourceIds,
             diagnostics,
             sourceResults,
@@ -307,6 +312,12 @@ async function reindexRawSources(input) {
         opened.kernel.close();
     }
 }
+function sealImportedEpisodeIfReady(kernel, episodeId, reason) {
+    if (kernel.listEpisodeEventLinks(episodeId).length === 0)
+        return false;
+    kernel.sealImportedEpisode(episodeId, { reason });
+    return true;
+}
 async function recordRawImportedEvidence(kernel, projectId, envelope) {
     const sourceRef = envelope.ingestInput.sourceRefs?.[0];
     const record = envelope.record;
@@ -483,6 +494,8 @@ function printHumanSummary(result) {
     console.log(`records ${action}: ${result.dryRun ? result.recordsWouldIngest : result.recordsIngested}`);
     if (result.rawRecordsAnchored !== undefined)
         console.log(`raw ledger anchors: ${result.rawRecordsAnchored}`);
+    if (result.emptyEpisodesSkipped)
+        console.log(`empty episodes skipped: ${result.emptyEpisodesSkipped}`);
     console.log(`records skipped: ${result.skippedRecords}`);
     if (result.diagnostics.length > 0) {
         console.log('diagnostics:');

package/dist/bin/mcp.js

@@ -29,7 +29,8 @@ function stringArg(values, key) {
 }
 function usage() {
     return [
-        'Usage: cogmem-mcp [--db <memory.db>|--config <config.toml>] [--cwd <dir>]',
+        'Usage: cogmem mcp [--db <memory.db>|--config <config.toml>] [--cwd <dir>]',
+        '       cogmem-mcp [--db <memory.db>|--config <config.toml>] [--cwd <dir>]',
         '',
         'Starts a stdio MCP server exposing recall, strategy, episode append/import/status/seal, conditional dream tick/status, memory map, maintenance, and prospective-memory tools.',
     ].join('\n');

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.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.4';
 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;

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,23 @@ 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 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 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
 ```
 
+`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:

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,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
@@ -97,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.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.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
 
@@ -155,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,35 +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
-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
+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
 ```
 
-If Bun is already installed and the operator wants npm global installation instead of the one-line installer, use:
+Global npm is also supported when the operator wants one CLI for every workspace:
 
 ```bash
 npm install -g cogmem@latest
-cogmem init --yes --agent hermes
-cogmem connect hermes --workspace . --auto --force
+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="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:
@@ -159,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.
@@ -304,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:
@@ -337,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.3 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,22 +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
 ```
 
-If Bun is already installed and the operator prefers npm global installation:
+Use this resolver in agent-run scripts:
 
 ```bash
-npm install -g cogmem@latest
-cogmem init --yes --agent hermes
-cogmem connect hermes --workspace . --auto --force --json
+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
 ```
 
-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.
+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. New configs start the bridge as `cogmem mcp`; `cogmem-mcp` remains a compatibility bin for older host configs.
 
 ## Upgrade and migrate
 
@@ -61,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.3 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.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
 
@@ -98,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,19 +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
 ```
 
-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 openclaw --scope project
-cogmem connect openclaw --workspace . --auto --force
+"$COGMEM" init --agent openclaw --scope project
 ```
 
 ## Local Quantized Embeddings
@@ -61,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
 ```
@@ -86,7 +83,7 @@ cogmem memory tick --project openclaw --json
 cogmem memory bind --project openclaw --json
 ```
 
-Cogmem 3.6.3 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
@@ -126,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

package/examples/openclaw-backend/SKILL.md

@@ -31,30 +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
-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
+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
 ```
 
-If Bun is already installed and the operator wants npm global installation instead of the one-line installer, use:
+Global npm is also supported when the operator wants one CLI for every workspace:
 
 ```bash
 npm install -g cogmem@latest
-cogmem init --yes --agent openclaw --scope project
-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.
+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 init --yes --agent openclaw --scope project
+COGMEM_SKIP_INIT=1 curl -fsSL https://raw.githubusercontent.com/liuqin164/cogmem/main/install.sh | bash
+COGMEM="cogmem"
+"$COGMEM" connect openclaw --workspace . --auto --force --json
 ```
 
-The install creates:
+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 --agent openclaw --scope project
+```
+
+OpenClaw workspaces should normally use project-local kernel config and storage:
 
 ```text
 .cogmem/config.toml
@@ -155,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:
 
@@ -359,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
 ```
@@ -395,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:
 
@@ -441,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.3 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,19 +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
 ```
 
-If Bun is already installed and the operator prefers npm global installation:
+Use this resolver in agent-run scripts:
 
 ```bash
-npm install -g cogmem@latest
-cogmem init --yes --agent openclaw --scope project
-cogmem connect openclaw --workspace . --auto --force --json
+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.
@@ -70,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.3 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.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:
 
@@ -121,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
@@ -266,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`.

package/package.json

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