open-memex 0.7.0-alpha.9 → 0.7.1-alpha.1

package/AGENTS.md

@@ -14,7 +14,9 @@ via `prepublishOnly` — Node refuses `--experimental-strip-types` for files und
 - **CLI** (`src/cli.ts`) and smoke tests run under **Node 22+** with `--experimental-strip-types`. SQLite here is `better-sqlite3` (native module).
 - **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same eleven memory tools to any MCP client (VS Code Copilot, Cursor, Claude Code). **stdout is the protocol channel — never log to stdout in `mcp.ts`; diagnostics go to stderr.**
 
-`src/store/db.ts` picks the backend at runtime by sniffing `globalThis.Bun`. Both backends share the same surface (`new Database(path)`, `.exec`, `.prepare().run/all/get`, `.close`). Any DB code you write must stay on that common subset — do not import `better-sqlite3` or `bun:sqlite` directly outside `db.ts`.
+`src/store/db.ts` picks the backend at runtime by sniffing `globalThis.Bun`. Both backends share the same surface (`new Database(path)`, `.exec`, `.prepare().run/all/get`, `.close`). Any DB code you write must stay on that common subset — do not import `better-sqlite3` or `bun:sqlite` directly outside `db.ts`. The Node driver is pinned to the `better-sqlite3` 13 N-API line (D72): the pre-13 `node::ObjectWrap` build aborts intermittently on Node 24.19+ when a prepared statement is finalized by GC.
+
+D74 — the Node floor is **22.14**, not 22.6. `better-sqlite3` 13 is compiled against Node-API 10, which Node gained in 22.14.0; below that floor `require()` succeeds and `new Database()` segfaults the process with no diagnostic (measured: Node 22.12.0 dies with `0xC0000005` on win32-x64, Node 22.23.3 / 24.20.0 are fine; upstream WiseLibs/better-sqlite3#1514). The gate lives in `src/runtime-floor.ts` (pure, unit-tested) and is enforced in `loadDatabase` (`src/store/db.ts`) so every entry point fails with an actionable message instead of a silent crash; `doctor` reports the floor plus a live driver probe run in a child process (a segfault cannot be caught in-process, so the probe must be spawned, and it must resolve the driver from this package's directory, not the caller's cwd). `engines.node` is `>=22.14.0`. Never lower it back to the `--experimental-strip-types` floor of 22.6 — that number is a different constraint and predates the driver bump.
 
 Tool logic is host-agnostic and lives in `src/tools/ops.ts` (plain functions + shared zod arg shapes + `TOOL_DESCRIPTIONS`). `src/tools/memory.ts` (opencode) and `src/mcp.ts` are thin adapters — when adding or changing a tool, change `ops.ts` once and both hosts pick it up.
 
@@ -33,7 +35,7 @@ npm run typecheck                                    # tsc --noEmit — the only
 npm run cli -- where | list | search "q" | add ... | forget <id> | reindex
 npm run cli -- <command> --help                          # per-command help (AI assistants discover flags this way)
 npm run cli -- sync-status                                  # last sync time/kind + outbox drafts + repo review states + uncommitted files
-npm run cli -- inventory [--format text|json] [--scope both]  # what is remembered, in the open (D68); personal-bearing output refused inside a git worktree without --allow-personal
+npm run cli -- inventory [--format text|json|html] [--scope both]  # what is remembered, in the open (D68); personal-bearing output refused inside a git worktree without --allow-personal
 npm run cli -- audit [--scope project|personal|both]            # memory health: near-dup pairs, stale actives, broken chains, personal-in-repo (read-only)
 npm run cli -- pull                                          # fetch + fast-forward only (explicit; diverged = clean failure, never force-merge)
 npm run cli -- push                                          # push current branch to remote (explicit only; open-memex never auto-pushes)
@@ -126,6 +128,7 @@ Layout: `memories/<scope_key>/<id>.md` (YAML frontmatter + body) + `index.db` (S
 
 - `personal` scope key is literal `"personal"` (v1 called this `user`; renamed in v2, design §19).
 - `project` scope key: `project__<sanitized-name>__<12-hex-sha256>`, seeded from normalized git origin URL, else lowercased cwd. See `src/scope.ts`. Same repo across machines → same key (intentional; enables future git-commit of memories).
+- The root a host adapter seeds on matters: OpenCode v1 reports the **filesystem root** as `worktree` for non-git folders, so the v1 adapter goes through `pickScopeRoot` (src/scope.ts) — `worktree` only when it is a real directory below the filesystem root, else the opened `directory` (D71). Seeding on a filesystem root merges every non-git folder on a drive into one `project__workspace__…` bucket.
 - `org`, `team`, `public` are reserved — the schema rejects writes. See `docs/SCOPES.md`.
 - The scope key **changes** when a repo gains/loses a git origin. `src/index.ts` logs a one-shot warning on load if it finds files under the legacy cwd-only key (`resolveCwdScope`). Use `cli scopes` to enumerate all scope dirs and `cli migrate --from <old>` to reconcile — see `src/store/migrate.ts`. No auto-migration; two unrelated repos at the same cwd would silently merge.
 - Read-only callers must use `memoriesDirPath` (in `src/paths.ts`), never `memoriesDirFor`. The latter `mkdir -p`s the directory as a side effect and will pollute storage with empty scope dirs.
@@ -154,21 +157,24 @@ AGENTS.md hygiene footer, the MCP handshake, and the tool descriptions.
 - Never hand-write `status: superseded` or half a chain. Use the `supersede` code path (`src/store/lifecycle.ts`): the old record keeps its file, flips to `superseded`, and both sides get `supersedes`/`superseded_by`. Only `active` memories can be superseded.
 - Superseding a memory that had entered review (proposed/approved/published/rejected) starts the replacement at `review_state: proposed` so `promote` can advance it (D64). Never reset it to `draft` — a draft in the repo dir is stranded (submit only moves outbox files).
 - `setStatus` refuses `retracted → active` (D64): retracted content must not silently return to recall. Save a new memory instead.
+- **Visibility surfaces share one contract (D70).** `memory_list`, `cli list` and `inventory` render the same `formatInventoryLine`; numbering is a running counter across every section of one listing (never per scope), and a cut list discloses how many entries it dropped. Any *correction* that touches an in-repo memory (`memory_forget`, `soft=true`, `forget --soft`) must say the change is local until committed and pushed — use `isInRepoMemoryFile` (`src/paths.ts`). Report output paths go through `inventoryWriteRefusal` (`src/cli.ts`), which fails closed on an unresolvable directory.
 - **Every memory-file write goes through `atomicWriteTextSync`** (markdown.ts; tmp + rename). The create path, supersede flips, review transitions, submit landings, migrate/v2migrate rewrites — no direct `fs.writeFileSync` on a memory file. A torn read mid-rewrite parses as a deletion and drops the memory from the index.
 - Chain integrity is self-healing: on read, a missing counterpart is auto-completed with a warning; a dangling pointer warns but is never fabricated. Don't "fix" chains by editing frontmatter directly — let the read path do it.
 - Frontmatter is `schema_version: 2`. The SQLite index schema is versioned separately and rebuilds automatically on version change — never hand-edit `index.db`.
 
 Keyword capture fires from `chat.message` on the user's message parts (`UserMessage`). Patterns live in `src/capture/keywords.ts` / config `keywordPatterns`; regex group 1 is the memory body. Scope routing: personal patterns (`cfg.keywordPersonalPatterns`) force the personal scope — the rule is 我 → personal (记住我/替我记/帮我记/我觉得/我喜欢/remember for me/help me remember), 我们 → current scope (我们认为/我们决定/帮我们记住); personal patterns run first and claim their line so a generic trigger can't double-fire (a rejected personal match keeps the claim — see D67).
 
+D73 — one user statement, one memory. The hook and the agent are two writers for one turn, and only the hook knows the sentence is stored. Both hooks therefore take the session id (`chat.message` on v1, `prompt` on v2), `captureFromText` records each capture in `PluginState.captures`, and the system/context hook pushes the hand-off note (`captureHandoff` → `formatHandoffBlock`, `src/capture/handoff.ts`) once per capture. `memory_add` additionally refuses a write overlapping a `source: keyword`/`user` memory created in the same scope within `TURN_ECHO_WINDOW_MS` (`findTurnEcho`, threshold `TURN_ECHO_THRESHOLD` = 0.28) and returns the stored id plus the supersede route. Keep the note, the refusal text, `TOOL_DESCRIPTIONS.memory_add`, the skill, and this paragraph saying the same thing — an agent that reads only one of them still has to behave. Never lower `TURN_ECHO_THRESHOLD` to catch more: the measured reason it is high is that an agent's gloss (0.211) and a genuinely new fact from the same sentence (0.214) are lexically indistinguishable.
+
 D67 rules for any new pattern: a trigger must be a **statement to the store**, not narration — 记得… / `remind me to…` are deliberately out, and the ambiguous forms require an explicit marker (`别忘了：…`, `don't forget: …`, `don't forget that …`). The 帮/替/我们 family takes the full verb phrase (`记` + optional `住|录`, never followed by a verb continuation) + optional `一下`; the separator boundary applies to the **bare** verb only, so `帮我记一下这个配置` captures while `帮我记得带伞` cannot produce mid-word garbage. Bodies under `MIN_CAPTURE_CHARS` (3) are rejected as fragments — never lower the floor silently; `scanKeywords` returns the drop so `capture --dry-run` and the debug log can report it.
 
 Context injection happens exactly once per session in `experimental.chat.system.transform`, guarded by an in-memory `Set<sessionID>` in `src/index.ts`. It is not persisted — restarting opencode re-injects on the next first turn.
 
 ## Design constraints — read the frozen design first
 
-`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D68; open questions tracked at the end of the doc). Per its §12:
+`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D73; open questions tracked at the end of the doc). Per its §12:
 AGENTS.md answers "how should AI work here"; the design doc answers "why is it
-built this way" (principles, iron rules, the append-only decision log, currently D1–D68). Before changing
+built this way" (principles, iron rules, the append-only decision log, currently D1–D73). Before changing
 architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
 schema, MCP tools, CLI contract), read the relevant design section — the decision
 log records what was already considered and rejected.

package/CHANGELOG.md

@@ -9,6 +9,46 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+## The Node floor is 22.14, because the driver says so (D74)
+
+- **Fixed: every command could die with no output on Node older than 22.14.** `better-sqlite3` 13 (the D72 N-API line) is compiled against Node-API 10, which Node only gained in **22.14.0**. Below that, `require()` succeeds and the first `new Database()` segfaults the process - no message, no stack, exit 139 on macOS/Linux and `0xC0000005` on Windows. Reproduced on win32-x64 with Node 22.12.0; Node 22.23.3 and 24.20.0 are fine, and Node 20 can never work with v13 (upstream [WiseLibs/better-sqlite3#1514](https://github.com/WiseLibs/better-sqlite3/issues/1514), open). open-memex now refuses to load the driver below the floor and says exactly what to do (upgrade Node, or pin `better-sqlite3@^12.11.1`) instead of dying.
+- **`engines.node` corrected to `>=22.14.0`.** It claimed `>=22.6`, which was the `--experimental-strip-types` floor - a different constraint that predates the driver bump, and wrong for the driver.
+- **`open-memex doctor` gained a `sqlite driver` check** that loads the driver and opens an in-memory database in a **child process** (a segfault cannot be caught in-process) and reports the exit code or signal. It resolves the driver from this package's own directory, so it works when `doctor` runs with cwd set to a user project.
+- Both READMEs gained a troubleshooting entry for the crash signature (`exit 139` / `0xC0000005` / "Segmentation fault"). No protocol, schema, or data change.
+
+## [0.7.0] - 2026-10-04
+
+## One thing you said is one memory (D73)
+
+Saying "remember ." used to save the same statement up to three times: the keyword hook stored your sentence verbatim with no agent in the loop, then the agent - which could see the chat but not the store - saved its own paraphrase beside it, and `memory_add`'s near-duplicate check scored the two too far apart (0.21-0.38 against a 0.80 bar) to notice. `open-memex audit` reported zero near-duplicates while three copies sat in the folder, and search returned all of them.
+
+- **The agent is told what was already stored.** When the keyword hook captures a sentence, the plugin records it against the session and the next system context carries a short note naming the stored memory. Do not save that text again in any rewording; save only what it does not contain, or `memory_supersede` it. Delivered once per capture, in memory only (nothing new is written to disk).
+- **`memory_add` refuses the echo anyway.** A write that overlaps a memory captured from your own words in the same scope within the last 10 minutes is refused with the stored id, as a deterministic backstop for when the note is not enough. The bar is deliberately high (0.28 token overlap) and never applies to the agent's own inferences - a distinct fact the same sentence carried still saves normally. A refusal is recoverable: supersede the stored one, or re-save with only the new information.
+- Reports nothing and changes no data: existing memories are not merged or rewritten, and the near-duplicate notice for ordinary agent saves is unchanged.
+
+## Node 24 CLI aborts: SQLite driver moves to the N-API line (D72)
+
+- **Fixed: CLI processes intermittently aborted on Node 24.19+.** `better-sqlite3` 11 could finalize a prepared statement from a garbage-collection callback after Node's environment was gone (`RemoveEnvironmentCleanupHook ... Assertion failed`), killing the process with `SIGABRT` and losing its output even though the memory work had already landed. The driver is now `better-sqlite3` 13 (the N-API rewrite; Node �22 unchanged) - same API surface, no protocol or data change. If you build from source on Node 24.19+, reinstall dependencies so the new driver is picked up.
+
+## Non-git folders shared one scope bucket (D71)
+
+- **Fixed: every non-git folder on a drive shared a single project scope.** OpenCode v1 reports the filesystem root (`C:\`, `/`) as the project `worktree` when the opened folder is not a git repo, and the plugin seeded its scope on that root — so unrelated folders like `C:\temp` and `C:\scratch` all wrote to one `project__workspace__…` bucket. The scope now seeds on the folder actually opened (`pickScopeRoot` in `src/scope.ts`); real repo worktrees are unchanged. Memories already saved under the shared bucket are not moved automatically: run `open-memex scopes` to spot it, then `open-memex migrate --from <old-key>`.
+
+## Visibility follow-ups: one number, one guard, one truth (D70)
+
+Review of the D68/D69 inventory surfaces — each was honest on its own, and they disagreed with each other:
+
+- `open-memex list` no longer truncates silently: it renders the same structured line the agent sees and says how many entries it left out (20 of 25 used to look like all 25).
+- Numbers are unique within one listing. `memory_list(scope: both)` and the text report restarted the counter per scope, so a single listing held two `#1`s and "delete #3" was a guess.
+- Hiding an in-repo memory now says what the delete path already said: the retraction is a local working-tree edit until you commit and push it — until then the team still sees the memory.
+- The report's worktree guard fails closed (it used to skip the check when the output directory did not exist yet), explains a missing directory instead of dying with a raw `ENOENT`, and is shared by all three formats instead of existing twice.
+- `inventory --format json` is now `open-memex-inventory/2`: the absolute `file` path is gone — that artifact is meant for an agent, and it carried your home directory with it.
+- An empty scope is reported as `(0)` rather than disappearing; only the HTML audit view loads the hidden rows themselves; the page enforces its "no network requests" promise with a `default-src 'none'` CSP.
+
+## Inventory HTML report (D68 follow-up)
+
+- **`open-memex inventory --format html`** renders the same data layer as the text/JSON formats into a single local page: current memories grouped by scope, outbox drafts in their own section, and the replaced/hidden history folded at the bottom with supersede-chain pointers. All content is escaped; the filter box is local show/hide only. Default output is `<data dir>/inventory.html`; the worktree refusal (`--allow-personal`) applies here too. Sections fold when the store grows past 50 current entries.
+
 ## Memory visibility: see it, hide it, delete it (D68)
 
 Group 3-C — the surface a user reads to learn what the store actually remembers:

package/README.md

@@ -53,7 +53,7 @@ depth once you're up and running.
 
 ## Quick start
 
-You need **Node.js ≥ 22.6** (check with `node -v`). Then:
+You need **Node.js ≥ 22.14** (check with `node -v`). Then:
 
 ```sh
 npm install -g open-memex
@@ -163,7 +163,9 @@ no one remembers to write down.
 
 ### Requirements
 
-- **Node.js ≥ 22.6** (`open-memex doctor` verifies this for you)
+- **Node.js ≥ 22.14** (`open-memex doctor` verifies this for you). The floor is
+  the SQLite driver's: `better-sqlite3` 13 is built against Node-API 10, which
+  Node gained in 22.14.0 — older Node segfaults on the first database open.
 
 ### Install the CLI
 
@@ -375,7 +377,11 @@ Three ways memories get in:
   `don't forget the wifi password` never fire (add a separator — `别忘了：…`,
   `don't forget: …` — or `that` to make it an instruction); and a captured body
   under 3 characters is rejected as a fragment rather than saved — `capture
-  --dry-run` says so instead of dropping it silently.
+  --dry-run` says so instead of dropping it silently. A trigger also owns its
+  own sentence: the plugin tells the agent what it just stored, and a
+  `memory_add` that re-saves the same words within the next few minutes is
+  refused with the stored id (D73) — one thing you said is one memory, not
+  three copies of it.
 - **The agent saves it**: in any editor, ask your agent to remember something
   (or it saves on its own when you state a fact worth keeping) — it calls
   `memory_add`. The routing above is a heuristic; you can always say "save this
@@ -651,9 +657,11 @@ open-memex forget <id> --soft      # hide instead of delete (retracted; one-way)
 
 open-memex inventory                        # everything remembered, as readable text
 open-memex inventory --format json          # the same data, for agents
+open-memex inventory --format html          # the same data as a local page (writes <data dir>/inventory.html)
 # Personal + current project, outbox drafts in their own section, hidden
 # history counted. Refuses to write a personal-bearing report inside a
 # git working tree unless you pass --allow-personal.
+# `list` numbers every entry in one listing and says how many it left out.
 ```
 
 Team review workflow (two homes, one per stage):
@@ -799,6 +807,18 @@ walks through the mental model end to end.
 
 ## Troubleshooting
 
+**Every command dies with no output, or the process crashes (`exit 139`,
+`0xC0000005`, "Segmentation fault").**
+Your Node is older than **22.14** and the bundled SQLite driver cannot load on
+it. `better-sqlite3` 13 is compiled against Node-API 10, which Node only gained
+in 22.14.0; on anything older `require()` succeeds and then the first database
+open segfaults the process with no diagnostic. open-memex now refuses to load
+the driver and says so, but anything already crashing was almost certainly this.
+Check with `node -v`, then either upgrade Node (`nvm install 22.14 && nvm use
+22.14`, or any current 22.x/24.x) or pin the driver down with `npm install
+better-sqlite3@^12.11.1`. `open-memex doctor` reports both the Node floor and a
+live driver probe. Known upstream: WiseLibs/better-sqlite3#1514.
+
 **`open-memex` is not recognized / command not found.**
 A global `npm install -g` puts the `open-memex` launcher in npm's global bin
 folder. If your terminal can't find it, that folder isn't on your `PATH`:

package/README.zh-CN.md

@@ -42,7 +42,7 @@
 
 ## 快速开始
 
-需要 **Node.js ≥ 22.6**（用 `node -v` 检查）。然后：
+需要 **Node.js ≥ 22.14**（用 `node -v` 检查）。然后：
 
 ```sh
 npm install -g open-memex
@@ -118,7 +118,7 @@ open-memex 用两种方式接编辑器：原生的 **opencode 插件**，和标
 
 ### 环境要求
 
-- **Node.js ≥ 22.6**（`open-memex doctor` 会替你核查）
+- **Node.js ≥ 22.14**（`open-memex doctor` 会替你核查）。这个下限来自 SQLite 驱动：`better-sqlite3` 13 是按 Node-API 10 编译的，而 Node 直到 22.14.0 才支持它——更老的 Node 在第一次打开数据库时会直接段错误崩溃。
 
 ### 安装 CLI
 
@@ -252,7 +252,7 @@ open-memex uninstall --yes
 
 三种存入方式：
 
-- **关键词触发**（仅 opencode 原生插件）：说 `remember …`、`note that …`、`don't forget: …`、`TIL …`、`save this …`——中文 `记住…` / `记一下…` / `记录一下…` / `别忘了：…`——这句话就被存下来，不需要任何工具调用。捕获默认进当前 **project**；`remember for me …`、`help me remember: …`、`记住我…`、`替我记…`、`帮我记…`、`我觉得…`、`我喜欢…` 这类"这是关于我"的信号会改为进 **personal**；`我们决定…`、`帮我们记住…` 等团队语境仍留在项目里。两条降噪规则（D67）：触发词必须是**对存储说的话**，所以叙述型的 `记得…` / `remind me to…` / `别忘了带伞` / `don't forget the wifi password` 一律不触发（加一个分隔符——`别忘了：…`、`don't forget: …`——或用 `that`，才算指令）；捕获内容不足 3 个字符按碎片丢弃，不会存下来——`capture --dry-run` 会明确说明，不再悄悄吞掉。
+- **关键词触发**（仅 opencode 原生插件）：说 `remember …`、`note that …`、`don't forget: …`、`TIL …`、`save this …`——中文 `记住…` / `记一下…` / `记录一下…` / `别忘了：…`——这句话就被存下来，不需要任何工具调用。捕获默认进当前 **project**；`remember for me …`、`help me remember: …`、`记住我…`、`替我记…`、`帮我记…`、`我觉得…`、`我喜欢…` 这类"这是关于我"的信号会改为进 **personal**；`我们决定…`、`帮我们记住…` 等团队语境仍留在项目里。两条降噪规则（D67）：触发词必须是**对存储说的话**，所以叙述型的 `记得…` / `remind me to…` / `别忘了带伞` / `don't forget the wifi password` 一律不触发（加一个分隔符——`别忘了：…`、`don't forget: …`——或用 `that`，才算指令）；捕获内容不足 3 个字符按碎片丢弃，不会存下来——`capture --dry-run` 会明确说明，不再悄悄吞掉。另外，一句触发捕获的话只归一条记忆：插件会把它刚存下的内容告诉助手，几分钟内再用 `memory_add` 重复存同样的字眼会被拒绝（并给出已存的 id，D73）——你说的一件事就是一条记忆，不是它的三个副本。
 - **助手主动保存**：在任何编辑器里，你让助手记住某件事（或者你陈述了一个值得记的事实、它自己判断该保存），它会调用 `memory_add`。上面的路由是启发式规则；你可以明说"存到我的个人记忆"，或用 CLI 加 `--scope` 明确指定。
 - **检查点提议**：一个任务收尾时，助手会提议 1–3 条从这轮工作里提炼的候选记忆——决定及其理由、约定、踩过的坑、走过又放弃的路——只有你点头的那几条才存。不会有任何东西在你不知情时被写下来。
 - **CLI**：`open-memex add "…"`，可选 `--scope` / `--tag` / `--type` / `--aliases`。
@@ -451,8 +451,10 @@ open-memex forget <id> --soft      # 隐藏而不是删除（retracted，单向
 
 open-memex inventory                        # 记住的一切，纯文本清单
 open-memex inventory --format json          # 同一份数据，JSON 格式给 agent 用
+open-memex inventory --format html          # 同一份数据的本地网页（写到 <数据目录>/inventory.html)
 # 个人 + 当前项目，outbox 草稿单独成节，被藏起的历史只计数。含个人内容的
 # 报告拒绝写进 git 工作树，除非显式 --allow-personal。
+# `list` 在同一份清单里连续编号，并说明自己少显示了哪些条目。
 ```
 
 团队评审工作流（两个家，一个阶段一个）：
@@ -559,6 +561,9 @@ npx -y open-memex mcp        # 无需安装
 
 ## 故障排查
 
+**每条命令都毫无输出地死掉，或进程直接崩溃（`exit 139`、`0xC0000005`、"Segmentation fault"）。**
+你的 Node 比 **22.14** 老，内置的 SQLite 驱动在它上面加载不了。`better-sqlite3` 13 是按 Node-API 10 编译的，而 Node 直到 22.14.0 才支持；在更老的版本上 `require()` 会成功，然后第一次打开数据库就把进程段错误掉，没有任何诊断信息。open-memex 现在会拒绝加载驱动并明确告诉你，但如果之前就是毫无输出一路崩溃，基本可以确定是这个原因。用 `node -v` 确认后，二选一：升级 Node（`nvm install 22.14 && nvm use 22.14`，或任意当前的 22.x/24.x），或者把驱动降回去：`npm install better-sqlite3@^12.11.1`。`open-memex doctor` 会同时报告 Node 下限和一次真实的驱动探测。上游已知问题：WiseLibs/better-sqlite3#1514。
+
 **`open-memex` 无法识别 / 命令找不到。**
 全局 `npm install -g` 把 `open-memex` 启动器放在 npm 的全局 bin 文件夹里。终端找不到命令，就是这个文件夹不在 PATH 上：
 

package/dist/.build-stamp

@@ -1 +1 @@
-3a590ae176c625e174a075a2d9068fe443d23c374f70fc7df76809ff10a63ad4
+e9cc36b1db649d899fdd7298be01622709e4f6d8d4e583764c294bd009cfd0e6

package/dist/capture/handoff.js

@@ -0,0 +1,59 @@
+/**
+ * Turn hand-off between keyword capture and the agent (D73).
+ *
+ * The keyword hook and the agent are two writers for one user turn. The hook
+ * stores the user's sentence verbatim, with no agent in the loop; the agent
+ * then sees only the chat transcript and cannot tell the sentence is already
+ * stored, so it saves its own paraphrase — the same statement lands two or
+ * three times (observed 2026-10-04: one `remember …` sentence → one
+ * `source: keyword` file plus two `source: tool` files).
+ *
+ * Two mechanisms, in this order:
+ *   (a) the hand-off note — this module's `formatHandoffBlock`, pushed into the
+ *       turn's system context so the agent knows what is already stored;
+ *   (b) the turn-echo guard — `TURN_ECHO_THRESHOLD` below, enforced in
+ *       `addMemory` (src/tools/ops.ts) over what the hook just wrote.
+ *
+ * Pure module: no db, no fs, no config, so the threshold behavior is testable
+ * in scripts/smoke-pure.ts.
+ */
+/**
+ * Overlap bar for refusing a re-save of a just-captured user statement.
+ *
+ * Deliberately high, and only ever applied to memories the *hook* wrote
+ * (`source: keyword` / `user`) inside `TURN_ECHO_WINDOW_MS`. Measured on the
+ * reported case and its near neighbours (token Jaccard, see
+ * `similarity` in src/store/lifecycle.ts): a wholesale re-save of the captured
+ * sentence scores 0.29–0.36, while a genuinely distinct fact the same
+ * sentence also contained scores 0.21 and below. Lexical overlap cannot
+ * separate an agent's gloss from a new fact — those two measured 0.211 and
+ * 0.214 — so the guard sits at the high-confidence end and everything under
+ * the bar is left to (a) and the agent's judgment. A refusal is always
+ * reported with the stored id, so the caller can supersede or rephrase.
+ */
+export const TURN_ECHO_THRESHOLD = 0.28;
+/** How long a hook capture counts as "this turn" (10 minutes). */
+export const TURN_ECHO_WINDOW_MS = 10 * 60 * 1000;
+export function isTurnEcho(score) {
+    return score >= TURN_ECHO_THRESHOLD;
+}
+/** Records still inside the window. */
+export function freshCaptures(records, now) {
+    return records.filter((r) => now - r.at <= TURN_ECHO_WINDOW_MS);
+}
+function preview(content) {
+    const one = content.replace(/\s+/g, " ").trim();
+    return one.length > 160 ? `${one.slice(0, 160)}…` : one;
+}
+/** The hand-off note (a). Empty string when there is nothing to hand off. */
+export function formatHandoffBlock(records) {
+    if (records.length === 0)
+        return "";
+    const lines = records.map((r) => `- id=${r.id} (${r.scopeKey}) — "${preview(r.content)}"`);
+    return [
+        "[open-memex] The user's own wording in this turn was ALREADY stored verbatim, before you saw it. It is not unsaved.",
+        ...lines,
+        "Do not call memory_add to save that text again in any rewording — one statement is already one memory, and a rewording only adds a second copy that retrieval will return alongside the first.",
+        "Save a memory only for information those lines do NOT contain, as its own self-contained statement. If your version is meant to replace one of them, call memory_supersede with that id instead of memory_add.",
+    ].join("\n");
+}

package/dist/cli.js

@@ -9,20 +9,34 @@ import { findDuplicates, supersede, setStatus } from "./store/lifecycle.js";
 import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory } from "./review.js";
 import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.js";
 import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.js";
-import { search, list, hitStateLabel } from "./retrieve/search.js";
+import { search, list, countList, hitStateLabel } from "./retrieve/search.js";
+import { formatInventoryLine, truncationNote } from "./retrieve/display.js";
 import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, normalizeAliases, } from "./store/markdown.js";
 import { loadConfig, configSource } from "./config.js";
-import { paths, projectRoot } from "./paths.js";
+import { paths, projectRoot, isInRepoMemoryFile } from "./paths.js";
 import { redact } from "./redact.js";
 import { resolveMcpCommand } from "./init.js";
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-/** True when `target` sits inside a git working tree (D68 guard). */
+/**
+ * True when `target` sits inside a git working tree (D68 guard).
+ *
+ * D70: resolve the nearest EXISTING ancestor first. `git -C` on a
+ * directory that does not exist throws, and the old code turned that
+ * into "not in a worktree" — a fail-open guard on the one path where
+ * personal memories would ride a commit.
+ */
 function isInsideWorkTree(target) {
     try {
-        const dir = path.dirname(path.resolve(target));
+        let dir = path.dirname(path.resolve(target));
+        while (!fs.existsSync(dir)) {
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
         const out = execFileSync("git", ["-C", dir, "rev-parse", "--is-inside-work-tree"], {
             stdio: ["ignore", "pipe", "ignore"],
             encoding: "utf8",
@@ -33,6 +47,24 @@ function isInsideWorkTree(target) {
         return false;
     }
 }
+/**
+ * D70: the one place that decides where a report may be written, for
+ * every `inventory` format. Returns an error message to print, or null
+ * when the path is safe. Kept single so the text/json/html paths cannot
+ * drift apart (they already had two copies, D68).
+ */
+function inventoryWriteRefusal(target, includesPersonal, allowPersonal) {
+    // Personal content must not ride a commit (the design's hardest rule).
+    if (includesPersonal && !allowPersonal && isInsideWorkTree(target)) {
+        return (`inventory: ${target} is inside a git working tree and this report includes personal memories. ` +
+            `Refusing to write it there. Pass --allow-personal if you really want that, or write outside the repo.`);
+    }
+    const parent = path.dirname(path.resolve(target));
+    if (!fs.existsSync(parent)) {
+        return `inventory: the directory ${parent} does not exist — create it first, or choose another --out path.`;
+    }
+    return null;
+}
 /** Per-command help, printed by `open-memex <command> --help`.
     AI assistants discover the CLI through --help, so every command needs one. */
 const COMMAND_HELP = {
@@ -42,17 +74,21 @@ Usage: open-memex where
 
 Example:
   open-memex where`,
-    list: `List memories in a scope, newest first.
+    list: `List memories in a scope, newest first, as a numbered inventory.
 
 Usage: open-memex list [--scope project|personal|both] [--type T] [--limit N] [--include active|all]
 
 Flags:
   --scope    project (default), personal, or both
   --type     filter by memory type
-  --limit    max results
+  --limit    max results (default 20, max 100)
   --include  active (default: what is currently remembered) or all (audit
              view: superseded versions, retracted and archived included)
 
+A cut list says how many entries it left out. Numbers are unique within one
+listing, so "the third one" names exactly one memory - but they are only
+valid for the listing you just ran.
+
 Examples:
   open-memex list
   open-memex list --scope personal --limit 20`,
@@ -104,7 +140,8 @@ Example:
   open-memex status 01ABC deprecated`,
     forget: `Delete a memory by id. With --soft, hide it instead: the memory
 is retracted (out of lists and search, file kept). Retraction is one-way —
-save the content as a new memory to bring it back.
+save the content as a new memory to bring it back. If the memory lives in
+the repo, either action is only local until you commit and push it.
 
 Usage: open-memex forget <id> [--soft]
 
@@ -160,16 +197,18 @@ Example:
     inventory: `Show everything remembered — personal + this project — in the
 open: what each memory says, where it came from, and whether it has reached
 the repo yet. Read-only; deleting stays a confirmed conversation with your
-agent. Formats: text (default, diffable) and json (for agents).
+agent. Formats: text (default, diffable), json (for agents), html (a local
+page for your browser; default writes <data dir>/inventory.html).
 
-Usage: open-memex inventory [--format text|json] [--scope project|personal|both] [--out <path>] [--allow-personal]
+Usage: open-memex inventory [--format text|json|html] [--scope project|personal|both] [--out <path>] [--allow-personal]
 
-Default scope: both. Without --out the report goes to stdout. A report that
+Default scope: both. Without --out, text/json go to stdout. A report that
 includes personal memories is refused inside a git working tree unless
 --allow-personal is passed — personal content must not ride a commit.
 
 Example:
-  open-memex inventory --format json --out ~/inventory.json`,
+  open-memex inventory --format json --out ~/inventory.json
+  open-memex inventory --format html`,
     pull: `Pull shared project memories from the git remote: fetch + fast-forward
 only. Never auto-merges — a diverged branch fails with a clear message and is
 left for you to resolve by hand. On success the local index re-syncs.
@@ -377,7 +416,7 @@ Usage:
   open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
   open-memex resolve [id-or-path]
   open-memex sync-status
-  open-memex inventory [--format text|json] [--scope project|personal|both] [--out <path>] [--allow-personal]
+  open-memex inventory [--format text|json|html] [--scope project|personal|both] [--out <path>] [--allow-personal]
   open-memex pull
   open-memex push
   open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
@@ -812,25 +851,38 @@ async function main() {
         const flags = parseFlags(rest);
         // D66: --scope both, on par with the memory_list tool — prints each
         // scope's newest under its own header.
-        const scopes = flags.scope === "both" ? [project, PERSONAL_SCOPE] : [resolveCliScope(flags, project)];
+        const scopes = flags.scope === "both" ? [PERSONAL_SCOPE, project] : [resolveCliScope(flags, project)];
+        const include = flags.include === "all" ? "all" : "active";
+        // D70: the CLI renders the SAME structured inventory the agent sees,
+        // numbering runs across the whole listing, and a cut list says how
+        // many entries it dropped — `open-memex list` is the surface a
+        // sceptical user runs first, so it may not look complete when it isn't.
+        let seq = 0;
         for (const s of scopes) {
             syncScope(s.key, "cli");
             const hits = list(s.key, {
                 type: flags.type,
                 limit: flags.limit ? Number(flags.limit) : undefined,
-                include: flags.include === "all" ? "all" : "active",
+                include,
             });
-            if (scopes.length > 1)
-                console.log(`## ${s.kind} (${s.key})`);
+            const total = countList(s.key, { type: flags.type, include });
+            if (scopes.length > 1) {
+                console.log(s.key === PERSONAL_SCOPE.key
+                    ? "## About you (personal — stays on this machine, applies everywhere)"
+                    : `## This project (${s.projectName || s.key})`);
+            }
             if (hits.length === 0) {
-                console.log(`(no memories in ${s.key})`);
+                console.log(scopes.length > 1
+                    ? "(nothing remembered in this scope yet)"
+                    : `(no memories in ${s.key})`);
                 continue;
             }
             for (const h of hits) {
-                const dep = h.status !== "active" ? ` [${h.status}]` : "";
-                const rev = hitStateLabel(h);
-                console.log(`[${h.type}]${dep}${rev} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+                console.log(formatInventoryLine(seq++, h, PERSONAL_SCOPE.key));
             }
+            const note = truncationNote(hits.length, total);
+            if (note)
+                console.log(note);
         }
         return;
     }
@@ -1002,10 +1054,16 @@ async function main() {
         // D68: --soft hides (retracts) instead of deleting — same action as
         // the memory_forget tool's soft flag. One-way (D64).
         if (rest.includes("--soft")) {
+            const target = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id);
             try {
                 const mf = setStatus(id, "retracted");
                 upsertFromFile(mf);
                 console.log(`hidden ${id} (retracted — out of lists and search; save it again as a new memory to bring it back)`);
+                // D70: same honesty as the hard delete — a retraction of an in-repo
+                // memory is a local working-tree edit until it is committed and pushed.
+                if (target && isInRepoMemoryFile(target.file_path)) {
+                    console.log(`note: that memory lives in the repo (.ai/open-memex/) — the retraction is only local until you commit and push it; until then the team still sees it.`);
+                }
             }
             catch (e) {
                 console.error(`hide failed: ${e.message}`);
@@ -1157,8 +1215,8 @@ async function main() {
         syncScope(PERSONAL_SCOPE.key, "cli");
         const flags = parseFlags(rest);
         const format = flags.format ?? "text";
-        if (format !== "text" && format !== "json") {
-            console.error(`inventory: unknown --format '${format}' (text|json; html arrives separately)`);
+        if (format !== "text" && format !== "json" && format !== "html") {
+            console.error(`inventory: unknown --format '${format}' (text|json|html)`);
             process.exit(2);
         }
         const scopeKeys = flags.scope === "personal"
@@ -1167,22 +1225,38 @@ async function main() {
                 ? [project.key]
                 : [PERSONAL_SCOPE.key, project.key];
         const outPath = flags["out"] ?? flags["output"];
-        // D68/3-C v2: the report contains personal content. Writing it into
-        // a git working tree would ride the next commit off this machine —
-        // refuse unless the user explicitly accepts that.
-        if (outPath &&
-            scopeKeys.includes(PERSONAL_SCOPE.key) &&
-            flags["allow-personal"] !== "true" &&
-            isInsideWorkTree(outPath)) {
-            console.error(`inventory: ${outPath} is inside a git working tree and this report includes personal memories. ` +
-                `Refusing to write it there. Pass --allow-personal if you really want that, or write outside the repo.`);
-            process.exit(2);
-        }
+        const includesPersonal = scopeKeys.includes(PERSONAL_SCOPE.key);
+        const allowPersonal = flags["allow-personal"] === "true";
         try {
             const { loadInventory, renderInventoryText, renderInventoryJson } = await import("./inventory.js");
+            if (format === "html") {
+                const { renderInventoryHtml, defaultHtmlOutPath } = await import("./inventory-html.js");
+                const target = outPath ?? defaultHtmlOutPath(paths().root);
+                // D70: one guard for every format (this path had its own copy).
+                const refusal = inventoryWriteRefusal(target, includesPersonal, allowPersonal);
+                if (refusal) {
+                    console.error(refusal);
+                    process.exit(2);
+                }
+                // D70: only the audit surface needs the hidden rows themselves;
+                // text/json report counts, so they must not pay to load them.
+                const data = loadInventory(scopeKeys, { hidden: "entries" });
+                fs.writeFileSync(target, renderInventoryHtml(data), "utf8");
+                console.log(`inventory: ${data.total} memories → ${target}`);
+                console.log(`open it in any browser; the report is read-only.`);
+                return;
+            }
             const data = loadInventory(scopeKeys);
             const rendered = format === "json" ? renderInventoryJson(data) : renderInventoryText(data);
             if (outPath) {
+                // D68/3-C v2: the report contains personal content. Writing it into
+                // a git working tree would ride the next commit off this machine —
+                // refuse unless the user explicitly accepts that.
+                const refusal = inventoryWriteRefusal(outPath, includesPersonal, allowPersonal);
+                if (refusal) {
+                    console.error(refusal);
+                    process.exit(2);
+                }
                 fs.writeFileSync(outPath, rendered, "utf8");
                 console.log(`inventory: ${data.total} memories → ${outPath}`);
             }