claude-mem-lite 2.89.0 → 2.90.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.89.0",
+      "version": "2.90.1",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.89.0",
+  "version": "2.90.1",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/cli/activity.mjs

@@ -11,6 +11,7 @@
 import { inferProject } from '../utils.mjs';
 import { resolveProject } from '../project-utils.mjs';
 import { parseArgs, out, fail } from './common.mjs';
+import { parseIntFlag } from '../lib/cli-flags.mjs';
 
 function formatActivityResults(rows) {
   if (!rows || rows.length === 0) return '(no events)';
@@ -77,17 +78,20 @@ export async function cmdActivity(db, args) {
       fail(`[mem] activity search: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);
       return;
     }
-    const limit = flags.limit !== undefined ? parseInt(flags.limit, 10) : 10;
+    const limit = parseIntFlag(flags.limit, { name: '--limit', defaultValue: 10, max: 1000 });
     const rows = searchEvents(db, q, { project, type, limit });
     out(formatActivityResults(rows));
     return;
   }
 
   if (sub === 'recent') {
-    // Accept either `activity recent 5` or `activity recent --limit 5`.
-    const posLimit = positional.length > 0 ? parseInt(positional[0], 10) : NaN;
-    const flagLimit = flags.limit !== undefined ? parseInt(flags.limit, 10) : NaN;
-    const limit = Number.isFinite(posLimit) ? posLimit : (Number.isFinite(flagLimit) ? flagLimit : 20);
+    // Accept either `activity recent 5` or `activity recent --limit 5`. Both routed
+    // through parseIntFlag so garbage ("2abc"), negatives (SQLite LIMIT -1 = UNLIMITED
+    // full-table dump), and uncapped huge values warn + clamp to default/max, matching
+    // the search/recent/browse siblings.
+    const limit = positional.length > 0
+      ? parseIntFlag(positional[0], { name: 'count', defaultValue: 20, max: 1000 })
+      : parseIntFlag(flags.limit, { name: '--limit', defaultValue: 20, max: 1000 });
     const type = flags.type || null;
     if (type !== null && !VALID_EVENT_TYPES.has(type)) {
       fail(`[mem] activity recent: invalid --type "${type}". Valid: ${[...VALID_EVENT_TYPES].join(', ')}`);

package/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'citation-stats', 'delete', 'update', 'export', 'compress', 'maintain', 'optimize', 'fts-check', 'registry', 'import', 'import-jsonl', 'enrich', 'activity', 'adopt', 'unadopt', 'memdir-audit', 'defer', 'help']);
+const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'citation-stats', 'delete', 'update', 'export', 'restore', 'compress', 'maintain', 'optimize', 'fts-check', 'registry', 'import', 'import-jsonl', 'enrich', 'activity', 'adopt', 'unadopt', 'memdir-audit', 'defer', 'help']);
 const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'repair', 'release']);
 
 const cmd = process.argv[2];
@@ -13,14 +13,16 @@ if (cmd === '--version' || cmd === '-v') {
 } else if (cmd === '--help' || cmd === '-h') {
   const { run } = await import('./mem-cli.mjs');
   await run(['help']);
-} else if (cmd === 'doctor' && process.argv.slice(3).some(a => a.startsWith('--') && a.length > 2)) {
-  // Per #8217 single-source-of-truth: any flagged `doctor --X` is a DB-layer
-  // inspection tool (--benchmark, --metrics, --session-audit, future flags)
-  // and routes to mem-cli. Plain `doctor` (no flags) keeps running the
-  // install health-check below — adding a new flag in cli/doctor.mjs no
-  // longer requires touching this enumeration. The `length > 2` guard
-  // ignores a bare `--` (POSIX end-of-options separator) so `doctor --`
-  // continues to route to install.mjs, not mem-cli.
+} else if (cmd === 'doctor' && process.argv.slice(3).some(a => a === '--benchmark' || a === '--metrics' || a === '--session-audit')) {
+  // Per #8217: the DB-layer doctor modes (--benchmark / --metrics / --session-audit,
+  // each implemented in cli/doctor.mjs) route to mem-cli. Everything else — plain
+  // `doctor`, `doctor --` (POSIX end-of-options), and `doctor --json` — stays with
+  // install.mjs's health-check, which OWNS --json (install.mjs doctor() line ~1216).
+  // Pre-fix the router forwarded ANY flagged `doctor --X` to mem-cli, so the documented
+  // `doctor --json` (install health JSON, advertised in install.mjs usage) was shadowed
+  // and rejected by cli/doctor.mjs. Gating on the three DB-layer flags keeps --json
+  // (and any future install-doctor flag) on the install path. Adding a NEW DB-layer
+  // mode requires extending this list — a deliberate trade for a working --json.
   const { run } = await import('./mem-cli.mjs');
   await run(process.argv.slice(2));
 } else if (CLI_COMMANDS.has(cmd)) {
@@ -30,7 +32,10 @@ if (cmd === '--version' || cmd === '-v') {
   // No command: show CLI help if installed, install help if not
   const { existsSync } = await import('fs');
   const { join } = await import('path');
-  const dbPath = join(process.env.HOME || '', '.claude-mem-lite', 'claude-mem-lite.db');
+  // D#29: honor CLAUDE_MEM_DIR so the install-vs-CLI help routing is correct on
+  // relocated installs (matches schema.mjs DB_DIR; HOME fallback when env unset).
+  const dataDir = process.env.CLAUDE_MEM_DIR || join(process.env.HOME || '', '.claude-mem-lite');
+  const dbPath = join(dataDir, 'claude-mem-lite.db');
   if (existsSync(dbPath)) {
     const { run } = await import('./mem-cli.mjs');
     await run(['help']);

package/hook-handoff.mjs

@@ -32,12 +32,26 @@ import * as taskReaderModule from './lib/task-reader.mjs';
  * @param {string|null} [scopeSessionId=null] CC UUID for session_handoffs.session_id column
  */
 export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapshot, scopeSessionId = null) {
-  // 1. Working objective — from user prompts
-  const prompts = db.prepare(`
-    SELECT prompt_text FROM user_prompts
-    WHERE content_session_id = ?
-    ORDER BY prompt_number ASC LIMIT 5
-  `).all(sessionId);
+  // 1. Working objective — from user prompts.
+  // D#26: getSessionId() is project-scoped, so multiple CC sessions in one project
+  // share `content_session_id`. When a genuine CC scope is passed (scopeSessionId is
+  // the CC UUID, i.e. differs from the mem-internal sessionId), filter to THIS CC
+  // session's prompts so working_on doesn't merge concurrent/sequential sessions.
+  // `OR cc_session_id IS NULL` keeps legacy rows + non-CC/no-stdin invocations. When
+  // scopeSessionId is absent or == sessionId (legacy/test/no-stdin), fall back to the
+  // unfiltered query (identical to pre-D#26 behavior).
+  const ccScope = scopeSessionId && scopeSessionId !== sessionId ? scopeSessionId : null;
+  const prompts = ccScope
+    ? db.prepare(`
+        SELECT prompt_text FROM user_prompts
+        WHERE content_session_id = ? AND (cc_session_id = ? OR cc_session_id IS NULL)
+        ORDER BY prompt_number ASC LIMIT 5
+      `).all(sessionId, ccScope)
+    : db.prepare(`
+        SELECT prompt_text FROM user_prompts
+        WHERE content_session_id = ?
+        ORDER BY prompt_number ASC LIMIT 5
+      `).all(sessionId);
   if (prompts.length === 0) return;  // Empty session — nothing to hand off
 
   // Filter prompts whose only content is workflow/control language ("继续",
@@ -73,12 +87,30 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
     }
   }
 
+  // D#28 (completes D#26): observations carry the project-scoped memory_session_id, shared by
+  // parallel/sequential same-project CC sessions. Lower-bound the observation queries below to
+  // THIS CC session's start (earliest prompt epoch for ccScope) so Completed / Key Files / Key
+  // Decisions stop merging a prior session's work — the observation-side complement of
+  // working_on's cc-scoping. When ccScope is absent or its session has no prompts (MIN→null),
+  // ccWindowStart stays null and the queries run unscoped (pre-D#28 behavior). Residual: truly
+  // concurrent same-project sessions whose windows overlap can still co-attribute a few rows.
+  let ccWindowStart = null;
+  if (ccScope) {
+    const w = db.prepare(`
+      SELECT MIN(created_at_epoch) AS startEpoch FROM user_prompts
+      WHERE content_session_id = ? AND cc_session_id = ?
+    `).get(sessionId, ccScope);
+    if (typeof w?.startEpoch === 'number') ccWindowStart = w.startEpoch;
+  }
+  const obsWindowClause = ccWindowStart !== null ? 'AND created_at_epoch >= ?' : '';
+  const obsWindowParams = ccWindowStart !== null ? [ccWindowStart] : [];
+
   // 2. Completed — from observations (include narrative for richer handoff)
   const completed = db.prepare(`
     SELECT title, type, narrative FROM observations
-    WHERE memory_session_id = ? AND COALESCE(compressed_into, 0) = 0
+    WHERE memory_session_id = ? AND COALESCE(compressed_into, 0) = 0 ${obsWindowClause}
     ORDER BY created_at_epoch DESC LIMIT 15
-  `).all(sessionId);
+  `).all(sessionId, ...obsWindowParams);
 
   // 3. Recent activity — episode snapshot + full session edit history from narratives.
   // Keep only entries that represent in-flight work (file edits) or outright failures
@@ -131,9 +163,9 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   if (episodeSnapshot?.files) episodeSnapshot.files.filter(isValidFile).forEach(f => fileSet.add(f));
   const obsFiles = db.prepare(`
     SELECT files_modified FROM observations
-    WHERE memory_session_id = ? AND files_modified IS NOT NULL
+    WHERE memory_session_id = ? AND files_modified IS NOT NULL ${obsWindowClause}
     ORDER BY created_at_epoch DESC LIMIT 10
-  `).all(sessionId);
+  `).all(sessionId, ...obsWindowParams);
   for (const row of obsFiles) {
     try { JSON.parse(row.files_modified).filter(isValidFile).forEach(f => fileSet.add(f)); } catch {}
   }
@@ -142,9 +174,9 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   const decisions = db.prepare(`
     SELECT title FROM observations
     WHERE memory_session_id = ? AND COALESCE(importance, 1) >= 2
-      AND COALESCE(compressed_into, 0) = 0
+      AND COALESCE(compressed_into, 0) = 0 ${obsWindowClause}
     ORDER BY created_at_epoch DESC LIMIT 10
-  `).all(sessionId).filter(d => d.title && !LOW_SIGNAL_TITLE.test(d.title)).slice(0, 5);
+  `).all(sessionId, ...obsWindowParams).filter(d => d.title && !LOW_SIGNAL_TITLE.test(d.title)).slice(0, 5);
 
   // 6. Match keywords
   const allText = [workingOn, ...completed.map(c => c.title).filter(Boolean), unfinished].join(' ');

package/hook-update.mjs

@@ -7,7 +7,7 @@ import { readFileSync, writeFileSync, copyFileSync, cpSync, readdirSync, existsS
 import { join, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { tmpdir, homedir } from 'node:os';
-import { DB_DIR } from './schema.mjs';
+import { DB_DIR, CODE_DIR } from './schema.mjs';
 import { debugCatch, debugLog } from './utils.mjs';
 // Local manifest is fallback only — the active manifest is loaded from the
 // extracted tarball's own source-files.mjs inside installExtractedRelease.
@@ -16,8 +16,15 @@ import { SOURCE_FILES as LOCAL_SOURCE_FILES, HOOK_SCRIPT_FILES as LOCAL_HOOK_SCR
 
 // ── Configuration ──────────────────────────────────────────
 const GITHUB_REPO = 'sdsrss/claude-mem-lite';
-const INSTALL_DIR = DB_DIR;  // ~/.claude-mem-lite/
-const STATE_FILE = join(INSTALL_DIR, 'runtime', 'update-state.json');
+// Plugin CODE location (server.mjs / package.json / install target) — always
+// homedir-rooted, NEVER follows CLAUDE_MEM_DIR (see schema.mjs CODE_DIR). Used
+// for dev-mode detection, current-version read, and the install target dir.
+const INSTALL_DIR = CODE_DIR;  // ~/.claude-mem-lite/ (code)
+// DATA/state location — runtime/update-state.json lives with the data (env-aware
+// DB_DIR), matching hook-shared RUNTIME_DIR and install.mjs doctor's read path.
+// Equal to INSTALL_DIR unless CLAUDE_MEM_DIR relocates the data dir.
+const STATE_DIR = DB_DIR;
+const STATE_FILE = join(STATE_DIR, 'runtime', 'update-state.json');
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;       // 24 hours
 const FETCH_TIMEOUT_MS = 3000;                         // 3s network timeout
 const RATE_LIMIT_INTERVAL_MS = 6 * 60 * 60 * 1000;   // 6h if rate-limited
@@ -558,7 +565,7 @@ function readState() {
 
 function saveState(state) {
   try {
-    const dir = join(INSTALL_DIR, 'runtime');
+    const dir = join(STATE_DIR, 'runtime');
     mkdirSync(dir, { recursive: true });
     const tmpFile = STATE_FILE + `.tmp-${process.pid}`;
     writeFileSync(tmpFile, JSON.stringify(state, null, 2));

package/hook.mjs

@@ -1208,7 +1208,12 @@ async function handleUserPrompt() {
   // every downstream consumer (user_prompts INSERT, FTS query, continuation
   // detection, semantic-memory injection) sees the redacted text — single
   // source of truth for the privacy primitive.
-  const promptText = stripPrivate(rawPrompt);
+  // Strip NUL / C0 control chars (keep \t \n \r) before any downstream use: an
+  // embedded NUL terminates SQLite's C string, silently truncating the stored
+  // prompt_text at the first NUL (and breaking FTS). Single source of truth, so the
+  // user_prompts INSERT, FTS query, and continuation detection all see clean text.
+  // eslint-disable-next-line no-control-regex -- intentional: NUL/C0 strip prevents SQLite C-string truncation
+  const promptText = stripPrivate(rawPrompt).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');
 
   const sessionId = getSessionId();
   const db = openDb();
@@ -1233,24 +1238,27 @@ async function handleUserPrompt() {
     ).get(sessionId);
     const promptNumber = bumped?.prompt_counter || 1;
 
+    // Claude Code's real session_id (CC UUID) from hook stdin. Persisted on the
+    // prompt row (cc_session_id) so buildAndSaveHandoff can scope working_on to ONE
+    // CC session — getSessionId() is project-scoped (no CC-UUID), so without this
+    // concurrent/within-TTL same-project sessions merge each other's prompts (D#26).
+    // Also scopes handoff-row injection below. Null (legacy) when stdin lacks session_id.
+    const ccSessionId = typeof hookData.session_id === 'string' && hookData.session_id.length > 0
+      ? hookData.session_id
+      : null;
+
     db.prepare(`
-      INSERT INTO user_prompts (content_session_id, prompt_text, prompt_number, created_at, created_at_epoch)
-      VALUES (?, ?, ?, ?, ?)
+      INSERT INTO user_prompts (content_session_id, prompt_text, prompt_number, cc_session_id, created_at, created_at_epoch)
+      VALUES (?, ?, ?, ?, ?, ?)
     `).run(
       sessionId,
       scrubSecrets(promptText.slice(0, 10000)),
       promptNumber,
+      ccSessionId,
       now.toISOString(), now.getTime()
     );
 
     // Cross-session handoff injection (first 3 prompts window, before semantic memory).
-    // Use Claude Code's real session_id from hook stdin to scope handoffs to this CC
-    // session — prevents cross-session bleed when running parallel sessions for the
-    // same project (see docs/bug.txt). Falls back to null (legacy behavior) if the
-    // hook input does not carry session_id.
-    const ccSessionId = typeof hookData.session_id === 'string' && hookData.session_id.length > 0
-      ? hookData.session_id
-      : null;
     if (promptNumber <= 3) {
       try {
         if (detectContinuationIntent(db, promptText, project, ccSessionId)) {

package/install.mjs

@@ -10,8 +10,18 @@ import { createRequire } from 'node:module';
 
 const PROJECT_DIR = resolve(import.meta.dirname ?? dirname(fileURLToPath(import.meta.url)));
 const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
+// Plugin CODE / install location — ALWAYS homedir-rooted. Claude Code's
+// settings.json + MCP registration bake ABSOLUTE paths to server.mjs / hooks here,
+// and env vars are per-shell (the MCP launcher won't reliably inherit
+// CLAUDE_MEM_DIR), so code must NOT follow the relocation env var.
 const DATA_DIR = join(homedir(), '.claude-mem-lite');
-const DB_PATH = join(DATA_DIR, 'claude-mem-lite.db');
+// User DATA location — DB, managed resources, registry DB, runtime/. Honors
+// CLAUDE_MEM_DIR exactly like schema.mjs DB_DIR so the installer WRITES data where
+// the runtime/data layer READS it (pre-fix: installer wrote homedir, runtime read
+// the relocated dir → preinstalled skills silently vanished, doctor read the wrong
+// DB). Equals DATA_DIR when CLAUDE_MEM_DIR is unset (the common case).
+const MEM_DATA_DIR = process.env.CLAUDE_MEM_DIR || DATA_DIR;
+const DB_PATH = join(MEM_DATA_DIR, 'claude-mem-lite.db');
 const OLD_DATA_DIR = join(homedir(), '.claude-mem');
 
 // Detect ephemeral context (npx) — files won't persist after exit
@@ -319,6 +329,8 @@ async function install() {
   }
 
   if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
+  // Under relocation the DB/managed/runtime live here, not in the code dir — create it too.
+  if (!existsSync(MEM_DATA_DIR)) mkdirSync(MEM_DATA_DIR, { recursive: true });
 
   if (IS_DEV) {
     log('Dev mode — creating symlinks in ~/.claude-mem-lite/...');
@@ -675,7 +687,7 @@ async function install() {
   // "no such column: memory_session_id". Rename to a timestamped backup
   // so the new install creates a fresh v28 DB.
   try {
-    const r = migrateLegacyClaudeMemData(OLD_DATA_DIR, DATA_DIR);
+    const r = migrateLegacyClaudeMemData(OLD_DATA_DIR, MEM_DATA_DIR);
     if (r.action === 'backed-up') {
       ok(`Legacy ~/.claude-mem/ DB backed up to ${r.backupPath}`);
       log('New v28 DB will be created on first launch (legacy schema is incompatible).');
@@ -685,7 +697,7 @@ async function install() {
   }
 
   // 5b. Rename claude-mem.db → claude-mem-lite.db in same directory
-  const oldDbInDir = join(DATA_DIR, 'claude-mem.db');
+  const oldDbInDir = join(MEM_DATA_DIR, 'claude-mem.db');
   if (existsSync(oldDbInDir) && !existsSync(DB_PATH)) {
     renameSync(oldDbInDir, DB_PATH);
     for (const ext of ['-wal', '-shm']) {
@@ -714,7 +726,7 @@ async function install() {
       const resources = manifest.resources || [];
 
       if (resources.length > 0) {
-        const managedDir = join(DATA_DIR, 'managed');
+        const managedDir = join(MEM_DATA_DIR, 'managed');
 
         // 6a. Git shallow clone unique repos
         const repos = new Map();
@@ -805,7 +817,7 @@ async function install() {
 
         // 6b. Init registry DB and record preinstalled entries
         const { ensureRegistryDb } = await importFromInstall('registry.mjs');
-        const regDbPath = join(DATA_DIR, 'resource-registry.db');
+        const regDbPath = join(MEM_DATA_DIR, 'resource-registry.db');
         const rdb = ensureRegistryDb(regDbPath);
 
         const insertPre = rdb.prepare(`
@@ -853,7 +865,7 @@ async function install() {
         // 6d. Scan and index resources (fallback-only, Haiku indexing deferred to first run)
         log('  Scanning resources...');
         const { scanAllResources, diffResources } = await importFromInstall('registry-scanner.mjs');
-        const scanned = scanAllResources({ dataDir: DATA_DIR });
+        const scanned = scanAllResources({ dataDir: MEM_DATA_DIR });
 
         // Attach star counts and repo URLs
         for (const s of scanned) {
@@ -1063,15 +1075,26 @@ async function uninstall() {
 
   // 6. Purge data if requested
   if (flags.has('--purge')) {
-    const expectedPurgePath = join(homedir(), '.claude-mem-lite');
-    if (existsSync(DATA_DIR) && DATA_DIR === expectedPurgePath) {
+    const homeDir = join(homedir(), '.claude-mem-lite');
+    // Always remove the homedir code/install dir (guarded to the canonical path).
+    if (existsSync(DATA_DIR) && DATA_DIR === homeDir) {
       rmSync(DATA_DIR, { recursive: true, force: true });
       ok('Data purged (~/.claude-mem-lite/)');
     } else if (existsSync(DATA_DIR)) {
       fail('DATA_DIR path mismatch, refusing to purge for safety: ' + DATA_DIR);
     }
+    // Also remove the relocated data dir — but ONLY if it's genuinely our data dir
+    // (contains claude-mem-lite.db), so a mistyped CLAUDE_MEM_DIR is never rm'd.
+    if (MEM_DATA_DIR !== homeDir) {
+      if (existsSync(join(MEM_DATA_DIR, 'claude-mem-lite.db'))) {
+        rmSync(MEM_DATA_DIR, { recursive: true, force: true });
+        ok(`Relocated data purged (${MEM_DATA_DIR})`);
+      } else if (existsSync(MEM_DATA_DIR)) {
+        warn(`CLAUDE_MEM_DIR (${MEM_DATA_DIR}) has no claude-mem-lite.db — left untouched. Remove manually if intended.`);
+      }
+    }
   } else {
-    log('Data preserved in ~/.claude-mem-lite/ (use --purge to remove)');
+    log('Data preserved (use --purge to remove)');
   }
 
   console.log('\n  Done!\n');
@@ -1383,7 +1406,7 @@ async function doctor() {
 
   // Update state
   try {
-    const stateFile = join(INSTALL_DIR, 'runtime', 'update-state.json');
+    const stateFile = join(MEM_DATA_DIR, 'runtime', 'update-state.json');
     if (existsSync(stateFile)) {
       const state = JSON.parse(readFileSync(stateFile, 'utf8'));
       const parts = [];
@@ -1439,11 +1462,14 @@ async function doctor() {
 
   // Stale temp files
   try {
-    const runtimeDir = join(INSTALL_DIR, 'runtime');
+    // hook-update + the episode workers write runtime/ + staging under DB_DIR
+    // (= MEM_DATA_DIR, env-aware), NOT the homedir code dir — scan there so doctor
+    // sees the real residue under relocation.
+    const runtimeDir = join(MEM_DATA_DIR, 'runtime');
     let staleCount = 0;
     const stalePatterns = ['.update-staging-', '.update-backup-'];
-    if (existsSync(INSTALL_DIR)) {
-      for (const f of readdirSync(INSTALL_DIR)) {
+    if (existsSync(MEM_DATA_DIR)) {
+      for (const f of readdirSync(MEM_DATA_DIR)) {
         if (stalePatterns.some(p => f.startsWith(p))) staleCount++;
       }
     }
@@ -1712,10 +1738,11 @@ function cleanup() {
   console.log(`\nclaude-mem-lite cleanup${dryRun ? ' (--dry-run)' : ''}\n`);
   let removed = 0;
 
-  // Clean .update-staging-* / .update-backup-* in INSTALL_DIR
+  // Clean .update-staging-* / .update-backup-* — hook-update writes these under
+  // DB_DIR (= MEM_DATA_DIR, env-aware), so scan the data dir, not the homedir code dir.
   const stalePatterns = ['.update-staging-', '.update-backup-'];
-  if (existsSync(INSTALL_DIR)) {
-    for (const f of readdirSync(INSTALL_DIR)) {
+  if (existsSync(MEM_DATA_DIR)) {
+    for (const f of readdirSync(MEM_DATA_DIR)) {
       if (stalePatterns.some(p => f.startsWith(p))) {
         if (dryRun) {
           ok(`Would remove: ${f}`);
@@ -1723,7 +1750,7 @@ function cleanup() {
           continue;
         }
         try {
-          rmSync(join(INSTALL_DIR, f), { recursive: true, force: true });
+          rmSync(join(MEM_DATA_DIR, f), { recursive: true, force: true });
           ok(`Removed: ${f}`);
           removed++;
         } catch (e) {
@@ -1733,8 +1760,8 @@ function cleanup() {
     }
   }
 
-  // Clean pending-* / ep-flush-* in runtime/
-  const runtimeDir = join(INSTALL_DIR, 'runtime');
+  // Clean pending-* / ep-flush-* in runtime/ (under the env-aware data dir)
+  const runtimeDir = join(MEM_DATA_DIR, 'runtime');
   if (existsSync(runtimeDir)) {
     for (const f of readdirSync(runtimeDir)) {
       if (f.startsWith('pending-') || f.startsWith('ep-flush-')) {

package/lib/cli-flags.mjs

@@ -19,6 +19,21 @@
 
 const DEFAULT_STDERR_WRITE = msg => process.stderr.write(msg);
 
+/**
+ * True if `raw` is a clean integer or float-literal token — no trailing garbage,
+ * hex, or scientific notation. Float literals ARE accepted (callers truncate via
+ * parseInt, the deliberate #8277 decision); this only rejects shapes bare parseInt
+ * would silently coerce ("2abc"→2, "0x10"→0, "1e2"→1). Single source of the
+ * strict-shape rule shared by parseIntFlag and the reject-style numeric flags
+ * (save/update --importance, defer --priority).
+ *
+ * @param {string|number} raw Flag value as captured by parseArgs.
+ * @returns {boolean}
+ */
+export function isNumericToken(raw) {
+  return /^-?\d+(\.\d+)?$/.test(String(raw).trim());
+}
+
 /**
  * Validate and parse a CLI numeric flag with optional bounds.
  *
@@ -38,8 +53,15 @@ export function parseIntFlag(rawValue, opts) {
     return defaultValue;
   }
 
-  const parsed = parseInt(rawValue, 10);
-  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+  // Reject trailing-garbage / hex / scientific tokens that bare parseInt would
+  // silently coerce by stopping at the first non-digit ("2abc"→2, "0x10"→0,
+  // "1e2"→1) — those slip past the Number.isInteger gate and violate the
+  // warn+default contract above. Float literals ("3.7"→3) stay ACCEPTED via
+  // parseInt truncation: that's the deliberate #8277 decision pinned by the
+  // 'rejects floats' case in cli-flags.test.mjs, so the shape check admits them.
+  const str = String(rawValue).trim();
+  const parsed = parseInt(str, 10);
+  if (!isNumericToken(str) || !Number.isInteger(parsed) || parsed < min || parsed > max) {
     const range = max === Number.MAX_SAFE_INTEGER ? `≥ ${min}` : `between ${min} and ${max}`;
     warn(`[mem] Invalid ${name} "${rawValue}" (must be an integer ${range}); using default ${defaultValue}\n`);
     return defaultValue;

package/mem-cli.mjs

@@ -23,10 +23,10 @@ import {
 import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
 import { buildSessionContextLines } from './hook-context.mjs';
 import { cmdAdopt, cmdUnadopt } from './adopt-cli.mjs';
-import { parseIntFlag } from './lib/cli-flags.mjs';
+import { parseIntFlag, isNumericToken } from './lib/cli-flags.mjs';
 import { auditMemdir, memdirPath } from './memdir.mjs';
 import { probeOtherSources as probeIdSources, bucketIdTokens } from './lib/id-routing.mjs';
-import { basename, join } from 'path';
+import { basename, join, sep } from 'path';
 import { readFileSync, existsSync, readdirSync } from 'fs';
 
 // v2.41: shared CLI helpers extracted to cli/common.mjs. Keep this file as the
@@ -71,16 +71,16 @@ function cmdSearch(db, args) {
     process.stderr.write(`[mem] Note: --from "${flags.from}" is after --to "${flags.to}"; this range is empty\n`);
   }
   const minImportance = flags.importance !== undefined ? parseInt(flags.importance, 10) : null;
-  if (minImportance !== null && (isNaN(minImportance) || minImportance < 1 || minImportance > 3)) {
+  // isNumericToken first: "2abc"→2 / "1e2"→1 would pass the range check and silently
+  // filter at a value the user never typed. Reject garbage like out-of-range does.
+  if (minImportance !== null && (!isNumericToken(flags.importance) || isNaN(minImportance) || minImportance < 1 || minImportance > 3)) {
     fail(`[mem] Invalid --importance "${flags.importance}". Must be 1, 2, or 3.`);
     return;
   }
   const branch = flags.branch || null;
-  const rawOffset = flags.offset !== undefined ? parseInt(flags.offset, 10) : NaN;
-  if (flags.offset !== undefined && (!Number.isInteger(rawOffset) || rawOffset < 0)) {
-    process.stderr.write(`[mem] Invalid --offset "${flags.offset}" (must be a non-negative integer); using 0\n`);
-  }
-  const offset = Number.isInteger(rawOffset) && rawOffset >= 0 ? rawOffset : 0;
+  // parseIntFlag (min=0) rejects garbage ("2abc"→2, "1e2"→1) the old isInteger check let
+  // through, warns once, and falls back to 0 — same WARN-style contract, now garbage-proof.
+  const offset = parseIntFlag(flags.offset, { name: '--offset', defaultValue: 0, min: 0 });
   const tier = flags.tier || null;
   if (tier && !['working', 'active', 'archive'].includes(tier)) {
     fail(`[mem] Invalid --tier "${tier}". Use: working, active, archive`);
@@ -126,8 +126,14 @@ function cmdSearch(db, args) {
   // so the post-merge sort has room to pick the best from each (paired-path with
   // server.mjs:377 — without this, obs gets systematically squeezed out by sessions).
   const isCrossSourceMode = !effectiveSource;
-  const perSourceLimit = isCrossSourceMode ? Math.max(limit * 3, offset + limit + 10) : limit;
-  const perSourceOffset = isCrossSourceMode ? 0 : offset;
+  // Over-fetch from offset 0 and apply --offset ONCE at the final slice (below) in
+  // ALL modes — mirrors server.mjs. Pushing OFFSET into the obs hybrid path was
+  // unreliable: its AND→OR fallback / vector / concept-cooccurrence stages re-add
+  // rows the SQL OFFSET already skipped, so engine-side paging dropped (or
+  // duplicated) rows on the --type/--tier/--importance/--branch path (a page that
+  // MCP returned came back empty).
+  const perSourceLimit = Math.max(limit * 3, offset + limit + 10);
+  const perSourceOffset = 0;
 
   const results = [];
   // Tracks whether AND returned 0 and OR recovered non-empty. Mirrors server.mjs
@@ -305,7 +311,10 @@ function cmdSearch(db, args) {
   }
   // else 'relevance' keeps BM25 score order (already sorted)
 
-  // Trim to limit with offset
+  // Trim to limit with offset. The engine always received perSourceOffset=0 and
+  // over-fetched (see above), so the merged+reranked `results` start at row 0 and
+  // the offset is applied exactly ONCE here — for every mode. `total` is the full
+  // match count (capped at perSourceLimit), enabling the "N of M" display.
   const total = results.length;
   const paged = results.slice(offset, offset + limit);
 
@@ -389,7 +398,9 @@ function cmdRecent(db, args) {
   const { positional, flags } = parseArgs(args);
   const rawArg = positional[0];
   const rawLimit = parseInt(rawArg, 10);
-  const isValid = Number.isInteger(rawLimit) && rawLimit > 0;
+  // isNumericToken first: "2abc"→2 / "1e2"→1 are positive integers that the bare check
+  // accepted silently; the positional path must reject garbage like the --limit flag does.
+  const isValid = rawArg !== undefined && isNumericToken(rawArg) && Number.isInteger(rawLimit) && rawLimit > 0;
   if (rawArg !== undefined && !isValid) {
     process.stderr.write(`[mem] Invalid count "${rawArg}" (must be a positive integer); using default 10\n`);
   }
@@ -692,7 +703,9 @@ function cmdTimeline(db, args) {
   const parseWindow = (label, raw) => {
     if (raw === undefined) return 5;
     const n = parseInt(raw, 10);
-    if (!Number.isInteger(n) || n < 0) {
+    // isNumericToken first: "2abc"→2 / "1e2"→1 are non-negative integers the bare check
+    // accepted silently; reject garbage tokens like the negative path already does.
+    if (!isNumericToken(raw) || !Number.isInteger(n) || n < 0) {
       process.stderr.write(`[mem] Invalid --${label} "${raw}" (must be a non-negative integer); using default 5\n`);
       return 5;
     }
@@ -925,7 +938,9 @@ function cmdSave(db, args) {
 
   // Explicit saves default to importance=2 (notable) — user chose to save
   const rawImp = flags.importance !== undefined ? parseInt(flags.importance, 10) : 2;
-  if (flags.importance !== undefined && (isNaN(rawImp) || rawImp < 1 || rawImp > 3)) {
+  // isNumericToken first: bare parseInt would coerce "2abc"→2 / "1e2"→1 and persist a
+  // wrong importance that silently skews ranking/decay. Float literals still truncate (#8277).
+  if (flags.importance !== undefined && (!isNumericToken(flags.importance) || isNaN(rawImp) || rawImp < 1 || rawImp > 3)) {
     fail(`[mem] Invalid importance "${flags.importance}". Must be 1, 2, or 3.`);
     return;
   }
@@ -1041,6 +1056,12 @@ function cmdDeferAdd(db, args) {
     return;
   }
   const priority = flags.priority !== undefined ? parseInt(flags.priority, 10) : 2;
+  // isNumericToken first: bare parseInt would coerce "3xyz"→3 and silently escalate a
+  // deferred item's urgency. Float literals still truncate (#8277).
+  if (flags.priority !== undefined && !isNumericToken(flags.priority)) {
+    fail(`[mem] Invalid --priority "${flags.priority}". Must be 1 (low), 2 (normal), or 3 (urgent).`);
+    return;
+  }
   if (![1, 2, 3].includes(priority)) {
     fail(`[mem] Invalid --priority "${flags.priority}". Must be 1 (low), 2 (normal), or 3 (urgent).`);
     return;
@@ -1255,6 +1276,7 @@ async function cmdStats(db, args) {
   const lowVal = db.prepare(`
     SELECT COUNT(*) as c FROM observations
     WHERE COALESCE(importance,1) = 1 AND COALESCE(access_count,0) = 0
+      AND COALESCE(compressed_into, 0) = 0
       AND created_at_epoch < ? ${projectFilter}
   `).get(thirtyDaysAgo, ...baseParams);
   const noiseRatio = obsTotal.c > 0 ? lowVal.c / obsTotal.c : 0;
@@ -1607,6 +1629,19 @@ function cmdUpdate(db, args) {
     return;
   }
 
+  // A value-less `--flag` (last arg, or immediately followed by another --flag)
+  // parses to boolean `true` (cli/common.mjs parseArgs). For string-valued fields
+  // that boolean would slip past the string-only empty guards below and reach the
+  // SQLite bind, surfacing a raw "TypeError: SQLite3 can only bind ..." stacktrace
+  // — the same accidental shell-strip class the empty-title guard (#8470) catches.
+  // Reject it cleanly for every string-valued update flag.
+  for (const key of ['title', 'narrative', 'lesson', 'lesson-learned', 'concepts']) {
+    if (flags[key] === true) {
+      fail(`[mem] --${key} requires a value (received a bare flag with no value).`);
+      return;
+    }
+  }
+
   const updates = [];
   const params = [];
   if (flags.title !== undefined) {
@@ -1629,7 +1664,9 @@ function cmdUpdate(db, args) {
   }
   if (flags.importance) {
     const imp = parseInt(flags.importance, 10);
-    if (isNaN(imp) || imp < 1 || imp > 3) {
+    // isNumericToken first: bare parseInt would coerce "2abc"→2 and UPDATE the row to a
+    // wrong importance. Float literals still truncate (#8277).
+    if (!isNumericToken(flags.importance) || isNaN(imp) || imp < 1 || imp > 3) {
       fail(`[mem] Invalid importance "${flags.importance}". Must be 1, 2, or 3.`);
       return;
     }
@@ -1731,8 +1768,16 @@ function cmdExport(db, args) {
     return;
   }
 
+  // Full round-trippable column set so `restore` rebuilds observations faithfully —
+  // content + value-signals (access/cited/uncited/injection/decay) + branch + timing.
+  // Additive vs the pre-v2.90 13-col shape; existing `export | jq '.[].title'` consumers
+  // are unaffected. id + memory_session_id are informational (restore remaps id and
+  // buckets under a restore session).
   const rows = db.prepare(`
-    SELECT id, project, type, title, subtitle, narrative, concepts, facts, lesson_learned, importance, files_modified, created_at, created_at_epoch
+    SELECT id, memory_session_id, project, type, title, subtitle, narrative, concepts, facts,
+           files_read, files_modified, lesson_learned, importance, branch,
+           access_count, cited_count, uncited_streak, injection_count, decay_seen_count,
+           last_accessed_at, created_at, created_at_epoch
     FROM observations WHERE ${wheres.join(' AND ')}
     ORDER BY created_at_epoch DESC LIMIT ?
   `).all(...params, limit);
@@ -1759,6 +1804,83 @@ function cmdExport(db, args) {
   }
 }
 
+// ─── Restore ───────────────────────────────────────────────────────────────
+// Inverse of `export` — the backup/restore half README:690 promises. Reuses
+// lib/save-observation.mjs so FK / FTS / TF-IDF vector / minhash / files-junction
+// stay consistent with cmdSave, then a targeted UPDATE re-applies the value-signals
+// (access/cited/uncited/injection/decay), branch, and concepts/facts/files_read that
+// saveObservation derives or zeros — so a restored backup keeps its citation-decay
+// history and original timing (created_at via the `now` param). Source ids are
+// discarded (local AUTOINCREMENT; export omits related_ids); session provenance
+// collapses to saveObservation's manual-<project> bucket (documented MVP tradeoff).
+function cmdRestore(db, argv) {
+  const { positional, flags } = parseArgs(argv);
+  const file = positional[0];
+  if (!file) { fail('[mem] Usage: claude-mem-lite restore <file> [--project P] [--dry-run]'); return; }
+  let raw;
+  try { raw = readFileSync(file, 'utf8'); }
+  catch (e) { fail(`[mem] Cannot read "${file}": ${e.message}`); return; }
+  const trimmed = raw.trim();
+  if (!trimmed) { out('[mem] Empty file — nothing to restore.'); return; }
+  let rows;
+  try {
+    rows = trimmed[0] === '['
+      ? JSON.parse(trimmed)
+      : trimmed.split('\n').filter(l => l.trim()).map(l => JSON.parse(l));
+  } catch (e) { fail(`[mem] "${file}" is not valid export JSON/JSONL: ${e.message}`); return; }
+  if (!Array.isArray(rows) || rows.length === 0) { out('[mem] No observations in file.'); return; }
+
+  const projOverride = flags.project ? resolveProject(db, flags.project) : null;
+  const dryRun = flags['dry-run'] === true || flags['dry-run'] === 'true';
+  const num = (v) => Number.isFinite(Number(v)) ? Math.trunc(Number(v)) : 0;
+
+  const dupCheck = db.prepare('SELECT id FROM observations WHERE project = ? AND title = ? AND created_at_epoch = ? LIMIT 1');
+  const signalUpdate = db.prepare(`UPDATE observations SET
+      subtitle = ?, concepts = ?, facts = ?, files_read = ?, branch = COALESCE(?, branch),
+      access_count = ?, cited_count = ?, uncited_streak = ?, injection_count = ?,
+      decay_seen_count = ?, last_accessed_at = ?
+    WHERE id = ?`);
+
+  let restored = 0, skipped = 0, malformed = 0;
+  for (const r of rows) {
+    if (!r || typeof r !== 'object' || !r.type || !r.title) { malformed++; continue; }
+    const project = projOverride || r.project || inferProject();
+    const createdEpoch = Number.isFinite(Number(r.created_at_epoch)) ? Number(r.created_at_epoch) : Date.now();
+    // Durable exact-dup guard — saveObservation's 5-min Jaccard window can't catch a
+    // re-restore of an old-timestamped backup, so gate on project+title+created_at.
+    if (dupCheck.get(project, r.title, createdEpoch)) { skipped++; continue; }
+    if (dryRun) { restored++; continue; }
+    try {
+      let files = [];
+      try { const fm = JSON.parse(r.files_modified || '[]'); if (Array.isArray(fm)) files = fm; } catch { /* leave [] */ }
+      const imp = num(r.importance);
+      const res = saveObservation(db, {
+        content: r.narrative || r.title,
+        title: r.title,
+        type: r.type,
+        importance: imp >= 1 && imp <= 3 ? imp : 1,
+        project,
+        files,
+        lesson_learned: r.lesson_learned || null,
+        now: new Date(createdEpoch),
+      });
+      if (res.kind !== 'saved') { skipped++; continue; } // saveObservation Jaccard dedup
+      // Re-apply the fields saveObservation zeros/derives so the backup is faithful.
+      signalUpdate.run(
+        r.subtitle || '', r.concepts || '', r.facts || '', r.files_read || '[]', r.branch ?? null,
+        num(r.access_count), num(r.cited_count), num(r.uncited_streak), num(r.injection_count),
+        num(r.decay_seen_count), r.last_accessed_at ?? null,
+        res.id,
+      );
+      restored++;
+    } catch (e) {
+      malformed++;
+      if (process.env.CLAUDE_MEM_DEBUG) process.stderr.write(`[mem] restore row failed: ${e.message}\n`);
+    }
+  }
+  out(`[mem] Restore${dryRun ? ' (dry-run)' : ''}: ${restored} restored, ${skipped} duplicate(s) skipped, ${malformed} malformed/failed from ${rows.length} row(s).`);
+}
+
 // ─── Compress ────────────────────────────────────────────────────────────────
 
 function cmdCompress(db, args) {
@@ -1876,7 +1998,11 @@ function cmdMaintain(db, args) {
 
   // Execute
   const VALID_OPS = ['cleanup', 'decay', 'boost', 'demote_pinned', 'dedup', 'purge_stale', 'rebuild_vectors', 'vacuum'];
-  const opsStr = flags.ops || 'cleanup,decay,boost';
+  // Distinguish flag-absent (use default op set) from flag-present-but-empty
+  // (`--ops ""`, e.g. an unset shell var). The latter previously coerced via `||`
+  // to the destructive default cleanup,decay,boost and EXECUTED it; route it to the
+  // VALID_OPS check below instead so it's rejected like `--ops " "` / `--ops "decay,"`.
+  const opsStr = flags.ops === undefined ? 'cleanup,decay,boost' : String(flags.ops);
   const ops = opsStr.split(',').map(s => s.trim());
   const invalidOps = ops.filter(op => !VALID_OPS.includes(op));
   if (invalidOps.length > 0) {
@@ -2054,7 +2180,7 @@ function cmdRegistry(_memDb, args) {
       for (const r of results) {
         const badge = r.quality_tier === 'installed' ? '[✓]' : r.quality_tier === 'verified' ? '[★]' : '[○]';
         const categoryLabel = r.category ? ` [${r.category}]` : '';
-        const isManaged = r.local_path && r.local_path.includes('/.claude-mem-lite/managed/');
+        const isManaged = r.local_path && r.local_path.includes(join(DB_DIR, 'managed') + sep);
         const portablePath = isManaged && r.local_path.startsWith(home) ? '~' + r.local_path.slice(home.length) : (r.local_path || '');
         let howToUse;
         if (isManaged) {
@@ -2119,6 +2245,12 @@ function cmdRegistry(_memDb, args) {
     }
 
     if (action === 'import') {
+      // A bare value-less flag parses to boolean `true` (parseArgs); for these string
+      // fields that boolean reaches the SQLite bind in upsertResource and throws a raw
+      // TypeError — same class as the `update` guard above (#8470). Reject up front.
+      for (const key of ['name', 'resource-type', 'invocation-name', 'source', 'repo-url', 'local-path', 'intent-tags', 'domain-tags', 'trigger-patterns', 'capability-summary', 'keywords', 'tech-stack', 'use-cases']) {
+        if (flags[key] === true) { fail(`[mem] --${key} requires a value (received a bare flag with no value).`); return; }
+      }
       const name = flags.name;
       const resourceType = flags['resource-type'];
       if (!name || !resourceType) { fail('[mem] Usage: claude-mem-lite registry import --name N --resource-type skill|agent [--invocation-name I] [--capability-summary S]'); return; }
@@ -2140,6 +2272,11 @@ function cmdRegistry(_memDb, args) {
     }
 
     if (action === 'remove') {
+      // Bare value-less --name / --resource-type → boolean true → SQLite-bind crash
+      // on the DELETE below; reject like the import branch and the `update` guard.
+      for (const key of ['name', 'resource-type']) {
+        if (flags[key] === true) { fail(`[mem] --${key} requires a value (received a bare flag with no value).`); return; }
+      }
       const name = flags.name;
       const resourceType = flags['resource-type'];
       if (!name || !resourceType) { fail('[mem] Usage: claude-mem-lite registry remove --name N --resource-type skill|agent'); return; }
@@ -2414,6 +2551,7 @@ Commands:
     --concepts T        Space-separated concept tags
 
   export                Export observations as JSON/JSONL
+  restore <file>        Restore observations from an export file (JSON/JSONL); --dry-run to preview
     --project P         Filter by project
     --type T            Filter by type
     --format F          json (default) or jsonl
@@ -2641,6 +2779,13 @@ async function cmdImportJsonl(db, argv) {
   out(`[mem] Total: ${totalPrompts} prompts, ${totalObs} observations, ${totalOrphans} orphan tool_use, ${totalSkip} skipped from ${files.length} file(s)${errorTail}.`);
   if (totalPrompts > 0 || totalObs > 0) {
     out(`[mem] Try: claude-mem-lite recent 5 --project ${project}`);
+  } else if (totalSkip > 0 && errorCount === 0) {
+    // Nothing imported but every line was skipped — almost always the wrong file
+    // format (import-jsonl ingests Claude Code transcript JSONL, not `export` output,
+    // which is observation-shaped). Pre-fix this exited 0 with no signal, so pointing
+    // it at the wrong file looked like success. Make the no-op explicit (stdout, like
+    // the summary lines above).
+    out(`[mem] Warning: 0 imported, ${totalSkip} line(s) skipped — none matched the expected Claude Code transcript JSONL shape (user/assistant/tool_result). 'export' output is NOT re-importable via import-jsonl.`);
   }
 }
 
@@ -2865,6 +3010,7 @@ export async function run(argv) {
       case 'delete':    cmdDelete(db, cmdArgs); break;
       case 'update':    cmdUpdate(db, cmdArgs); break;
       case 'export':    cmdExport(db, cmdArgs); break;
+      case 'restore':   cmdRestore(db, cmdArgs); break;
       case 'compress':  cmdCompress(db, cmdArgs); break;
       case 'maintain':  cmdMaintain(db, cmdArgs); break;
       case 'optimize':  await cmdOptimize(db, cmdArgs); break;

package/nlp.mjs

@@ -218,6 +218,12 @@ export const FTS_STOP_WORDS = new Set([...BASE_STOP_WORDS]);
 export function sanitizeFtsQuery(query) {
   if (!query) return null;
   const cleaned = query
+    // Strip ASCII control chars / NUL FIRST. A NUL survives tokenization (it's not
+    // \s), gets phrase-quoted by expandToken, and then terminates SQLite's C string
+    // mid-phrase → FTS5 "unterminated string" throw, breaking the documented
+    // "never throws on MATCH" invariant. The metachar class below doesn't cover them.
+    // eslint-disable-next-line no-control-regex -- intentional: stripping control chars IS the fix
+    .replace(/[\x00-\x1f\x7f]/g, ' ')
     .replace(/[{}()[\]^~*:"\\]/g, ' ')
     .replace(/(^|\s)-/g, '$1')
     .trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.89.0",
+  "version": "2.90.1",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/registry-importer.mjs

@@ -8,9 +8,12 @@ import { debugLog, isPathConfined } from './utils.mjs';
 import { createHash } from 'crypto';
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
-import { homedir } from 'os';
+import { DB_DIR } from './schema.mjs';
 
-const MANAGED_DIR = join(homedir(), '.claude-mem-lite', 'managed');
+// DATA artifact — managed resources live under the env-aware data dir (DB_DIR),
+// NOT a hardcoded homedir, so GitHub imports land where install.mjs + registry-scanner
+// read them under CLAUDE_MEM_DIR relocation (D#29). Equals homedir when the env is unset.
+const MANAGED_DIR = join(DB_DIR, 'managed');
 
 // ─── Tree Discovery ─────────────────────────────────────────────────────────
 

package/schema.mjs

@@ -8,9 +8,17 @@ import { join } from 'path';
 import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, chmodSync } from 'fs';
 import { OBS_FTS_COLUMNS } from './utils.mjs';
 
+// DATA location — DB, managed resources, registry DB, runtime/. Honors
+// CLAUDE_MEM_DIR so users can relocate state to a larger/faster volume.
 export const DB_DIR = process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite');
 export const DB_PATH = join(DB_DIR, 'claude-mem-lite.db');
 export const REGISTRY_DB_PATH = join(DB_DIR, 'resource-registry.db');
+// CODE / install location — server.mjs, hook.mjs, cli.mjs, package.json live
+// here. ALWAYS homedir-rooted: Claude Code's settings.json + MCP registration
+// bake ABSOLUTE paths to server.mjs/hooks, so the code must NOT follow the
+// CLAUDE_MEM_DIR relocation env var (mirrors install.mjs INSTALL_DIR). Equals
+// DB_DIR when CLAUDE_MEM_DIR is unset — the common, non-relocated case.
+export const CODE_DIR = join(homedir(), '.claude-mem-lite');
 
 // Increment when schema changes (tables, columns, indexes, FTS, migrations)
 //
@@ -61,13 +69,15 @@ export const REGISTRY_DB_PATH = join(DB_DIR, 'resource-registry.db');
 // SQLITE_CORRUPT_VTAB blast radius v27 fixed for the other FTS tables. Version
 // bumped to force one migration pass; the conditional drop below replaces the
 // legacy trigger on existing DBs. LATEST_MIGRATION_COLUMN unchanged (no new column).
-export const CURRENT_SCHEMA_VERSION = 36;
+// v37 (D#26): adds user_prompts.cc_session_id (additive, nullable). LATEST_MIGRATION_COLUMN
+// MOVES to it so the half-migrated-DB self-heal fast-path covers the new column.
+export const CURRENT_SCHEMA_VERSION = 37;
 
 // Sentinel column for the LATEST migration set. The fast-path uses this to
 // self-heal half-migrated DBs — schema_version bumped but column ALTERs rolled
 // back (observed once in dev during v2.74.0). Update both the column AND
 // (if needed) the table when adding a new migration batch.
-const LATEST_MIGRATION_COLUMN = { table: 'observations', column: 'decay_seen_count' };
+const LATEST_MIGRATION_COLUMN = { table: 'user_prompts', column: 'cc_session_id' };
 
 function hasLatestMigrationColumn(db) {
   try {
@@ -205,6 +215,14 @@ const MIGRATIONS = [
   // share the unrelated injection_count column. Same-source numerator
   // (cited_count) + same-source denominator = meaningful ratio.
   'ALTER TABLE observations ADD COLUMN decay_seen_count INTEGER NOT NULL DEFAULT 0',
+  // v37 (D#26 — parallel-session handoff content scoping): the Claude-Code session
+  // UUID per user prompt. handleUserPrompt writes hookData.session_id here so
+  // buildAndSaveHandoff can scope working_on to ONE CC session — concurrent (and
+  // within-12h-TTL sequential) same-project sessions previously merged each other's
+  // prompts because getSessionId() is project-scoped (no CC-UUID component). Nullable:
+  // legacy rows + non-CC/no-stdin invocations read back NULL and the handoff falls
+  // back to its legacy unfiltered query.
+  'ALTER TABLE user_prompts ADD COLUMN cc_session_id TEXT DEFAULT NULL',
 ];
 
 /**
@@ -355,6 +373,7 @@ export function initSchema(db) {
   db.exec(`CREATE INDEX IF NOT EXISTS idx_sess_sum_epoch ON session_summaries(created_at_epoch DESC, project)`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_obs_project_epoch_minhash ON observations(project, created_at_epoch DESC) WHERE minhash_sig IS NOT NULL`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_user_prompts_session ON user_prompts(content_session_id)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_user_prompts_cc ON user_prompts(cc_session_id) WHERE cc_session_id IS NOT NULL`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_obs_superseded ON observations(superseded_at) WHERE superseded_at IS NOT NULL`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_obs_branch ON observations(branch) WHERE branch IS NOT NULL`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_project ON sdk_sessions(project)`);

package/scripts/pre-skill-bridge.js

@@ -11,9 +11,15 @@ import { recordHookError } from '../lib/hook-telemetry.mjs';
 // CLAUDE_MEM_DIR mirrors pre-tool-recall.js — one env var sandboxes everything.
 const DATA_DIR = process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite');
 const RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || join(DATA_DIR, 'runtime');
-const REGISTRY_DB_PATH = join(homedir(), '.claude-mem-lite', 'resource-registry.db');
-const MANAGED_BASE = join(homedir(), '.claude-mem-lite');
-const MANAGED_MARKER = '/.claude-mem-lite/managed/';
+// D#29: all data artifacts follow DATA_DIR (CLAUDE_MEM_DIR-aware), not a hardcoded
+// homedir — previously REGISTRY_DB_PATH/MANAGED_BASE/MARKER pinned homedir while line 12
+// honored the env, so relocated installs opened the wrong DB and the marker never matched
+// the relocated local_path. MANAGED_MARKER is only a coarse LIKE prefilter; the exact
+// MANAGED_BASE prefix check below is the real confinement gate (so LIKE-wildcard chars in
+// a relocated path can at worst over-admit to that gate, never bypass it).
+const REGISTRY_DB_PATH = join(DATA_DIR, 'resource-registry.db');
+const MANAGED_BASE = DATA_DIR;
+const MANAGED_MARKER = join(DATA_DIR, 'managed') + sep;
 
 try {
   // Skip if recursive hook

package/scripts/user-prompt-search.js

@@ -8,7 +8,7 @@ import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject,
 import { citeFactorClause } from '../scoring-sql.mjs';
 import { cjkPrecisionOk } from '../nlp.mjs';
 import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
-import { join } from 'path';
+import { join, sep } from 'path';
 import Database from 'better-sqlite3';
 import { shouldSkip, computeEffectiveLen, detectIntent, shouldSkipByDedup, extractFiles, extractErrorSignature, DEDUP_STALE_MS, matchRegistrySkillName, detectMemOverride } from './prompt-search-utils.mjs';
 
@@ -439,10 +439,18 @@ function loadManagedSkillNames() {
     const rdb = new Database(REGISTRY_DB_PATH, { readonly: true });
     rdb.pragma('busy_timeout = 500');
     try {
+      // D#29: derive the managed marker from the env-aware data dir, not a hardcoded
+      // homedir literal — under CLAUDE_MEM_DIR relocation the stored local_path lives at
+      // DB_DIR/managed, so the old literal matched nothing and dropped every managed skill
+      // from injection. Coarse LIKE prefilter; resource names are re-validated downstream.
+      // D#29: derive the managed marker from the env-aware data dir, not a hardcoded
+      // homedir literal — under CLAUDE_MEM_DIR relocation the stored local_path lives at
+      // DB_DIR/managed, so the old literal matched nothing and dropped every managed skill
+      // from injection. Coarse LIKE prefilter; resource names are re-validated downstream.
       const rows = rdb.prepare(`
         SELECT name FROM resources
-        WHERE status = 'active' AND local_path LIKE '%/.claude-mem-lite/managed/%'
-      `).all();
+        WHERE status = 'active' AND local_path LIKE ?
+      `).all(`%${join(DB_DIR, 'managed') + sep}%`);
       return new Set(rows.map(r => r.name.toLowerCase()));
     } finally { rdb.close(); }
   } catch { return new Set(); }

package/server.mjs

@@ -8,7 +8,7 @@ import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, scrubSecrets, cjkBigrams, fmtDate, debugLog, debugCatch, SESS_BM25, DEFAULT_DECAY_HALF_LIFE_MS, isPathConfined, notLowSignalTitleClause } from './utils.mjs';
 import { extractCjkLikePatterns, cjkPrecisionOk } from './nlp.mjs';
 import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
-import { ensureDb, DB_PATH, REGISTRY_DB_PATH } from './schema.mjs';
+import { ensureDb, DB_PATH, DB_DIR, REGISTRY_DB_PATH } from './schema.mjs';
 import { reRankWithContext, markSuperseded, autoBoostIfNeeded, runIdleCleanup, buildServerInstructions } from './server-internals.mjs';
 import { searchObservationsHybrid, findFtsAnchor } from './search-engine.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
@@ -30,7 +30,7 @@ function descriptionOf(name) {
   return d;
 }
 import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
-import { basename, join } from 'path';
+import { basename, join, sep } from 'path';
 import { homedir } from 'os';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
@@ -475,7 +475,12 @@ server.registerTool(
           `SELECT id, compressed_into, superseded_at, memory_session_id, project, importance, last_accessed_at, created_at_epoch, type FROM observations WHERE id IN (${placeholders})`
         ).all(...obsIds);
         const rowMap = new Map(fullRows.map(r => [r.id, r]));
-        const tierCtx = { now: Date.now(), currentProject: currentProject, currentSessionId: '' };
+        // Use the explicitly-requested project for tier classification, not the
+        // CWD-inferred one — else computeTier's "obs.project === currentProject"
+        // (working/active rules) fails for cross-project searches and the tier=
+        // filter silently drops valid rows. mem_stats/mem_browse already resolve
+        // args.project first; this restores parity.
+        const tierCtx = { now: Date.now(), currentProject: args.project || currentProject, currentSessionId: '' };
         const filtered = results.filter(r => {
           if (r.source !== 'obs') return true;
           const full = rowMap.get(r.id);
@@ -1108,6 +1113,7 @@ server.registerTool(
     const lowVal = db.prepare(`
       SELECT COUNT(*) as c FROM observations
       WHERE COALESCE(importance,1) = 1 AND COALESCE(access_count,0) = 0
+        AND COALESCE(compressed_into, 0) = 0
         AND created_at_epoch < ? ${projectFilter}
     `).get(thirtyDaysAgo, ...baseParams);
 
@@ -1500,7 +1506,7 @@ server.registerTool(
       const lines = results.map(r => {
         const qualityBadge = r.quality_tier === 'installed' ? '[✓]' : r.quality_tier === 'verified' ? '[★]' : '[○]';
         const categoryLabel = r.category ? ` [${r.category}]` : '';
-        const isManaged = r.local_path && r.local_path.includes('/.claude-mem-lite/managed/');
+        const isManaged = r.local_path && r.local_path.includes(join(DB_DIR, 'managed') + sep);
         const portablePath = isManaged ? toPortable(r.local_path) : '';
         let howToUse;
         if (isManaged) {
@@ -1645,7 +1651,9 @@ server.registerTool(
       if (!row.local_path) {
         return { content: [{ type: 'text', text: `No local_path for ${args.name}` }], isError: true };
       }
-      const enrichBase = join(homedir(), '.claude-mem-lite');
+      // Confine to the env-aware data dir (managed/ relocates with CLAUDE_MEM_DIR, D#29);
+      // === homedir when the env is unset, so non-relocated confinement is unchanged.
+      const enrichBase = DB_DIR;
       if (!isPathConfined(row.local_path, enrichBase)) {
         return { content: [{ type: 'text', text: `Access denied: path outside managed directory` }], isError: true };
       }
@@ -1713,8 +1721,10 @@ server.registerTool(
       }
     }
 
-    // 4. Path confinement check — prevent reading arbitrary files via crafted local_path
-    const managedBase = join(homedir(), '.claude-mem-lite');
+    // 4. Path confinement check — prevent reading arbitrary files via crafted local_path.
+    // Base is the env-aware data dir (D#29): managed/ relocates with CLAUDE_MEM_DIR and
+    // equals homedir when unset, so this does not weaken the non-relocated confinement.
+    const managedBase = DB_DIR;
     if (skillPath && !isPathConfined(skillPath, managedBase)) {
       return { content: [{ type: 'text', text: `Access denied: path "${skillPath}" is outside managed directory` }], isError: true };
     }