cogmem 3.6.2 → 3.6.4

package/dist/bin/update.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { loadCogmemConfig, resolveCogmemConfigPath } from '../config/CogmemConfig.js';
 import { printCliJson } from './CliJson.js';
 import { DEFAULT_NPM_PACKAGE, resolveLatestNpmSpec } from './update-release.js';
@@ -29,6 +30,8 @@ function readArgs(argv) {
         json: values.json === true,
         from: typeof values.from === 'string' ? values.from : 'latest',
         installHome: typeof values['install-home'] === 'string' ? values['install-home'] : undefined,
+        global: values.global === true,
+        localDev: values['local-dev'] === true,
         manager,
         configPath: typeof values.config === 'string' ? values.config : undefined,
         skipMigrate: values['skip-migrate'] === true,
@@ -42,7 +45,10 @@ function detectManager(cwd) {
         return 'pnpm';
     return 'npm';
 }
-function buildCommand(manager, spec) {
+function buildCommand(target, spec) {
+    if (target.kind === 'npm_global')
+        return ['npm', 'install', '-g', `cogmem@${spec}`];
+    const manager = target.manager;
     if (manager === 'bun')
         return ['bun', 'add', `cogmem@${spec}`];
     if (manager === 'pnpm')
@@ -52,18 +58,18 @@ function buildCommand(manager, spec) {
 function localCogmemBin(cwd) {
     return join(cwd, 'node_modules', '.bin', 'cogmem');
 }
-function buildMigrationExec(targetCwd, configPath) {
+function buildMigrationExecForTarget(target, configPath) {
     return [
-        localCogmemBin(targetCwd),
+        target.bin,
         'migrate',
         '--yes',
         '--backup',
         ...(configPath ? ['--config', configPath] : []),
     ];
 }
-function buildOpenClawRepairExec(targetCwd, configPath, workspaceRoot) {
+function buildOpenClawRepairExecForTarget(target, configPath, workspaceRoot) {
     return [
-        localCogmemBin(targetCwd),
+        target.bin,
         'doctor',
         '--fix',
         '--agent',
@@ -99,16 +105,57 @@ function shouldUpdateCwd(cwd) {
     const manifest = readPackageManifest(cwd);
     return manifest?.name === 'cogmem' || installedSpec(cwd) !== undefined;
 }
-function resolveUpdateCwd(args, env) {
+function isCogmemSourceCheckout(cwd) {
+    const manifest = readPackageManifest(cwd);
+    return manifest?.name === 'cogmem'
+        && existsSync(join(cwd, 'src', 'bin', 'update.ts'))
+        && existsSync(join(cwd, '.git'));
+}
+function ownPackageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+function isLikelyNpmGlobalInstall(env) {
+    if (env.COGMEM_INSTALL_KIND === 'npm_global')
+        return true;
+    const root = ownPackageRoot();
+    const marker = `${sep}node_modules${sep}cogmem`;
+    if (!root.includes(marker))
+        return false;
+    const cwd = resolve(process.cwd());
+    return !cwd.startsWith(root + sep);
+}
+function resolveUpdateTarget(args, env) {
     const cwd = process.cwd();
-    if (args.installHome)
-        return args.installHome;
-    if (shouldUpdateCwd(cwd))
-        return cwd;
+    if (args.global || isLikelyNpmGlobalInstall(env)) {
+        return { cwd, kind: 'npm_global', manager: 'npm', bin: 'cogmem' };
+    }
+    if (args.installHome) {
+        const targetCwd = args.installHome;
+        return { cwd: targetCwd, kind: 'install_home', manager: args.manager || detectManager(targetCwd), bin: localCogmemBin(targetCwd) };
+    }
+    if (isCogmemSourceCheckout(cwd)) {
+        return {
+            cwd,
+            kind: 'source_checkout',
+            manager: args.manager || detectManager(cwd),
+            bin: localCogmemBin(cwd),
+            warning: args.localDev ? undefined : 'source_checkout_requires_local_dev_for_write',
+        };
+    }
+    if (shouldUpdateCwd(cwd)) {
+        return { cwd, kind: 'local_project', manager: args.manager || detectManager(cwd), bin: localCogmemBin(cwd) };
+    }
     const installHome = defaultInstallHome(env);
-    if (existsSync(join(installHome, 'package.json')))
-        return installHome;
-    return cwd;
+    if (existsSync(join(installHome, 'package.json'))) {
+        return { cwd: installHome, kind: 'install_home', manager: args.manager || detectManager(installHome), bin: localCogmemBin(installHome) };
+    }
+    return {
+        cwd,
+        kind: 'cwd_fallback',
+        manager: args.manager || detectManager(cwd),
+        bin: localCogmemBin(cwd),
+        warning: 'no_install_home_or_project_dependency_detected',
+    };
 }
 function loadConfigForUpdate(args) {
     const resolution = resolveCogmemConfigPath({ configPath: args.configPath, cwd: process.cwd() });
@@ -136,18 +183,24 @@ async function main() {
     const resolvedSpec = args.from === 'latest'
         ? resolveLatestNpmSpec({ env: process.env })
         : args.from;
-    const targetCwd = resolveUpdateCwd(args, process.env);
-    const manager = args.manager || detectManager(targetCwd);
-    const command = buildCommand(manager, resolvedSpec);
+    const target = resolveUpdateTarget(args, process.env);
+    if (!args.dryRun && target.kind === 'source_checkout' && !args.localDev) {
+        throw new Error('Refusing to update the Cogmem source checkout. Pass --local-dev for an intentional development update, --global for npm global, or --install-home <dir> for the one-line installer home.');
+    }
+    if (!args.dryRun && target.kind === 'cwd_fallback') {
+        throw new Error('Unable to find an installed Cogmem package to update. Pass --global for npm global installs or --install-home <dir> for the one-line installer home.');
+    }
+    const manager = target.manager;
+    const command = buildCommand(target, resolvedSpec);
     const config = loadConfigForUpdate(args);
     const migrationExec = !args.skipMigrate && config.configPath
-        ? buildMigrationExec(targetCwd, config.configPath)
+        ? buildMigrationExecForTarget(target, config.configPath)
         : undefined;
     const openclawWorkspace = config.loaded?.integrations.openclaw.enabled
         ? config.loaded.integrations.openclaw.workspaceDir || process.cwd()
         : undefined;
     const openclawRepairExec = !args.skipAgentRefresh && openclawWorkspace && config.configPath
-        ? buildOpenClawRepairExec(targetCwd, config.configPath, openclawWorkspace)
+        ? buildOpenClawRepairExecForTarget(target, config.configPath, openclawWorkspace)
         : undefined;
     const restartRequired = [
         ...(openclawWorkspace ? ['restart OpenClaw gateway or agent host'] : []),
@@ -157,13 +210,15 @@ async function main() {
         command: 'update',
         dryRun: args.dryRun,
         manager,
+        installKind: target.kind,
         from: args.from,
         source: 'npm',
         npmPackage: DEFAULT_NPM_PACKAGE,
         packageSpec: resolvedSpec,
-        targetCwd,
-        currentSpec: installedSpec(targetCwd),
+        targetCwd: target.cwd,
+        currentSpec: target.kind === 'npm_global' ? 'npm:global' : installedSpec(target.cwd),
         nextCommand: command.join(' '),
+        updateWarning: target.warning,
         configPath: config.configPath,
         migrationCommand: migrationExec?.join(' '),
         migrationSkippedReason: migrationExec ? undefined : (args.skipMigrate ? 'skip_migrate_flag' : config.skippedReason),
@@ -182,6 +237,8 @@ async function main() {
     else {
         console.log(`cogmem update ${args.dryRun ? 'dry-run' : 'running'}`);
         console.log(`target: ${result.targetCwd}`);
+        if (result.updateWarning)
+            console.log(`warning: ${result.updateWarning}`);
         console.log(`current: ${result.currentSpec || 'not listed in package.json'}`);
         console.log(`command: ${result.nextCommand}`);
         if (result.migrationCommand)
@@ -191,7 +248,7 @@ async function main() {
         console.log(result.followUp);
     }
     if (!args.dryRun) {
-        const updateExitCode = await runCommand(command, targetCwd);
+        const updateExitCode = await runCommand(command, target.cwd);
         if (updateExitCode !== 0)
             process.exit(updateExitCode);
         if (migrationExec) {

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.1';
+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/dist/host/openclaw/AutoMemoryPluginInstaller.js

@@ -5,7 +5,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveCogmemConfigPath } from '../../config/CogmemConfig.js';
 const PLUGIN_ID = 'cogmem-auto-memory';
-const PLUGIN_VERSION = '0.6.2';
+const PLUGIN_VERSION = '0.6.3';
 function defaultPublicEntrypoint() {
     return join(resolve(dirname(fileURLToPath(import.meta.url)), '../..'), 'public.js');
 }
@@ -735,6 +735,7 @@ function bridgeConfig(config) {
     rememberQueuePath: rememberQueuePath(config),
     rememberMaxAttempts: config.rememberMaxAttempts || 3,
     rememberDrainBatchSize: config.rememberDrainBatchSize || 20,
+    rememberDrainTimeoutMs: config.rememberDrainTimeoutMs || 60000,
   };
 }
 
@@ -988,7 +989,7 @@ function audit(config, record) {
 const plugin = {
   id: PLUGIN_ID,
   name: 'CogMem Auto Memory',
-  version: '0.6.2',
+  version: '0.6.3',
   register(api) {
     if (!api || typeof api.on !== 'function') {
       throw new Error('OpenClaw plugin API missing api.on');
@@ -1231,7 +1232,7 @@ module.exports.__testing = {
 }
 function pluginBridgeMjs() {
     return String.raw `#!/usr/bin/env bun
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
@@ -1581,7 +1582,8 @@ function acquireRememberQueueLock(bridgeConfig) {
   if (!queuePath) throw new Error('missing rememberQueuePath');
   mkdirSync(dirname(queuePath), { recursive: true });
   const lockPath = queuePath + '.lock';
-  if (!existsSync(queuePath)) return { acquired: false, locked: false, empty: true, lockPath };
+  const recoveredProcessing = recoverStaleProcessingFiles(bridgeConfig);
+  if (!existsSync(queuePath)) return { acquired: false, locked: false, empty: true, lockPath, recoveredProcessing };
   const timeoutMs = Number(bridgeConfig.rememberDrainTimeoutMs || 60000);
   try {
     mkdirSync(lockPath);
@@ -1602,12 +1604,12 @@ function acquireRememberQueueLock(bridgeConfig) {
           staleLockRecovered: true,
           queuePath,
         }) + '\n');
-        return { acquired: true, locked: false, empty: false, lockPath, staleRecovered: true };
+        return { acquired: true, locked: false, empty: false, lockPath, staleRecovered: true, recoveredProcessing };
       }
     } catch {}
     return { acquired: false, locked: true, empty: false, lockPath };
   }
-  return { acquired: true, locked: false, empty: false, lockPath };
+  return { acquired: true, locked: false, empty: false, lockPath, recoveredProcessing };
 }
 
 async function drainRememberQueueWithLock(bridgeConfig, queueLock, kernel, memory) {
@@ -1655,7 +1657,29 @@ async function drainRememberQueueWithLock(bridgeConfig, queueLock, kernel, memor
   } finally {
     if (queueLock.acquired) rmSync(queueLock.lockPath, { recursive: true, force: true });
   }
-  return { drained, failed, deferred, locked: false, staleRecovered: queueLock.staleRecovered === true };
+  return { drained, failed, deferred, locked: false, staleRecovered: queueLock.staleRecovered === true, recoveredProcessing: queueLock.recoveredProcessing || 0 };
+}
+
+function recoverStaleProcessingFiles(bridgeConfig) {
+  const queuePath = bridgeConfig.rememberQueuePath;
+  const dir = dirname(queuePath);
+  const prefix = queuePath.split('/').pop() + '.';
+  const timeoutMs = Number(bridgeConfig.rememberDrainTimeoutMs || 60000);
+  let recovered = 0;
+  if (!existsSync(dir)) return recovered;
+  for (const entry of readdirSync(dir)) {
+    if (!entry.startsWith(prefix) || !entry.endsWith('.processing')) continue;
+    const path = join(dir, entry);
+    try {
+      const ageMs = Date.now() - statSync(path).mtimeMs;
+      if (!Number.isFinite(ageMs) || ageMs < timeoutMs) continue;
+      const lines = readFileSync(path, 'utf8').split('\n').map((line) => line.trim()).filter(Boolean);
+      for (const line of lines) appendFileSync(queuePath, line + '\n');
+      rmSync(path, { force: true });
+      recovered += lines.length;
+    } catch {}
+  }
+  return recovered;
 }
 
 function compactRecallItems(items, config) {

package/dist/migrations/SchemaMigrationRunner.d.ts

@@ -3,6 +3,9 @@ import type { Migration } from '../types/Migration.js';
 export interface SchemaMigrationRunOptions {
     dryRun?: boolean;
 }
+export interface SchemaMigrationRunnerOptions {
+    readonly?: boolean;
+}
 export interface SchemaMigrationResult {
     pending: string[];
     applied: string[];
@@ -12,10 +15,15 @@ export interface SchemaMigrationResult {
 export declare class SchemaMigrationRunner {
     private readonly db;
     private readonly migrations;
-    constructor(db: Database, migrations: Migration[]);
+    private readonly options;
+    constructor(db: Database, migrations: Migration[], options?: SchemaMigrationRunnerOptions);
     plan(): Migration[];
     run(options?: SchemaMigrationRunOptions): SchemaMigrationResult;
     currentVersion(): string | undefined;
+    private appliedVersions;
+    private schemaMigrationsTableExists;
+    private legacySchemaVersion;
+    private legacyCurrentVersion;
     private adoptLegacyVersion;
 }
 //# sourceMappingURL=SchemaMigrationRunner.d.ts.map

package/dist/migrations/SchemaMigrationRunner.js

@@ -1,9 +1,13 @@
 export class SchemaMigrationRunner {
     db;
     migrations;
-    constructor(db, migrations) {
+    options;
+    constructor(db, migrations, options = {}) {
         this.db = db;
         this.migrations = migrations;
+        this.options = options;
+        if (this.options.readonly)
+            return;
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS _schema_migrations (
         version TEXT PRIMARY KEY,
@@ -14,7 +18,7 @@ export class SchemaMigrationRunner {
         this.adoptLegacyVersion();
     }
     plan() {
-        const applied = new Set(this.db.prepare(`SELECT version FROM _schema_migrations`).all().map((row) => row.version));
+        const applied = this.appliedVersions();
         return [...this.migrations]
             .sort((a, b) => a.version.localeCompare(b.version))
             .filter((migration) => !applied.has(migration.version));
@@ -39,20 +43,57 @@ export class SchemaMigrationRunner {
         return { pending: pending.map((item) => item.version), applied, currentVersion: this.currentVersion(), dryRun: false };
     }
     currentVersion() {
+        const legacyCurrent = this.legacyCurrentVersion();
+        if (!this.schemaMigrationsTableExists()) {
+            return legacyCurrent;
+        }
         const row = this.db.prepare(`
       SELECT version FROM _schema_migrations ORDER BY version DESC LIMIT 1
     `).get();
-        return row?.version;
+        return [row?.version, legacyCurrent].filter((version) => Boolean(version)).sort((a, b) => b.localeCompare(a))[0];
     }
-    adoptLegacyVersion() {
+    appliedVersions() {
+        const applied = new Set();
+        const legacyVersion = this.legacySchemaVersion();
+        for (const migration of this.migrations) {
+            if (legacyVersion !== undefined && Number.parseInt(migration.version, 10) <= legacyVersion) {
+                applied.add(migration.version);
+            }
+        }
+        if (!this.schemaMigrationsTableExists()) {
+            return applied;
+        }
+        for (const row of this.db.prepare(`SELECT version FROM _schema_migrations`).all()) {
+            applied.add(row.version);
+        }
+        return applied;
+    }
+    schemaMigrationsTableExists() {
+        return Boolean(this.db.prepare(`
+      SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_schema_migrations'
+    `).get());
+    }
+    legacySchemaVersion() {
         const metaExists = this.db.prepare(`
       SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_meta'
     `).get();
         if (!metaExists)
-            return;
+            return undefined;
         const row = this.db.prepare(`SELECT value FROM _meta WHERE key = 'schema_version'`).get();
         const legacyVersion = Number.parseInt(row?.value || '', 10);
-        if (!Number.isFinite(legacyVersion))
+        return Number.isFinite(legacyVersion) ? legacyVersion : undefined;
+    }
+    legacyCurrentVersion() {
+        const legacyVersion = this.legacySchemaVersion();
+        if (legacyVersion === undefined)
+            return undefined;
+        return [...this.migrations]
+            .filter((migration) => Number.parseInt(migration.version, 10) <= legacyVersion)
+            .sort((a, b) => b.version.localeCompare(a.version))[0]?.version;
+    }
+    adoptLegacyVersion() {
+        const legacyVersion = this.legacySchemaVersion();
+        if (legacyVersion === undefined)
             return;
         const insert = this.db.prepare(`
       INSERT OR IGNORE INTO _schema_migrations (version, description, applied_at)

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: