cogmem 3.6.2 → 3.6.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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`.
+- Fixed `cogmem migrate --dry-run` so it opens SQLite read-only and plans legacy `_meta.schema_version` adoption without creating `_schema_migrations` or writing migration rows.
+- Hardened `cogmem update` target resolution for npm global installs, one-line installer homes, local project dependencies, and source checkouts so `cogmem update --yes` does not silently install into an arbitrary current directory.
+- Updated OpenClaw diagnostics and generated bridge behavior to propagate `rememberDrainTimeoutMs`, recover stale `.processing` queue files, and report pending/dead/lock/processing queue state.
+
 ## 3.6.2
 
 - Switched the public distribution channel to the npm registry while keeping GitHub as the source and review mirror.

package/CONTRIBUTING.md

@@ -18,10 +18,10 @@ bun run typecheck
 bun test
 npm pack --dry-run --json
 npm publish --dry-run --access public
-npm publish --access public
+npm publish --provenance --access public
 ```
 
-`cogmem` is distributed through the npm registry. Use `npm pack --dry-run --json` to verify package contents, then `npm publish --dry-run --access public` before `npm publish --access public`. Keep the GitHub branch or release synchronized for source review and for older GitHub-installed users migrating onto the npm-first updater.
+`cogmem` is distributed through the npm registry. Use `npm pack --dry-run --json` to verify package contents. Normal publishing happens by creating a GitHub Release from the matching version tag; `.github/workflows/publish.yml` is intentionally triggered by the release `published` event, not by tag pushes. Use `npm publish --provenance --access public` only as an emergency manual fallback.
 
 ## API Discipline
 

package/README.md

@@ -11,7 +11,7 @@ It is not a knowledge-base app, a note-taking app, a vector RAG wrapper, an Obsi
 
 ## Status
 
-Current version: `3.6.2`
+Current version: `3.6.3`
 
 Distribution: npm registry. GitHub remains the source mirror and hosts this installer, but package install and upgrade resolve `cogmem` from npm by default.
 
@@ -178,6 +178,13 @@ npm install cogmem@latest
 ./node_modules/.bin/cogmem init
 ```
 
+Or install globally with npm when Bun is already on PATH:
+
+```bash
+npm install -g cogmem@latest
+cogmem init
+```
+
 Validate configuration:
 
 ```bash
@@ -190,7 +197,7 @@ Upgrade from npm and migrate an existing database:
 cogmem update --yes
 ```
 
-`cogmem update --yes` installs `cogmem@latest` from npm, then runs the newly installed `cogmem migrate --yes --backup --config <resolved-config>`. If OpenClaw is configured, the updater also runs the newly installed plugin-only repair command so stale `index.js` and `bridge.mjs` files are refreshed before you restart the agent. To inspect changes without writing:
+`cogmem update --yes` installs `cogmem@latest` from npm, then runs the newly installed `cogmem migrate --yes --backup --config <resolved-config>`. It updates npm-global installs with `npm install -g`, the one-line installer home under `~/.cogmem/pkg`, or the current workspace dependency when Cogmem is a project dependency. If OpenClaw is configured, the updater also runs the newly installed plugin-only repair command so stale `index.js` and `bridge.mjs` files are refreshed before you restart the agent. To inspect changes without writing:
 
 ```bash
 cogmem update --dry-run --json
@@ -199,7 +206,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.2 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.3 schema set with one command:
 
 ```bash
 cogmem migrate --yes --backup --json
@@ -241,7 +248,7 @@ For a host timer, call `dream tick`; the timer only wakes the scheduler. An empt
 cogmem dream tick --project my-agent --mode auto --max-episodes 10 --json
 ```
 
-Raw events are always written first. `KernelAgentMemoryBackend` and OpenClaw plugin 0.6.2 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.
+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.
 
@@ -337,7 +344,7 @@ cogmem strategy plan --project hermes --query "我当时的原话是什么？" -
 cogmem strategy outcomes --project hermes --json
 ```
 
-OpenClaw plugin 0.6.2 skips Cogmem entirely for greetings, uses only session state/turn bridge for short continuations, and applies Strategy Cortex before full recall. Navigation turns use one bridge/kernel lifecycle for Atlas exploration, evidence-bearing node/timeline drill-down, and recall. The bounded volatile `<COGMEM_MEMORY_ATLAS>` block includes evidence event IDs and drill-down commands; OpenClaw does not need MCP for this path.
+OpenClaw plugin 0.6.3 skips Cogmem entirely for greetings, uses only session state/turn bridge for short continuations, and applies Strategy Cortex before full recall. Navigation turns use one bridge/kernel lifecycle for Atlas exploration, evidence-bearing node/timeline drill-down, and recall. The bounded volatile `<COGMEM_MEMORY_ATLAS>` block includes evidence event IDs and drill-down commands; OpenClaw does not need MCP for this path.
 
 `ProspectiveMemoryService` stores future intentions, commitments, reminders, open loops, and plans as candidates only. A candidate is not actionable until an explicit user event confirms it. Rejected candidates stay suppressed unless genuinely new evidence creates a new version. The service and `cogmem prospective` CLI manage state only; they expose no task or tool execution capability.
 
@@ -732,7 +739,15 @@ npm pack --dry-run --json
 npm publish --dry-run --access public
 ```
 
-Publish with `npm publish --access public` after the dry run and full tests pass. Keep GitHub branches/releases in sync so old GitHub-installed 3.6.1 users have a discoverable bridge to the npm-first 3.6.2 updater.
+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`.
+
+Publish manually only for emergency fallback:
+
+```bash
+npm publish --provenance --access public
+```
+
+Keep GitHub branches/releases in sync so old GitHub-installed users have a discoverable bridge to the npm-first updater.
 
 ## Security and Privacy
 

package/RELEASE_CHECKLIST.md

@@ -1,11 +1,11 @@
-# cogmem 3.6.2 Release Checklist
+# cogmem 3.6.3 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.2`.
+- `package.json` version is `3.6.3`.
 - `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.
@@ -85,8 +85,10 @@ 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, publish with:
+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.
+
+Emergency manual fallback:
 
 ```bash
-npm publish --access public
+npm publish --provenance --access public
 ```

package/dist/bin/migrate.js

@@ -62,11 +62,13 @@ async function main() {
     const args = parseArgs(process.argv.slice(2));
     const dbPath = resolveDbPath(args);
     const shouldBackup = !args.dryRun && args.backup && dbPath !== ':memory:' && existsSync(dbPath);
-    const db = new Database(dbPath);
+    const db = new Database(dbPath, args.dryRun && dbPath !== ':memory:' ? { readonly: true, create: false } : undefined);
     db.exec('PRAGMA busy_timeout = 5000;');
+    if (args.dryRun)
+        db.exec('PRAGMA query_only = ON;');
     try {
         const backupPath = shouldBackup ? backupDatabase(db, dbPath) : undefined;
-        const runner = new SchemaMigrationRunner(db, ALL_MIGRATIONS);
+        const runner = new SchemaMigrationRunner(db, ALL_MIGRATIONS, { readonly: args.dryRun });
         const result = runner.run({ dryRun: args.dryRun });
         if (!args.dryRun) {
             db.exec(`CREATE TABLE IF NOT EXISTS _meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);`);

package/dist/bin/openclaw.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
-import { existsSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { defaultOpenClawAutoMemoryPluginDir, inspectOpenClawAutoMemoryPlugin, } from '../host/openclaw/AutoMemoryPluginInstaller.js';
 function readArg(name) {
     const index = process.argv.indexOf(name);
@@ -42,6 +42,54 @@ function readAudit(workspaceRoot) {
         recentErrors: records.filter((record) => record.action === 'error').slice(-20),
     };
 }
+function countJsonlLines(path) {
+    if (!existsSync(path))
+        return 0;
+    return readFileSync(path, 'utf8').split('\n').map((line) => line.trim()).filter(Boolean).length;
+}
+function readLock(path) {
+    if (!existsSync(path))
+        return undefined;
+    const ownerPath = join(path, 'owner.json');
+    let owner;
+    if (existsSync(ownerPath)) {
+        try {
+            owner = JSON.parse(readFileSync(ownerPath, 'utf8'));
+        }
+        catch {
+            owner = { parseError: true };
+        }
+    }
+    const stat = statSync(path);
+    return {
+        path,
+        mtimeMs: stat.mtimeMs,
+        ageMs: Date.now() - stat.mtimeMs,
+        owner,
+    };
+}
+function inspectQueue(workspaceRoot) {
+    const queuePath = join(workspaceRoot, '.cogmem', 'queue', 'openclaw-remember.jsonl');
+    const queueDir = dirname(queuePath);
+    const processingFiles = existsSync(queueDir)
+        ? readdirSync(queueDir)
+            .filter((entry) => entry.startsWith('openclaw-remember.jsonl.') && entry.endsWith('.processing'))
+            .map((entry) => {
+            const path = join(queueDir, entry);
+            const stat = statSync(path);
+            return { path, lines: countJsonlLines(path), mtimeMs: stat.mtimeMs, ageMs: Date.now() - stat.mtimeMs };
+        })
+        : [];
+    return {
+        queuePath,
+        pendingLines: countJsonlLines(queuePath),
+        deadPath: `${queuePath}.dead.jsonl`,
+        deadLines: countJsonlLines(`${queuePath}.dead.jsonl`),
+        lock: readLock(`${queuePath}.lock`),
+        spawnLock: readLock(`${queuePath}.spawn.lock`),
+        processingFiles,
+    };
+}
 function main() {
     const [command] = process.argv.slice(2).filter((arg) => !arg.startsWith('--'));
     if (command !== 'diagnose' || hasFlag('--help') || hasFlag('-h')) {
@@ -55,12 +103,14 @@ function main() {
     const pluginDir = readArg('--plugin-dir') || defaultOpenClawAutoMemoryPluginDir(workspaceRoot);
     const plugin = inspectOpenClawAutoMemoryPlugin({ workspaceRoot, pluginDir });
     const audit = readAudit(workspaceRoot);
+    const queue = inspectQueue(workspaceRoot);
     const payload = {
         schemaVersion: 'cogmem.cli.v1',
         command: 'openclaw diagnose',
         workspaceRoot,
         plugin,
         audit,
+        queue,
     };
     if (hasFlag('--json')) {
         console.log(JSON.stringify(payload));
@@ -74,5 +124,6 @@ function main() {
     else {
         console.log('last before_prompt_build: none');
     }
+    console.log(`queue: pending=${queue.pendingLines} dead=${queue.deadLines} processing=${Array.isArray(queue.processingFiles) ? queue.processingFiles.length : 0}`);
 }
 main();

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/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.3';
 const LATEST_SCHEMA_VERSION = 27;
 export class MemoryKernel {
     options;

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/README.md

@@ -21,6 +21,14 @@ cogmem connect hermes --workspace . --auto
 cogmem connect hermes --workspace .
 ```
 
+If Bun is already installed, npm global install is also supported:
+
+```bash
+npm install -g cogmem@latest
+cogmem init --yes --agent hermes
+cogmem connect hermes --workspace . --auto --force
+```
+
 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.
 
 ## Local Quantized Embeddings
@@ -89,7 +97,7 @@ Dream stores explicit user clarification as organizational correction evidence r
 
 After upgrades, reload MCP. Rerun `cogmem connect hermes --workspace . --auto --force` when MCP wiring, allow-listed tools, or the installed skill bundle changed.
 
-Cogmem 3.6.2 exposes seven read-only/idempotent Memory Atlas query tools plus explicit `cogmem_graph_touch`, and installs from npm by default. Use explore for broad memory inventory/history, search and node for a known concept, path/neighbors for relations, timeline for ordered reconstruction, and normal recall for a direct fact. Query facets combine the user's actual project, time, topic, entity/target, memory-kind, action, and keyword conditions like table filters, so cold memory can be revived without requiring an entity-time-action tuple. Touch only nodes actually used, and follow returned event IDs to raw evidence before quoting exact wording.
+Cogmem 3.6.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.
 
 ## Runtime
 

package/examples/hermes-backend/SKILL.md

@@ -40,6 +40,14 @@ cogmem doctor
 cogmem connect hermes --workspace . --auto --force
 ```
 
+If Bun is already installed and the operator wants npm global installation instead of the one-line installer, use:
+
+```bash
+npm install -g cogmem@latest
+cogmem init --yes --agent hermes
+cogmem connect hermes --workspace . --auto --force
+```
+
 Use project-local config only when this workspace needs isolation:
 
 ```bash
@@ -98,7 +106,7 @@ cogmem update --yes
 # Manual equivalent: cogmem migrate --yes --backup
 ```
 
-`cogmem update --yes` installs `cogmem@latest` from npm, runs the newly installed backed-up migration with the resolved config, and then reports that the Hermes MCP server or agent host must be reloaded. Agents should inspect `cogmem update --dry-run --json` or `cogmem migrate --dry-run --json` when an operator wants a preview. Schema migration preserves Raw Ledger events; it updates governed projections and indexes only.
+`cogmem update --yes` installs `cogmem@latest` from npm, runs the newly installed backed-up migration with the resolved config, and then reports that the Hermes MCP server or agent host must be reloaded. For npm global installs, `cogmem update --yes` resolves to `npm install -g cogmem@latest` instead of writing into the current directory. Agents should inspect `cogmem update --dry-run --json` or `cogmem migrate --dry-run --json` when an operator wants a preview. Schema migration preserves Raw Ledger events; dry-run is read-only and updates governed projections and indexes only during apply.
 
 Default Hermes memory contract:
 

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

@@ -1,4 +1,4 @@
-# Cogmem 3.6.2 Operations Reference for Hermes
+# Cogmem 3.6.3 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.
 
@@ -28,6 +28,14 @@ cogmem doctor
 cogmem connect hermes --workspace . --auto --force --json
 ```
 
+If Bun is already installed and the operator prefers npm global installation:
+
+```bash
+npm install -g cogmem@latest
+cogmem init --yes --agent hermes
+cogmem connect hermes --workspace . --auto --force --json
+```
+
 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.
 
 ## Upgrade and migrate
@@ -38,7 +46,7 @@ For normal upgrades, use one command:
 cogmem update --yes
 ```
 
-`cogmem update --yes` installs `cogmem@latest` from npm, then runs post-install work through the newly installed local CLI. With a valid config it runs `cogmem migrate --yes --backup --config <config>` and reports that the Hermes MCP server or agent host must be reloaded.
+`cogmem update --yes` installs `cogmem@latest` from npm, then runs post-install work through the newly installed CLI. For npm global installs it uses `npm install -g cogmem@latest`; for the one-line installer it updates `~/.cogmem/pkg`; for a workspace dependency it updates that workspace. With a valid config it runs `cogmem migrate --yes --backup --config <config>` and reports that the Hermes MCP server or agent host must be reloaded.
 
 Preview the package and migration plan without writing:
 
@@ -53,7 +61,7 @@ cogmem doctor
 cogmem connect hermes --workspace . --auto --force --json
 ```
 
-The backed-up command upgrades 3.5.2 schema 24, an existing 3.6.0 schema-26 database, or a pre-release schema-25 test database to the 3.6.2 schema-27 state in one run and preserves Raw Ledger evidence. Reload MCP after reconnecting.
+The backed-up command upgrades 3.5.2 schema 24, an existing 3.6.0 schema-26 database, or a pre-release schema-25 test database to the 3.6.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.
 
 ## Import Hermes memory
 

package/examples/openclaw-backend/README.md

@@ -16,6 +16,14 @@ cogmem connect openclaw --workspace .
 cogmem connect openclaw --workspace . --auto --force
 ```
 
+If Bun is already installed, npm global install is also supported:
+
+```bash
+npm install -g cogmem@latest
+cogmem init --yes --agent openclaw --scope project
+cogmem connect openclaw --workspace . --auto --force
+```
+
 ## Local Quantized Embeddings
 
 Imports use the configured kernel embedder. To import existing OpenClaw memory through a local quantized model, configure the kernel before running the import command:
@@ -78,7 +86,7 @@ cogmem memory tick --project openclaw --json
 cogmem memory bind --project openclaw --json
 ```
 
-Cogmem 3.6.2 keeps the 3.6.x Memory Atlas and OpenClaw reliability work, then makes npm the default install and update channel. The auto plugin uses one shared bridge/kernel lifecycle for graph exploration, evidence-bearing node/timeline drill-down, and recall, so OpenClaw does not need MCP for broad inventory/history questions. Atlas combines the query's actual project, time, topic, entity/target, memory-kind, action, and keyword conditions like table filters; no fixed entity-time-action tuple is required.
+Cogmem 3.6.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.
 
 ```bash
 cogmem memory graph-explore --project openclaw --query "去年与 Hermes 有关的决定" --json
@@ -206,7 +214,7 @@ To make future OpenClaw turns automatically recall and record memory, run:
 cogmem connect openclaw --workspace . --auto --force
 ```
 
-`--auto` installs `<workspace>/extensions/cogmem-auto-memory/`, patches OpenClaw `plugins.load.paths`, and enables a local plugin wrapper with `before_prompt_build` and `agent_end` hooks. The wrapper calls `KernelAgentMemoryBackend` through the public `cogmem` API via a Bun bridge; core still does not import OpenClaw. Plugin 0.6.2 uses singleton queue/spawn locks, stale-lock recovery, and bounded remember batches so queued `agent_end` recording does not hold SQLite open longer than necessary.
+`--auto` installs `<workspace>/extensions/cogmem-auto-memory/`, patches OpenClaw `plugins.load.paths`, and enables a local plugin wrapper with `before_prompt_build` and `agent_end` hooks. The wrapper calls `KernelAgentMemoryBackend` through the public `cogmem` API via a Bun bridge; core still does not import OpenClaw. Plugin 0.6.3 uses singleton queue/spawn locks, stale-lock and stale-processing recovery, and bounded remember batches so queued `agent_end` recording does not hold SQLite open longer than necessary.
 
 The wrapper does not rewrite OpenClaw's native prompt, tool instructions, skills, or conversation order. It only prepends Cogmem-owned blocks:
 

package/examples/openclaw-backend/SKILL.md

@@ -40,6 +40,14 @@ cogmem doctor
 cogmem connect openclaw --workspace . --auto --force
 ```
 
+If Bun is already installed and the operator wants npm global installation instead of the one-line installer, use:
+
+```bash
+npm install -g cogmem@latest
+cogmem init --yes --agent openclaw --scope project
+cogmem connect openclaw --workspace . --auto --force
+```
+
 This creates project-local kernel config and storage under `.cogmem/`, which is the recommended OpenClaw workspace setup.
 
 ```bash
@@ -98,7 +106,7 @@ cogmem update --yes
 # Manual equivalent: cogmem migrate --yes --backup && cogmem doctor --fix --agent openclaw --workspace . --plugin-only
 ```
 
-`cogmem update --yes` installs `cogmem@latest` from npm, runs the newly installed backed-up migration with the resolved config, refreshes OpenClaw's generated plugin files when the integration is configured, and then reports that the OpenClaw gateway or agent host must be restarted. Agents should inspect `cogmem update --dry-run --json` or `cogmem migrate --dry-run --json` when an operator wants a preview. Schema migration preserves Raw Ledger events; it updates governed projections and indexes only.
+`cogmem update --yes` installs `cogmem@latest` from npm, runs the newly installed backed-up migration with the resolved config, refreshes OpenClaw's generated plugin files when the integration is configured, and then reports that the OpenClaw gateway or agent host must be restarted. For npm global installs, `cogmem update --yes` resolves to `npm install -g cogmem@latest` instead of writing into the current directory. Agents should inspect `cogmem update --dry-run --json` or `cogmem migrate --dry-run --json` when an operator wants a preview. Schema migration preserves Raw Ledger events; dry-run is read-only and updates governed projections and indexes only during apply.
 
 After any 3.5.2 -> 3.6.x OpenClaw upgrade, refresh the generated OpenClaw plugin files. Use the plugin-only path first when OpenClaw is misbehaving, because it does not open the Cogmem database:
 
@@ -298,7 +306,7 @@ cogmem connect openclaw --workspace . --auto --force
 
 `--auto` writes `<workspace>/extensions/cogmem-auto-memory/`, patches `plugins.load.paths`, and enables `hooks.allowPromptInjection=true` and `hooks.allowConversationAccess=true` for the wrapper. The wrapper registers `before_prompt_build` for governed recall and `agent_end` for turn recording, then calls `KernelAgentMemoryBackend` through `cogmem` public API via a Bun bridge. Core does not import OpenClaw.
 
-Queued remember is the default. `agent_end` appends a durable JSONL job under `.cogmem/queue/openclaw-remember.jsonl` and starts a singleton drainer, so Telegram or gateway responses are not blocked by embeddings, SQLite writes, or slow local models. Plugin 0.6.2 acquires the queue lock before opening Cogmem, recovers stale lock directories older than `rememberDrainTimeoutMs`, writes `owner.json` lock metadata, and processes bounded batches controlled by `rememberDrainBatchSize` (default `20`). If a drain fails, the job is retried and then moved to a dead-letter file instead of being silently discarded.
+Queued remember is the default. `agent_end` appends a durable JSONL job under `.cogmem/queue/openclaw-remember.jsonl` and starts a singleton drainer, so Telegram or gateway responses are not blocked by embeddings, SQLite writes, or slow local models. Plugin 0.6.3 acquires the queue lock before opening Cogmem, recovers stale lock directories and stale `.processing` queue files older than `rememberDrainTimeoutMs`, writes `owner.json` lock metadata, and processes bounded batches controlled by `rememberDrainBatchSize` (default `20`). If a drain fails, the job is retried and then moved to a dead-letter file instead of being silently discarded.
 
 When automatic memory recording looks stuck, do not delete queue files first. Diagnose the plugin and locks:
 
@@ -309,6 +317,8 @@ cat .cogmem/queue/openclaw-remember.jsonl.lock/owner.json 2>/dev/null || true
 cat .cogmem/queue/openclaw-remember.jsonl.spawn.lock/owner.json 2>/dev/null || true
 ```
 
+`openclaw diagnose` reports pending queue lines, dead-letter lines, active lock metadata, spawn-lock metadata, and stale `.processing` files. Use that JSON before deleting anything manually.
+
 If `plugin.current=false`, refresh without opening the database:
 
 ```bash

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

@@ -1,4 +1,4 @@
-# Cogmem 3.6.2 Operations Reference for OpenClaw
+# Cogmem 3.6.3 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.
 
@@ -33,6 +33,14 @@ cogmem doctor
 cogmem connect openclaw --workspace . --auto --force --json
 ```
 
+If Bun is already installed and the operator prefers npm global installation:
+
+```bash
+npm install -g cogmem@latest
+cogmem init --yes --agent openclaw --scope project
+cogmem connect openclaw --workspace . --auto --force --json
+```
+
 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.
 
 ## Upgrade and migrate
@@ -44,7 +52,7 @@ cogmem update --yes
 openclaw gateway restart
 ```
 
-`cogmem update --yes` installs `cogmem@latest` from npm, then runs post-install work through the newly installed local CLI. With a valid config it runs `cogmem migrate --yes --backup --config <config>`. When OpenClaw integration is enabled, it also runs `cogmem doctor --fix --agent openclaw --plugin-only --config <config> --workspace <workspace>` so stale generated plugin files are replaced before restart.
+`cogmem update --yes` installs `cogmem@latest` from npm, then runs post-install work through the newly installed CLI. For npm global installs it uses `npm install -g cogmem@latest`; for the one-line installer it updates `~/.cogmem/pkg`; for a workspace dependency it updates that workspace. With a valid config it runs `cogmem migrate --yes --backup --config <config>`. When OpenClaw integration is enabled, it also runs `cogmem doctor --fix --agent openclaw --plugin-only --config <config> --workspace <workspace>` so stale generated plugin files are replaced before restart.
 
 Preview the package, migration, and plugin-refresh plan without writing:
 
@@ -62,7 +70,7 @@ openclaw gateway restart
 cogmem openclaw diagnose --workspace . --json
 ```
 
-The second command upgrades 3.5.2 schema 24, an existing 3.6.0 schema-26 database, or a pre-release schema-25 test database to the 3.6.2 schema-27 state in one run. It preserves Raw Ledger evidence. Keep the returned `backupPath` until verification passes.
+The second command upgrades 3.5.2 schema 24, an existing 3.6.0 schema-26 database, or a pre-release schema-25 test database to the 3.6.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`.
 
 After upgrading the package/database, refresh OpenClaw's generated plugin files. `doctor --plugin-only` avoids opening the Cogmem kernel, so it can repair stale `extensions/cogmem-auto-memory/index.js` and `bridge.mjs` even when an old drainer has SQLite busy. Use `connect --auto --force` when intentionally reinstalling the full integration and patching OpenClaw config:
 
@@ -75,15 +83,16 @@ Use `cogmem openclaw diagnose --workspace . --json` when automatic memory blocks
 - `plugin.current=false`: generated files are stale; run plugin-only fix and restart gateway.
 - no `audit.lastBeforePromptBuild`: plugin is not loaded or the hook did not fire.
 - `audit.lastBeforePromptBuild.action=error`: bridge or DB failure; inspect `reason`, `bridgeCommand`, and `dbLocked`.
-- `action=inject` but no visible block: inspect `returnedInjectionShape`. Plugin 0.6.2 returns `prependContext`, `context`, and `promptPrefix`; if OpenClaw still ignores all three, the host hook contract changed and the OpenClaw plugin API must be checked before blaming recall.
+- `action=inject` but no visible block: inspect `returnedInjectionShape`. Plugin 0.6.3 returns `prependContext`, `context`, and `promptPrefix`; if OpenClaw still ignores all three, the host hook contract changed and the OpenClaw plugin API must be checked before blaming recall.
 
-Plugin 0.6.2 queue behavior:
+Plugin 0.6.3 queue behavior:
 
 - `agent_end` only appends durable JSONL jobs, then starts at most one drainer through queue/spawn locks.
 - `drain-remember-queue` acquires the queue lock before opening Cogmem or SQLite. A second drainer exits without opening the DB.
-- Stale `.cogmem/queue/openclaw-remember.jsonl.lock` and `.spawn.lock` directories older than `rememberDrainTimeoutMs` are recovered automatically and carry `owner.json` metadata for diagnosis.
+- Stale `.cogmem/queue/openclaw-remember.jsonl.lock`, `.spawn.lock`, and `.processing` files older than `rememberDrainTimeoutMs` are recovered automatically and carry enough metadata for diagnosis.
 - `rememberDrainBatchSize` defaults to `20`, so a busy workspace drains bounded batches and releases DB handles quickly. Lower it temporarily if OpenClaw shares a slow SQLite disk.
 - Failed jobs retry up to `rememberMaxAttempts`; exhausted jobs move to `.dead.jsonl`.
+- `cogmem openclaw diagnose --workspace . --json` reports pending queue lines, dead-letter lines, lock owners, spawn-lock owners, and `.processing` files.
 
 If the queue is not draining, diagnose before deleting files:
 

package/install.sh

@@ -50,6 +50,12 @@ link_cli() {
     fi
   done
   log "Installed CLI: $BIN_DIR/cogmem"
+  case ":$PATH:" in
+    *":$BIN_DIR:"*) ;;
+    *)
+      log "Warning: $BIN_DIR is not on PATH. Add it to PATH or run $BIN_DIR/cogmem directly."
+      ;;
+  esac
 }
 
 main() {

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "cogmem",
 
-  "version": "3.6.2",
+  "version": "3.6.3",
 
   "type": "module",
   "description": "cogmem — agent-native memory kernel for a single local-first AI agent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liuqin164/cogmem.git"
+  },
   "main": "./dist/public.js",
   "types": "./dist/public.d.ts",
   "exports": {
@@ -46,7 +50,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "prepare": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
-    "prepublishOnly": "bun run typecheck && bun test __tests__/release-metadata.unit.test.ts __tests__/update-release.unit.test.ts __tests__/agent-import-cli.unit.test.ts && bun run build",
+    "prepublishOnly": "bun run typecheck && bun test __tests__ && bun run build && npm pack --dry-run --json",
     "type": "tsc -p tsconfig.json --noEmit",
     "test": "bun test __tests__",
     "typecheck": "tsc -p tsconfig.json --noEmit"