open-memex 0.7.0-alpha.8 → 0.7.0

package/AGENTS.md

@@ -14,7 +14,7 @@ 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.
 
 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,6 +33,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|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)
@@ -125,6 +126,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.
@@ -153,21 +155,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 D1–D64 settled; 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–D67). 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]
 
+## 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:
+
+- **`memory_list` is now a numbered inventory.** Lines are structured (`[type] id=… created=… source=…`), keep the raw provenance, and every listing states its true total — a truncated list says how many entries it is not showing instead of quietly looking complete. New input `include: "active" | "all"` (default `active`): **behavior change** — superseded versions, retracted and archived memories no longer appear unless you pass `include=all` (the audit view). The CLI gains the matching `list --include` flag.
+- **`open-memex inventory`** renders the same data as readable text (default) or JSON (`--format json`, format `open-memex-inventory/1`) — personal plus the current project, outbox drafts in their own section, hidden history counted rather than silently dropped. A report containing personal memories refuses to be written inside a git working tree without `--allow-personal`.
+- **Hide instead of delete:** `memory_forget` gains `soft=true` (CLI: `forget --soft`) — the memory is retracted: out of lists and search, file kept. Still one-way (D64): bringing the fact back means saving it again.
+- **Guidance kept in one voice:** the tool descriptions, the MCP session-start instructions, SKILL.md and the `distill-agents` AGENTS.md snippet all teach the same flow — answer "what do you remember?" conversationally from the inventory, re-list before acting on a number, read an entry back before deleting it.
+
 ## Keyword capture: what counts as a trigger (D67)
 
 The D66 review left two questions open and introduced one regression. Ruled, not deferred:

package/README.md

@@ -375,7 +375,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
@@ -416,9 +420,9 @@ they only matter once you share memories through Git.
 |---|---|
 | ● `memory_add`       | Save a fact, preference, decision, note |
 | ● `memory_search`    | Keyword search (BM25) across project + personal memories |
-| ● `memory_list`      | List memories in a scope (`project`, `personal`, or `both`), newest first |
+| ● `memory_list`      | List memories in a scope (`project`, `personal`, or `both`) as a numbered inventory; `include=all` is the audit view |
 | ● `memory_supersede` | Replace a memory with a newer version (keeps a supersede chain) |
-| ● `memory_forget`    | Delete a memory by id |
+| ● `memory_forget`    | Delete a memory by id (`soft=true` hides it instead — retracted, one-way) |
 | `memory_status`      | Show the sync queue: outbox drafts, repo review states, uncommitted files |
 | `memory_submit`      | Move named drafts into the repo memory dir (local branch + commit) |
 | `memory_propose`     | Copy personal memories into the project scope as review candidates |
@@ -643,9 +647,19 @@ open-memex search "auth flow"
 open-memex search "auth flow" --explain   # show FTS expression, scores, lifecycle-hidden counts
 open-memex list --scope project
 open-memex list --scope both       # each scope's newest under its own header
+open-memex list --include all      # audit view: superseded versions, retracted, archived
 open-memex supersede <id> "Updated content"
 open-memex status <id> deprecated
 open-memex forget <id>
+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):

package/README.zh-CN.md

@@ -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`。
@@ -275,9 +275,9 @@ MCP 服务器暴露十一个工具；opencode 原生插件暴露其中五个核
 |---|---|
 | ● `memory_add`       | 保存一条事实、偏好、决策、笔记 |
 | ● `memory_search`    | 关键词搜索（BM25），横跨项目 + 个人记忆 |
-| ● `memory_list`      | 列出某个作用域（`project`、`personal` 或 `both`）的记忆，最新在前 |
+| ● `memory_list`      | 以编号清单列出某个作用域（`project`、`personal` 或 `both`）的记忆；`include=all` 是审计视图 |
 | ● `memory_supersede` | 用新版本替换一条记忆（保留 supersede 链） |
-| ● `memory_forget`    | 按 id 删除一条记忆 |
+| ● `memory_forget`    | 按 id 删除一条记忆（`soft=true` 改为隐藏——retracted，单向） |
 | `memory_status`      | 显示同步队列：outbox 草稿、仓库评审状态、未提交文件 |
 | `memory_submit`      | 把指定的草稿移进仓库记忆目录（本地分支 + 提交） |
 | `memory_propose`     | 把个人记忆复制到项目作用域，作为评审候选 |
@@ -443,9 +443,18 @@ open-memex search "auth flow"
 open-memex search "auth flow" --explain   # 显示 FTS 表达式、分数、被生命周期藏掉的计数
 open-memex list --scope project
 open-memex list --scope both       # 两个作用域各自最新的，各带一个标题
+open-memex list --include all      # 审计视图：被替换的版本、已撤回、已归档
 open-memex supersede <id> "Updated content"
 open-memex status <id> deprecated
 open-memex forget <id>
+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` 在同一份清单里连续编号，并说明自己少显示了哪些条目。
 ```
 
 团队评审工作流（两个家，一个阶段一个）：

package/dist/.build-stamp

@@ -1 +1 @@
-f4cf4e253bbf0f3254ec439b1344af50e88cc4fd068b04be73cdc20ee770e819
+c84b05d4afadebb4346f31a95ca00c4075a700269fc5019453799d0eeeb8b09e

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,15 +9,62 @@ 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).
+ *
+ * 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 {
+        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",
+        });
+        return out.trim() === "true";
+    }
+    catch {
+        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 = {
@@ -27,14 +74,20 @@ 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]
+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
+  --scope    project (default), personal, or both
+  --type     filter by memory type
+  --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
@@ -85,12 +138,16 @@ Retraction is one-way: a retracted memory cannot be set back to active
 
 Example:
   open-memex status 01ABC deprecated`,
-    forget: `Delete a memory by id.
+    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. If the memory lives in
+the repo, either action is only local until you commit and push it.
 
-Usage: open-memex forget <id>
+Usage: open-memex forget <id> [--soft]
 
 Example:
-  open-memex forget 01ABC`,
+  open-memex forget 01ABC
+  open-memex forget 01ABC --soft`,
     propose: `Copy personal memories into the project outbox as review drafts.
 The personal originals stay put. Nothing enters git at this step.
 
@@ -137,6 +194,21 @@ Usage: open-memex sync-status
 
 Example:
   open-memex sync-status`,
+    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), json (for agents), html (a local
+page for your browser; default writes <data dir>/inventory.html).
+
+Usage: open-memex inventory [--format text|json|html] [--scope project|personal|both] [--out <path>] [--allow-personal]
+
+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 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.
@@ -334,16 +406,17 @@ function usage(exitCode = 1) {
 
 Usage:
   open-memex where
-  open-memex list [--scope project|personal] [--type T] [--limit N]
+  open-memex list [--scope project|personal|both] [--type T] [--limit N] [--include active|all]
   open-memex search "query" [--scope project|personal|both] [--type T] [--limit N] [--explain]
   open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
   open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
   open-memex status <id> active|deprecated|retracted|archived
-  open-memex forget <id>
+  open-memex forget <id> [--soft]
   open-memex propose <id...> --to project [--local-approve]
   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|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>]
@@ -778,24 +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,
             });
-            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 === "deprecated" ? " [deprecated]" : "";
-                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;
     }
@@ -964,6 +1051,26 @@ async function main() {
         const id = rest[0];
         if (!id)
             usage();
+        // 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}`);
+                process.exit(1);
+            }
+            return;
+        }
         const row = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id);
         if (!row) {
             console.error("not found");
@@ -1101,6 +1208,68 @@ async function main() {
         }
         return;
     }
+    if (cmd === "inventory") {
+        // D68: refresh both scopes first so the report matches the markdown
+        // on disk. Default scope: personal + this project.
+        syncScope(project.key, "cli");
+        syncScope(PERSONAL_SCOPE.key, "cli");
+        const flags = parseFlags(rest);
+        const format = flags.format ?? "text";
+        if (format !== "text" && format !== "json" && format !== "html") {
+            console.error(`inventory: unknown --format '${format}' (text|json|html)`);
+            process.exit(2);
+        }
+        const scopeKeys = flags.scope === "personal"
+            ? [PERSONAL_SCOPE.key]
+            : flags.scope === "project"
+                ? [project.key]
+                : [PERSONAL_SCOPE.key, project.key];
+        const outPath = flags["out"] ?? flags["output"];
+        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}`);
+            }
+            else {
+                process.stdout.write(rendered);
+            }
+        }
+        catch (e) {
+            console.error(`inventory failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
     if (cmd === "sync-status") {
         syncScope(project.key, "cli");
         syncScope(PERSONAL_SCOPE.key, "cli");

package/dist/distill-agents.js

@@ -62,7 +62,10 @@ export function distillAgentsMarkdown(opts) {
     // inferred captures source: "inference"; this footer omitted it, so
     // opencode agents saved distilled conclusions as if the user had
     // stated them ("tool"). Keep the rubric one voice across surfaces.
-    `- Mark captures you infer (rather than the user stating) with`, `  \`source: "inference"\` — provenance matters more than polish.`);
+    `- Mark captures you infer (rather than the user stating) with`, `  \`source: "inference"\` — provenance matters more than polish.`, 
+    // D68: same voice for the visibility surface — opencode agents reading
+    // this footer never see the MCP handshake either.
+    `- When the user asks what you remember, list it conversationally`, `  (\`memory_list\` with scope both, or \`open-memex inventory\`) — plain`, `  words, not raw ids. Before deleting an entry they point at, read it`, `  back in full and confirm; deletion is permanent. Offer hiding`, `  (\`memory_forget\` soft / \`forget --soft\`) when they hesitate.`);
     lines.push(``);
     return lines.join("\n");
 }

package/dist/index.js

@@ -1,4 +1,5 @@
-import { PLUGIN_ID, bootstrapPlugin, captureFromText, injectOnce, } from "./plugin-core.js";
+import { PLUGIN_ID, bootstrapPlugin, captureFromText, captureHandoff, injectOnce, } from "./plugin-core.js";
+import { pickScopeRoot } from "./scope.js";
 import { makeTools } from "./tools/memory.js";
 import { v2Plugin } from "./opencode-v2.js";
 /**
@@ -12,23 +13,30 @@ import { v2Plugin } from "./opencode-v2.js";
  * type-only (D58), and v2's decode is structural.
  */
 const server = async ({ worktree, directory }) => {
-    const roots = worktree || directory || process.cwd();
-    const state = bootstrapPlugin(roots);
+    // v1's `worktree` is the filesystem root for non-git folders — never seed a
+    // scope on it (D71). `pickScopeRoot` falls back to the opened `directory`.
+    const state = bootstrapPlugin(pickScopeRoot(worktree, directory));
     const tools = makeTools(() => state.scope, state.cfg);
     return {
         tool: tools,
-        async "chat.message"(_input, output) {
+        async "chat.message"(input, output) {
             const parts = (output.parts ?? []);
             const text = parts
                 .map((p) => (p?.type === "text" ? p.text ?? "" : ""))
                 .filter(Boolean)
                 .join("\n");
-            captureFromText(text, state);
+            captureFromText(text, state, input.sessionID ?? "");
         },
         async "experimental.chat.system.transform"(input, output) {
-            injectOnce(input.sessionID ?? "", state, (block) => {
+            const sessionID = input.sessionID ?? "";
+            injectOnce(sessionID, state, (block) => {
                 output.system.push(block);
             });
+            // D73: runs on every request, so the note lands on the very turn whose
+            // message the hook just captured. Delivered once per capture.
+            const handoff = captureHandoff(sessionID, state);
+            if (handoff)
+                output.system.push(handoff);
         },
     };
 };