open-memex 0.7.0-alpha.1 → 0.7.0-alpha.13

package/AGENTS.md

@@ -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)
@@ -102,7 +103,7 @@ The published `open-memex` bin points at `dist/cli.js` (compiled at publish time
 From a source checkout, `npm run cli` / `npm run mcp` still run `src/` directly
 with type-stripping — no build step needed for development.
 
-There is **no `npm test`** and no CI. Verification loop is: `npm run typecheck` + `smoke-pure.ts` + (if touching sqlite) `npm run cli -- reindex` against a scratch `MY_O_MEMORY_HOME`.
+There is **no `npm test`** and no CI. Verification loop is: `npm run typecheck` + `smoke-pure.ts` + (if touching sqlite) `npm run cli -- reindex` against a scratch `OPEN_MEMEX_HOME`.
 
 To load the plugin in opencode locally, `~/.config/opencode/opencode.jsonc` must have:
 ```
@@ -115,7 +116,7 @@ Restart opencode after any change — the plugin is not hot-reloaded.
 Storage root:
 - Windows: `%APPDATA%\open-memex\`
 - Linux/macOS: `$XDG_DATA_HOME/open-memex/` (fallback `~/.local/share/open-memex/`)
-- Override with `MY_O_MEMORY_HOME` (use this for tests to avoid clobbering real data).
+- Override with `OPEN_MEMEX_HOME` (use this for tests to avoid clobbering real data). The pre-rename `MY_O_MEMORY_HOME` is still honored as a fallback (D62).
 
 Layout: `memories/<scope_key>/<id>.md` (YAML frontmatter + body) + `index.db` (SQLite FTS5).
 
@@ -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.
@@ -136,23 +138,39 @@ Every write path (tool, keyword hook, CLI `add`) must:
 2. If `hadSecret` → the matched secret is **masked in place** (first 4 characters kept, the rest replaced with `x`) and the write proceeds; never save the unmasked original. `<private>…</private>` spans are stripped to `[REDACTED]` instead (design D14).
 3. Check `findDuplicates` (design §3.4): identical content is idempotent (return existing id); near-duplicates (similarity ≥ 0.8) warn but save — suggest `supersede` when the new content replaces the old.
 4. `writeMemoryFile` first, then `readMemoryFile` + `upsertFromFile` to keep FTS in sync.
+5. Deletion reports honestly (D63): only ENOENT counts as "deleted"; any other unlink failure keeps the index row and returns failure — the file is the source of truth and would otherwise resurrect the memory on next sync.
+
+Capture-time aliases (D61): `memory_add`/`supersede` may carry up to 4
+`aliases` (alternate phrasings) into frontmatter; they index in their own FTS
+column. Only when `cfg.captureAliases` is on (init asks once, default on) —
+when off, passed aliases are dropped. Always pass them through
+`normalizeAliases`; the keyword-capture path (no agent in the loop) never
+invents aliases. Checkpoint-proposal guidance (propose, never auto-draft) is
+copy, not mechanism: keep the rubric wording in sync across the skill, the
+AGENTS.md hygiene footer, the MCP handshake, and the tool descriptions.
 
 ## Lifecycle invariants (design §3.3)
 
 - Statuses: `active → superseded | deprecated | retracted | archived`. Retrieval excludes `retracted`/`archived`, ranks `active` above `deprecated`.
 - 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), 我们 → current scope (我们认为/我们决定/帮我们记住); personal patterns run first and claim their line so a generic trigger can't double-fire.
+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).
+
+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 (zero open questions). Per its §12:
+`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D71; 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, D1–D49 decision log). Before changing
+built this way" (principles, iron rules, the append-only decision log, currently D1–D71). 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,94 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+## 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:
+
+- **Fixed a regression:** D66's separator boundary was one notch too strict — it also demanded a separator after a *complete* verb phrase, so `帮我记一下这个配置`, `帮我记住这个配置`, `替我记一下我住在杭州` and `帮我们记一下这个约定` stopped matching. The boundary now guards the bare verb only, so `帮我记得…` still can't produce mid-word garbage.
+- **The ≥3-character body floor stays, but is no longer silent.** `记住：这个` is a fragment, not a memory, so it isn't captured — but `open-memex capture --dry-run` now says why, and `logLevel: debug` logs it. A rejected *personal* match also keeps its line, so `记住我：OK` can no longer fall through to the generic 记住 and be saved as `我：OK`.
+- **Narration is not a trigger.** `记得…`, `remind me to…` and friends stay out on purpose (a false trigger writes unreviewed memory; a missed one costs a sentence). The ambiguous forms already in the list now need an explicit marker: `别忘了：…`, `don't forget: …` and `don't forget that …` capture; bare `别忘了带伞` and `don't forget the wifi password` do not. The `note` family is unchanged.
+- **Test tooling:** the stale-`dist/` guard is now a content fingerprint (`scripts/build-stamp.mjs`) instead of mtimes, which a branch switch could defeat; the agent-facing `memory_status` cap (20 per section + a "full list" pointer) is pinned again after D66's test replaced that coverage.
+
+## Review follow-ups (D66)
+
+Fixes from the follow-up review of the D63–D65 stack:
+
+- Keyword patterns: `请帮我记住…` works (the D65 pattern had missed its `请` prefix), `帮我记录一下：…` / `替我记录一下：…` capture cleanly instead of saving mid-word garbage, `帮我记得…` no longer fires, and `help me remember: …` routes personal like `remember for me`.
+- `open-memex sync-status` (the CLI) shows the full list again — the 20-per-section cap now applies only to agent tool results, whose "… and N more" line points at the CLI. `open-memex list --scope both` matches the `memory_list` tool.
+- `open-memex status --help` documents that retraction is one-way.
+- The full test suite is Windows-safe now (file:// probe imports, USERPROFILE-aware uninstall test) and refuses to run against a stale `dist/` build.
+
+## Keyword capture gaps (D65)
+
+The most natural phrasings were the ones that fell through:
+
+- `帮我记住…` / `帮我记一下…` now capture (personal scope, same 我-rule as 替我记； `帮我们记住…` still routes project).
+- A leading `请` no longer defeats capture: `请记住我…`, `请记住（个人）…`, and `请记住：…` all work.
+- English `remember to …` no longer leaves a stray "to" at the front of the captured body.
+
+Patterns are code defaults, so these apply automatically on upgrade — unless you hand-customized `keywordPatterns` / `keywordPersonalPatterns` in your config, in which case your lists win and you can port the additions by hand.
+
+## P1 fixes: stale answers and stranded files (D64)
+
+Second batch from the whole-project review — the index, the files, and the guidance can no longer quietly disagree:
+
+- The opencode plugin now re-syncs the index before every tool call (previously only at startup): memories added via the CLI or another client are visible right away instead of after a restart.
+- Superseding a published memory re-enters review as `proposed` instead of a stranded `draft` no command could advance; `promote` can move it forward again.
+- All memory-file rewrites are atomic (tmp + rename), not just creates.
+- A retracted memory can't be flipped back to `active` via status changes — save a new memory if the content is valid again.
+- Proposed copies of personal memories are `visibility: internal` (was: `private`, which export silently excluded from team bundles).
+- `uninstall` finds the real global opencode config (`.jsonc` included), and `doctor` checks all eleven MCP tools plus stranded v1 (`user`-scope) memories.
+- `memory_status` output is capped per section; `memory_list` accepts `scope: both`; `forget` notes when the deleted file was in the repo; `where` prints the config path.
+
+## Correctness fixes from the whole-project review (D63)
+
+Six silent-wrong-answer bugs found by an external three-lens review, each fixed with a regression test:
+
+- `init --client visualstudio` no longer wipes other servers from an existing `.mcp.json` (the parsed config was dropped instead of merged).
+- `memory_forget` / `forget` tell the truth: when the memory file can't be deleted (locked, in use), they report failure and keep the index entry, instead of claiming success while the file — the source of truth — brings the memory back on next sync.
+- Config parsing is string-aware: a redact pattern like `src/**/secrets` is no longer eaten as a block comment and silently disabled. `doctor` and the config loader now share one parser.
+- `loadConfig` enforces the `memoryDir` invariant on hand-edited configs; an escaping value (`../../shared`) falls back to the default with a warning instead of writing project memories outside the repo.
+- `migrate` re-scopes as well as re-keys: migrated files get the destination's `scope`/`visibility`, so personal→project migrations are submittable and project→personal memories stay private in exports. Conflict resolution compares parsed timestamps, not RFC-3339 strings.
+- `import` rejects bundle entries whose paths escape the bundle (`../` or symlinks) instead of reading arbitrary local files into the store; rejected paths are printed.
+
+## Environment variable names (D62)
+
+- The override variables now answer to `OPEN_MEMEX_HOME` (storage root) and `OPEN_MEMEX_CONFIG` (config path). The pre-rename `MY_O_MEMORY_HOME` / `MY_O_MEMORY_CONFIG` names keep working as fallbacks — nothing to migrate, the data root itself does not move. `doctor` notes when the storage root came from the legacy variable.
+
+## Proactive capture: checkpoint proposals and aliases (D61)
+
+- At task checkpoints the agent now proposes instead of waiting to be asked: when a task wraps up, it offers 1–3 short candidate memories distilled from the session (decisions and their reasons, conventions, gotchas, approaches tried and abandoned) and saves only the ones you approve — approved inferences are marked `source: "inference"`. One memorability rubric and one search discipline (break the question into concepts, try several phrasings, check both scopes) are written into every guidance surface — the bundled skill, the AGENTS.md memory-hygiene footer, the MCP handshake, and the tool descriptions — so behavior is consistent across editors. Nothing is auto-drafted in the background; that posture waits on memory visibility.
+- Memories can carry up to 4 **aliases** — alternate phrasings, synonyms, other-language equivalents — stored in the memory file and indexed with it, so a differently-worded question still matches ("vacation days" finds the holiday policy; "节假日" too). `init` asks once (default on); `open-memex config set captureAliases false` turns it off. Existing memory files are untouched — the index rebuilds itself on first use.
+
 ## One plugin, both opencode generations (D60)
 
 - The native plugin now loads on **opencode 2** as well as opencode 1. `open-memex init --client opencode --global` writes both config spellings — the v1 `"plugin"` file entry and the v2 `"plugins"` directory entry — and each host reads its own. Previously an opencode 2 host silently skipped the plugin (a file entry is not a directory it can load), leaving no tools and no explanation.

package/README.md

@@ -222,9 +222,10 @@ open-memex init --client vscode
 ```
 
 Writes the MCP server entry; reload the window afterwards and confirm the
-`open-memex` server is started in Copilot Chat's MCP panel. By default the
-server entry goes to VS Code's *user-level* config (works in every project);
-`init` can also write a project-level `.vscode/mcp.json` if you prefer.
+`open-memex` server is started in Copilot Chat's MCP panel. By default this
+writes a project-level `.vscode/mcp.json` (an interactive run asks which
+level you want); add `--global` for VS Code's *user-level* config instead —
+one setup that works in every project.
 
 **Cursor:**
 
@@ -232,8 +233,8 @@ server entry goes to VS Code's *user-level* config (works in every project);
 open-memex init --client cursor
 ```
 
-Same shape as VS Code: user-level MCP config by default, project-level
-`.cursor/mcp.json` on request, plus Copilot-style instructions.
+Same shape as VS Code: project-level `.cursor/mcp.json` by default,
+user-level MCP config with `--global`, plus Copilot-style instructions.
 
 **opencode** (native plugin — recommended):
 
@@ -363,17 +364,35 @@ snippet to paste instead.
 Three ways memories get in:
 
 - **Keyword triggers** (opencode native plugin only): say `remember …`,
-  `note that …`, `don't forget …`, `TIL …`, `save this …` — or in Chinese
-  `记住…` / `记一下` / `记录一下` / `别忘了…` — and the sentence is captured
+  `note that …`, `don't forget: …`, `TIL …`, `save this …` — or in Chinese
+  `记住…` / `记一下…` / `记录一下…` / `别忘了：…` — and the sentence is captured
   without any tool call. Captures land in the current **project** by default;
-  phrases that signal "this is about me" — `remember for me …`, `记住我…`,
-  `替我记…`, `我觉得…`, `我喜欢…` — go to **personal** instead, and
+  phrases that signal "this is about me" — `remember for me …`, `help me remember: …`,
+  `记住我…`, `替我记…`, `帮我记…`, `我觉得…`, `我喜欢…` — go to **personal** instead, and
   team-context phrases (`我们决定…`, `帮我们记住…`) stay in project.
+  Two rules keep the noise down (D67): a trigger must be a *statement to the
+  store*, so the narration forms `记得…` / `remind me to…` / `别忘了带伞` /
+  `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.
 - **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
   to my personal memory" or use the CLI with `--scope` to be explicit.
-- **The CLI**: `open-memex add "…"` with optional `--scope` / `--tags` / `--type`.
+- **Checkpoint proposals**: when a task wraps up, the agent proposes 1–3 short
+  candidate memories distilled from the session — decisions and their reasons,
+  conventions, gotchas, approaches tried and abandoned — and saves only the
+  ones you approve. Nothing is written silently: no draft is created behind
+  your back.
+- **The CLI**: `open-memex add "…"` with optional `--scope` / `--tag` / `--type`
+  / `--aliases`.
+
+**Aliases.** Each saved memory can carry up to 4 alternate phrasings
+(synonyms, another language's equivalent) that are indexed with it, so a
+question worded differently still finds the memory — "vacation days" finds the
+holiday policy. `init` asks once whether to enable this (default on); turn it
+off any time with `open-memex config set captureAliases false`.
 
 **Redaction.** Wrap anything sensitive in `<private>…</private>` and it is
 stripped before saving. Recognized secrets (API keys, tokens, high-entropy
@@ -397,9 +416,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, 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 |
@@ -566,8 +585,9 @@ branches and PRs like any other file.
 
 Settings live in `~/.config/opencode/open-memex.jsonc` — the `opencode` in the
 path is historical; this one file is shared by every client. Override the config
-path with `MY_O_MEMORY_CONFIG` and the storage root with `MY_O_MEMORY_HOME`
-(legacy environment names from before the rename, still honored).
+path with `OPEN_MEMEX_CONFIG` and the storage root with `OPEN_MEMEX_HOME`
+(the pre-rename `MY_O_MEMORY_CONFIG` / `MY_O_MEMORY_HOME` names are still
+honored as fallbacks).
 
 Defaults:
 
@@ -592,7 +612,7 @@ open-memex config set sync.autoPull true   # best-effort pull at MCP session sta
 ```
 
 Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
-`keywordCaptureEnabled`, `logLevel`, `memoryDir`, and `sync.autoPull` (a dotted
+`keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`, and `sync.autoPull` (a dotted
 key that writes into the nested `sync` object). Full design:
 [docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
 
@@ -622,9 +642,20 @@ open-memex add "This repo uses better-sqlite3" --type fact
 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

@@ -162,7 +162,7 @@ npx -y open-memex init --yes
 open-memex init --client vscode
 ```
 
-写入 MCP 服务器配置并可干净重载；重载窗口，确认 Copilot Chat 的 MCP 面板里 `open-memex` 服务器已启动。默认把配置写到 VS Code 的*用户级*配置（每个项目都生效）；也可以写到项目级 `.vscode/mcp.json`。
+写入 MCP 服务器配置；重载窗口，确认 Copilot Chat 的 MCP 面板里 `open-memex` 服务器已启动。默认写到项目级 `.vscode/mcp.json`（交互式运行会问你选哪一级）；加 `--global` 改写 VS Code 的*用户级*配置——一次设置，每个项目都生效。
 
 **Cursor**：
 
@@ -170,7 +170,7 @@ open-memex init --client vscode
 open-memex init --client cursor
 ```
 
-形态和 VS Code 一样：默认用户级 MCP 配置，可选项目级 `.cursor/mcp.json`，外加 Copilot 风格的指令文件。
+形态和 VS Code 一样：默认项目级 `.cursor/mcp.json`，`--global` 改为用户级 MCP 配置，外加 Copilot 风格的指令文件。
 
 **opencode**（原生插件——推荐）：
 
@@ -252,9 +252,12 @@ open-memex uninstall --yes
 
 三种存入方式：
 
-- **关键词触发**（仅 opencode 原生插件）：说 `remember …`、`note that …`、`don't forget …`、`TIL …`、`save this …`——中文 `记住…` / `记一下` / `记录一下` / `别忘了…`——这句话就被存下来，不需要任何工具调用。捕获默认进当前 **project**；`remember for me …`、`记住我…`、`替我记…`、`我觉得…`、`我喜欢…` 这类"这是关于我"的信号会改为进 **personal**；`我们决定…`、`帮我们记住…` 等团队语境仍留在项目里。
+- **关键词触发**（仅 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`。上面的路由是启发式规则；你可以明说"存到我的个人记忆"，或用 CLI 加 `--scope` 明确指定。
-- **CLI**：`open-memex add "…"`，可选 `--scope` / `--tags` / `--type`。
+- **检查点提议**：一个任务收尾时，助手会提议 1–3 条从这轮工作里提炼的候选记忆——决定及其理由、约定、踩过的坑、走过又放弃的路——只有你点头的那几条才存。不会有任何东西在你不知情时被写下来。
+- **CLI**：`open-memex add "…"`，可选 `--scope` / `--tag` / `--type` / `--aliases`。
+
+**别名。** 每条记忆可以带最多 4 个换一种说法（同义词、另一种语言的对应词），和记忆一起进索引，这样问法不同也能找到——比如搜 "vacation days" 能找到假期政策那条。`init` 时会问一次是否开启（默认开）；随时可用 `open-memex config set captureAliases false` 关掉。
 
 **脱敏。** 把敏感内容包在 `<private>…</private>` 里，它在保存前会被整段剥离。识别出的密钥（API key、token、高熵凭证）会被就地掩码——保留前 4 个字符（让你能认出是哪个 key），其余替换——记忆仍会保存。随时安全地预览一句话会被捕获成什么样：
 
@@ -272,9 +275,9 @@ MCP 服务器暴露十一个工具；opencode 原生插件暴露其中五个核
 |---|---|
 | ● `memory_add`       | 保存一条事实、偏好、决策、笔记 |
 | ● `memory_search`    | 关键词搜索（BM25），横跨项目 + 个人记忆 |
-| ● `memory_list`      | 列出某个作用域的记忆，最新在前 |
+| ● `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`     | 把个人记忆复制到项目作用域，作为评审候选 |
@@ -320,7 +323,7 @@ MCP 服务器暴露十一个工具；opencode 原生插件暴露其中五个核
 4. **PR 评审**——记忆是纯 Markdown；评审者走正常分支/PR 流程批准、要求修改或拒绝。
 5. **回想**——已发布的记忆在会话开始时注入，平时也能随时搜，人和助手都一样。
 
-看护共享记忆的人遵循 [维护者约定](./docs/CURATOR.md)：什么该批准、什么该打回、哪些卫生规则让共享记忆不腐烂。
+看护共享记忆的人遵循 [维护者约定](./docs/CURATOR.md)（英文）：什么该批准、什么该打回、哪些卫生规则让共享记忆不腐烂。
 
 ## 回想：记忆是怎么回来的
 
@@ -388,7 +391,7 @@ npm install -g open-memex@latest   # 或 @alpha
 
 ## 配置
 
-设置放在 `~/.config/opencode/open-memex.jsonc`——路径里的 `opencode` 是历史名；这一个文件由所有客户端共享。用 `MY_O_MEMORY_CONFIG` 覆盖配置路径，用 `MY_O_MEMORY_HOME` 覆盖存储根目录（改名之前留下的旧环境变量名，仍然有效）。
+设置放在 `~/.config/opencode/open-memex.jsonc`——路径里的 `opencode` 是历史名；这一个文件由所有客户端共享。用 `OPEN_MEMEX_CONFIG` 覆盖配置路径，用 `OPEN_MEMEX_HOME` 覆盖存储根目录（改名之前的旧变量名 `MY_O_MEMORY_CONFIG` / `MY_O_MEMORY_HOME` 仍然有效，作为回退）。
 
 默认值：
 
@@ -411,7 +414,7 @@ open-memex config set maxProjectMemories 12
 open-memex config set sync.autoPull true   # MCP 会话开始时尽力而为地 pull
 ```
 
-可设置的键：`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`logLevel`、`memoryDir`，以及 `sync.autoPull`（带点的键，写入嵌套的 `sync` 对象）。完整设计：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)。
+可设置的键：`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`captureAliases`、`logLevel`、`memoryDir`，以及 `sync.autoPull`（带点的键，写入嵌套的 `sync` 对象）。完整设计：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)（英文）。
 
 ## CLI 参考
 
@@ -439,9 +442,19 @@ open-memex add "This repo uses better-sqlite3" --type fact
 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` 在同一份清单里连续编号，并说明自己少显示了哪些条目。
 ```
 
 团队评审工作流（两个家，一个阶段一个）：
@@ -459,7 +472,7 @@ open-memex submit <id...> [--branch <name>] [--base <branch>]
 # 把你点名的草稿移进 .ai/open-memex/，标为 "proposed"：
 # 复制、翻转 review_state、在当前分支本地 git 提交。
 # 永不自己建分支——建分支是你（或拿到完整链路明确许可的助手）的事。
-# 全有全無；冲突（同 id 不同内容）干净地中止。
+# 全有全无；冲突（同 id 不同内容）干净地中止。
 # 打印 push + gh pr 命令；持有你 Yes 的助手可以一并执行 push/PR。
 # --branch <name> 先建分支（助手全链路路径）。PR base 默认是当前分支
 # （记忆 PR 叠在你的工作分支上）；--base 可改指到 main 或你的评审分支。
@@ -470,7 +483,7 @@ open-memex pr-status [--apply]
 # 要求修改 → 只给建议。默认只报告；--apply 在本地执行映射的迁移（不推送）。
 
 open-memex pull
-# 从 git 远程拉共享记忆：fetch + 純 fast-forward。
+# 从 git 远程拉共享记忆：fetch + 纯 fast-forward。
 # 分支分叉则明确报错失败——open-memex 永不强制合并；手工解决后再 pull。
 # 成功后本地索引重新同步。pull 默认显式触发；设置
 # `open-memex config set sync.autoPull true` 可在 MCP 会话开始时尽力拉一次
@@ -499,7 +512,7 @@ open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N]
 
 open-memex propose <id...> --to project [--local-approve]
 # 一次提议一条或多条个人记忆（一个分支、一个 PR）；
-# 每条复制并生成新 id。全有全無：任何一条 id 出错，整批中止，绝不半途。
+# 每条复制并生成新 id。全有全无：任何一条 id 出错，整批中止，绝不半途。
 # 把一条个人记忆复制到项目作用域作为评审候选
 # （是复制不是移动——个人原件保留）。结果落进 outbox；
 # 准备进仓库时再跑 sync-status / submit。
@@ -544,7 +557,7 @@ npx -y open-memex mcp        # 无需安装
 - **project（项目）**——限定在当前仓库，键由 git origin URL 的 hash 派生（所以同一仓库的多个 clone 共享一个作用域），没有远程时退回到当前工作目录路径。新记忆的默认作用域。
 - **personal（个人）**——横跨你的所有项目，仅限本机，永不向外同步。放个人偏好用。（v1 里叫 `user`；`migrate --to-v2` 会改名。）
 
-完整的 scope 模型（键派生、迁移、可见性、保留名）见 [docs/SCOPES.md](./docs/SCOPES.md)。[概念指南](./docs/CONCEPTS.zh-CN.md)把心智模型完整走了一遍。
+完整的 scope 模型（键派生、迁移、可见性、保留名）见 [docs/SCOPES.md](./docs/SCOPES.md)（英文）。[概念指南](./docs/CONCEPTS.zh-CN.md)把心智模型完整走了一遍。
 
 ## 故障排查
 
@@ -599,7 +612,7 @@ Windows 上已加载的 DLL 是锁定的：如果 open-memex 的 MCP 服务器
 
 ## 项目状态
 
-open-memex 是稳定且日常在用的；当前稳定线以 `latest` 发到 npm 上，`alpha` 构建给测试者。发版历史在 [GitHub Releases](https://github.com/stoneskin/open-memex/releases)；设计决策记录在只追加的日志 [docs/V2-DESIGN.md](./docs/V2-DESIGN.md) 里。
+open-memex 是稳定且日常在用的；当前稳定线以 `latest` 发到 npm 上，`alpha` 构建给测试者。发版历史在 [GitHub Releases](https://github.com/stoneskin/open-memex/releases)；设计决策记录在只追加的日志 [docs/V2-DESIGN.md](./docs/V2-DESIGN.md) 里（英文）。
 
 在望的方向（不承诺版本号）：更多编辑器的原生助手插件（作为在同一组 MCP 工具之上的增强路径）；本地 embedding 作为可选择开启的实验（没经询问，永不下载任何模型）；只有在真实多仓库共享、ACL 或合规需求出现时才做 org 层。
 

package/dist/.build-stamp

@@ -0,0 +1 @@
+f8a813363fbd1433ce149e78defa533d42be7ccbb7f37f1d53be64cd48b90c14

package/dist/capture/keywords.js

@@ -1,15 +1,27 @@
 /**
- * Scan user text for memory-capture keyword triggers.
+ * D67: capture-body length bounds. The lower bound rejects fragments — a
+ * trigger that yields "这个" or "OK" is a match on the trigger, not a memory,
+ * and a 2-char memory is noise in every future session's injection. The floor
+ * stays deliberately above 1: D67 considered lowering it and decided against
+ * it. What changed is that a rejection is no longer silent (see KeywordDrop).
+ */
+export const MIN_CAPTURE_CHARS = 3;
+export const MAX_CAPTURE_CHARS = 2000;
+/**
+ * Scan user text for memory-capture keyword triggers, reporting both what
+ * would be captured and what matched but was rejected (D67) — a dropped match
+ * that says nothing reads as a broken feature.
  * Each pattern must have a single capture group whose value becomes the memory body.
  * Personal patterns (cfg.keywordPersonalPatterns) force the personal scope.
  *
  * Personal patterns run first and claim their line: an explicit scope signal
  * (e.g. "记住我对花粉过敏") must not also fire the generic 记住 into the project scope.
  */
-export function detectKeywords(userText, cfg) {
-    if (!cfg.keywordCaptureEnabled)
-        return [];
+export function scanKeywords(userText, cfg) {
     const hits = [];
+    const dropped = [];
+    if (!cfg.keywordCaptureEnabled)
+        return { hits, dropped };
     const lines = userText.split(/\r?\n/);
     const claimed = new Set();
     const scan = (patterns, personal, skipClaimed) => {
@@ -28,16 +40,37 @@ export function detectKeywords(userText, cfg) {
                 if (!m || !m[1])
                     continue;
                 const content = m[1].trim().replace(/[.!?]$/, "").trim();
-                if (content.length >= 3 && content.length <= 2000) {
+                if (personal)
+                    claimed.add(i);
+                if (content.length >= MIN_CAPTURE_CHARS && content.length <= MAX_CAPTURE_CHARS) {
                     hits.push({ content, pattern: src, personal });
-                    if (personal)
-                        claimed.add(i);
                     break; // one hit per pattern per message
                 }
+                // Rejected: record it once per pattern. The line stays claimed for
+                // personal patterns even here - "记住我：OK" must not fall through to
+                // the generic 记住 and be saved as "我：OK" (D67).
+                if (!dropped.some((d) => d.pattern === src && d.content === content)) {
+                    dropped.push({
+                        content,
+                        pattern: src,
+                        personal,
+                        reason: content.length < MIN_CAPTURE_CHARS ? "too-short" : "too-long",
+                    });
+                }
+                break;
             }
         }
     };
     scan(cfg.keywordPersonalPatterns, true, false);
     scan(cfg.keywordPatterns, false, true);
-    return hits;
+    if (cfg.logLevel === "debug" && dropped.length > 0) {
+        for (const d of dropped) {
+            console.error(`[open-memex] keyword match not captured (${d.reason === "too-short" ? `body ${d.content.length} chars < ${MIN_CAPTURE_CHARS}` : `body ${d.content.length} chars > ${MAX_CAPTURE_CHARS}`}): "${d.content}"`);
+        }
+    }
+    return { hits, dropped };
+}
+/** Capture-only view of {@link scanKeywords} (drops are logged, not returned). */
+export function detectKeywords(userText, cfg) {
+    return scanKeywords(userText, cfg).hits;
 }