claude-mem-lite 6.30.6 → 6.30.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,7 +9,7 @@
9
9
  "plugins": [
10
10
  {
11
11
  "name": "claude-mem-lite",
12
- "version": "6.30.6",
12
+ "version": "6.30.8",
13
13
  "source": "./",
14
14
  "homepage": "https://github.com/sdsrss/claude-mem-lite",
15
15
  "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword 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)."
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-mem-lite",
3
- "version": "6.30.6",
3
+ "version": "6.30.8",
4
4
  "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword 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).",
5
5
  "author": {
6
6
  "name": "sdsrss"
package/README.md CHANGED
@@ -197,7 +197,7 @@ node install.mjs install
197
197
  2. **Register MCP server** -- `mem-lite` server with 19 tool definitions (10 core + 9 hidden-but-callable; `mem_search_feedback` is registered only when search telemetry is enabled). The pre-v2.78 generic server name `mem` is renamed to `mem-lite` for namespace hygiene; the tool names themselves (`mem_search`, `mem_recall`, ...) are unchanged.
198
198
  3. **Configure hooks** -- all seven lifecycle events: `SessionStart`, `PreCompact`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `UserPromptSubmit`
199
199
  4. **Create data directory** -- `~/.claude-mem-lite/` (hidden) for database, runtime, and managed resource files
200
- 5. **Auto-migrate** -- `~/.claude-mem/claude-mem.db` (original claude-mem) is moved into `~/.claude-mem-lite/` as a `.legacy-backup-<time>` file and a fresh database is created. A database left in `~/claude-mem-lite/` (the unhidden directory of versions before the first release, 2.0.0) is moved into the data directory at the first open, when the data directory holds no database, log, snapshot or kept copy of a claude-mem-lite store yet; nothing else in either directory is moved or removed (the plugin install differs: see Migration)
200
+ 5. **Auto-migrate** -- `~/.claude-mem/claude-mem.db` (original claude-mem) is moved into `~/.claude-mem-lite/` as a `.legacy-backup-<time>` file (the plugin, and install across filesystems, copy it instead) and a fresh database is created. A database left in `~/claude-mem-lite/` (the unhidden directory of versions before the first release, 2.0.0) is moved into the data directory at the first open, when the data directory holds no database, log, snapshot or kept copy of a claude-mem-lite store yet; nothing else in either directory is moved or removed
201
201
  6. **Initialize database** -- SQLite with WAL mode, FTS5 indexes created on first server start
202
202
 
203
203
  Restart Claude Code after installation to activate.
@@ -207,13 +207,14 @@ Restart Claude Code after installation to activate.
207
207
  All installation methods auto-detect and migrate from previous versions:
208
208
 
209
209
  **From claude-mem (original `~/.claude-mem/`):**
210
- - `claude-mem.db` and its `-wal`/`-shm` are moved into `~/.claude-mem-lite/` under `.legacy-backup-<time>` names (`claude-mem-lite.db.legacy-backup-<time>`, `claude-mem-lite.db-wal.legacy-backup-<time>`), when `~/.claude-mem-lite/claude-mem-lite.db` does not exist yet
210
+ - `claude-mem.db` and its `-wal`/`-shm` are moved into `~/.claude-mem-lite/` as `claude-mem-lite.db.legacy-backup-<time>`, `claude-mem-lite.db.legacy-backup-<time>-wal` and `-shm`, when `~/.claude-mem-lite/claude-mem-lite.db` does not exist yet. With the data directory on another filesystem they are copied instead, `~/.claude-mem/` stays as it is, and a backup already there is not copied again
211
+ - The plugin install copies `claude-mem.db` and its `-wal` into the data directory under those names and leaves `~/.claude-mem/` as it is; it does so while the data directory holds neither a database nor such a backup
212
+ - A backup that `install` made before v6.30.8 names its log `claude-mem-lite.db-wal.legacy-backup-<time>`, and SQLite does not read that log with the backup; rename it to `claude-mem-lite.db.legacy-backup-<time>-wal` before opening the backup
211
213
  - A fresh database is created: the original claude-mem schema has no upgrade path
212
214
 
213
215
  **From the unhidden directory of versions before the first release, 2.0.0 (`~/claude-mem-lite/`):**
214
216
  - Its database (`claude-mem-lite.db` or `claude-mem.db`, with its `-wal` and `-shm`) is moved into the data directory at the first open, when the data directory holds no database, log, snapshot or kept copy of a claude-mem-lite store yet. Nothing else is moved, and nothing in either directory is removed
215
217
  - The move is a rename: with `CLAUDE_MEM_DIR` on another filesystem it fails, and so does every open, until the database is moved there by hand together with its `-wal` and `-shm`
216
- - The plugin install differs: at session start, when `~/.claude-mem-lite/` does not exist, `scripts/setup.sh` moves the whole `~/claude-mem-lite/` directory there, whatever it holds; with `CLAUDE_MEM_DIR` set, nothing then reads the database it moved
217
218
 
218
219
  **In-place rename:**
219
220
  - Existing `claude-mem.db` in `~/.claude-mem-lite/` is automatically renamed to `claude-mem-lite.db`
@@ -653,7 +654,7 @@ surface — reach them through the CLI column in the second table.
653
654
  | `mem_maintain` | `claude-mem-lite maintain scan --ops dedup,decay` | dedup / decay / cleanup / vacuum (`scan` previews, `execute` applies). |
654
655
  | `mem_optimize` | `claude-mem-lite optimize` | LLM-powered re-enrich / normalize / cluster-merge (preview default; `--run` to apply). |
655
656
  | `mem_export` | `claude-mem-lite export` | JSON / JSONL dump, filters by project, type, date. |
656
- | `mem_fts_check` | `claude-mem-lite fts-check <check\|rebuild>` | FTS5 integrity + rebuild. |
657
+ | `mem_fts_check` | `claude-mem-lite fts-check <check\|rebuild>` | FTS5 integrity check; rebuild of the FTS5 indexes, then every other index (REINDEX). |
657
658
  | `mem_browse` | `claude-mem-lite browse` | Tier-grouped dashboard (working / active / archive). |
658
659
 
659
660
  **Headless runs (`claude -p`).** With no permission prompt to answer, Claude Code 2.1.292
@@ -1070,7 +1071,7 @@ claude-mem-lite/
1070
1071
  skill.md # MCP skill definition (npx/git clone mode)
1071
1072
  package.json # Dependencies and metadata
1072
1073
  scripts/
1073
- setup.sh # Setup hook: npm install + migration (hidden dir + old dir)
1074
+ setup.sh # Setup hook: npm install + migration (original claude-mem DB, old file name)
1074
1075
  post-tool-use.sh # Bash pre-filter: skips noise in ~5ms, tracks Read paths
1075
1076
  user-prompt-search.js # UserPromptSubmit hook: auto-search memory on user prompts
1076
1077
  pre-tool-recall.js # PreToolUse hook: file lesson recall before Edit/Write
package/README.zh-CN.md CHANGED
@@ -159,7 +159,7 @@ node install.mjs install
159
159
  > **想把托管块改写进 `CLAUDE.md`**(例如与团队共享)?运行 `claude-mem-lite adopt`:它向 `<cwd>/CLAUDE.md` 写入 slug 限定的托管块和详情文件,块以外的内容逐字保留,并删除自动写入的那份本地副本(`CLAUDE.local.md` 或 rules 文件)。`CLAUDE.md` 一存在,Claude Code 就不再读 `AGENTS.md`,所以 adopt 在 `AGENTS.md`(或 `.claude/AGENTS.md`)旁边新建 `CLAUDE.md` 时,会在文件开头导入它(`@AGENTS.md`,前面一行是 Claude Code 不加载的标记注释),`AGENTS.md` 因此继续加载;上层目录里的、或 git 跟踪在子目录里的 `AGENTS.md` 不能这样导入,adopt 会在输出里列出它们,并给出保留它们的设置(Project instructions 设为 `claude-md-and-agents-md`)。已经有你自己的 `CLAUDE.md` 时不导入,因为那里本来就不读 `AGENTS.md`。`unadopt` 会删除只剩这些行和托管块的 `CLAUDE.md`。带托管块的项目在**每次 SessionStart** 都会同步,出货模板变了会刷新,且不会再叠加本地副本或注入,从子目录启动的会话也一样。只有托管块的 `CLAUDE.md`(旧版本自动 adopt 写的)会在下一次从它所在目录启动的会话里补上同样的 `AGENTS.md` 导入,并给一次性提示。从子目录启动的会话看来,这个导入指向工作目录之外,Claude Code 会请你批准一次。插件创建过、又被你删掉(或被 `claude-mem-lite unadopt` 删掉)的本地托管块(`CLAUDE.local.md` 或 rules 文件)不会被写回,改为注入,直到运行 `claude-mem-lite adopt --enable`(在 `CLAUDE.local.md` 会让 `AGENTS.md` 失效的仓库里,还要设 `CLAUDE_MEM_RULES_STEERING=1` 才会再写文件)。关闭方式:项目级 `claude-mem-lite adopt --disable`(同时删除本地托管块;`CLAUDE.md` 托管块保留到 `unadopt`;重新启用用 `--enable`);全局 `export MEM_NO_AUTO_ADOPT=1`(已写入的托管块保留并继续加载,直到 `unadopt`);只冻结模板刷新用 `CLAUDE_MEM_NO_TEMPLATE_REFRESH=1`。`claude-mem-lite unadopt` 会移除 `CLAUDE.md` 托管块、详情文件,以及本地托管块(`CLAUDE.local.md` 或 `.claude/rules/claude-mem-lite.md`)和它的 exclude 条目。
160
160
  3. **配置钩子** -- 全部七个生命周期事件:`SessionStart`、`PreCompact`、`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`Stop`、`UserPromptSubmit`
161
161
  4. **创建数据目录** -- `~/.claude-mem-lite/`(隐藏目录),存放数据库与运行时文件
162
- 5. **自动迁移** -- `~/.claude-mem/claude-mem.db`(原版 claude-mem)以 `.legacy-backup-<时间>` 文件的形式移入 `~/.claude-mem-lite/`,并新建一个数据库。`~/claude-mem-lite/`(首个发布版 2.0.0 之前的非隐藏目录)里留下的数据库在第一次打开时移入数据目录,前提是数据目录里还没有 claude-mem-lite 的数据库、日志、快照或保留副本;两个目录里的其他文件都不移动、不删除(插件安装不同,见"迁移")
162
+ 5. **自动迁移** -- `~/.claude-mem/claude-mem.db`(原版 claude-mem)以 `.legacy-backup-<时间>` 文件的形式移入 `~/.claude-mem-lite/`(插件、以及跨文件系统时的 install 改为复制),并新建一个数据库。`~/claude-mem-lite/`(首个发布版 2.0.0 之前的非隐藏目录)里留下的数据库在第一次打开时移入数据目录,前提是数据目录里还没有 claude-mem-lite 的数据库、日志、快照或保留副本;两个目录里的其他文件都不移动、不删除
163
163
  6. **初始化数据库** -- SQLite WAL 模式,FTS5 索引在服务器首次启动时创建
164
164
 
165
165
  安装后重启 Claude Code 以激活。
@@ -169,14 +169,14 @@ node install.mjs install
169
169
  所有安装方式自动检测并从旧版本迁移:
170
170
 
171
171
  **从 claude-mem 原版(`~/.claude-mem/`):**
172
- - 复制 `claude-mem.db` → `~/.claude-mem-lite/claude-mem-lite.db`(重命名)
173
- - 复制 `runtime/` 目录
174
- - **原 `~/.claude-mem/` 保持不变**(不删除、不覆盖)
172
+ - `claude-mem.db` 连同 `-wal`/`-shm` 以 `claude-mem-lite.db.legacy-backup-<时间>`、`claude-mem-lite.db.legacy-backup-<时间>-wal` 和 `-shm` 的名字移入 `~/.claude-mem-lite/`,前提是 `~/.claude-mem-lite/claude-mem-lite.db` 还不存在。数据目录在另一个文件系统上时改为复制,`~/.claude-mem/` 原样不动,数据目录里已有备份就不再复制
173
+ - 插件安装把 `claude-mem.db` 连同 `-wal` 以上面的名字复制进数据目录,`~/.claude-mem/` 原样不动;数据目录里既没有数据库、也没有这样的备份时才复制
174
+ - v6.30.8 之前 `install` 做的备份,日志名是 `claude-mem-lite.db-wal.legacy-backup-<时间>`,SQLite 打开备份时不会读这个日志;打开备份前先把它改名为 `claude-mem-lite.db.legacy-backup-<时间>-wal`
175
+ - 新建一个数据库:原版 claude-mem 的 schema 没有升级路径
175
176
 
176
177
  **从首个发布版(2.0.0)之前的非隐藏目录(`~/claude-mem-lite/`):**
177
178
  - 它的数据库(`claude-mem-lite.db` 或 `claude-mem.db`,连同 `-wal` 和 `-shm`)在第一次打开时移入数据目录,前提是数据目录里还没有 claude-mem-lite 的数据库、日志、快照或保留副本。其他文件都不移动,两个目录里都不删除任何东西
178
179
  - 移动用的是改名:`CLAUDE_MEM_DIR` 在另一个文件系统上时会失败,之后每次打开都失败,直到手动把数据库连同 `-wal` 和 `-shm` 移过去
179
- - 插件安装不同:会话开始时,如果 `~/.claude-mem-lite/` 不存在,`scripts/setup.sh` 会把整个 `~/claude-mem-lite/` 目录移过去,不管里面有什么;设了 `CLAUDE_MEM_DIR` 时,移过去的数据库之后没有人读
180
180
 
181
181
  **就地重命名:**
182
182
  - 已有的 `~/.claude-mem-lite/claude-mem.db` 会自动重命名为 `claude-mem-lite.db`
@@ -513,7 +513,7 @@ README 和 `docs/ARCHITECTURE.md` 都钉在它上面。)
513
513
  | `mem_maintain` | `claude-mem-lite maintain scan --ops dedup,decay` | 去重 / decay / 清理 / vacuum(`scan` 预览,`execute` 执行)。 |
514
514
  | `mem_optimize` | `claude-mem-lite optimize` | LLM 深度优化:re-enrich / normalize / cluster-merge(默认 preview;`--run` 执行)。 |
515
515
  | `mem_export` | `claude-mem-lite export` | JSON / JSONL 导出,支持项目/类型/日期过滤。 |
516
- | `mem_fts_check` | `claude-mem-lite fts-check <check\|rebuild>` | FTS5 完整性检查与重建。 |
516
+ | `mem_fts_check` | `claude-mem-lite fts-check <check\|rebuild>` | FTS5 完整性检查;重建 FTS5 索引,再重建其余所有索引(REINDEX)。 |
517
517
  | `mem_browse` | `claude-mem-lite browse` | 分层仪表盘(working / active / archive)。 |
518
518
 
519
519
  **无人值守运行(`claude -p`)。** 没有权限确认可答时,Claude Code 2.1.292 拒绝了所有 `mem_*` 调用,直到服务的工具被放行;模型也没有自己改用 CLI。在 88 个无人值守会话里(2026-10-06),13 次调用全部被拒,什么都没存下。在 2.1.284 上(2026-09-29),同样的参数会放行这些调用,所以这取决于 Claude Code 版本。在这次运行读取的 `settings.json` 里放行一次即可:
@@ -841,7 +841,7 @@ claude-mem-lite/
841
841
  skill.md # MCP 技能定义(npx/git clone 模式)
842
842
  package.json # 依赖和元数据
843
843
  scripts/
844
- setup.sh # Setup 钩子:npm install + 迁移(隐藏目录 + 旧目录)
844
+ setup.sh # Setup 钩子:npm install + 迁移(原版 claude-mem 数据库、旧文件名)
845
845
  post-tool-use.sh # Bash 预过滤器:~5ms 跳过噪声,追踪 Read 路径
846
846
  user-prompt-search.js # UserPromptSubmit 钩子:用户提问时自动搜索记忆
847
847
  pre-tool-recall.js # PreToolUse 钩子:Edit/Write 前文件教训回忆
package/cli/fts-check.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  // cli/fts-check.mjs — `claude-mem-lite fts-check <check|rebuild>`.
2
2
  // Extracted from mem-cli.mjs (v2.41, god-module split).
3
3
 
4
- import { checkFTSIntegrity, rebuildFTS } from '../schema.mjs';
4
+ import { checkFTSIntegrity, rebuildIndexes } from '../schema.mjs';
5
5
  import { parseArgs, out, fail } from './common.mjs';
6
6
  import { CLI_INVOKE } from '../cli-path.mjs';
7
7
 
@@ -48,7 +48,9 @@ export function cmdFtsCheck(db, args) {
48
48
  }
49
49
 
50
50
  if (action === 'rebuild') {
51
- const result = rebuildFTS(db);
51
+ // The FTS5 indexes, then every other index (REINDEX): the last step of doctor's restore
52
+ // command, which the restore check ran on its copy (D#558).
53
+ const result = rebuildIndexes(db);
52
54
  if (result.errors.length > 0) {
53
55
  // Partial success is a failure of the requested operation: the caller asked
54
56
  // for a rebuild and at least one index still is not rebuilt.
package/hook.mjs CHANGED
@@ -2780,14 +2780,14 @@ async function emitDbUnusableNotice() {
2780
2780
  const mod = await import('./lib/db-unusable.mjs');
2781
2781
  // TWO DIFFERENT STRINGS, unlike the skew twin, and the asymmetry is the point: the
2782
2782
  // human channel carries the repair command, the model channel carries only the fact.
2783
- // See formatDbUnusableModelNotice — this family's remedy overwrites the database.
2783
+ // See formatDbUnusableModelNotice — this family's remedy moves the database file aside.
2784
2784
  queueHookSystemMessage(
2785
2785
  mod.formatDbUnusableNotice({
2786
2786
  dbPath: DB_PATH,
2787
2787
  remedy: mod.dbUnusableRemedy(DB_PATH, lastDbUnusableError()),
2788
2788
  }),
2789
2789
  );
2790
- queueHookContext('SessionStart', mod.formatDbUnusableModelNotice());
2790
+ queueHookContext('SessionStart', mod.formatDbUnusableModelNotice(DB_PATH));
2791
2791
  } catch (e) {
2792
2792
  // A hook must never crash the host session, and a notice that cannot render is better
2793
2793
  // handled by staying quiet than by taking SessionStart down with it.
package/install.mjs CHANGED
@@ -5,6 +5,7 @@ import { OUR_MCP_SERVER_RE, isOurMcpRegistration } from './lib/mcp-ownership.mjs
5
5
  import { execSync, execFileSync } from 'child_process';
6
6
  import {
7
7
  readFileSync,
8
+ copyFileSync,
8
9
  writeFileSync,
9
10
  existsSync,
10
11
  rmSync,
@@ -176,10 +177,18 @@ export function copyHookScripts(srcDir, destDir) {
176
177
  * first launch. Backing up rather than copying-as-current lets the new
177
178
  * install create a fresh v28 DB while preserving legacy bytes for recovery.
178
179
  *
179
- * Returns: {action: 'noop'|'skip'|'backed-up', backupPath?}
180
+ * Returns: {action: 'noop'|'skip'|'backed-up'|'copied', backupPath?}
180
181
  * - noop: no legacy DB found
181
- * - skip: working `claude-mem-lite.db` already exists in newDir
182
- * - backed-up: legacy files renamed to `<newDir>/claude-mem-lite.db.legacy-backup-<ts>` etc.
182
+ * - skip: working `claude-mem-lite.db` already exists in newDir, or (across filesystems) a backup
183
+ * database is already there (an earlier install's copy, or the plugin's)
184
+ * - backed-up: legacy files renamed to `<newDir>/claude-mem-lite.db.legacy-backup-<ts>` and,
185
+ * beside it, that name with `-wal` and `-shm` added, the names SQLite pairs with it (D#584: the
186
+ * log was named `claude-mem-lite.db-wal.legacy-backup-<ts>`, and the backup opened as found
187
+ * read none of the rows only in it)
188
+ * - copied: newDir is on another filesystem, where a rename fails with EXDEV (D#579): the files
189
+ * are copied to those names and the source is left in place, as the plugin's setup.sh does.
190
+ * Every file is copied under a private name first and then renamed into place, the store's own
191
+ * file last, so a copy killed partway leaves no backup of the store.
183
192
  */
184
193
  export function migrateLegacyClaudeMemData(oldDir, newDir, opts = {}) {
185
194
  const legacyDb = join(oldDir, 'claude-mem.db');
@@ -190,10 +199,25 @@ export function migrateLegacyClaudeMemData(oldDir, newDir, opts = {}) {
190
199
  if (!existsSync(newDir)) mkdirSync(newDir, { recursive: true });
191
200
  const ts = opts.now ?? Date.now();
192
201
  const backupPath = join(newDir, `claude-mem-lite.db.legacy-backup-${ts}`);
193
- renameSync(legacyDb, backupPath);
202
+ try {
203
+ renameSync(legacyDb, backupPath);
204
+ } catch (e) {
205
+ if (e?.code !== 'EXDEV') throw e;
206
+ // A copy killed partway left its private files. Only install names files so (the plugin's
207
+ // session start has its own prefix), and install runs one at a time (install.lock).
208
+ const names = readdirSync(newDir);
209
+ for (const n of names) if (n.startsWith('.legacy-backup-copy-')) rmSync(join(newDir, n), { force: true });
210
+ // The source stays, so a backup of the store here is the copy an earlier install made. Its log
211
+ // alone is not: a copy killed between the renames below leaves that.
212
+ if (names.some((n) => /^claude-mem-lite\.db\.legacy-backup-\d+$/.test(n))) return { action: 'skip' };
213
+ const exts = ['-wal', '-shm', ''].filter((ext) => existsSync(legacyDb + ext));
214
+ const tmp = join(newDir, `.legacy-backup-copy-${process.pid}-${ts}`);
215
+ for (const ext of exts) copyFileSync(legacyDb + ext, tmp + ext);
216
+ for (const ext of exts) renameSync(tmp + ext, backupPath + ext);
217
+ return { action: 'copied', backupPath };
218
+ }
194
219
  for (const ext of ['-wal', '-shm']) {
195
- const src = legacyDb + ext;
196
- if (existsSync(src)) renameSync(src, join(newDir, `claude-mem-lite.db${ext}.legacy-backup-${ts}`));
220
+ if (existsSync(legacyDb + ext)) renameSync(legacyDb + ext, backupPath + ext);
197
221
  }
198
222
  return { action: 'backed-up', backupPath };
199
223
  }
@@ -473,24 +497,34 @@ export async function dbCheckRemedy(dbPath, err) {
473
497
  // only inside the Database check's catch, so the cost of loading it lazily is paid by
474
498
  // the rare failure rather than by every invocation. Same shape as the six dynamic
475
499
  // imports doctor already uses.
476
- const { isDbUnusableError, dbUnusableRemedy } = await import('./lib/db-unusable.mjs');
500
+ const { isDbUnusableError, dbUnusableRemedy, checkSnapshot } = await import('./lib/db-unusable.mjs');
477
501
  if (!isDbUnusableError(err)) return null;
478
- const remedy = dbUnusableRemedy(dbPath, err);
502
+ // doctor checks the snapshots (D#558): each is restored into a private copy and opened by the
503
+ // product's opener in a child process; the command names the newest that passes, and the older
504
+ // ones that pass are listed with their own commands (D#577). One line per check on stderr: a large
505
+ // snapshot takes seconds, and stdout may be the --json face.
506
+ const remedy = dbUnusableRemedy(dbPath, err, {
507
+ check: (path, { nth, of }) => {
508
+ process.stderr.write(` Checking backup snapshot ${nth} of ${of}: ${basename(path)}\n`);
509
+ return checkSnapshot(path);
510
+ },
511
+ });
479
512
  if (remedy.kind === 'unknown') return remedy.note;
480
513
  if (remedy.kind === 'schema') return `SQLite cannot read the database's schema. ${remedy.note}`;
481
- // Both commands start by deleting the -wal and -shm and then replace or move the database file,
482
- // under any session still holding the store (D#534). The SessionStart notice says the same before
483
- // its copy of the command.
514
+ // Both commands move the database file and its -wal aside and delete the -shm, under any session
515
+ // still holding the store (D#534). The SessionStart notice says the same before its copy of the
516
+ // command.
517
+ const kept = `The broken file and its log are kept as ${remedy.keptAs} and ${remedy.keptAs}-wal.`;
484
518
  if (remedy.kind === 'set-aside') {
485
519
  return (
486
- `No non-empty backup snapshot exists beside the database. Once every Claude Code session is closed, ` +
487
- `set the broken file aside so a fresh store is created on the next session: ${remedy.command}`
520
+ `${remedy.found} Once every Claude Code session is closed, set the broken file aside so a fresh ` +
521
+ `store is created on the next session: ${remedy.command} — ${kept}`
488
522
  );
489
523
  }
490
- return (
491
- `Restore the newest of ${remedy.snapshotCount} backup snapshot(s) once every Claude Code session ` +
492
- `is closed: ${remedy.command} — move the broken file aside first if you want to keep it for inspection.`
493
- );
524
+ // The older snapshots to choose from (D#577) follow the command they are the alternatives to; the
525
+ // list with their counts is in `found`, before it.
526
+ const also = (remedy.alternatives ?? []).map((a) => ` To restore ${a.path} instead: ${a.command}`).join('');
527
+ return `${remedy.found} Once every Claude Code session is closed, restore it: ${remedy.command} — ${kept}${also}`;
494
528
  }
495
529
 
496
530
  // ─── Install ────────────────────────────────────────────────────────────────
@@ -1371,8 +1405,9 @@ function backupLegacyClaudeMemData() {
1371
1405
  // so the new install creates a fresh v28 DB.
1372
1406
  try {
1373
1407
  const r = migrateLegacyClaudeMemData(OLD_DATA_DIR, MEM_DATA_DIR);
1374
- if (r.action === 'backed-up') {
1375
- ok(`Legacy ~/.claude-mem/ DB backed up to ${r.backupPath}`);
1408
+ if (r.action === 'backed-up' || r.action === 'copied') {
1409
+ ok(`Legacy ~/.claude-mem/ DB ${r.action === 'copied' ? 'copied' : 'backed up'} to ${r.backupPath}`);
1410
+ if (r.action === 'copied') log('~/.claude-mem/ is on another filesystem and is left as it is.');
1376
1411
  log('New v28 DB will be created on first launch (legacy schema is incompatible).');
1377
1412
  }
1378
1413
  } catch (e) {
@@ -3093,6 +3128,16 @@ async function doctor() {
3093
3128
  }
3094
3129
 
3095
3130
  // Database
3131
+ // A check of a backup snapshot that was interrupted (Ctrl-C, SIGTERM) leaves its private copy in
3132
+ // the data directory; sweep it before the check below, healthy store or not (D#558).
3133
+ if (!dataDirUnreadable) {
3134
+ try {
3135
+ const { sweepSnapshotChecks } = await import('./lib/db-unusable.mjs');
3136
+ sweepSnapshotChecks(dirname(DB_PATH));
3137
+ } catch {
3138
+ /* a sweep is housekeeping: it never takes the run */
3139
+ }
3140
+ }
3096
3141
  if (dataDirUnreadable) {
3097
3142
  notCheckedDenied('Database');
3098
3143
  } else if (existsSync(DB_PATH) && bindingBrokenHere) {
package/lib/db-backup.mjs CHANGED
@@ -52,7 +52,7 @@ const SNAPSHOT_STAMP_RE = /-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-\d+-\d+\.
52
52
  * ends the reader's search with a false fact. Same rule the doctor bash-hook check
53
53
  * settled on — "nothing to check" and "I could not look" are different answers.
54
54
  *
55
- * @returns {{ok: true, snapshots: Array<{path:string,size:number,mtimeMs:number}>}
55
+ * @returns {{ok: true, snapshots: Array<{path:string,size:number,mtimeMs:number,isFile:boolean}>}
56
56
  * | {ok: false, reason: string}}
57
57
  */
58
58
  export function readSnapshots(dbPath) {
@@ -76,7 +76,7 @@ export function readSnapshots(dbPath) {
76
76
  const full = join(dir, n);
77
77
  try {
78
78
  const st = statSync(full);
79
- snapshots.push({ path: full, size: st.size, mtimeMs: st.mtimeMs });
79
+ snapshots.push({ path: full, size: st.size, mtimeMs: st.mtimeMs, isFile: st.isFile() });
80
80
  } catch {
81
81
  /* raced away */
82
82
  }
@@ -23,15 +23,30 @@
23
23
  // one, on a condition that never heals by itself. That is the schema-skew shape exactly, and
24
24
  // this module is deliberately its mirror image so the two cannot drift apart.
25
25
  //
26
- // It imports no native binding: the static graph is 10 modules and zero package edges (the
27
- // only bare specifiers anywhere in it are the `node:` builtins). That is the property that
26
+ // It imports no native binding: its static graph has zero package edges (the only bare
27
+ // specifiers anywhere in it are the `node:` builtins). That is the property that
28
28
  // matters — a classifier the hook path may need while the binding is the broken thing must
29
29
  // not sit behind a native import. It is NOT as tight as schema-skew.mjs, which imports
30
30
  // `node:` builtins and nothing else; this one reaches `db-backup → utils → …` for
31
31
  // `readSnapshots`. Same guarantee, larger graph — do not restate it as "same discipline".
32
32
 
33
- import { basename, dirname } from 'node:path';
33
+ import { spawnSync } from 'node:child_process';
34
+ import {
35
+ constants as fsConstants,
36
+ chmodSync,
37
+ copyFileSync,
38
+ existsSync,
39
+ lstatSync,
40
+ mkdtempSync,
41
+ readdirSync,
42
+ rmSync,
43
+ statSync,
44
+ } from 'node:fs';
45
+ import { basename, dirname, join } from 'node:path';
46
+ import { fileURLToPath } from 'node:url';
34
47
  import { readSnapshots } from './db-backup.mjs';
48
+ import { CODE_DIR } from './data-paths.mjs';
49
+ import { SCHEMA_SKEW_CODE } from './schema-skew.mjs';
35
50
  import { shellWord, CLI_INVOKE } from '../cli-path.mjs';
36
51
 
37
52
  /** Marker prefix for lib/record-once.mjs. Per project, like the skew one. */
@@ -85,8 +100,8 @@ export function isFtsCorruptionError(err) {
85
100
  * nothing" rather than "search is broken".
86
101
  *
87
102
  * ONE STRING FOR BOTH CHANNELS, unlike the file-level family below. The split there exists
88
- * because that remedy OVERWRITES the database and must not be handed ready-to-run to an
89
- * agent holding Bash. This one re-derives every index from its own content table: the rows
103
+ * because that remedy moves the database file out from under every session and must not be
104
+ * handed ready-to-run to an agent holding Bash. This one re-derives every index from its own content table: the rows
90
105
  * are never read from the index, so a rebuild is lossless and idempotent, and `doctor`
91
106
  * already runs it unprompted. Naming "intact" is load-bearing — the reading this line
92
107
  * exists to prevent is "my memories are corrupt".
@@ -140,81 +155,446 @@ export function isDbUnusableError(err) {
140
155
  return UNUSABLE_RE.test(msg) || SCHEMA_UNREADABLE_RE.test(msg);
141
156
  }
142
157
 
158
+ /** The child checkSnapshot runs: lib/snapshot-probe.mjs, beside this file. */
159
+ const SNAPSHOT_PROBE = join(dirname(fileURLToPath(import.meta.url)), 'snapshot-probe.mjs');
160
+ /** checkSnapshot's private directories in the data directory: `<prefix><pid>-XXXXXX`, the pid
161
+ * being the process that made it. */
162
+ const CHECK_DIR_PREFIX = '.snapshot-check-';
163
+ const CHECK_DIR_RE = /^\.snapshot-check-(\d+)-[A-Za-z0-9]{6}$/;
164
+ /** The probe's run on one copy: open (migrations included), index rebuild, integrity check. The
165
+ * copy before it is not bounded by this. */
166
+ const CHECK_TIMEOUT_MS = 10 * 60 * 1000;
167
+ /** No check runs this long, so a private directory this old was left by a killed check even when
168
+ * its pid now names a live process. */
169
+ const STALE_CHECK_MS = 24 * 60 * 60 * 1000;
170
+ // SQLite codes about the check's own copy rather than about the snapshot: the copy lives in the
171
+ // data directory, so a full or failing disk there says nothing about what a restore would give,
172
+ // and neither does a path SQLite cannot open (the private directory makes it longer than the
173
+ // store's: v6.30.6 r1 defects P3-3).
174
+ const CHECK_OWN_CODE_RE = /^SQLITE_(FULL|IOERR|CANTOPEN)/;
175
+
176
+ function nonEmptyFile(path) {
177
+ try {
178
+ const st = statSync(path);
179
+ return st.isFile() && st.size > 0;
180
+ } catch {
181
+ return false;
182
+ }
183
+ }
184
+
185
+ /**
186
+ * What restoring the snapshot at `path` would give (D#558). The snapshot is copied into a private
187
+ * directory beside it, with its own `-wal` when it has a non-empty one (a hand-made `cp` of a live
188
+ * store), and lib/snapshot-probe.mjs opens the copy in a child process with the opener every
189
+ * product face uses, rebuilds its indexes as the restore command's last step (`fts-check rebuild`)
190
+ * does, then runs SQLite's integrity check and counts observations. The directory is removed
191
+ * before this returns.
192
+ *
193
+ * - `ok`: the copy opens, its indexes rebuild, it passes the integrity check, and it holds
194
+ * `observations`, or `otherRows` in the other tables a user's rows live in (at least one);
195
+ * - `empty`: the same with no row in either, so restoring it gives what a fresh store gives;
196
+ * - `bad`: the product's opener throws on it (`why: 'open'`), an index does not rebuild
197
+ * (`why: 'rebuild'`), or the integrity check fails or throws (`why: 'integrity'`), `reason`
198
+ * saying how;
199
+ * - `unchecked`: the check itself could not run (the copy, the child, a full or failing disk, a
200
+ * copy SQLite cannot open, whichever step met it), or the snapshot was written by a newer
201
+ * claude-mem-lite, `reason` saying why and `where` naming the directory when making the private
202
+ * one failed.
203
+ *
204
+ * `listed`, when present, is how many observations the copy's own index listed before the rebuild,
205
+ * more than its table holds after it: the table lost rows, or the index kept entries for rows a
206
+ * delete removed. The restore gives what the table holds; doctor prints both numbers.
207
+ *
208
+ * `withLog` says whether the snapshot's own `-wal` was part of the copy, so the restore command
209
+ * copies it too. The first attempt checked the file itself with integrity_check, which rejects a
210
+ * snapshot whose damage an index rebuild repairs, and could not read a file over 2 GiB; this one
211
+ * checks what a restore gives.
212
+ *
213
+ * @param {string} path
214
+ * @param {{probe?: string, timeoutMs?: number}} [opts] `probe` replaces the child script (tests)
215
+ * @returns {{verdict: 'ok'|'empty'|'bad'|'unchecked', withLog: boolean, observations?: number, otherRows?: number, listed?: number, why?: 'open'|'rebuild'|'integrity', reason?: string, where?: string}}
216
+ */
217
+ export function checkSnapshot(path, { probe = SNAPSHOT_PROBE, timeoutMs = CHECK_TIMEOUT_MS } = {}) {
218
+ let dir = null;
219
+ let withLog = false;
220
+ const unchecked = (reason) => ({ verdict: 'unchecked', withLog, reason });
221
+ const bad = (why, reason) => ({ verdict: 'bad', withLog, why, reason: String(reason).slice(0, 200) });
222
+ try {
223
+ try {
224
+ dir = mkdtempSync(join(dirname(path), `${CHECK_DIR_PREFIX}${process.pid}-`));
225
+ } catch (e) {
226
+ return { ...unchecked(e?.code || e?.message || 'unwritable'), where: dirname(path) };
227
+ }
228
+ const copy = join(dir, 'claude-mem-lite.db');
229
+ // FICLONE: a reflink where the filesystem has them, a plain streamed copy elsewhere.
230
+ copyFileSync(path, copy, fsConstants.COPYFILE_FICLONE);
231
+ withLog = nonEmptyFile(`${path}-wal`);
232
+ if (withLog) copyFileSync(`${path}-wal`, `${copy}-wal`, fsConstants.COPYFILE_FICLONE);
233
+ // The copy takes the snapshot's mode, and a read-only one opened read-only and read as damage
234
+ // (v6.30.6 r1 defects P2-3); the restore command makes the restored store writable the same way.
235
+ for (const f of withLog ? [copy, `${copy}-wal`] : [copy]) chmodSync(f, 0o600);
236
+ // SQLite's sort files and Node's temporary files go into the private directory too, so a full
237
+ // /tmp is not read as the snapshot's (v6.30.6 r1 defects P3-4). So does the home directory:
238
+ // an opener that finds no store moves one from ~/claude-mem-lite (v6.30.8 r1 defects F7).
239
+ const r = spawnSync(process.execPath, [probe], {
240
+ env: {
241
+ ...process.env,
242
+ CLAUDE_MEM_DIR: dir,
243
+ SQLITE_TMPDIR: dir,
244
+ TMPDIR: dir,
245
+ HOME: dir,
246
+ USERPROFILE: dir,
247
+ },
248
+ encoding: 'utf8',
249
+ timeout: timeoutMs,
250
+ stdio: ['ignore', 'pipe', 'pipe'],
251
+ });
252
+ if (r.error) {
253
+ if (r.error.code === 'ETIMEDOUT') return unchecked(`ETIMEDOUT, over ${elapsed(timeoutMs)}`);
254
+ return unchecked(r.error.code || r.error.message);
255
+ }
256
+ let out = null;
257
+ try {
258
+ out = JSON.parse(String(r.stdout).trim().split('\n').pop());
259
+ } catch {
260
+ /* no result line: the probe did not run to its end */
261
+ }
262
+ if (r.status !== 0 || !out || typeof out !== 'object') {
263
+ const how = r.signal ? `probe killed by ${r.signal}` : `probe exited ${r.status}`;
264
+ // The error line, not the first one: Node prints a source location above a load failure.
265
+ const lines = String(r.stderr)
266
+ .split('\n')
267
+ .map((l) => l.trim())
268
+ .filter(Boolean);
269
+ const said = (lines.find((l) => /^\w*Error\b/.test(l)) ?? lines[0] ?? '').slice(0, 200);
270
+ return unchecked(said ? `${how}: ${said}` : how);
271
+ }
272
+ const rebuildErrors = Array.isArray(out.rebuildErrors) ? out.rebuildErrors : [];
273
+ const own = [out.error, ...rebuildErrors].find((e) => CHECK_OWN_CODE_RE.test(e?.code ?? ''));
274
+ if (own) return unchecked(own.code);
275
+ // This version refuses a store a newer one wrote, which says nothing about the snapshot; an
276
+ // older snapshot named past it could hold less (v6.30.6 r1 defects P2-1).
277
+ if (out.error?.code === SCHEMA_SKEW_CODE) {
278
+ return unchecked('written by a newer claude-mem-lite; update claude-mem-lite, then run doctor again');
279
+ }
280
+ if (out.error && !out.opened) return bad('open', out.error.code || out.error.message);
281
+ if (rebuildErrors.length > 0) return bad('rebuild', rebuildErrors[0].message);
282
+ if (out.error) return bad('integrity', out.error.code || out.error.message);
283
+ if (out.integrity !== 'ok') return bad('integrity', out.integrity);
284
+ const otherRows = Number.isInteger(out.otherRows) ? out.otherRows : 0;
285
+ const passed = {
286
+ verdict: out.observations > 0 || otherRows > 0 ? 'ok' : 'empty',
287
+ withLog,
288
+ observations: out.observations,
289
+ otherRows,
290
+ };
291
+ if (Number.isInteger(out.listed) && out.listed > out.observations) passed.listed = out.listed;
292
+ return passed;
293
+ } catch (e) {
294
+ return unchecked(e?.code || e?.message || 'unreadable');
295
+ } finally {
296
+ if (dir) {
297
+ try {
298
+ rmSync(dir, { recursive: true, force: true });
299
+ } catch {
300
+ /* left behind: sweepSnapshotChecks removes it once this process has exited */
301
+ }
302
+ }
303
+ }
304
+ }
305
+
306
+ function elapsed(ms) {
307
+ return ms >= 1000 ? `${Math.round(ms / 1000)} s` : `${ms} ms`;
308
+ }
309
+
310
+ /** Whether `pid` names a running process (EPERM: one this user may not signal, still running). */
311
+ function running(pid) {
312
+ try {
313
+ process.kill(pid, 0);
314
+ return true;
315
+ } catch (e) {
316
+ return e?.code === 'EPERM';
317
+ }
318
+ }
319
+
320
+ /**
321
+ * Remove the private directories checkSnapshot leaves when it is killed mid-check (each holds a
322
+ * full copy of a snapshot): those whose process has exited, and any older than a check can run
323
+ * (its pid may name another process by then). A doctor checking in another terminal keeps its
324
+ * own. Only directories named exactly as checkSnapshot names them; never a link. doctor calls
325
+ * this before its database check, healthy store or not, so a copy left by an interrupted check
326
+ * goes on the next doctor run even once the store is restored.
327
+ * @param {string} dir the data directory
328
+ * @param {{nowMs?: number}} [opts]
329
+ */
330
+ export function sweepSnapshotChecks(dir, { nowMs = Date.now() } = {}) {
331
+ let names;
332
+ try {
333
+ names = readdirSync(dir);
334
+ } catch {
335
+ return;
336
+ }
337
+ for (const n of names) {
338
+ const m = CHECK_DIR_RE.exec(n);
339
+ if (!m) continue;
340
+ const full = join(dir, n);
341
+ try {
342
+ const st = lstatSync(full);
343
+ if (!st.isDirectory()) continue;
344
+ if (running(Number(m[1])) && nowMs - st.mtimeMs < STALE_CHECK_MS) continue;
345
+ rmSync(full, { recursive: true, force: true });
346
+ } catch {
347
+ /* raced away, or not ours to remove */
348
+ }
349
+ }
350
+ }
351
+
352
+ /**
353
+ * The CLI, run against `dbPath`'s data directory. A relocated one gets a `CLAUDE_MEM_DIR=` prefix,
354
+ * since it may be set only in Claude Code's environment; the default one gets none, which
355
+ * PowerShell, cmd and csh cannot run (v6.30.6 r1 defects P3-7), so there a CLAUDE_MEM_DIR the
356
+ * shell exports for another store wins.
357
+ */
358
+ function cliFor(dbPath, args) {
359
+ const dir = dirname(dbPath);
360
+ return dir === CODE_DIR
361
+ ? `${CLI_INVOKE} ${args}`
362
+ : `CLAUDE_MEM_DIR=${shellWord(dir)} ${CLI_INVOKE} ${args}`;
363
+ }
364
+
365
+ function doctorCommand(dbPath) {
366
+ return cliFor(dbPath, 'doctor');
367
+ }
368
+
143
369
  /**
144
370
  * What the user should actually run. Three outcomes, never two — the same rule schema-skew.mjs
145
371
  * states: "there is no backup" and "I could not look for one" must not print in the same
146
372
  * voice, because a green-sounding line ends the reader's search.
147
373
  *
148
- * `snapshotCount` is part of the return rather than something a caller re-derives: doctor's
149
- * sentence names it ("Restore the newest of 2 backup snapshot(s)"), and a second
150
- * `readSnapshots` call to recover a number this function already had would be a second
151
- * directory read that can disagree with the first.
374
+ * A snapshot goes into a command only after `check` (doctor passes checkSnapshot) calls it `ok`,
375
+ * newest first: `bad` and `empty` ones are passed over and counted; one the check could not run on
376
+ * before any passes stops the walk with no command (kind 'unknown', or 'schema'), since an older
377
+ * snapshot named past it could hold less. The command restores the newest that passes; every older
378
+ * snapshot is checked as well, and each that passes is listed in `found` with its counts and given
379
+ * its own command in `alternatives`, newest first (D#577). Without `check` (the SessionStart notice, which must not copy and open every
380
+ * candidate on each session start while the store is broken) no snapshot goes into a command:
381
+ * kind 'unknown' counts them and points at doctor, the kind every version's doctor renders as its
382
+ * note (a killed update can leave an older install.mjs beside this file). None `ok`, or none at
383
+ * all: the set-aside. Only regular files count as snapshots: a directory or a device named like
384
+ * one is not a copy of anything, and copying it fails. Every doctor named in a note carries a
385
+ * relocated data directory, which the shell the user runs it from may not (cliFor).
386
+ *
387
+ * Both commands keep every byte they replace (D#539): the broken file and its `-wal` move to
388
+ * `keptAs` and `keptAs-wal`, the names SQLite pairs, and only the `-shm` is deleted. The restore
389
+ * ends with `fts-check rebuild`, the step the check ran after the product's open. Each starts
390
+ * with a guard so running it a second time stops before overwriting the first kept copy, and
391
+ * `touch` gives `mv` a log to move when there is none (an empty `-wal` reads as no log).
392
+ * Chained with `&&` only: fish has no `{ }` grouping. The kept name carries the broken file's
393
+ * mtime, not the clock, so every doctor run on one broken file prints the same command (and the
394
+ * --json face matches the human one); a later broken file gets another name. When that name or its
395
+ * `-wal` already exists (a kept file moved back keeps its mtime) a `-1`, `-2`, … is added, so the
396
+ * command doctor prints never stops at its own guard.
397
+ *
398
+ * `found` is the sentence about the snapshots, which doctor puts in front of its own command
399
+ * sentence; `note` is what the SessionStart notice prints. `snapshotCount` counts the non-empty
400
+ * snapshots, so a caller does not re-read the directory for it.
152
401
  *
153
402
  * `err`, when given, picks the family: a schema SQLite cannot read gets kind 'schema', which
154
403
  * carries no command (see SCHEMA_UNREADABLE_RE).
155
404
  *
156
405
  * @param {string} dbPath
157
406
  * @param {unknown} [err]
158
- * @returns {{kind: 'restore'|'set-aside'|'unknown'|'schema', command: string, note: string, snapshotCount: number}}
407
+ * @param {{check?: (path: string) => ReturnType<typeof checkSnapshot>, stampMs?: number}} [opts]
408
+ * `stampMs` replaces the broken file's mtime in the kept name (tests)
409
+ * @returns {{kind: 'restore'|'set-aside'|'unknown'|'schema', command: string, keptAs: string, found: string, note: string, snapshotCount: number, alternatives?: Array<{path: string, command: string}>}}
159
410
  */
160
- export function dbUnusableRemedy(dbPath, err) {
161
- const clear = `rm -f ${shellWord(`${dbPath}-wal`)} ${shellWord(`${dbPath}-shm`)}`;
411
+ export function dbUnusableRemedy(dbPath, err, { check, stampMs } = {}) {
162
412
  const schema = SCHEMA_UNREADABLE_RE.test(String(err?.message ?? err ?? ''));
413
+ let stamp = stampMs;
414
+ if (stamp === undefined) {
415
+ try {
416
+ stamp = statSync(dbPath).mtimeMs;
417
+ } catch {
418
+ stamp = Date.now();
419
+ }
420
+ }
421
+ const keptBase = `${dbPath}.corrupt-${new Date(Math.floor(stamp)).toISOString().replace(/[:.]/g, '-')}`;
422
+ let keptAs = keptBase;
423
+ for (let i = 1; existsSync(keptAs) || existsSync(`${keptAs}-wal`); i++) keptAs = `${keptBase}-${i}`;
424
+ const setAsideCommand = [
425
+ `test ! -e ${shellWord(keptAs)}`,
426
+ `test ! -e ${shellWord(`${keptAs}-wal`)}`,
427
+ `rm -f ${shellWord(`${dbPath}-shm`)}`,
428
+ `touch ${shellWord(`${dbPath}-wal`)}`,
429
+ `mv ${shellWord(dbPath)} ${shellWord(keptAs)}`,
430
+ `mv ${shellWord(`${dbPath}-wal`)} ${shellWord(`${keptAs}-wal`)}`,
431
+ ].join(' && ');
432
+ const keeps = `as ${keptAs} and ${keptAs}-wal`;
433
+ const noCommand = (kind, found, note = found, snapshotCount = 0) => ({
434
+ kind,
435
+ command: '',
436
+ keptAs: '',
437
+ snapshotCount,
438
+ found,
439
+ note,
440
+ });
163
441
  const snap = readSnapshots(dbPath);
164
442
  if (!snap.ok) {
165
- return {
166
- kind: schema ? 'schema' : 'unknown',
167
- command: '',
168
- snapshotCount: 0,
169
- note:
170
- `Could not read ${dirname(dbPath)} to look for a backup snapshot (${snap.reason}) — ` +
171
- `fix that directory first, then look for ${basename(dbPath)}.*.bak beside the database.`,
172
- };
173
- }
174
- // A 0-byte `.bak` is what a failed snapshot of a damaged store left before 6.31.0 (D#551),
175
- // usually the newest one; it is not a copy of anything.
176
- const snapshots = snap.snapshots.filter((s) => s.size > 0);
177
- const empty = snap.snapshots.length - snapshots.length;
178
- const none =
179
- empty > 0
180
- ? `No backup snapshot beside the database holds any data (${empty} empty .bak file${empty === 1 ? '' : 's'} skipped).`
181
- : 'No backup snapshot exists beside the database.';
182
- if (schema && snapshots.length === 0) {
183
- return {
184
- kind: 'schema',
185
- command: '',
186
- snapshotCount: 0,
187
- note: none,
188
- };
443
+ const found =
444
+ `Could not read ${dirname(dbPath)} to look for a backup snapshot (${snap.reason}) — ` +
445
+ `fix that directory first, then look for ${basename(dbPath)}.*.bak beside the database.`;
446
+ return noCommand(schema ? 'schema' : 'unknown', found);
189
447
  }
448
+ // A 0-byte `.bak` is what a failed snapshot of a damaged store left before 6.30.4 (D#551),
449
+ // usually the newest one; it is not a copy of anything. Newest first by mtime, ties broken by
450
+ // path so the order is total rather than readdir's — the D#9 shape.
451
+ const files = snap.snapshots.filter((s) => s.isFile);
452
+ const snapshots = files
453
+ .filter((s) => s.size > 0)
454
+ .sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? 1 : -1));
455
+ const empty = files.length - snapshots.length;
456
+ const skipped = empty > 0 ? ` (${empty} empty .bak file${empty === 1 ? '' : 's'} skipped)` : '';
457
+ const count = `${snapshots.length} backup snapshot(s) beside the database${skipped}`;
458
+ const setAside = (found) => ({
459
+ kind: 'set-aside',
460
+ command: setAsideCommand,
461
+ keptAs,
462
+ snapshotCount: snapshots.length,
463
+ found,
464
+ note: `${found} That command moves the broken file and its log aside, ${keeps}, so a fresh store is created on the next session.`,
465
+ });
190
466
  if (snapshots.length === 0) {
191
- return {
192
- kind: 'set-aside',
193
- command: `${clear} && mv ${shellWord(dbPath)} ${shellWord(`${dbPath}.corrupt`)}`,
194
- snapshotCount: 0,
195
- note: `${none} That command sets the broken file aside so a fresh store is created on the next session.`,
196
- };
467
+ const found =
468
+ empty > 0
469
+ ? `No backup snapshot beside the database holds any data${skipped}.`
470
+ : 'No backup snapshot exists beside the database.';
471
+ return schema ? noCommand('schema', found) : setAside(found);
472
+ }
473
+ if (!check) {
474
+ const found = `${snapshots.length} backup snapshot(s) exist beside the database${skipped}.`;
475
+ const checks = schema
476
+ ? 'checks which ones restore'
477
+ : 'checks which ones restore before it gives a command';
478
+ const note = `${found} \`${doctorCommand(dbPath)}\` ${checks}.`;
479
+ return noCommand(schema ? 'schema' : 'unknown', found, note, snapshots.length);
480
+ }
481
+ // doctor prints which one it is checking: a large snapshot takes seconds (v6.30.6 r1 defects P3-2).
482
+ const ask = (i) => check(snapshots[i].path, { nth: i + 1, of: snapshots.length });
483
+ const reject = (counts, r) => {
484
+ counts[r.verdict === 'empty' ? 'empty' : r.why === 'rebuild' || r.why === 'integrity' ? r.why : 'open'] +=
485
+ 1;
486
+ };
487
+ const rejectedText = (counts) =>
488
+ [
489
+ counts.open && `${counts.open} ${counts.open === 1 ? 'does' : 'do'} not open`,
490
+ counts.rebuild && `${counts.rebuild} ${counts.rebuild === 1 ? 'fails' : 'fail'} the index rebuild`,
491
+ counts.integrity &&
492
+ `${counts.integrity} ${counts.integrity === 1 ? 'fails' : 'fail'} the integrity check`,
493
+ counts.empty && `${counts.empty} ${counts.empty === 1 ? 'holds' : 'hold'} no rows`,
494
+ ]
495
+ .filter(Boolean)
496
+ .join(', ');
497
+ const rejected = { open: 0, rebuild: 0, integrity: 0, empty: 0 };
498
+ let at = 0;
499
+ let result;
500
+ for (; at < snapshots.length; at++) {
501
+ result = ask(at);
502
+ if (result.verdict === 'ok' || result.verdict === 'unchecked') break;
503
+ reject(rejected, result);
504
+ }
505
+ const why = rejectedText(rejected);
506
+ if (at === snapshots.length) {
507
+ const found = `None of the ${count} restores cleanly (${why}).`;
508
+ return schema ? noCommand('schema', found, found, snapshots.length) : setAside(found);
509
+ }
510
+ const passedOver =
511
+ at === 0
512
+ ? ''
513
+ : `Of the ${count}, the newest ${at === 1 ? 'one does' : `${at} do`} not restore cleanly (${why}); the next one`;
514
+ if (result.verdict === 'unchecked') {
515
+ const found = `${passedOver || `The newest of the ${count}`} could not be checked (${result.reason}): ${result.where ?? snapshots[at].path}.`;
516
+ const note = `${found} Once that is resolved, run \`${doctorCommand(dbPath)}\` again; no snapshot goes into a command before then.`;
517
+ return noCommand(schema ? 'schema' : 'unknown', found, note, snapshots.length);
197
518
  }
198
- // Newest by mtime, ties broken by name (which carries an ISO stamp) so the answer is total
199
- // rather than dependent on readdir order — the D#9 shape.
200
- const newest = snapshots.slice().sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? 1 : -1))[0];
519
+ // The command restores the newest snapshot that passes, and every older one is checked too, so
520
+ // each that passes is listed with its counts before the command and given its own (D#577). The
521
+ // fourth attempt named an older one when the newest was short of its own index (`listed`), but
522
+ // that shape has two causes: the table lost rows, or a delete's write to an index page was lost
523
+ // and the index still lists the rows the user removed (v6.30.7 r1 claims P2-1). Doctor chooses
524
+ // by age alone, as the established tools do, and the user chooses between them with the numbers
525
+ // in front of them (the survey in docs/audits, 2026-10-24). One the check cannot run on is named
526
+ // with its reason; the command restores a snapshot newer than it, so it passes over nothing newer.
527
+ const older = [];
528
+ const olderUnchecked = [];
529
+ const olderRejected = { open: 0, rebuild: 0, integrity: 0, empty: 0 };
530
+ for (let j = at + 1; j < snapshots.length; j++) {
531
+ const r = ask(j);
532
+ if (r.verdict === 'ok') older.push({ path: snapshots[j].path, result: r });
533
+ else if (r.verdict === 'unchecked') olderUnchecked.push(`${r.where ?? snapshots[j].path} (${r.reason})`);
534
+ else reject(olderRejected, r);
535
+ }
536
+ const holds = (r) =>
537
+ `${r.observations} observation(s)${r.observations === 0 && r.otherRows ? ` and ${r.otherRows} other row(s)` : ''}`;
538
+ const what = `a copy of it, restored with its indexes rebuilt the way the command does it, opens in this version, passes SQLite's integrity check and holds ${holds(result)}${result.listed ? `, ${result.listed - result.observations} fewer than its own index lists` : ''}`;
539
+ const restores = result.listed ? 'restores, but short' : passedOver ? 'does' : 'restores cleanly';
540
+ let found = `${passedOver || `The newest of the ${count}`} ${restores}: ${what}.`;
541
+ if (result.listed) {
542
+ found +=
543
+ ' Short of its own index means its table lost those rows or its index still lists rows a delete removed.';
544
+ }
545
+ if (older.length > 0) {
546
+ const each = older.map(
547
+ ({ path, result: r }) => `${path}, ${holds(r)}${r.listed ? ` (its index lists ${r.listed})` : ''}`,
548
+ );
549
+ found += ` ${older.length === 1 ? 'An older snapshot also restores' : `${older.length} older snapshots also restore`}: ${each.join('; ')}.`;
550
+ if (older.some(({ result: r }) => r.observations > result.observations)) {
551
+ found += ` ${older.length === 1 ? 'It holds' : 'One of them holds'} more observations than the one the command restores.`;
552
+ }
553
+ found +=
554
+ ' Restoring an older one instead loses what was written after it was taken and brings back what was deleted since.';
555
+ }
556
+ if (olderUnchecked.length > 0) {
557
+ found += ` ${olderUnchecked.length === 1 ? 'An older snapshot' : `${olderUnchecked.length} older snapshots`} could not be checked: ${olderUnchecked.join('; ')}.`;
558
+ }
559
+ const olderWhy = rejectedText(olderRejected);
560
+ if (olderWhy) found += ` Of the older ones, ${olderWhy}.`;
561
+ // The restore puts the snapshot (and its own -wal, when the check used one) in place writable, as
562
+ // the check's copy was, then rebuilds the indexes as the check did. `test -s` first: with the
563
+ // snapshot gone, nothing moves (v6.30.6 r1 defects P3-5).
564
+ const restoreCommand = (path, withLog) => {
565
+ const db = shellWord(dbPath);
566
+ const wal = shellWord(`${dbPath}-wal`);
567
+ return [
568
+ `test -s ${shellWord(path)}`,
569
+ ...(withLog ? [`test -s ${shellWord(`${path}-wal`)}`] : []),
570
+ setAsideCommand,
571
+ `cp ${shellWord(path)} ${db}`,
572
+ `chmod 600 ${db}`,
573
+ ...(withLog ? [`cp ${shellWord(`${path}-wal`)} ${wal}`, `chmod 600 ${wal}`] : []),
574
+ // The rebuild is part of what the check vouched for: an FTS5 index whose damage FTS5's own
575
+ // check does not see (a shadow table's rows out of key order), and an ordinary index whose
576
+ // entries no longer match its table, both pass doctor and fail integrity_check until rebuilt.
577
+ cliFor(dbPath, 'fts-check rebuild'),
578
+ ].join(' && ');
579
+ };
580
+ const named = snapshots[at].path;
201
581
  if (schema) {
202
- return {
203
- kind: 'schema',
204
- command: '',
205
- snapshotCount: snapshots.length,
206
- note:
207
- `${snapshots.length} backup snapshot(s) exist beside it; the newest is ${newest.path}. ` +
208
- 'Restoring one replaces the database file, so copy the broken file aside first.',
209
- };
582
+ const note = `${found} It is ${named}. Restoring it replaces the database file, so copy the broken file aside first.`;
583
+ return noCommand('schema', found, note, snapshots.length);
210
584
  }
585
+ // Each starts with the same set-aside, so once one has run every other stops at its guard.
586
+ const alternatives = older.map(({ path, result: r }) => ({
587
+ path,
588
+ command: restoreCommand(path, r.withLog),
589
+ }));
211
590
  return {
212
591
  kind: 'restore',
213
- command: `${clear} && cp ${shellWord(newest.path)} ${shellWord(dbPath)}`,
592
+ command: restoreCommand(named, result.withLog),
593
+ keptAs,
214
594
  snapshotCount: snapshots.length,
215
- note:
216
- `Restores the newest of ${snapshots.length} backup snapshot(s). Move the broken ` +
217
- 'file aside first if you want to keep it for inspection.',
595
+ found,
596
+ note: `${found} The command keeps the broken file and its log ${keeps}, and rebuilds the store's indexes.`,
597
+ alternatives,
218
598
  };
219
599
  }
220
600
 
@@ -233,13 +613,13 @@ export function formatDbUnusableNotice({ dbPath, remedy }) {
233
613
  : ` ${dbPath} exists but SQLite does not recognise it as a database.`,
234
614
  ];
235
615
  if (remedy.command) {
236
- // Before the command: it deletes the -wal and -shm, then replaces or moves the database file,
616
+ // Before the command: it moves the database file and its -wal aside and deletes the -shm,
237
617
  // under any session still holding the store (D#534). doctor says the same.
238
618
  lines.push(' Once every Claude Code session is closed, this one included, run:');
239
619
  lines.push(` ${remedy.command}`);
240
620
  }
241
621
  if (remedy.note) lines.push(` ${remedy.note}`);
242
- lines.push(` Saves and recall are disabled. \`${CLI_INVOKE} doctor\` re-checks.`);
622
+ lines.push(` Saves and recall are disabled. \`${doctorCommand(dbPath)}\` re-checks.`);
243
623
  return lines.join('\n');
244
624
  }
245
625
 
@@ -247,22 +627,23 @@ export function formatDbUnusableNotice({ dbPath, remedy }) {
247
627
  * The same fact, with NO COMMAND IN IT, for the model channel.
248
628
  *
249
629
  * The schema-skew twin sends one string to both channels and that is safe there — its
250
- * commands are `git pull` / `claude plugin update` / `npm i -g`. This family's remedy is
251
- * `rm -f …-wal …-shm && cp "<snapshot>" "<db>"`, which OVERWRITES the database, and handing
252
- * a ready-to-run irreversible shell line to an agent that has Bash — with no addressee and no
253
- * "ask first" — is a different proposition. Worse, the restore arm defeats its own advice: a
254
- * reader who acts on the command line destroys the broken file the next line tells them to
255
- * keep for inspection.
630
+ * commands are `git pull` / `claude plugin update` / `npm i -g`. This family's remedy moves the
631
+ * database file and its log out from under every session and copies a snapshot into place, which
632
+ * is safe only once every Claude Code session is closed, and handing that as a ready-to-run shell
633
+ * line to an agent that has Bash, from inside one of those sessions, with no addressee and no
634
+ * "ask first", is a different proposition.
256
635
  *
257
636
  * So the human gets the command and the model gets the situation. Both still learn memory is
258
637
  * off, which is the point of using both channels at all.
259
638
  *
639
+ * @param {string} [dbPath] absent when an update killed partway left a hook.mjs from 6.30.7 or
640
+ * earlier beside this file (it calls this with no argument)
260
641
  * @returns {string}
261
642
  */
262
- export function formatDbUnusableModelNotice() {
643
+ export function formatDbUnusableModelNotice(dbPath) {
263
644
  return [
264
645
  '⚠️ [claude-mem-lite] Memory is OFF for this session: the database file is unreadable.',
265
646
  ' Saves and recall are disabled. Do not attempt to repair it yourself — tell the user to',
266
- ` run \`${CLI_INVOKE} doctor\`.`,
647
+ ` run \`${dbPath ? doctorCommand(dbPath) : `${CLI_INVOKE} doctor`}\`.`,
267
648
  ].join('\n');
268
649
  }
@@ -0,0 +1,74 @@
1
+ // lib/snapshot-probe.mjs — what restoring one backup snapshot would give (D#558).
2
+ //
3
+ // Run as a CHILD by lib/db-unusable.mjs `checkSnapshot`, with CLAUDE_MEM_DIR set to a private
4
+ // directory that holds a copy of the snapshot as claude-mem-lite.db. It does what the restore
5
+ // command does after its `cp`: opens the copy with the opener every product face uses
6
+ // (ensureDbWithWalRecovery, its FTS-rebuild and WAL branches included) and rebuilds its indexes
7
+ // with rebuildIndexes, which is what `fts-check rebuild` runs. Then it runs SQLite's integrity
8
+ // check on that read-write connection and counts observations. One JSON line on stdout, carrying
9
+ // every rebuild error with its SQLite code, so checkSnapshot can tell the check's own disk filling
10
+ // up from damage (the second attempt dropped those codes, r1 P1-1).
11
+ //
12
+ // A child process, not a call: ensureDb opens DB_PATH, which lib/data-paths.mjs fixes from
13
+ // CLAUDE_MEM_DIR when it is first imported, so the product's own opener reaches a copy only in a
14
+ // process whose data directory is the copy's. A second opener written for the copy would be a
15
+ // twin of ensureDb, and the first attempt at this check (v6.30.5, withdrawn) failed on exactly
16
+ // that kind of gap: a stand-in check that disagreed with what a restore gives.
17
+
18
+ import { existsSync } from 'node:fs';
19
+ import { resolve } from 'node:path';
20
+ import { fileURLToPath } from 'node:url';
21
+ import { DB_PATH, ensureDbWithWalRecovery, rebuildIndexes } from '../schema.mjs';
22
+
23
+ /** The other tables a user's rows live in: a snapshot holding rows only here is not empty. */
24
+ const OTHER_ROW_TABLES = ['session_summaries', 'user_prompts', 'events', 'deferred_work'];
25
+
26
+ /**
27
+ * The checks after the open, on a connection to the restored copy. Exported for tests. Each
28
+ * field is set before the next step runs, so a step that throws leaves the earlier ones in place.
29
+ * `listed` is the observation count before the rebuild, which SQLite takes from an index when the
30
+ * table has one, so it can list more rows than the table holds once rebuilt. `otherRows` counts
31
+ * the rows of OTHER_ROW_TABLES.
32
+ * @param {import('better-sqlite3').Database} db
33
+ * @param {object} [into] the result being built
34
+ * @returns {{listed: number, rebuildErrors: {code: string|null, message: string}[], integrity?: string, observations?: number, otherRows?: number}}
35
+ */
36
+ export function probeOpenedStore(db, into = {}) {
37
+ into.listed = db.prepare('SELECT count(*) FROM observations').pluck().get();
38
+ const { errors, codes } = rebuildIndexes(db);
39
+ into.rebuildErrors = errors.map((message, i) => ({ code: codes[i], message }));
40
+ into.integrity = db.prepare('PRAGMA integrity_check(1)').pluck().all().join('; ');
41
+ into.observations = db.prepare('SELECT count(*) FROM observations').pluck().get();
42
+ into.otherRows = OTHER_ROW_TABLES.reduce(
43
+ (n, t) => n + db.prepare(`SELECT count(*) FROM ${t}`).pluck().get(),
44
+ 0,
45
+ );
46
+ return into;
47
+ }
48
+
49
+ function main() {
50
+ // The opener creates a fresh store where none is, which would read as an empty snapshot.
51
+ if (!existsSync(DB_PATH)) {
52
+ process.stderr.write('Error: the copy to check is gone\n');
53
+ process.exitCode = 2;
54
+ return;
55
+ }
56
+ let db = null;
57
+ const result = { opened: false };
58
+ try {
59
+ db = ensureDbWithWalRecovery();
60
+ result.opened = true;
61
+ probeOpenedStore(db, result);
62
+ } catch (e) {
63
+ result.error = { code: e?.code ?? null, message: String(e?.message ?? e) };
64
+ } finally {
65
+ try {
66
+ db?.close();
67
+ } catch {
68
+ /* a private copy: nothing to keep */
69
+ }
70
+ }
71
+ process.stdout.write(`${JSON.stringify(result)}\n`);
72
+ }
73
+
74
+ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main();
package/mem-cli.mjs CHANGED
@@ -3454,8 +3454,10 @@ Commands:
3454
3454
  --session-audit Audit session/episode state for orphans and drift
3455
3455
  --json Machine-readable output (plain doctor run)
3456
3456
 
3457
- fts-check <check|rebuild> FTS5 index check or rebuild
3458
- Exit 0 when every index is healthy / rebuilt, 1 otherwise —
3457
+ fts-check <check|rebuild> FTS5 index check, or a rebuild of the FTS5 indexes and then
3458
+ every other index (REINDEX)
3459
+ Exit 0 when the FTS5 indexes are healthy (check) or every index
3460
+ is rebuilt (rebuild), 1 otherwise —
3459
3461
  so "fts-check rebuild && <next step>" is safe to chain.
3460
3462
 
3461
3463
  stats Show memory statistics
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "claude-mem-lite",
3
- "version": "6.30.6",
3
+ "version": "6.30.8",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "claude-mem-lite",
9
- "version": "6.30.6",
9
+ "version": "6.30.8",
10
10
  "os": [
11
11
  "darwin",
12
12
  "linux",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-mem-lite",
3
- "version": "6.30.6",
3
+ "version": "6.30.8",
4
4
  "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword 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).",
5
5
  "type": "module",
6
6
  "packageManager": "npm@10.9.2",
@@ -120,6 +120,7 @@
120
120
  "lib/install-shape.mjs",
121
121
  "lib/schema-skew.mjs",
122
122
  "lib/db-unusable.mjs",
123
+ "lib/snapshot-probe.mjs",
123
124
  "lib/db-busy.mjs",
124
125
  "lib/record-once.mjs",
125
126
  "lib/hook-stdin.mjs",
package/schema.mjs CHANGED
@@ -1662,18 +1662,19 @@ function capBusyWaits(db) {
1662
1662
  * ~/claude-mem-lite/, into DB_DIR. Only the store's own files move (the database, then its -wal
1663
1663
  * and -shm, under the same name; ensureDb then renames claude-mem.db), and only into a DB_DIR
1664
1664
  * holding no file of a store's family: a database, a log, a snapshot or a kept copy. install's
1665
- * backup of an original claude-mem store (migrateLegacyClaudeMemData, `.legacy-backup-<ms>`) is
1666
- * not one. Nothing is removed. It used to rename the whole directory over a DB_DIR it first
1667
- * removed when DB_DIR held no `*.db` name (D#561): after the set-aside command that took the kept
1668
- * file, DB_DIR is also the code dir of a direct install, and a git clone of this repository made
1669
- * in ~ is at that path.
1665
+ * backup of an original claude-mem store (migrateLegacyClaudeMemData, `.legacy-backup-<ms>` and
1666
+ * its `-wal` and `-shm`) is not one. Nothing is removed. It used to rename the whole directory over
1667
+ * a DB_DIR it first removed when DB_DIR held no `*.db` name (D#561): after the set-aside command
1668
+ * that took the kept file, DB_DIR is also the code dir of a direct install, and a git clone of
1669
+ * this repository made in ~ is at that path.
1670
1670
  */
1671
1671
  function migrateUnhiddenStore() {
1672
1672
  const oldDir = join(homedir(), 'claude-mem-lite');
1673
1673
  const name = ['claude-mem-lite.db', 'claude-mem.db'].find((n) => existsSync(join(oldDir, n)));
1674
1674
  if (!name) return;
1675
1675
  const storeFile = (f) =>
1676
- (f.startsWith('claude-mem-lite.db') || f.startsWith('claude-mem.db')) && !/\.legacy-backup-\d+$/.test(f);
1676
+ (f.startsWith('claude-mem-lite.db') || f.startsWith('claude-mem.db')) &&
1677
+ !/\.legacy-backup-\d+(-wal|-shm)?$/.test(f);
1677
1678
  if (existsSync(DB_DIR) && readdirSync(DB_DIR).some(storeFile)) return;
1678
1679
  mkdirSync(DB_DIR, { recursive: true, mode: 0o700 });
1679
1680
  for (const ext of ['', '-wal', '-shm']) {
@@ -1951,32 +1952,59 @@ export function ensureDbWithWalRecovery({ warn, info } = {}) {
1951
1952
  /**
1952
1953
  * Rebuild all FTS5 indexes. Use after suspected index corruption (e.g. crash mid-trigger).
1953
1954
  * Safe to call at any time — rebuilds are idempotent.
1955
+ * `codes[i]` is the SQLite code of `errors[i]` (null for a table that is missing), so a caller
1956
+ * can tell its own disk filling up from damage: the restore check does (D#558).
1954
1957
  * @param {Database} db Opened database instance
1955
- * @returns {{rebuilt: string[], errors: string[]}} Results per FTS table
1958
+ * @returns {{rebuilt: string[], errors: string[], codes: (string|null)[]}} Results per FTS table
1956
1959
  */
1957
1960
  export function rebuildFTS(db) {
1958
1961
  const FTS_TABLES = ['observations_fts', 'session_summaries_fts', 'user_prompts_fts', 'events_fts'];
1959
1962
  const idRe = /^[a-z][a-z0-9_]*$/;
1960
1963
  const rebuilt = [];
1961
1964
  const errors = [];
1965
+ const codes = [];
1962
1966
  for (const fts of FTS_TABLES) {
1963
1967
  try {
1964
1968
  if (!idRe.test(fts)) {
1965
1969
  errors.push(`${fts}: invalid identifier`);
1970
+ codes.push(null);
1966
1971
  continue;
1967
1972
  }
1968
1973
  const exists = db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name=?`).get(fts);
1969
1974
  if (!exists) {
1970
1975
  errors.push(`${fts}: not found`);
1976
+ codes.push(null);
1971
1977
  continue;
1972
1978
  }
1973
1979
  db.exec(`INSERT INTO ${fts}(${fts}) VALUES('rebuild')`);
1974
1980
  rebuilt.push(fts);
1975
1981
  } catch (e) {
1976
1982
  errors.push(`${fts}: ${e.message}`);
1983
+ codes.push(e.code ?? null);
1977
1984
  }
1978
1985
  }
1979
- return { rebuilt, errors };
1986
+ return { rebuilt, errors, codes };
1987
+ }
1988
+
1989
+ /**
1990
+ * Rebuild every index the store derives from its tables: the FTS5 indexes (rebuildFTS), then
1991
+ * every other index (REINDEX). What `fts-check rebuild` runs, and what the restore check runs on
1992
+ * its copy after the open, so the two cannot drift (D#558). REINDEX repairs an index whose entries
1993
+ * no longer match its table, which no FTS rebuild touches and doctor's checks never read (D#562).
1994
+ * @param {Database} db Opened database instance
1995
+ * @returns {{rebuilt: string[], errors: string[], codes: (string|null)[]}} as rebuildFTS, with
1996
+ * 'indexes' standing for the REINDEX
1997
+ */
1998
+ export function rebuildIndexes(db) {
1999
+ const result = rebuildFTS(db);
2000
+ try {
2001
+ db.exec('REINDEX');
2002
+ result.rebuilt.push('indexes');
2003
+ } catch (e) {
2004
+ result.errors.push(`indexes: ${e.message}`);
2005
+ result.codes.push(e.code ?? null);
2006
+ }
2007
+ return result;
1980
2008
  }
1981
2009
 
1982
2010
  /**
package/scripts/setup.sh CHANGED
@@ -99,8 +99,6 @@ if [[ -n "${CLAUDE_MEM_DIR:-}" || -n "${CLAUDE_MEM_RUNTIME_DIR:-}" ]] && [[ -f "
99
99
  unset _resolved _db _rt
100
100
  fi
101
101
 
102
- OLD_UNHIDDEN_DIR="$HOME/claude-mem-lite"
103
-
104
102
  # Colors
105
103
  if [[ -t 2 ]]; then
106
104
  GREEN='\033[0;32m'; YELLOW='\033[0;33m'; BLUE='\033[0;34m'; RED='\033[0;31m'; NC='\033[0m'
@@ -120,17 +118,12 @@ log_warn() { echo -e "${YELLOW}⚠${NC} $*" >&2; }
120
118
  # day GitHub bumps the runner image. Keep SC2317 for anyone on an older shellcheck.
121
119
  log_err() { echo -e "${RED}✗${NC} $*" >&2; }
122
120
 
123
- # 1. Migrate unhidden dir (~/claude-mem-lite/ → ~/.claude-mem-lite/)
124
- # CODE_DIR, not DB_DIR, and deliberately: the unhidden directory of versions before the
125
- # first release held the INSTALL — server.mjs, hook.mjs, package.json — and CODE_DIR is the
126
- # one location that must never follow the relocation env var. Moving it into a relocated
127
- # DB_DIR would strand every absolute path settings.json and the MCP registration baked.
128
- if [[ -d "$OLD_UNHIDDEN_DIR" && ! -d "$CODE_DIR" ]]; then
129
- mv "$OLD_UNHIDDEN_DIR" "$CODE_DIR"
130
- log_ok "Migrated ~/claude-mem-lite/ → ~/.claude-mem-lite/"
131
- fi
121
+ # 1. ~/claude-mem-lite/ (the unhidden dir of versions before the first release) is not moved
122
+ # here: the first open moves a store left there into DB_DIR, and only the store
123
+ # (schema.mjs migrateUnhiddenStore). This script moved the whole directory into a missing
124
+ # CODE_DIR, and a git clone of this repository made in ~ is at that path (D#568).
132
125
 
133
- # 2. Ensure both locations exist (runtime created after migration check)
126
+ # 2. Ensure both locations exist
134
127
  mkdir -p "$CODE_DIR"
135
128
  mkdir -p "$DB_DIR"
136
129
  if [[ "$DB_DIR" == "$CODE_DIR" ]]; then
@@ -150,10 +143,39 @@ fi
150
143
  # a relocation it never closed — nothing ever writes a database THERE — so this block
151
144
  # copied the legacy database again on every single SessionStart, without bound. Measured
152
145
  # 2026-09-14: control arm stable at 1 backup across three runs, relocated arm 1 → 3.
146
+ # A backup already in DB_DIR closes it as well: while every open fails before creating the
147
+ # database (D#569's EXDEV did), the first condition never closes (D#573). Only the suffix is a
148
+ # pattern, so a `[` or `*` in DB_DIR's own path is matched as itself. The backup's database, not
149
+ # its log, which starts with the same name and is placed first.
150
+ #
151
+ # The log goes under the name SQLite pairs with the backup (D#584: the database alone lacked the
152
+ # rows only in the log). Each file is copied under a private name and then moved into place, the
153
+ # database last, so a session start killed partway leaves no backup; the next one copies again
154
+ # while no database has been created yet. Whether there is a log is decided before the copy, so
155
+ # a private copy that went away fails the backup rather than leaving the log out of it.
156
+ # Private files not written for ten minutes are removed first: a session start is killed at
157
+ # 30 s. install's own (`.legacy-backup-copy-`) are left to install, which removes them before a
158
+ # copy of its own, under its lock.
153
159
  OLD_DIR="$HOME/.claude-mem"
154
- if [[ -f "$OLD_DIR/claude-mem.db" && ! -f "$DB_DIR/claude-mem-lite.db" && ! -f "$DB_DIR/claude-mem.db" ]]; then
155
- BACKUP="$DB_DIR/claude-mem-lite.db.legacy-backup-$(date +%s)"
156
- if cp "$OLD_DIR/claude-mem.db" "$BACKUP" 2>/dev/null; then
160
+ has_legacy_backup() {
161
+ local f
162
+ for f in "$DB_DIR"/claude-mem-lite.db.legacy-backup-*; do
163
+ [[ -e "$f" && "$f" =~ \.legacy-backup-[0-9]+$ ]] && return 0
164
+ done
165
+ return 1
166
+ }
167
+ find "$DB_DIR/" -maxdepth 1 -name '.legacy-backup-setup-*' -mmin +10 -exec rm -f {} + 2>/dev/null || true
168
+ if [[ -f "$OLD_DIR/claude-mem.db" && ! -f "$DB_DIR/claude-mem-lite.db" && ! -f "$DB_DIR/claude-mem.db" ]] &&
169
+ ! has_legacy_backup; then
170
+ TS="$(date +%s)"
171
+ BACKUP="$DB_DIR/claude-mem-lite.db.legacy-backup-$TS"
172
+ TMP="$DB_DIR/.legacy-backup-setup-$$-$TS"
173
+ WAL="$OLD_DIR/claude-mem.db-wal"
174
+ [[ -f "$WAL" ]] || WAL=""
175
+ if { [[ -z "$WAL" ]] || cp "$WAL" "$TMP-wal" 2>/dev/null; } &&
176
+ cp "$OLD_DIR/claude-mem.db" "$TMP" 2>/dev/null &&
177
+ { [[ -z "$WAL" ]] || mv "$TMP-wal" "$BACKUP-wal"; } &&
178
+ mv "$TMP" "$BACKUP"; then
157
179
  log_info "Legacy ~/.claude-mem/ DB is schema-incompatible; backed up to $(basename "$BACKUP") (a fresh DB will be created). Old ~/.claude-mem/ preserved."
158
180
  else
159
181
  log_warn "Legacy DB backup failed — a fresh database will be created"
@@ -169,7 +191,7 @@ if [[ -f "$DB_DIR/claude-mem.db" && ! -f "$DB_DIR/claude-mem-lite.db" ]]; then
169
191
  log_ok "Database renamed: claude-mem.db → claude-mem-lite.db"
170
192
  fi
171
193
 
172
- # 5. Ensure runtime directories exist (after migration to not mask migration check).
194
+ # 5. Ensure runtime directories exist.
173
195
  # Both: RUNTIME_DIR carries the cross-component flag below, while CODE_DIR/runtime keeps
174
196
  # the two run-once install markers at the bottom of this file.
175
197
  mkdir -p "$RUNTIME_DIR"
@@ -5,7 +5,7 @@
5
5
  // here (see memFtsCheckSchema). No shared state beyond the `db` handle passed
6
6
  // in from the server-process module scope.
7
7
 
8
- import { checkFTSIntegrity, rebuildFTS } from '../schema.mjs';
8
+ import { checkFTSIntegrity, rebuildIndexes } from '../schema.mjs';
9
9
 
10
10
  /**
11
11
  * Handle `mem_fts_check({ action })`. Returns an MCP content wrapper.
@@ -24,8 +24,9 @@ export function handleMemFtsCheck(db, args) {
24
24
  : `FTS5 issues found:\n${result.details.join('\n')}`;
25
25
  return { content: [{ type: 'text', text }] };
26
26
  }
27
- // args.action === 'rebuild' (Zod enum enforces one of the two)
28
- const result = rebuildFTS(db);
27
+ // args.action === 'rebuild' (Zod enum enforces one of the two). The FTS5 indexes, then every
28
+ // other index, as `fts-check rebuild` does (D#558).
29
+ const result = rebuildIndexes(db);
29
30
  const summary =
30
31
  result.errors.length > 0
31
32
  ? `Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`
package/source-files.mjs CHANGED
@@ -283,6 +283,9 @@ export const SOURCE_FILES = [
283
283
  'lib/db-backup.mjs',
284
284
  'lib/db-unusable.mjs',
285
285
  'schema.mjs',
286
+ // Imports schema.mjs, copied before it. lib/db-unusable.mjs runs it as a child by path (not an
287
+ // import), and only install.mjs's doctor asks it to; install.mjs is copied after both.
288
+ 'lib/snapshot-probe.mjs',
286
289
  'cli/doctor.mjs',
287
290
  'hook-memory.mjs',
288
291
  'haiku-client.mjs',