claude-mem-lite 6.27.0 → 6.29.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.27.0",
+      "version": "6.29.0",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "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)."

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.27.0",
+  "version": "6.29.0",
   "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).",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -88,7 +88,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 - **Observation relations** -- Bidirectional links between related observations based on file overlap
 - **User prompt capture** -- Records user prompts via UserPromptSubmit hook for intent tracking
 - **Read file tracking** -- Tracks files read during sessions for richer episode context
-- **Degraded fallback when the LLM fails** -- An episode the deterministic rules already rate notable (an error fixed, a config or schema file changed) is saved with inferred metadata instead of being discarded. A routine edit the rules rate as noise (`Modified a.js, b.js` with no lesson) is dropped — as it is when the model answers without a lesson — so a failing provider loses those episodes; `claude-mem-lite doctor` warns when the `claude` CLI it would call does not resolve
+- **Degraded fallback when the LLM fails** -- An episode that fixed an error is saved with inferred metadata (as an activity event) instead of being discarded, when a command that exited 0 printed the error (`npm test 2>&1 | tail`): a command Claude Code reports as failed does not enter the episode, so a fix that follows one counts as edit-only. An edit-only episode, config and schema changes included, is summarised from raw tool output, which the noise rules drop in most cases (`Modified a.js, b.js` with no lesson; only a short single-file summary survives) — as they do when the model answers without a lesson — so a failing provider loses those episodes unless `CLAUDE_MEM_KEEP_LOW_SIGNAL=1` is set; `claude-mem-lite doctor` warns when the `claude` CLI it would call does not resolve
 - **Two-tier dedup** -- Jaccard similarity (5-minute window) + MinHash signatures (7-day cross-session window) prevent duplicates
 - **Synonym expansion** -- Abbreviations like `K8s`, `DB`, `auth` automatically expand to full forms in FTS5 search (100+ pairs including CJK↔EN cross-language mappings)
 - **CJK synonym extraction** -- Unsegmented Chinese text is scanned for known vocabulary words (数据库→database, 搜索→search, etc.) enabling cross-language memory recall
@@ -237,6 +237,65 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
     repos/               # Shallow-cloned source repos
 ```
 
+## Upgrading to 6.29.0
+
+**Chinese text in lessons, facts, concepts and aliases becomes searchable, and the database opens
+after the update fill that in without holding up a hook.** No schema-version change: 6.28.1 still
+opens, searches and writes the database after this release has. Go back only after the fill
+finishes: rows it has not reached stay without the Latin identifiers glued to Chinese under 6.28.1.
+
+- **What it costs.** Each database open spends about 250 ms filling the index terms of existing
+  observations, newest first, each batch committed, until all are done. On a copy of the
+  maintainer's store (516 observations, most already filled by an earlier build of this pass)
+  the pass walked every row in one open of 48–49 ms. On a synthetic v6.27.0 store of 250,000
+  observations and 200,000 events (mostly CJK) the first open takes about 1 s (6.28.1: about 9 s,
+  and a 5 s hook opening it first was killed), and the fill then takes 105 opens of about 0.5 s;
+  an open after it takes 3 ms.
+- **A lesson a model writes onto one of your explicit saves starts with `🤖`**, and `get` says
+  "🤖 lesson auto-written". A lesson you write is never marked.
+- **Exit codes.** A flag that takes no value (`--force`, `--json`, `--confirm`, `--or`,
+  `--dry-run`, …) no longer swallows the next word: `delete --confirm 12` now deletes #12, and
+  `recent --json 5` prints JSON. `maintain`, `compress`, `optimize`, `delete`, `activity promote` /
+  `delete`, `import-jsonl`, `defer drop` and `fts-check rebuild`, which never read `--dry-run`,
+  refuse it with exit 1 on a run that would write, instead of running; `activity save`, `import-jsonl` and `restore` refuse a mistyped
+  `--project`; `uninstall` exits 3 when the MCP registration is left. CHANGELOG.md lists the
+  rest; a script that relied on the old behaviour needs a look.
+- **Also in this release:** the database waits of a hook that opens through `ensureDb` all end by
+  its deadline, the first open's migration, the prompt search and the Agent injection included;
+  the unattended re-enrich raises importance to 2 at most; three more background prompts send
+  stored rows to the model as data, and smart-compress and cluster merge act only on an explicit
+  yes. Details in CHANGELOG.md.
+
+## Upgrading to 6.28.1
+
+**After the update, events are re-indexed so Chinese text in them is searchable** (the Han ranges
+U+4E00–9FFF and U+3400–4DBF; kana, Hangul and the rarer Han extensions are not segmented). No
+schema-version change: 6.27.0 still opens, searches and writes the database after this release has,
+and an event it writes is filled the next time this release opens the database.
+
+- **What it costs.** The first open adds a column, rebuilds the events index and adds the Latin
+  identifiers glued to Chinese text to existing observations' index text. Existing events are then
+  filled newest first, about 250 ms per database open (checked after each row), each batch
+  committed, so a killed open keeps its progress; with nothing left an open takes 3–4 ms. On the
+  maintainer's store (6963 events) the first three opens took 295–327, 80–102 and 4 ms, and the file
+  grew from 14 to 15 MB; on a CJK-heavy synthetic store of 200,000 events the first open takes 964
+  ms, the fill 79 opens, and the file grows from 93 to 273 MB. Until an event is filled, a Chinese
+  query misses it as before.
+- **The MCP server waits out another writer's lock at startup** (up to 15 s of retries) instead of
+  exiting with "database is locked".
+- **Exit codes.** Some commands that exited 0 now exit 1, among them `save`, `update`, `defer add`
+  and `activity save` given a flag they do not take, `save` and `defer add` given a mistyped
+  project, `delete` given an id list with a malformed part (`1,abc`), `self-update` when it checked
+  nothing, and `import-jsonl` on lines none of which is a transcript event (an empty file still
+  exits 0); CHANGELOG.md lists the rest. `install` exits 3 when only the MCP registration failed. A
+  script that relied on exit 0 there needs a look.
+- **Also in this release:** `install` no longer empties the marketplace clone's `hooks/hooks.json`
+  (it puts back, with `git checkout`, one an earlier install emptied); four MCP tool texts say what
+  the tools do; a hook under a long write lock exits instead of being killed (UserPromptSubmit and
+  SessionStart with their context), and a lock that ends between 3.5 s and the 5 s kill, which
+  6.27.0 waited out, now drops the write the hook was waiting to make (UserPromptSubmit's prompt
+  row, for one). Details in CHANGELOG.md.
+
 ## Upgrading to 6.25.0
 
 **Every session gets the same first line on a file-recall block again.** No schema-version
@@ -824,7 +883,7 @@ Episodes are batched related operations (edits to the same file group) that get
 Episode buffer -> Flush to JSON -> claude -p --model haiku -> Structured observation -> SQLite
 ```
 
-Each observation includes type, title, narrative, concepts, facts, importance (1-3), and is automatically deduplicated via two tiers: Jaccard similarity (>70% within 5 minutes) and MinHash signatures (>80% within 7 days across sessions). If the LLM call fails, an episode the rules rate notable is saved with inferred metadata; a routine edit the rules rate as noise is dropped. Related observations are linked via `related_ids` based on FTS5 title similarity and file overlap.
+Each observation includes type, title, narrative, concepts, facts, importance (1-3), and is automatically deduplicated via two tiers: Jaccard similarity (>70% within 5 minutes) and MinHash signatures (>80% within 7 days across sessions). If the LLM call fails, an episode that fixed an error a successful command printed is saved with inferred metadata (a command reported as failed does not enter the episode); an edit-only episode (config and schema changes included) is usually dropped as noise. Related observations are linked via `related_ids` based on FTS5 title similarity and file overlap.
 
 ## Management Commands
 
@@ -1232,7 +1291,7 @@ what is already stored — only whether new work runs.
 |----------|-------------|---------|
 | `CLAUDE_MEM_SKIP_SUMMARY` | Skip the background LLM session summary at **both** of its spawn sites — `Stop`, and the SessionStart `/clear`-handoff path. Until v5.3.0 only the `Stop` one honoured it. | _(runs)_ |
 | `CLAUDE_MEM_LEGACY_STOP_UNLINK` | Restore the pre-v5.4.0 behaviour where `Stop` deletes the session file. Documented revert path for the session-lifecycle change, not a supported configuration: it re-mints a mem session per turn and makes the `/clear` handoff unreachable again. Only reach for it on a host that fires `Stop` once per session rather than once per turn. | _(file kept)_ |
-| `CLAUDE_MEM_SKIP_EPISODE_LLM` | Skip LLM extraction on episode flush — observations are still batched, just not summarized. | _(runs)_ |
+| `CLAUDE_MEM_SKIP_EPISODE_LLM` | Skip LLM extraction on episode flush. Only the rule-based pre-save runs, through the noise gate: an error-fixing episode with a low-signal title ("Error: …") is dropped, where a failed call would save it as an activity event; an edit-only one is usually dropped as noise. It also turns off SessionStart's hand-off of a killed episode worker's flush file to a new worker. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_SAVE_ENRICH` | Skip the background Haiku call that backfills `lesson_learned` / search aliases after a save. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_COMPRESS` | Skip auto-compression of old observations. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_MAINTAIN` | Skip the 24h auto-maintain pass (decay, purge, backup). | _(runs)_ |
@@ -1242,7 +1301,7 @@ what is already stored — only whether new work runs.
 | `CLAUDE_MEM_SKIP_UPDATE` | Skip the 24h update check against GitHub Releases, its session-start notice, and `self-update` / `install.mjs update` (unset it to update). A `repair` triggered by a missing module or dependency still runs. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_SIG_VERIFY` | Skip Ed25519 signature verification of a downloaded update. **Escape hatch — leaves updates unauthenticated.** | _(verifies)_ |
 | `CLAUDE_MEM_NO_LESSON_RETRY` | `1` disables the one-shot retry that re-asks for a missing `lesson_learned`. | _(retries)_ |
-| `CLAUDE_MEM_FLUSH_TIMEOUT` | Seconds the Stop hook waits for pending episode flushes. | `15` |
+| `CLAUDE_MEM_FLUSH_TIMEOUT` | Seconds the background session-summary worker waits for its pending episode flushes; it stops as soon as they clear. The default spans the episode worker's longest legitimate run. | `275` |
 | `CLAUDE_MEM_BACKUP_BUDGET_MB` | Disk budget for backup snapshots; the next maintain/save evicts oldest snapshots past the 7-day undo grace. | `256` |
 
 ### Experimental
@@ -1311,7 +1370,7 @@ The original called an LLM on every tool use with raw JSON inputs. claude-mem-li
 
 ### Does this work cross-project? Cross-machine?
 
-Project-scoped by default — each project has its own memory namespace. Single-machine only (SQLite, not networked). Use `mem_export` (JSON / JSONL) to back up or migrate between machines.
+Each memory belongs to the project it was saved in (an id like `parent--dir`). Search covers every project and weights the current project's rows ×2 in the ranking; name a project (`project` on the MCP tools, `--project` on the CLI) to search only that one. `mem_recent`, mem_search's `obs_type` fallback and the timeline without an anchor use the current project. Single-machine only (SQLite, not networked). Use `mem_export` (JSON / JSONL) to back up or migrate between machines.
 
 ### What about privacy? Does it call external APIs?
 

package/README.zh-CN.md

@@ -67,7 +67,7 @@
 - **观察关联** -- 基于文件重叠自动建立观察之间的双向链接
 - **用户提示捕获** -- 通过 UserPromptSubmit 钩子记录用户提示，追踪用户意图
 - **Read 文件追踪** -- 追踪会话中读取的文件，丰富 episode 上下文
-- **LLM 失败时的降级保存** -- 规则已判定为有价值的 episode（修掉了报错、改了配置或 schema 文件）用推断的元数据保存，而非丢弃；规则判为噪声的日常编辑（`Modified a.js, b.js` 且没有 lesson）会被丢掉——模型成功但没给 lesson 时也一样——所以 LLM 不可用期间这类 episode 会丢失。`claude-mem-lite doctor` 会在要调用的 `claude` CLI 不存在时告警
+- **LLM 失败时的降级保存** -- 修掉了报错的 episode 用推断的元数据保存（作为活动事件），而非丢弃，前提是报错由一条正常退出的命令打印出来（如 `npm test 2>&1 | tail`）：Claude Code 报告为失败的命令不进入 episode，紧随其后的修复按只有编辑的 episode 处理；只有编辑的 episode（包括改配置、改 schema）只能用原始工具输出拼成摘要，多数会被噪声规则丢掉（`Modified a.js, b.js` 且没有 lesson；只有很短的单文件摘要能留下）——模型成功但没给 lesson 时也一样——所以 LLM 不可用期间这类 episode 会丢失，除非设了 `CLAUDE_MEM_KEEP_LOW_SIGNAL=1`。`claude-mem-lite doctor` 会在要调用的 `claude` CLI 不存在时告警
 - **两级去重** -- Jaccard 相似度（5 分钟窗口）+ MinHash 签名（7 天跨会话窗口）双重防重
 - **同义词扩展** -- 缩写如 `K8s`、`DB`、`auth` 在 FTS5 搜索时自动扩展为全称（48+ 对）
 - **伪相关反馈（PRF）** -- 首轮结果作为种子扩展查询，提升召回率
@@ -199,6 +199,33 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
     repos/               # 浅克隆的源代码仓库
 ```
 
+## 升级到 6.29.0
+
+**lesson、facts、concepts 和 aliases 里的中文变得可以搜到；更新后的数据库打开会逐步补上这些索引，不会拖住钩子。** 没有 schema 版本变化：本版打开过的数据库，6.28.1 仍能打开、搜索和写入。要退回，请等补完之后再退：还没补到的行，在 6.28.1 下会缺少粘在中文上的英文标识符。
+
+- **代价。** 每次打开数据库约花 250 ms 为已有的 observation 补索引词，从最新的开始，每批单独提交，直到补完。维护者的库的副本（516 条 observation，大部分已由这一遍的早期版本补过）上，这一遍一次打开（48–49 ms）就走完。在 25 万条 observation、20 万条 event（大部分含中文）的合成 v6.27.0 库上，首次打开约 1 s（6.28.1 约要 9 s，先打开它的 5 s 钩子 3 次都被杀掉），之后补完需要 105 次打开、每次约 0.5 s；补完后的一次打开 3 ms。
+- **模型写在你显式保存的记录上的 lesson 以 `🤖` 开头**，`get` 的标题行注明 "🤖 lesson auto-written"。你自己写的 lesson 不会被标记。
+- **退出码。** 不带值的 flag（`--force`、`--json`、`--confirm`、`--or`、`--dry-run` 等）不再吞掉后面的词：`delete --confirm 12` 现在会删除 #12，`recent --json 5` 输出 JSON。`maintain`、`compress`、`optimize`、`delete`、`activity promote` / `delete`、`import-jsonl`、`defer drop` 和 `fts-check rebuild` 从来不读 `--dry-run`，在会写入的运行中遇到它会以 exit 1 拒绝，而不是照常执行；`activity save`、`import-jsonl` 和 `restore` 拒绝拼错的 `--project`；MCP 注册没删掉时 `uninstall` 以 exit 3 结束。其余见 CHANGELOG.md；依赖旧行为的脚本需要检查一下。
+- **本版还有：** 经 `ensureDb` 打开数据库的钩子，所有数据库等待都在截止时间前结束，包括首次打开的迁移、提示词搜索和 Agent 注入；无人值守的 re-enrich 最多把 importance 提到 2；又有三个后台提示把存储的行作为数据交给模型；smart-compress 和 cluster merge 只在明确同意时才动手。详见 CHANGELOG.md。
+
+## 升级到 6.28.1
+
+**更新后会给事件重建索引，事件里的中文从此能搜到**（切分 U+4E00–9FFF 和 U+3400–4DBF 两段汉字；假名、韩文和更少见的汉字扩展区不切分）。
+没有 schema 版本变更：本版本打开过的数据库，6.27.0 仍能打开、搜索和写入；它写入的事件，本版本下一次打开数据库时会补上。
+
+- **代价。** 第一次打开时加一列、重建事件索引，并给已有 observation 的索引文本补上粘在中文里的英文标识符。已有事件随后从新到旧补齐，
+  每次打开数据库约做 250 ms（每切分一行检查一次），每一批单独提交，所以被杀的那次打开也会保留进度；补完之后每次打开 3–4 ms。
+  在维护者的库上（6963 条事件）前三次打开分别为 295–327、80–102、4 ms，文件从 14 MB 变为 15 MB；在中文较多的 20 万条事件合成库上，
+  第一次打开 964 ms，补齐需 79 次打开，文件从 93 MB 变为 273 MB。补齐之前，用中文查询仍搜不到这条事件，和以前一样。
+- **MCP server 启动时遇到别的进程的写锁会等待**（最多重试 15 s），不再报 "database is locked" 退出。
+- **退出码。** 一些原来退出 0 的命令现在退出 1，其中包括：`save`、`update`、`defer add`、`activity save` 遇到不接受的 flag，
+  `save`、`defer add` 遇到拼错的项目名，`delete` 的 id 列表里有格式错误的部分（`1,abc`），`self-update` 什么都没检查成，`import-jsonl`
+  的输入里没有一行是 transcript 事件（空文件仍退出 0）；其余见 CHANGELOG.md。其余步骤都成功、只有 MCP 注册失败时，`install` 退出 3。
+  依赖这些地方退出 0 的脚本需要检查。
+- **本版本还有：** `install` 不再清空 marketplace clone 里的 `hooks/hooks.json`（早先被清空的，会用 `git checkout` 恢复）；
+  四处 MCP 工具文本改成了工具实际做的事；钩子遇到长时间的写锁时会自行退出，不再被杀（UserPromptSubmit 和 SessionStart 仍带着上下文），
+  代价是：锁在 3.5 s 之后、5 s 被杀之前结束时，6.27.0 会等到并完成的那次写入（例如 UserPromptSubmit 的 prompt 行），现在会丢掉。详见 CHANGELOG.md。
+
 ## 升级到 6.25.0
 
 **文件召回块的第一行，所有会话重新用同一种写法。** 没有 schema 版本变更：本版本打开过的数据库，6.24.0 仍能打开。
@@ -660,7 +687,7 @@ Episode 是一批相关操作（对同一组文件的编辑），由后台 LLM w
 Episode 缓冲区 -> 刷新为 JSON -> claude -p --model haiku -> 结构化观察 -> SQLite
 ```
 
-每条观察包含类型、标题、叙述、概念、事实和重要度（1-3），并通过两级机制自动去重：Jaccard 相似度（5 分钟内 >70%）和 MinHash 签名（7 天跨会话 >80%）。LLM 调用失败时，规则判定有价值的 episode 用推断的元数据保存降级记录，规则判为噪声的日常编辑会被丢掉。相关观察通过 FTS5 标题相似度和文件重叠自动建立 `related_ids` 链接。
+每条观察包含类型、标题、叙述、概念、事实和重要度（1-3），并通过两级机制自动去重：Jaccard 相似度（5 分钟内 >70%）和 MinHash 签名（7 天跨会话 >80%）。LLM 调用失败时，修掉了报错（报错由正常退出的命令打印；报告为失败的命令不进入 episode）的 episode 用推断的元数据保存降级记录；只有编辑的 episode（包括改配置、改 schema）多数会作为噪声丢掉。相关观察通过 FTS5 标题相似度和文件重叠自动建立 `related_ids` 链接。
 
 ## 管理命令
 

package/adopt-cli.mjs

@@ -23,6 +23,7 @@ import {
   writeFileSync,
   unlinkSync,
   readFileSync,
+  realpathSync,
 } from 'fs';
 import { claudeConfigDir, claudeStatePath } from './lib/data-paths.mjs';
 import { join, isAbsolute, relative, dirname } from 'path';
@@ -50,6 +51,7 @@ import {
   detailDocPath,
   addAgentsImports,
   holdsOnlyOwnLines,
+  straySentinelLines,
 } from './claudemd.mjs';
 import { PLUGIN_SLUG, CURRENT_SENTINEL_VERSION, buildClaudeMdBlock, getDetailDoc } from './adopt-content.mjs';
 import {
@@ -100,8 +102,23 @@ function log(msg) {
   console.log(msg);
 }
 
-function detectCwd() {
-  return process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd();
+// $PWD keeps a symlinked project's logical spelling (the one Claude Code's CLAUDE_PROJECT_DIR
+// uses), but only when it names the directory this process is in: a program that spawns `adopt`
+// with `cwd` set leaves its OWN PWD in the env, and adopt wrote into the caller's directory
+// instead of the one it ran in (E2E 2026-10-16).
+/** @public install.mjs reads it through a dynamic-import namespace (`adopt.detectCwd?.()`). */
+export function detectCwd() {
+  if (process.env.CLAUDE_PROJECT_DIR) return process.env.CLAUDE_PROJECT_DIR;
+  const cwd = process.cwd();
+  const pwd = process.env.PWD;
+  if (pwd) {
+    try {
+      if (realpathSync(pwd) === realpathSync(cwd)) return pwd;
+    } catch {
+      /* PWD names nothing that exists: use the real cwd */
+    }
+  }
+  return cwd;
 }
 
 function projectsRoot() {
@@ -182,6 +199,18 @@ function adoptOne(cwd, { force, dryRun }) {
   const block = buildClaudeMdBlock();
   const doc = getDetailDoc();
   const version = CURRENT_SENTINEL_VERSION;
+  // A damaged sentinel line pairs with no block, so writing would add a second block beside it
+  // (E2E 2026-10-16 round 2, B14). Which lines are the block is the user's call: refuse first.
+  const stray = straySentinelLines(claudeMdPath(cwd), PLUGIN_SLUG);
+  if (stray.length > 0) {
+    log(`[adopt] ${cwd} → refused, nothing was written:`);
+    for (const s of stray) log(`  ${claudeMdPath(cwd)} line ${s.line}: ${s.text}`);
+    log(
+      `  ${stray.length === 1 ? 'This sentinel line pairs' : 'These sentinel lines pair'} with no well-formed block, so adopt would add a second one. Make the block's first line exactly \`<!-- ${PLUGIN_SLUG}:begin ${version} -->\` and its last \`<!-- ${PLUGIN_SLUG}:end -->\`, each on a line of its own, or delete the marker lines and the text between them; then run adopt again.`,
+    );
+    process.exitCode = 1;
+    return { action: 'refused' };
+  }
   // Claude Code stops reading AGENTS.md once a CLAUDE.md exists: the one written here imports
   // the AGENTS.md files beside it and names the ones it cannot import.
   const agents = agentsMdForNewClaudeMd(cwd, PLUGIN_SLUG);
@@ -347,6 +376,11 @@ export function silentAutoAdopt({ cwd, markerDir, markerKey }) {
     const hasBlock = blockIn(cwd);
     if (!hasBlock) {
       if (markerDir && markerKey) writeMarker(markerDir, markerKey);
+      // A damaged sentinel line (`… --> (team note)`) leaves the block's text in CLAUDE.md, which
+      // the host loads, while the block no longer parses: a copy written to CLAUDE.local.md or
+      // injected here was a second one. Neither; `adopt` names the line and the fix (D#369 B14).
+      const stray = straySentinelLines(claudeMdPath(cwd), PLUGIN_SLUG);
+      if (stray.length > 0) return { ok: true, action: 'damaged', reason: 'stray-sentinel', lines: stray };
       const root = localSteeringRoot(cwd);
       if (root) {
         // A session started below the top-level (pre-tag claims review P2-3, P1-4): the host

package/claudemd.mjs

@@ -104,6 +104,35 @@ function orphanSentinelCount(raw, slug) {
   });
   return total - paired;
 }
+/**
+ * The lines of `p` that open with a sentinel of this slug and that no well-formed block
+ * accounts for: a begin marker with text after it, a lost version tag, a missing partner. The
+ * block pattern cannot see them, so a write that trusts it adds a second block beside them
+ * (E2E 2026-10-16 round 2, B14). A sentinel inside a sentence is prose, not a marker (pre-ship
+ * review P2-3), and is not listed.
+ * @param {string} p absolute path of the instructions file
+ * @param {string} slug
+ * @returns {{line: number, text: string}[]} 1-based; empty for a missing or unreadable file
+ */
+export function straySentinelLines(p, slug) {
+  let raw;
+  try {
+    raw = readFileSync(p, 'utf8');
+  } catch {
+    return [];
+  }
+  const spans = [...raw.matchAll(blockRegexG(slug))].map((m) => [m.index, m.index + m[0].length]);
+  const opensLine = new RegExp(`^\\s*<!-- ${escapeRe(slug)}:(?:begin|end)\\b`);
+  const stray = [];
+  let offset = 0;
+  raw.split('\n').forEach((text, i) => {
+    const at = offset + text.indexOf('<!--');
+    if (opensLine.test(text) && !spans.some(([s, e]) => at >= s && at < e))
+      stray.push({ line: i + 1, text: text.trim() });
+    offset += text.length + 1;
+  });
+  return stray;
+}
 function blockRegex(slug) {
   return new RegExp(blockBody(escapeRe(slug)));
 }
@@ -331,8 +360,8 @@ export function needsRefresh(cwd, { slug, version, block, doc }) {
 /**
  * Write (insert-or-replace) the managed block in CLAUDE.md and the detail doc
  * under .claude/, plus a state sidecar. Idempotent on the user-visible files:
- * re-running with identical inputs leaves CLAUDE.md and the detail doc byte-for-
- * byte unchanged (only the state sidecar's writtenAt updates).
+ * re-running with identical inputs leaves CLAUDE.md, the detail doc and the state
+ * sidecar byte-for-byte unchanged.
  *
  * CLAUDE.md is created if absent. Only our slug-scoped region is rewritten;
  * everything else in the file is preserved verbatim.
@@ -351,12 +380,20 @@ export function writeManaged(cwd, { slug, version, block, doc }) {
   const existingDoc = existsSync(dp) ? readFileSync(dp, 'utf8') : null;
   if (existingDoc !== docContent) atomicWrite(dp, docContent);
 
-  writeState(cwd, slug, {
-    version,
-    blockHash: sha256(block),
-    docHash: sha256(doc),
-    writtenAt: new Date().toISOString(),
-  });
+  // Only when what the sidecar records changed: it is committed alongside the block in a team
+  // repo, and a fresh writtenAt on every re-run of `adopt` left a diff each time (E2E
+  // 2026-10-16). Nothing reads writtenAt.
+  const blockHash = sha256(block);
+  const docHash = sha256(doc);
+  let prev = null;
+  try {
+    prev = JSON.parse(readFileSync(stateFilePath(cwd, slug), 'utf8'));
+  } catch {
+    /* absent or unreadable: write it */
+  }
+  if (!(prev?.version === version && prev?.blockHash === blockHash && prev?.docHash === docHash)) {
+    writeState(cwd, slug, { version, blockHash, docHash, writtenAt: new Date().toISOString() });
+  }
   return { action };
 }
 

package/cli/activity.mjs

@@ -9,16 +9,25 @@
 // events_fts via triggers.
 
 import { inferProject } from '../utils.mjs';
-import { resolveProject } from '../project-utils.mjs';
+import { resolveProject, checkWriteProject } from '../project-utils.mjs';
 import { resolveCliProject as cliProject } from '../lib/cli-project.mjs';
 import { parseArgs, out, fail, rejectBareStringFlags } from './common.mjs';
 import { parseIntFlag, isNumericToken } from '../lib/cli-flags.mjs';
+import { snapshotDb } from '../lib/db-backup.mjs';
+import { isBlankText } from '../lib/blank-text.mjs';
 
 function formatActivityResults(rows) {
   if (!rows || rows.length === 0) return '(no events)';
   return rows.map((r) => `#${r.id} [${r.event_type}] ${r.title}`).join('\n');
 }
 
+/** An event id as typed: N, #N or E#N (the form search and get print), else null. */
+function eventIdOf(token) {
+  const m = /^(?:[Ee]#?|#)?(\d+)$/.exec(String(token).trim());
+  const n = m ? Number(m[1]) : NaN;
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
 export async function cmdActivity(db, args) {
   const sub = args[0];
   if (!sub) {
@@ -33,9 +42,11 @@ export async function cmdActivity(db, args) {
   // `save` CREATES a row, so it keeps plain inferProject(): the DB-aware fallback is a read
   // affordance, and applying it to a write absorbs a not-yet-born subproject's first event
   // into the enclosing repo (pre-tag review, reproduced). Every other subcommand reads or
-  // operates on rows that already exist, where falling back is what finds them.
+  // operates on rows that already exist, where falling back is what finds them. A named
+  // project is resolved for `save` the way `save` and `defer add` resolve theirs: exact
+  // matching only, then checkWriteProject below.
   const project = flags.project
-    ? resolveProject(db, flags.project)
+    ? resolveProject(db, flags.project, sub === 'save' ? { mode: 'write' } : undefined)
     : sub === 'save'
       ? inferProject()
       : cliProject(db);
@@ -50,7 +61,7 @@ export async function cmdActivity(db, args) {
       return;
     }
     const title = flags.title || positional.join(' ').trim();
-    if (!title) {
+    if (isBlankText(title)) {
       fail('[mem] activity save: --title or positional text required');
       return;
     }
@@ -77,6 +88,13 @@ export async function cmdActivity(db, args) {
       fail(`[mem] Invalid importance "${flags.importance}". Must be 1, 2, or 3.`);
       return;
     }
+    // A near miss of an existing project is refused, a new name is noted: the check `save` and
+    // `defer add` make (pre-tag review 2026-10-16 P3-4). stdout stays the JSON line.
+    const projectCheck = flags.project ? checkWriteProject(db, project) : { ok: true, note: '' };
+    if (!projectCheck.ok) {
+      fail(`[mem] ${projectCheck.message}`);
+      return;
+    }
     const id = saveEvent(db, {
       project,
       event_type: type,
@@ -86,6 +104,7 @@ export async function cmdActivity(db, args) {
       file_paths,
     });
     out(JSON.stringify({ ok: true, id }));
+    if (projectCheck.note) process.stderr.write(`[mem] Saved event E#${id}${projectCheck.note}\n`);
     return;
   }
 
@@ -126,9 +145,11 @@ export async function cmdActivity(db, args) {
   }
 
   if (sub === 'show') {
-    const id = positional.length > 0 ? parseInt(positional[0], 10) : NaN;
-    if (!Number.isFinite(id)) {
-      fail('[mem] activity show: numeric id required');
+    const id = positional.length > 0 ? eventIdOf(positional[0]) : null;
+    if (id === null) {
+      fail(
+        `[mem] activity show: an event id is required (N, #N or E#N)${positional[0] ? `, got "${positional[0]}"` : ''}`,
+      );
       return;
     }
     const row = getEvent(db, id);
@@ -153,12 +174,20 @@ export async function cmdActivity(db, args) {
       fail('[mem] Usage: claude-mem-lite activity delete <id1,id2,...> [--confirm]');
       return;
     }
-    const ids = idStr
+    const tokens = idStr
       .split(',')
       .map((s) => s.trim())
-      .filter(Boolean)
-      .map((s) => parseInt(s, 10))
-      .filter((n) => Number.isInteger(n) && n > 0);
+      .filter(Boolean);
+    // Every token must be an id, or nothing is deleted: `2x` used to parseInt to 2 and delete
+    // a row the caller never named (E2E 2026-10-16).
+    const bad = tokens.filter((t) => eventIdOf(t) === null);
+    if (bad.length > 0) {
+      fail(
+        `[mem] activity delete: not an event id: ${bad.join(', ')} (use N, #N or E#N) — nothing was deleted`,
+      );
+      return;
+    }
+    const ids = [...new Set(tokens.map(eventIdOf))];
     if (ids.length === 0) {
       fail('[mem] activity delete: no valid IDs provided (must be positive integers)');
       return;
@@ -188,16 +217,23 @@ export async function cmdActivity(db, args) {
       return;
     }
 
+    // A pre-image first, as deleteObservations takes for observations (E2E 2026-10-16 round 2:
+    // this hard delete had none). Best-effort; outside the transaction (VACUUM INTO).
+    snapshotDb(db, { tag: 'pre-delete' });
     // The opt-in search telemetry keeps a title per returned result; an explicit delete drops the
     // deleted events' titles, as lib/delete-core.mjs does for observations (D#245 N6).
-    const result = db.transaction(() => {
-      if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'search_results'").get()) {
-        db.prepare(
-          `UPDATE search_results SET snapshot_label = NULL WHERE source = 'event' AND result_id IN (${placeholders})`,
-        ).run(...ids);
-      }
-      return db.prepare(`DELETE FROM events WHERE id IN (${placeholders})`).run(...ids);
-    })();
+    const result = db
+      .transaction(() => {
+        if (
+          db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'search_results'").get()
+        ) {
+          db.prepare(
+            `UPDATE search_results SET snapshot_label = NULL WHERE source = 'event' AND result_id IN (${placeholders})`,
+          ).run(...ids);
+        }
+        return db.prepare(`DELETE FROM events WHERE id IN (${placeholders})`).run(...ids);
+      })
+      .immediate(); // IMMEDIATE: it starts with a read (E2E 2026-10-16 round 3; see delete-core)
     out(`[mem] Deleted ${result.changes} event(s).`);
     return;
   }
@@ -206,7 +242,9 @@ export async function cmdActivity(db, args) {
     // P2(b): promote insight-bearing events (body present, importance>=N) into
     // searchable observations. Preview by default; --execute applies. One-time
     // backfill — the source events are marked promoted (idempotent re-runs).
-    const minImp = flags['min-importance'] !== undefined ? parseInt(flags['min-importance'], 10) : 2;
+    // Whole digits only: a bare parseInt read `2x` as 2.
+    const rawMin = flags['min-importance'];
+    const minImp = rawMin === undefined ? 2 : /^\d+$/.test(String(rawMin)) ? Number(rawMin) : NaN;
     if (isNaN(minImp) || minImp < 1 || minImp > 3) {
       fail('[mem] activity promote: --min-importance must be 1, 2, or 3.');
       return;

package/cli/common.mjs

@@ -8,16 +8,58 @@
 // relative-time formatting — every command imports from here so the CLI stays
 // consistent.
 
+import { editDistance } from '../lib/edit-distance.mjs';
 import { neutralizeContextDelimiters, neutralizeSkillDelimiters } from '../format-utils.mjs';
 
 // ─── Argument Parsing ────────────────────────────────────────────────────────
 
+/**
+ * Flags that take no value: every reader tests them against true / 'true' (or for presence in
+ * argv), so the word after one is a positional. parseArgs read every `--key next` as key=value,
+ * and `save --type bugfix --title X --force 'text'` parsed `force: 'text'` and no content (the
+ * usage error) while the text-first spelling saved; the swallowed word did not even turn the
+ * flag on, so `search --or redis` lost its query and its --or (D#385, same in v6.27.0). An
+ * explicit `--json true` / `--force false` still parses as before.
+ * tests/cli-boolean-flag-parsing.test.mjs derives the boolean readers from the sources and
+ * fails on one missing here.
+ */
+export const BOOLEAN_CLI_FLAGS = new Set([
+  'all',
+  'apply',
+  'benchmark',
+  'confirm',
+  'deep',
+  'disable',
+  'dry-run',
+  'enable',
+  'execute',
+  'force',
+  'help',
+  'include-compressed',
+  'include-noise',
+  'json',
+  'metrics',
+  'no-deep',
+  'or',
+  'print-project',
+  'quality',
+  'rerank',
+  'retry',
+  'run',
+  'run-all',
+  'search-telemetry',
+  'session-audit',
+  'sidechain',
+  'status',
+  'verbose',
+]);
+
 /**
  * Parse argv-style array into { positional, flags }.
  * `--key value` → flags.key = value; `--flag` (no value) → flags.key = true.
  * `-h` → flags.help = true.
  */
-export function parseArgs(argv) {
+export function parseArgs(argv, { track = true } = {}) {
   const positional = [];
   const flags = {};
   // Canonical flag name for a raw `--key`. Two normalizations, both aimed at the
@@ -53,6 +95,13 @@ export function parseArgs(argv) {
   let i = 0;
   while (i < argv.length) {
     const arg = argv[i];
+    // POSIX end of options: everything after a bare `--` is positional, so text that starts
+    // with `--` can be saved (`save -- "--dry-run is ignored by deploy.sh"`). It parsed as an
+    // empty-named flag and the text after it as a flag of its own (E2E 2026-10-16).
+    if (arg === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
     if (arg.startsWith('--')) {
       const body = arg.slice(2);
       // `--key=value` (GNU long-option form). Split on the FIRST '=' so values that
@@ -68,7 +117,11 @@ export function parseArgs(argv) {
       }
       const key = body;
       const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith('--') && (!next.startsWith('-') || /^-\d/.test(next))) {
+      // A flag that takes no value leaves the next word alone, except an explicit true/false.
+      const takes = BOOLEAN_CLI_FLAGS.has(canonicalFlag(key))
+        ? next === 'true' || next === 'false'
+        : next !== undefined && !next.startsWith('--') && (!next.startsWith('-') || /^-\d/.test(next));
+      if (takes) {
         setFlag(key, next);
         i += 2;
       } else {
@@ -83,7 +136,9 @@ export function parseArgs(argv) {
       i++;
     }
   }
-  return { positional, flags: trackFlagReads(flags) };
+  // `track: false` for the dispatcher's own peeks (typo hints, the unknown-project note): a read
+  // there is not the command consuming the flag, and recording it hid the inert-flag notice.
+  return { positional, flags: track ? trackFlagReads(flags) : flags };
 }
 
 // ─── Inert selection flags ───────────────────────────────────────────────────
@@ -269,7 +324,11 @@ export function fail(text) {
 export function rejectBareStringFlags(flags, keys) {
   for (const key of keys) {
     if (flags[key] === true) {
-      fail(`[mem] --${key} requires a value (received a bare flag with no value).`);
+      // A value that itself starts with `-` parses as a flag of its own and lands here; the
+      // `=` form is the way to pass one, and nothing said so (E2E 2026-10-16 round 2).
+      fail(
+        `[mem] --${key} requires a value (received a bare flag with no value). A value that starts with - is written --${key}="…".`,
+      );
       return true;
     }
   }
@@ -436,26 +495,6 @@ export const COMMAND_SCOPED_FLAGS = new Map([
   ['undo', 'verify-apply'],
 ]);
 
-/** Levenshtein distance, early-exit past `max` (cheap enough for a handful of flags). */
-function editDistance(a, b, max = 2) {
-  const m = a.length,
-    n = b.length;
-  if (Math.abs(m - n) > max) return max + 1;
-  let prev = Array.from({ length: n + 1 }, (_, j) => j);
-  for (let i = 1; i <= m; i++) {
-    const cur = [i];
-    let rowMin = i;
-    for (let j = 1; j <= n; j++) {
-      const d = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] !== b[j - 1] ? 1 : 0));
-      cur[j] = d;
-      if (d < rowMin) rowMin = d;
-    }
-    if (rowMin > max) return max + 1; // whole row already past budget → give up
-    prev = cur;
-  }
-  return prev[n];
-}
-
 /**
  * Detect likely-typo flags: names NOT in KNOWN_CLI_FLAGS but within edit distance 2 of
  * a known flag. parseArgs silently drops unknown flags, so `save --improtance 3` used to

package/cli/fts-check.mjs

@@ -32,6 +32,12 @@ export function cmdFtsCheck(db, args) {
     const result = checkFTSIntegrity(db);
     if (result.healthy) {
       out('[mem] FTS5 indexes are healthy — all integrity checks passed.');
+    } else if (result.busy) {
+      // Not a finding: "issues found" invited a rebuild of a healthy store, a long write that
+      // blocks the live hooks (E2E 2026-10-16 round 2). Exit 1 all the same: nothing was checked.
+      out('[mem] FTS5 check not run — the database is in use by another process. This is not');
+      out('  corruption; do not rebuild. Run the check again when the store is idle.');
+      process.exitCode = 1;
     } else {
       out(`[mem] FTS5 issues found:`);
       for (const d of result.details) out(`  ${d}`);