open-memex 0.8.2 → 0.9.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/AGENTS.md +21 -5
  2. package/CHANGELOG.md +10 -0
  3. package/README.md +46 -13
  4. package/README.zh-CN.md +25 -11
  5. package/dist/.build-stamp +1 -1
  6. package/dist/cli.js +103 -6
  7. package/dist/config.js +9 -0
  8. package/dist/doctor.js +4 -2
  9. package/dist/index.js +6 -1
  10. package/dist/init.js +13 -3
  11. package/dist/mcp.js +28 -5
  12. package/dist/opencode-v2.js +6 -2
  13. package/dist/plugin-core.js +28 -1
  14. package/dist/retrieve/inject.js +6 -0
  15. package/dist/retrieve/search.js +13 -2
  16. package/dist/review.js +7 -0
  17. package/dist/store/audit.js +14 -0
  18. package/dist/store/db.js +19 -0
  19. package/dist/store/lifecycle.js +8 -0
  20. package/dist/store/usage.js +151 -0
  21. package/dist/tools/memory.js +21 -2
  22. package/dist/tools/ops.js +123 -1
  23. package/dist/working-state.js +118 -0
  24. package/docs/CONCEPTS.md +16 -0
  25. package/docs/CONCEPTS.zh-CN.md +13 -0
  26. package/docs/V2-DESIGN.md +42 -1039
  27. package/docs/design/decisions.md +1146 -0
  28. package/docs/design/knowledge-graph.md +86 -0
  29. package/package.json +66 -66
  30. package/scripts/smoke-mcp.ts +67 -4
  31. package/scripts/smoke-pure.ts +70 -0
  32. package/scripts/test-full.ts +83 -0
  33. package/server.json +2 -2
  34. package/skills/open-memex/SKILL.md +19 -0
  35. package/src/cli.ts +111 -6
  36. package/src/config.ts +16 -0
  37. package/src/doctor.ts +4 -2
  38. package/src/index.ts +6 -0
  39. package/src/init.ts +13 -3
  40. package/src/mcp.ts +41 -4
  41. package/src/opencode-v2.ts +7 -2
  42. package/src/plugin-core.ts +32 -1
  43. package/src/retrieve/inject.ts +7 -0
  44. package/src/retrieve/search.ts +19 -3
  45. package/src/review.ts +6 -0
  46. package/src/store/audit.ts +20 -0
  47. package/src/store/db.ts +20 -0
  48. package/src/store/lifecycle.ts +9 -0
  49. package/src/store/usage.ts +178 -0
  50. package/src/tools/memory.ts +26 -1
  51. package/src/tools/ops.ts +158 -1
  52. package/src/working-state.ts +153 -0
@@ -0,0 +1,1146 @@
1
+ ## Decisions (append-only)
2
+
3
+ - **D1** — Markdown as source of truth, index rebuildable. *Rationale: human-editable, git-friendly,
4
+ no lock-in; the single decision that makes team sharing trivial.*
5
+ *Status (2026-11-02): 已实现 — `src/store/sync.ts:124` `syncScope()`.*
6
+ - **D2** — Instruction/data separation via `role` gate (iron rule 1). *Rationale: the #1 failure mode
7
+ of memory systems is history being mistaken for current rules.*
8
+ *Status (2026-11-02): 部分实现 — 铁律 1 的三元门(`role` + `instruction_state: approved` + `trust_level`)无代码执行:`instruction_state` / `trust_level` 字段在 `src/` 中不存在.*
9
+ - **D3** — `personal` scope never syncs. *Rationale: the trust anchor of the whole project.*
10
+ *Status (2026-11-02): 已实现 — `docs/SCOPES.md:11,15`("`personal` never leaves the machine. No sync, no upload, no exceptions.").*
11
+ - **D4** — MCP is an interface, not the product identity. *Rationale: transports evolve; the protocol
12
+ must outlive them.*
13
+ *Status (2026-11-02): 已实现 — 共享 host-agnostic 层 `src/tools/ops.ts`,两适配器同引:`src/mcp.ts:57`、`src/tools/memory.ts:20`.*
14
+ - **D5** — Git is transport, local index is query layer. *Rationale: answers the "git can't do
15
+ semantic search" objection by separating the two layers.*
16
+ *Status (2026-11-02): 已实现 — 传输:`src/providers/git.ts:2,82`(GitProvider).*
17
+ - **D6** — Promotion is explicit, never automatic. *Rationale: personal → shared is a governance
18
+ decision, not a sync event.*
19
+ *Status (2026-11-02): 已实现 — 无自动提升代码;提升只经显式 propose/submit/promote(src/review.ts、src/submit.ts).*
20
+ - **D7** — Embeddings are an optional capability, BM25+CJK is the default. *Rationale: zero-setup
21
+ default; no mandatory 100MB download or native dependency.*
22
+ *Status (2026-11-02): 部分实现 — Embeddings 作为"可选能力"未实现:`src/` 无 embedding 实现,只有 0.8.0 CHANGELOG 的离线实验(`scripts/bench-semantic.ts`,未进产品).*
23
+ - **D8** — Contested choices become **configurable with a popular default**, not hard-coded.
24
+ Applies to: in-repo dir name (default `.ai/open-memex/` per D23), CJK tokenizer (default bigram),
25
+ embeddings model (default `multilingual-e5-small`). *Rationale: the five-AI review split on all
26
+ three; maintainers shouldn't burn decision capital where config suffices.*
27
+ *Status (2026-11-02): 部分实现 — 另外两项未落地为配置:CJK tokenizer 选择与 embeddings 模型(`multilingual-e5-small`)在 `src/config.ts` 无对应键、`src/` 全文无 `e5-small`.*
28
+ - **D9** — The LAN reference server lives at `examples/remote-server/`. *Rationale: maintainer decision
29
+ 2026-09-26; "lan" is noise for OSS users, "remote-server" names what it proves (RemoteProvider).*
30
+ *Status (2026-11-02): 未实现 — LAN 参考服务器未写.*
31
+ - **D10** — Project renamed to **OpenMemex** (npm `open-memex`, repo `stoneskin/open-memex`).
32
+ *Rationale: `my-o-memory` was opencode-specific; the Memory Protocol positioning needs a broader name.
33
+ Fresh repo with no company-account commit history (see migration checklist 2026-09-26); old repo
34
+ archived with a pointer. Trademark check on "Memex"/"OpenMemex" required before public launch
35
+ (flagged in round-4 review).*
36
+ *Status (2026-11-02): 部分实现 — 商标检查条款无证据:全仓唯一提及是 `docs/design/decisions.md:25` 本身("required before public launch"),但产品已公开发布(0.1.0,0.7.2 进 MCP Registry),未见检查完成记录.*
37
+ - **D13** — Rename cascade (implements D10 in this doc, 2026-09-26): npm package `open-memex`,
38
+ CLI `open-memex` (e.g. `open-memex pull`), config dir `~/.open-memex/`, in-repo dir default
39
+ `.open-memex/` (**amends D8's** `.my-o-memory/` default). MCP tool name `memory_search` unchanged.
40
+ v1→v2 migration moves legacy `.my-o-memory/` dirs and `~/.my-o-memory/` config to the new paths
41
+ (with backup, explicit via `open-memex migrate`). *Rationale: one name everywhere; the old default
42
+ was set before the rename decision.*
43
+ *Status (2026-11-02): 已实现 — npm 包 open-memex、CLI、~/.open-memex/;migrate 可转 legacy my-o-memory 数据;MCP 工具名 memory_search 未变.*
44
+ - **D11** — `type` and `role` remain separate. `type` describes what a memory IS; `role`
45
+ (`knowledge` | `instruction`, default `knowledge`) describes how it may be USED. `role: instruction`
46
+ is an explicit, reviewable exception and may enter instruction context only when iron rule 1
47
+ (`role` + `instruction_state: approved` + `trust_level`) passes. *Rationale: content classification
48
+ and behavior authorization are separate concerns — the risky action is entering instruction
49
+ context, not the content's wording. Unanimous 5/5 in round-4 AI review, 2026-09-26.*
50
+ *Status (2026-11-02): 部分实现 — 条款级:分离已做,但 D11 的门条件(`instruction_state: approved` + `trust_level`)未实现——两字段不在 `src/` 中.*
51
+ - **D12** — Pull is explicit by default. Session start never pulls, never blocks on network, and
52
+ shows a staleness indicator instead. `sync.autoPull` is configurable, default `false`; even with
53
+ `autoPull: true`, a failed pull never blocks the session and every pull emits a receipt.
54
+ *Rationale: a memory pull can change agent behavior, so it must be a deliberate, visible act —
55
+ predictable offline-first beats silent freshness. Unanimous 5/5 in round-4 AI review, 2026-09-26.*
56
+ *Status (2026-11-02): 已实现 — `src/config.ts:88`(`sync: { autoPull: false }`).*
57
+ - **D14** — Secret detection masks instead of refusing. A write-path secret hit is **masked in
58
+ place** (first 4 characters kept, the rest replaced with `x`, length-preserving) and the write
59
+ proceeds with a notice; `<private>…</private>` spans are still stripped to `[REDACTED]`.
60
+ Amends the v0.2 rule "secret patterns refuse the write" (§8, §11). *Rationale: a refused write
61
+ loses the surrounding context the user asked to remember; a prefix-masked secret stays
62
+ recognizable (which key it was) while the credential itself is not recoverable from the file.
63
+ Supersedes the refusal behavior; applies to every write path (tools, keyword capture, CLI).
64
+ 2026-09-27.*
65
+ *Status (2026-11-02): 已实现 — `src/redact.ts:14-17`(头注)、`:194`(`<private>` → `[REDACTED]`)、`:202-206`(`maskMatch`:保留前 4 字符、其余换 `x`、等长).*
66
+ - **D15** — Phase 2A MCP server ships with all five tools, not read-only first. The MCP server
67
+ (`src/mcp.ts`, stdio) exposes `memory_add` / `memory_search` / `memory_list` /
68
+ `memory_supersede` / `memory_forget` — amends the §18 roadmap's "Read-only MCP" phasing.
69
+ *Rationale: the write path is the same Core (redact/D14, dedup, lifecycle) already shipped and
70
+ dogfooded in the opencode plugin, so a separate read-only stage adds process cost without
71
+ reducing risk. Core/adapters split implemented as `src/tools/ops.ts` (host-agnostic logic +
72
+ shared zod schemas); the opencode plugin and the MCP server are thin adapters over it.
73
+ Query-aware injection stays host-side: MCP is request/response and offers no hooks, so
74
+ proactive memory use depends on the host's agent instructions. 2026-09-27.*
75
+ *Update (2026-11-02): the server now exposes 11 tools (0.4.0 added six more); D15's five are the original subset.*
76
+ *Status (2026-11-02): 已实现 — 五个工具均在 MCP server:`src/mcp.ts:208-250`(`memory_add`/`memory_search`/`memory_list`/`memory_supersede`/`memory_forget`).*
77
+ - **D16** — No separate LLM extraction pass; memory intelligence lives in model-driven tool
78
+ calls. A dedicated post-session extraction (opencode `session.idle` hook → hidden session
79
+ → host model) was evaluated and rejected: the model's own decision to call `memory_add`
80
+ *is* the LLM judgment of "worth remembering", so a second pass is redundant and
81
+ host-specific. Investment goes into the shared layer instead — `TOOL_DESCRIPTIONS` in
82
+ `src/tools/ops.ts` and each host's agent instructions — so every host benefits at once.
83
+ Native plugins (opencode now; Claude Code / Codex as Phase 2C candidates) remain as
84
+ hook-enhanced paths, but opencode is also supported as a plain MCP consumer of
85
+ `open-memex mcp`, keeping one unified tool surface. 2026-09-27.
86
+ *Status (2026-11-02): 已实现 — 否定性决策:src/ 无 extraction pass;共享描述层 src/tools/ops.ts:67.*
87
+ - **D17** — `open-memex init` resolves the MCP server command at init time. A durable
88
+ `open-memex` on PATH (outside npm's ephemeral `_npx` cache) → `command: "open-memex"`;
89
+ otherwise (one-shot `npx open-memex@alpha init`) → `command: "npx", args: ["-y",
90
+ "open-memex@alpha", "mcp"]` plus a hint to `npm i -g` + re-run `init --force`.
91
+ `mcp --print-config` uses the same resolution. *Rationale: a one-shot npx run leaves
92
+ no bin behind, so writing `command: "open-memex"` would produce a dead MCP server on
93
+ the next editor launch; the npx fallback keeps the one-command setup actually
94
+ one-command. 2026-09-27.*
95
+ *Status (2026-11-02): 已实现 — `src/init.ts:43-55`(`resolveServerCommand`:PATH 外 durable bin → `command: "open-memex"`,否则 `npx -y open-memex@alpha mcp`),调用点 `src/init.ts:171,485,530`.*
96
+
97
+ - **D18** — Keyword scope routing: 我 → personal, 我们 → project. Chinese capture
98
+ keywords are split into two pattern lists: personal patterns (`记住我`/`替我记`/
99
+ `我觉得`/`我喜欢`, plus legacy `remember for me`/`记住(个人)`) route to the personal
100
+ scope, while project patterns (`我们认为`/`我们决定`/`帮我们记住`, and the generic
101
+ `记住…` for `记住我们的…`) route to the current project scope. Personal patterns are
102
+ scanned first and *claim* the line so the generic `记住…` pattern cannot double-fire;
103
+ `记住我` uses a `(?!们)` guard so it never swallows `记住我们…`. *Rationale: the
104
+ user's own rule — "我" is personal, "我们" is the current project — stated 2026-09-27;
105
+ scanning user messages (never assistant output) with personal-first claim keeps one
106
+ utterance to one memory. README + repo AGENTS.md keyword sections updated in the same
107
+ commit. 2026-09-27.*
108
+ *Status (2026-11-02): 已实现 — `src/capture/keywords.ts:38,68,82`(personal patterns 先扫并 claim,防 generic `记住…` double-fire).*
109
+ - **D19** — `open-memex init` asks setup questions; `open-memex config set` edits settings
110
+ after install. `init` prompts on a TTY (editor: vscode/cursor/opencode; keyword
111
+ auto-capture on/off; first-turn injection on/off), `--yes` accepts all defaults, and
112
+ non-terminal runs never prompt (scripts keep the historical vscode default).
113
+ Non-default answers persist to the JSONC config file; `open-memex config set <key>
114
+ <value>` changes them later (validated keys: `maxProjectMemories`, `maxProfileItems`,
115
+ `injectOnFirstTurn`, `keywordCaptureEnabled`, `logLevel`). `init --client opencode`
116
+ merges a `type: "local"` MCP entry into project-level `opencode.jsonc` (v1 format).
117
+ *Rationale: install time is the only moment the user's attention is guaranteed, and a
118
+ print-only `config` left no path to change settings afterwards. 2026-09-27.*
119
+ *Status (2026-11-02): 已实现 — init 提问:`src/init.ts:594-654`(readline:`promptClient` / `promptInstructionsScope` / `promptConfigLevel`).*
120
+ - **D20** — `init` / `mcp --print-config` support Visual Studio. Writes solution-level
121
+ `.mcp.json` with the `"servers"` section (`{ "type": "stdio", "command", "args" }`),
122
+ per Microsoft Learn (VS 2022 17.14+ / VS 2026, Windows-only). `.github/copilot-
123
+ instructions.md` is still written — VS's Copilot reads it too. Note VS also
124
+ auto-discovers `.vscode/mcp.json` and `.cursor/mcp.json`, so repos already set up for
125
+ VS Code get VS support for free; the explicit `.mcp.json` is the source-controllable
126
+ option. 2026-09-27.*
127
+ *Status (2026-11-02): 已实现 — `src/init.ts:503-507`(`writeVisualStudioMcpJson`,solution-level `.mcp.json`,`"servers"` section).*
128
+ - **D21** — The published npm package ships pre-compiled JS (`tsc -p tsconfig.build.json`
129
+ → `dist/`, via `prepublishOnly`; bin points at `dist/cli.js`). *Rationale: Node's
130
+ `--experimental-strip-types` refuses files under `node_modules`
131
+ (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so the old launcher
132
+ (`bin/open-memex.js` re-execing `src/cli.ts`) crashed on every global install —
133
+ reported 2026-09-27 on Node v22.12.0. Development stays build-free (`npm run cli`
134
+ / `npm run mcp` run `src/` directly); `doctor`'s MCP self-check resolves its server
135
+ entry the same way it is running (`dist/mcp.js` vs `src/mcp.ts`). The opencode
136
+ native plugin still loads `src/index.ts` (Bun strips types anywhere). 2026-09-27.*
137
+ *Status (2026-11-02): 已实现 — `package.json:43`(`prepublishOnly: npm run build`)、`:42`(`build: tsc -p tsconfig.build.json`)、`:60-61`(bin → `dist/cli.js`).*
138
+ - **D22** — `init` writes the Copilot memory instructions to the **user level** by
139
+ default (`~/.copilot/copilot-instructions.md`; `%USERPROFILE%\copilot-
140
+ instructions.md` for Visual Studio 2026) instead of the repo-level
141
+ `.github/copilot-instructions.md`. *Rationale: the repo-level file is checked in,
142
+ so teammates without open-memex get Copilot errors about missing `memory_*`
143
+ tools. The user-level location is GitHub's official personal-instructions slot
144
+ (highest priority, all projects, never in a repo). `--instructions project`
145
+ keeps the old repo-level behavior for teams where everyone uses open-memex.
146
+ The instructions carry a guard clause ("ignore this section when the
147
+ `open-memex` MCP server is not available") as cheap insurance. 2026-09-27.*
148
+ *Status (2026-11-02): 已实现 — `src/init.ts:634`("Personal (default)")、`:555-558`(默认写 `~/.copilot/copilot-instructions.md`,VS 2026 用 `%USERPROFILE%` 下同名文件)、`:641`(`--instructions project` 保留 repo 级行为)、`:884`(flag 校验).*
149
+ - **D23** — Default in-repo memory dir is `.ai/open-memex/` (configurable via
150
+ `memoryDir`; rejects absolute paths and `..`). *Rationale: `.ai/` is the
151
+ emerging convention for AI-local project state; the `open-memex/` leaf keeps
152
+ brand clarity and avoids collisions with other tools' `.ai/` content.
153
+ 2026-09-27.*
154
+ *Status (2026-11-02): 已实现 — `src/config.ts:87`(默认 `".ai/open-memex"`)、`:175`(拒绝绝对路径与 `..`).*
155
+ - **D24** — Project-scope markdown lives in the repo: writes with
156
+ `scope: project` go to `<projectRoot>/<memoryDir>/` (D23 default
157
+ `.ai/open-memex/`); `personal` never leaves appdata. Legacy appdata project
158
+ files are lazily migrated on first write/`syncScope` — the move is guarded by
159
+ the appdata dir name (which *is* the scope key), so it can only ever migrate
160
+ the current scope's files. The index's `file_path` is the single locator for
161
+ reads/deletes (`findMemoryFile`, `forget`); on the near-impossible id
162
+ collision between locations, the in-repo copy wins. *Rationale: one home per
163
+ scope, no silent data loss, no repo pollution before first use.* 2026-09-27.*
164
+ *Status (2026-11-02): 已废弃 — 被 D26 取代(Supersedes D24);appdata project 文件不再是 legacy,而是合法 draft.*
165
+ - **D25** — Review workflow semantics (`propose` / `promote` / `resolve`,
166
+ `src/review.ts`): (1) `review_state` frontmatter field
167
+ (`draft → proposed → approved/rejected → published`, default `draft`) plus
168
+ `proposed_by` / `approved_by` / `derived_from` / `review_note` provenance;
169
+ the SQLite index carries `review_state` (schema v6, rebuilt from markdown —
170
+ D1). (2) `propose` **copies** personal → project (new id, never moves — the
171
+ personal original stays private); one call takes several ids (one branch,
172
+ one PR; all-or-nothing — a bad id aborts the whole batch);
173
+ `--local-approve` skips the PR for solo
174
+ devs. (3) `promote` advances exactly one step up the ladder
175
+ (`proposed → approved → published`), `--reject`s with a note (also from
176
+ `approved`, withdrawing approval before merge), or `--resubmit`s a rejected
177
+ memory back to `proposed` for another round; `draft` and terminal states
178
+ refuse. (4) `resolve` lists conflicted memory files, or
179
+ attempts a field-level 3-way merge from git stages 1/2/3 (`tags` union,
180
+ `updated_at` takes latest, body merged only when one side changed); semantic
181
+ conflicts (same field / body changed differently on both sides) are reported
182
+ and the file is left untouched — **never auto-resolved**. (5) A rejection
183
+ never deletes anything: the file stays on the author's branch; the human
184
+ accepts (close PR, delete branch), revises + `--resubmit`s, or keeps it as
185
+ a `[rejected]` record. (6) No git
186
+ automation anywhere in the workflow: no branch creation, no commits, no PRs —
187
+ the commands print the exact next steps for the human. Org-level promotion is
188
+ Phase 4. *Rationale: the review ladder must be explicit and auditable; the
189
+ tool assists merging but a human always decides meaning.* 2026-09-27.*
190
+ *Update (2026-11-02): "schema v6" in this entry is now v9; clause (6) was corrected by D27.*
191
+ *Status (2026-11-02): 已实现 — `src/review.ts` 全套:(1) `review_state` + provenance `:122-126`(`proposed_by`/`derived_from`/`review_history`).*
192
+ - **D26** — **Supersedes D24.** Project-scope markdown has two homes, one per
193
+ lifecycle stage — never silently moved between them. (1) `memory_add` /
194
+ `memory_propose` with `scope: project` write to the **appdata outbox**
195
+ (`memories/<project_key>/<id>.md`, `review_state: draft`); the outbox is
196
+ git-invisible and branch-independent. The D24 lazy migration is deleted —
197
+ appdata project files are legitimate drafts, not legacy. (2) `open-memex
198
+ submit <id...>` / `memory_submit` moves user-named drafts into the repo's
199
+ `<memoryDir>/` (D23), flipping `review_state` to `proposed`: the file now
200
+ follows branches and PRs. `sync-status` / `memory_status` shows both sides
201
+ (outbox drafts, repo review states, uncommitted repo files). (3) The move is
202
+ one-stage-one-place: copy → verify hash → local commit → verify → delete
203
+ outbox original; re-running is idempotent (identical content skips, different
204
+ content aborts). `search` prefers the repo copy when both exist; conflicts
205
+ (same id, different content; push rejected) stop and ask the human — never
206
+ overwrite. *Rationale: an AI agent drafts constantly; the repo should only
207
+ ever see what the human explicitly approved for review. The outbox is the
208
+ agent's desk, the repo dir is the shared table. Approved 2026-09-28.*
209
+ *Status (2026-11-02): 已实现 — 取代 D24:outbox(appdata drafts)+ `submit`(`src/submit.ts:2,82-143`,`sync-status` 双边展示).*
210
+ - **D27** — **Revises D25 §6 (no git automation).** `submit` automates the
211
+ *local* half of the git workflow: create `mem/sync-<timestamp>` (or
212
+ `--onto` the current branch for code+memory PRs), copy, `git add` only the
213
+ memory files, local commit, verify. It prints the push + `gh pr create`
214
+ commands for the human — but an agent that already holds the user's Yes for
215
+ this sync carries through push and PR creation without re-asking (each step
216
+ is not a separate approval). Batch submit is all-or-nothing; an empty-branch
217
+ abort rolls the branch back. *Rationale: the old "no git automation" rule
218
+ assumed a human at the keyboard; the agent-driven flow needs local mechanics
219
+ automated while push/PR stay under the user's explicit per-sync Yes/No.
220
+ Approved 2026-09-28.*
221
+ *Status (2026-11-02): 已实现 — 修正 D25 §6:submit 自动化本地 git 半程——建分支 `mem/sync-<timestamp>`(`src/submit.ts:304-318`)、仅 `git add` 记忆文件(`:397`)、本地 commit(`:402`)、空分支 abort 回滚(`:383-384`).*
222
+ - **D28** — Memory PR base defaults to the **current branch**; the user may
223
+ redirect to `main` or the project's integration branch (`--base`). A
224
+ standalone memory PR and a code+memory PR are both supported — the agent asks
225
+ which one each time; on "with code" it uses `--onto` and never commits
226
+ unrelated staged changes. *Rationale: memory usually reviews against the work
227
+ it describes (current branch); the integration branch is the exception, not
228
+ the default. Approved 2026-09-28.*
229
+ *Status (2026-11-02): 已实现 — PR base 默认当前分支:`src/submit.ts:321`(`base = opts.base ?? startBranch`).*
230
+ - **D29** — Every review transition is written to a per-memory audit trail
231
+ (`review_history`: at/by/from/to/note) — reject / resubmit / approve /
232
+ publish all append, never overwrite; `propose` and `submit` seed it; merge
233
+ conflict resolution unions both sides' histories. *Rationale: review is a
234
+ decision log, not a flag — "who rejected this and why" must be answerable
235
+ months later. Approved 2026-09-28.*
236
+ *Status (2026-11-02): 已实现 — `src/review.ts:126`(propose/submit seed `review_history`)、`:239-240`(promote/reject/resubmit 追加不覆盖)、`:459-465`(resolve 时 union 双方 history).*
237
+ - **D30** — Retrieval ranks by review state: approved/published project
238
+ memories outrank unreviewed content; project drafts/rejected sink to the
239
+ bottom and are visibly tagged `[draft]` in search/list/inject output, while
240
+ personal memories (always draft by design) are never demoted or tagged.
241
+ Explicit search still finds drafts — they are deprioritized, not hidden.
242
+ *Rationale: reviewed knowledge should win the context window; drafts stay
243
+ discoverable but never masquerade as vetted. Approved 2026-09-28.*
244
+ *Status (2026-11-02): 已实现 — src/retrieve/search.ts:111-126(reviewTier:approved/published → 0,personal → 1 不降级,draft/rejected → 2).*
245
+ - **D31** — Every index sync records when it ran, what triggered it
246
+ (`session` / `request` / `cli` / `submit`) and its stats, in
247
+ `<appdata>/sync-state.json`; `sync-status` shows the last sync first.
248
+ *Rationale: "is my index fresh?" must be answerable without guessing —
249
+ especially across branch switches where the in-repo dir changes underneath.
250
+ Approved 2026-09-28.*
251
+ *Status (2026-11-02): 已实现 — src/store/sync.ts:180(SyncKind 7 种);recordSync() 写 sync-state.json;sync-status 命令在位.*
252
+ - **D32** — The branch PR's GitHub state maps back onto each in-repo
253
+ memory's review_state via `pr-status` / `memory_pr_status`: merged PR →
254
+ published, PR approval → approved with `approved_by` = reviewer login,
255
+ changes-requested → suggestion only (never auto-rejects). Report by
256
+ default; `--apply` performs the mapped transitions locally (no push —
257
+ inside the D27 line). Each memory keeps its own state: a human `rejected`
258
+ is never overridden by a PR signal. *Rationale: the PR is where the team
259
+ actually reviews — the mapping closes the loop without inventing new
260
+ review UI. Approved 2026-09-28.*
261
+ *Status (2026-11-02): 已实现 — `src/tools/ops.ts:89`(`memory_pr_status` 描述:merged→published、approval→approved、`approved_by` = reviewer、changes-requested 仅建议).*
262
+ - **D34** — The MCP server sends session-start guidance in the handshake
263
+ `instructions`: call `memory_status` at session start (and at work
264
+ checkpoints); if the outbox has drafts, summarize and ask the user which to
265
+ sync; proactive `memory_add`; `memory_search` before asking about the past;
266
+ personal never leaves the machine. *Rationale: the init-written instruction
267
+ files only exist if the user ran `init --client` — the handshake reaches
268
+ every MCP client at connect time. Still advisory: no MCP consumer offers a
269
+ hard session-start hook, and we do not claim otherwise. Approved 2026-09-28.*
270
+ *Update (2026-11-02): the session-start `memory_status` call is now conditional (D53) — only when the server reports drafts; the Checkpoints section is retired.*
271
+ *Status (2026-11-02): 部分实现 — **条款级修正(D53)**:D34 原文"session start 时调 `memory_status`"已改为有条件——仅当服务器报告有草稿时才调.*
272
+ - **D35** — "sync memory" (or "同步记忆") is a natural-language trigger for the
273
+ sync flow: the agent calls `memory_status`, summarizes the outbox drafts, and
274
+ asks the user which ones to sync — same flow as the session-start proposal,
275
+ but user-initiated. Taught in the MCP handshake instructions, the
276
+ init-written instruction files, and the `memory_status` tool description.
277
+ *Rationale: the user should not have to remember command names to sync;
278
+ saying it in words must work. Approved 2026-09-28.*
279
+ *Status (2026-11-02): 已实现 — `src/mcp.ts:94-97`(用户说 "sync memory"/"同步记忆" → 调 `memory_status`,绝不直接浏览数据目录).*
280
+ - **D36** — `submit` never creates a branch on its own (revises D26/D27): it
281
+ copies the named drafts into `.ai/open-memex/`, commits locally on the
282
+ CURRENT branch, and prints next-step commands. Branch creation is the human's
283
+ call — or the agent's, only with explicit approval for the full chain, via
284
+ `submit --branch <name>` / `memory_submit(branch=...)`. *Rationale: an
285
+ auto-created branch strands the user on it — they forget to switch back.
286
+ After a submit the agent asks ONE follow-up ("want me to create a branch +
287
+ push + open the PR, or will you handle it yourself?") instead of branching
288
+ silently. Checkpoints that trigger `memory_status`: session start, end of a
289
+ work chunk, after the user commits, and after any memory_* action.
290
+ The "sync memory" trigger ALWAYS goes through the `memory_status` tool —
291
+ never by browsing the appdata directory directly. Approved 2026-09-28.*
292
+ *Status (2026-11-02): 部分实现 — **条款级修正(D53)**:条目末尾所列"触发 `memory_status` 的检查点(session start / 工作块结束 / commit 后 / memory_* 后)"已随检查点机制退役,提示词中不再有 Checkpoints 一节.*
293
+ - **D33** — Every CLI command answers `open-memex <command> --help` (and `-h`)
294
+ with its own usage, flags, and examples; checked before config/DB load so
295
+ help works even in a broken environment. Unknown commands with `--help`
296
+ fall back to the global usage. *Rationale: AI assistants discover the CLI
297
+ through --help first — a command that silently swallows --help as a flag
298
+ teaches the agent nothing. Approved 2026-09-28.*
299
+ *Status (2026-11-02): 已实现 — `src/cli.ts:722-724`(`--help`/`-h` 在 `loadConfig()` 之前处理,注释明示).*
300
+ - **D37** — Conversation distillation is the memory unit; transcript storage is
301
+ not the default. Capture should preserve the useful conclusion from a human/AI
302
+ session — what was learned, what resolved the issue, what should be avoided,
303
+ and where the authoritative doc lives — as a short reviewable memory. If the
304
+ knowledge already exists in docs, store a `reference` memory with
305
+ `canonical_ref` instead of duplicating the doc. Tags are retrieval hints, not
306
+ content kinds: `type` classifies the memory, tags describe topics/tools/paths.
307
+ *Rationale: full chat logs are noisy, harder to review, and riskier for
308
+ privacy; the value is remembering the right conclusion at the right scope,
309
+ with enough context for the next human or AI session. Approved 2026-09-28.*
310
+ *Status (2026-11-02): 部分实现 — **缺口**:条目所说的 `reference` 记忆带 `canonical_ref` 字段——`Frontmatter`(`src/store/markdown.ts:44-80`)中**没有 `canonical_ref` 字段**,文档链接只能写在正文里.*
311
+ - **D38** — OpenMemex supports a Markdown second-brain use case while keeping
312
+ distillation as the default for implicit/model-suggested capture. If the user
313
+ explicitly asks to save a long note, meeting summary, troubleshooting record,
314
+ or write-up, preserve it as user-authored Markdown with tags and normal
315
+ scope/privacy rules. Git/GitHub sync is the default team-sharing provider, not
316
+ the product boundary: future export/import archives and API-backed providers
317
+ may move the same markdown memories to other computers, applications, or
318
+ enterprise systems. For generic "save/remember/note this" requests, the agent
319
+ routes project-specific knowledge to `project`, personal or repo-unrelated
320
+ knowledge to `personal`, and asks one clarification if ambiguous; `org` remains
321
+ curated/future, never a direct single-user chat write. *Rationale: users also
322
+ want a local AI-assisted second brain, but portability and ownership must stay
323
+ explicit; sharing mechanisms should be provider choices over the same memory
324
+ model, not the identity of the product. Approved 2026-09-28.*
325
+ *Status (2026-11-02): 已实现 — 长文仅用户明示才存:`src/mcp.ts:111`("Long-form notes are fine ONLY when the user explicitly asks").*
326
+ - **D39** — `type` and `tags` are complementary axes, not alternatives. `type` is
327
+ single-valued: what the memory IS — it drives behavior (lifecycle, review,
328
+ rendering, retrieval: a `todo` can be completed, a `reference` resolves
329
+ `canonical_ref`, a `decision` participates in supersede chains). `tags` are
330
+ multi-valued: what the memory is ABOUT — pure retrieval hints
331
+ (topics, tools, subsystems, paths, incidents). *Rationale: without type the
332
+ system cannot tell "a todo I must do" from "a fact I must know" even when both
333
+ are tagged `auth`; without tags, cross-cutting retrieval ("everything about
334
+ onboarding") would need a combinatorial type explosion. Type answers "how do I
335
+ handle this?", tags answer "how do I find this?". Approved 2026-09-28.*
336
+ *Status (2026-11-02): 部分实现 — **缺口**:条目举例 "a `reference` resolves `canonical_ref`"——无 `canonical_ref` 字段(同 D37).*
337
+ - **D40** — `open-memex export` excludes `visibility: private` memories by
338
+ default; `--all` / `-a` includes everything, for a full personal migration to
339
+ a new machine. *Rationale: the safe default protects privacy; the escape hatch
340
+ keeps the "no walled garden" promise — the user can always take everything
341
+ with them. Approved 2026-09-28.*
342
+ *Status (2026-11-02): 已实现 — `src/cli.ts:262-275`(export 用法:默认排除 `visibility: private`,`--all`/`-a` 全量).*
343
+ - **D42** — §3.5 checkpoint distillation is taught in the MCP handshake
344
+ instructions (`src/mcp.ts` `SERVER_INSTRUCTIONS`) and the `init`-written
345
+ instruction files (`src/init.ts` `INSTRUCTIONS`): at checkpoints the agent
346
+ DISTILLs the session and proposes 1–3 short memories (conclusion, not
347
+ transcript); nothing is saved without user approval. Approved captures are
348
+ saved via `memory_add` with the new optional `source` param set to
349
+ `"inference"` (default `"tool"`). *Rationale: closes the 0.4.0 TODO from D41 —
350
+ the design's capture loop now reaches the agent. Implemented 2026-09-29.*
351
+ *Status (2026-11-02): 已实现 — `memory_add` 的 `source` 参数:`src/tools/ops.ts:128-132`("Pass 'inference' for agent-proposed captures").*
352
+ - **D43** — `distill-agents` output gains a "Memory hygiene (open-memex)"
353
+ footer carrying the §3.5 checkpoint guidance (propose 1–3 distilled captures
354
+ at checkpoints; save nothing without approval; prefer `reference` over
355
+ copying). *Rationale: double insurance for opencode users, who never see the
356
+ MCP handshake instructions or the `init`-written instruction files — but
357
+ opencode reads AGENTS.md natively, so the distilled snippet teaches the
358
+ checkpoint habit wherever it lands. Approved 2026-09-29.*
359
+ *Status (2026-11-02): 已实现 — `src/distill-agents.ts:73`(输出 `### Memory hygiene (open-memex)` footer).*
360
+ - **D44** — `migrate --to-v2` hotfix (issue #7, 0.4.1): (1) `--dry-run` now
361
+ previews the legacy `my-o-memory` files in place — per-file conversion plans
362
+ without moving anything (previously it scanned only the new, still-empty
363
+ root and always reported "0 files", making the preview useless); (2) dry-run
364
+ no longer prints the false "legacy data dir merged" line; (3) the Windows
365
+ EPERM on the legacy-dir backup rename is caught and rethrown as an actionable
366
+ message (close the program holding the folder — e.g. a running MCP server —
367
+ and re-run; nothing was deleted), and the CLI prints it as `Error: …` with
368
+ exit 1 instead of a raw syscall stack; (4) `parseFlags` accepts `--key=value`
369
+ in addition to `--key value` (the `=` form was silently misparsed before,
370
+ dropping the flag — which can turn a `--dry-run` into a real run).
371
+ *Rationale: a preview that shows nothing is worse than no preview — the user
372
+ cannot confirm what the real run will do; and a destructive-path failure must
373
+ speak in user terms. Shipped as 0.4.1 hotfix on the stable line. Approved
374
+ 2026-09-29.*
375
+ *Status (2026-11-02): 已实现 — `src/store/v2migrate.ts:220-243`(`dryRun` 时就地预览 legacy 文件的转换计划,`:243` 仅非 dry-run 才落盘).*
376
+ - **D45** — `init --global` (0.5.0-alpha.1): one-time user-level MCP wiring for
377
+ VS Code / Cursor. Writes the open-memex server entry to the editor's
378
+ user-level `mcp.json` (`%APPDATA%\Code\User\mcp.json` on Windows,
379
+ `~/Library/Application Support/Code/User/mcp.json` on macOS,
380
+ `~/.config/Code/User/mcp.json` on Linux; `~/.cursor/mcp.json` for Cursor)
381
+ instead of the project's `.vscode/mcp.json` — init once, the server starts
382
+ in every project. The entry keeps `cwd: "${workspaceFolder}"` so VS Code
383
+ substitutes it per window and project-scope resolution keeps working;
384
+ a per-project config still wins when present. Merge semantics are shared
385
+ with project-level init (merge, never clobber; `--force` overwrites).
386
+ Interactive `init` now asks per-project vs user-level for vscode/cursor
387
+ (default: per-project, preserving old behavior); `--global` skips the
388
+ question. For opencode, `--global` is a no-op that prints the native-plugin
389
+ one-liner (already global, and strictly more capable than plain-MCP mode);
390
+ Visual Studio stays solution-level by design. *Rationale: per-project init
391
+ is a paper cut that compounds — the data layer already needs zero per-project
392
+ setup (scope is derived from cwd), so the editor wiring should be able to
393
+ match. Approved 2026-09-29.*
394
+ *Update (2026-11-02): opencode --global now merges into ~/.config/opencode/opencode.json (D46); the hint-only wording is superseded.*
395
+ *Status (2026-11-02): 已实现 — `src/cli.ts:379-393`(`init --global` 用户级 MCP 写入).*
396
+ - **D41** — The type taxonomy is reconciled to 11 types with one-line definitions
397
+ (§3.1): `fact` `preference` `decision` `constraint` `todo` `knowledge` `howto`
398
+ `gotcha` `lesson` `observation` `reference`. Merged away: `warning`→`gotcha`,
399
+ `workflow`→`howto`, `incident`→`lesson` (incident id goes in `tags`),
400
+ `architecture`→`knowledge` (tag `architecture`). *Rationale: a type earns its
401
+ place only if the system treats it differently (lifecycle, retrieval,
402
+ rendering); otherwise it is a tag. Fifteen types blur classification and hurt
403
+ agent accuracy — eleven keeps each type's behavioral slot distinct. `lesson`
404
+ is deliberately broader than `incident`: a postmortem's shape (timeline, root
405
+ cause, actions) is a template concern, not a type. Code
406
+ `MEMORY_TYPE_TAXONOMY` updated to match. Approved 2026-09-28.*
407
+ *Status (2026-11-02): 已实现 — `src/store/markdown.ts:14-26` `MEMORY_TYPE_TAXONOMY` 恰为 11 类(fact/preference/decision/constraint/todo/knowledge/howto/gotcha/lesson/observation/reference).*
408
+ - **D46** — `init` with no `--client` auto-detects installed editors and wires
409
+ them all (0.5.0-alpha.2). Detection: VS Code via `code` on `PATH`, well-known
410
+ install locations, or an existing user-level `mcp.json`; Cursor via `cursor`
411
+ on `PATH` or `~/.cursor`; opencode via `opencode` on `PATH` or its global
412
+ config dir; Visual Studio only when the project has a `.sln` (solution-scoped
413
+ by design). Auto mode always wires user-level where the editor supports it —
414
+ VS Code / Cursor MCP entry (D45), and for opencode the native plugin entry is
415
+ now *actually merged* into `~/.config/opencode/opencode.json` (replacing D45's
416
+ hint-only `--global`), so one init covers every editor and every project.
417
+ A config file with comments (JSONC) is never rewritten — init prints the
418
+ manual one-liner instead. Interactive `init` shows the detected editors and
419
+ confirms wiring all of them (declining falls back to the single-editor
420
+ prompt); non-interactive (`--yes`) wires all detected with no prompts.
421
+ An explicit `--client` keeps the old single-editor behavior, including the
422
+ per-project default for vscode/cursor. *Rationale: Stone's two hats — he
423
+ writes code in several editors himself, and new users / pilot colleagues
424
+ should not have to learn `--client` to get started. The help text already
425
+ promised "default: auto-detect"; D46 makes the code keep that promise.
426
+ Approved 2026-09-29.*
427
+ *Status (2026-11-02): 已实现 — `src/init.ts:841`(无 `--client` 时 auto-detect 并全接).*
428
+ - **D47** — when `init` refuses to touch a config file that isn't valid JSON
429
+ (usually JSONC with comments — VS Code / Cursor / opencode all accept them),
430
+ it now prints the exact snippet to add by hand: the section key plus the
431
+ `"open-memex"` entry, pretty-printed. Covers all three MCP-writing paths —
432
+ vscode/cursor (user + project level), opencode project-level `opencode.jsonc`,
433
+ and Visual Studio `.mcp.json` — matching the manual hint the opencode
434
+ `--global` plugin path already printed (D46). The file is still never
435
+ rewritten; the hint just makes "fix it manually" actionable. Triggered by
436
+ Stone's real Windows run: his user-level `mcp.json` had comments, init
437
+ correctly left it alone, but the old message gave him nothing to paste.
438
+ *Rationale: a refusal without a remedy is a dead end; the entry shape is
439
+ already computed, so printing it costs nothing. Approved 2026-09-29.*
440
+ *Status (2026-11-02): 已实现 — `src/init.ts:231` `parseJsonConfig`.*
441
+ - **D48** — new `open-memex uninstall` command, the reverse of `init`
442
+ (0.5.0-alpha.4). Removes the MCP server entry / opencode native plugin line /
443
+ Copilot instructions section that `init` wrote; memory data is never touched.
444
+ Client resolution mirrors `init` (explicit `--client`, else auto-detect with
445
+ an interactive confirm). Without `--global` it cleans both project-level and
446
+ user-level files — init may have written either, and a leftover entry at the
447
+ other level would be a surprise; `--global` restricts to user-level. Empty
448
+ sections/arrays are pruned; an instructions file that only held the
449
+ open-memex section is deleted. Non-JSON (JSONC) configs are left untouched
450
+ with the manual step, same D47 treatment as the init write path.
451
+ *Rationale: Stone asked "有 uninstall 吗" while testing init on Windows —
452
+ every write deserves an undo. Approved 2026-09-29.*
453
+ *Status (2026-11-02): 已实现 — `src/cli.ts:396-411`(`uninstall [--client ...] [--global] [--yes]`).*
454
+ - **D49** — empty config files are no longer treated as corrupt (0.5.0-alpha.5).
455
+ Stone's real Windows run: his user-level `mcp.json` existed but was empty,
456
+ and `init` refused it with "not valid JSON — left untouched", because
457
+ `JSON.parse("")` throws. New `parseJsonConfig` helper: empty or
458
+ whitespace-only content parses as `{}` — there is nothing to preserve, so
459
+ writers safely populate it; genuinely unparseable content (JSONC comments)
460
+ or non-objects still return null and keep the D47 leave-untouched + manual
461
+ hint behavior. Applied to all five config file touch points: the three init
462
+ writers (vscode/cursor MCP, opencode `opencode.jsonc`, Visual Studio
463
+ `.mcp.json`) and the two uninstall removers (empty file = nothing to remove).
464
+ *Rationale: an empty file is the safest write target, not a corrupt file;
465
+ refusing it sent the user down a manual path for no reason. Triggered by
466
+ Stone's report 2026-09-29.*
467
+ *Status (2026-11-02): 已实现 — `src/init.ts:231` `parseJsonConfig`(空/纯空白内容解析为 `{}`).*
468
+ - **D50** — close the install→init gap (0.6.0-alpha.1). `npm install -g`
469
+ only puts the CLI on PATH; the editor wiring is `init`'s job, and a clean
470
+ reinstall wipes it — Stone hit exactly this on 2026-09-30 (fresh opencode
471
+ reinstall + `npm i -g open-memex`, then no open-memex in `opencode.jsonc`).
472
+ Two changes, both CI-safe: (1) a `postinstall` script that **prints**
473
+ `Run \`open-memex init\`…` — postinstall must never prompt, it runs in CI /
474
+ Docker / `npm ci` where stdin isn't a terminal; (2) bare `open-memex` on a
475
+ machine where init never completed **offers** to run it (default yes) when
476
+ stdin+stdout are TTYs, otherwise prints usage exactly as before. Asked-state
477
+ is a `.init.json` marker at the data root — init writes it on success, a
478
+ declined offer writes it too, so the question is asked once; `uninstall`
479
+ removes it (unwiring is the reverse of init, so the next bare run offers to
480
+ wire again). The marker is a dotfile and export builds from DB rows, so it
481
+ can't leak into bundles. The offer re-execs `open-memex init` as a child
482
+ with inherited stdio rather than calling init in-process — the offer's own
483
+ readline already consumed stdin's buffer, and a second readline on the same
484
+ stream would see EOF on burst input (verified with a pty test).
485
+ *Rationale: install ≠ setup, and the gap only shows up on a fresh machine —
486
+ exactly when the user has the least context. A printed hint covers the
487
+ install moment; the interactive offer covers the first-run moment; neither
488
+ can hang a pipeline. Approved 2026-09-30.*
489
+ *Status (2026-11-02): 已实现 — `package.json:44` `postinstall` 脚本.*
490
+ - **D51** — close the init→first-use gap (0.6.0-alpha.2). D50 gets the user to
491
+ a wired editor; a first-time user then stops at "it's wired" with no idea
492
+ what to do next. `init` now ends with one concrete next step:
493
+ ``Next step: `open-memex add "standup is at 9:30"` — then ask your agent what
494
+ it remembers.`` One line, printed unconditionally — the cheapest possible
495
+ onboarding after wiring. *Rationale: the CLI is editor-independent, so the
496
+ hint works no matter which client was wired; `add` + recall is the smallest
497
+ loop that proves the whole system works. Approved 2026-09-30.*
498
+ *Status (2026-11-02): 已实现 — `src/init.ts:960`(`Next step: open-memex add "standup is at 9:30"`).*
499
+
500
+ - **D52** — agent-prompt clarity rewrite (0.6.0-alpha.3). Both agent-facing
501
+ prompts (MCP `initialize` instructions in `src/mcp.ts`, init instruction
502
+ template in `src/init.ts`) are rewritten to fix ambiguities found on review:
503
+ (1) the proactive-save vs approval-gate contradiction is resolved by naming
504
+ the two cases — facts the user *states* are saved proactively, conclusions
505
+ the agent *infers* are proposed first and saved only on approval;
506
+ (2) `memory_status`/`memory_search` are excluded from the "after any
507
+ memory_* action" checkpoint trigger (self-trigger loop);
508
+ (3) tool names use the full `memory_*` form in both prompts;
509
+ (4) the four checkpoints are defined once as "Checkpoints" and referenced,
510
+ with an operational heuristic ("a task the user would describe in one
511
+ sentence") replacing "meaningful chunk of work";
512
+ (5) empty outbox → do nothing; "the user commits" → "any git commit in this
513
+ session"; `type "reference"` named explicitly; PR-base mechanics spelled out
514
+ per D28. *Rationale: these prompts are the product's UI for agents — a
515
+ literal-minded agent must execute them correctly without guessing.
516
+ Approved 2026-10-01.*
517
+ *Update (2026-11-02): clauses (2) and (4) relied on the Checkpoints mechanism retired by D53; the remaining clauses stand.*
518
+ *Status (2026-11-02): 部分实现 — **条款级修正(D53)**:涉及检查点的子句 (2)(`memory_status`/`memory_search` 排除自触发)和 (4)(四检查点定义一次并引用)所依赖的检查点机制已于 D53 退役,提示词中已无 Checkpoints 一节.*
519
+
520
+ - **D53** — push-not-poll outbox: the checkpoint mechanism is retired; code
521
+ pushes state to the agent instead (0.6.0-alpha.4). `src/submit.ts` gains
522
+ `outboxDraftCount()` (one indexed SQLite COUNT on the current scope's outbox,
523
+ no git I/O); `src/tools/ops.ts` gains `withOutboxNote()`, which appends
524
+ `[open-memex: N draft(s) waiting in the project outbox — call memory_status
525
+ to review]` to mutating tool results, only when N > 0. It is wired into the
526
+ five MCP mutating tools (`memory_add`, `memory_supersede`, `memory_forget`,
527
+ `memory_submit`, `memory_propose`) and the three opencode-plugin mutating
528
+ tools (`memory_add`, `memory_supersede`, `memory_forget` — there the note
529
+ stays generic because the plugin has no `memory_status`). The MCP server
530
+ also appends the live draft count to the `initialize` instructions when N >
531
+ 0 (stdio servers start fresh per session, so construction-time state is
532
+ session-start state). Both agent-facing prompts drop the Checkpoints section
533
+ and the post-`memory_submit`/`memory_propose` status checks; the sync rule
534
+ becomes one line ("when the server reports drafts waiting, call
535
+ `memory_status`") plus the existing "sync memory" trigger. The static init
536
+ template keeps one explicit session-start `memory_status` call, since a
537
+ static file cannot carry live state. An anti-nag clause is added: if the
538
+ agent already asked about these drafts this session, it does not ask again.
539
+ *Rationale: the server knows the outbox state; making the agent poll for it
540
+ on a timer wastes tool calls and teaches a habit that scales badly. The note
541
+ is silent when the outbox is empty, so the common case costs nothing.
542
+ `memory_submit` drains the outbox, so its own note is naturally silent.
543
+ Approved 2026-10-01.*
544
+
545
+ - **F28** — install→init reminder was invisible (0.6.0-alpha.5). The D50
546
+ postinstall pointer never reaches the user: npm runs lifecycle scripts in
547
+ the background and swallows their stdout unless `--foreground-scripts` is
548
+ passed (reproduced on npm 10.9.4 — the script ran with code 0, its output
549
+ never displayed). The install-time channel is therefore best-effort only.
550
+ Fix: every CLI entry point now prints a one-line nudge on stderr until init
551
+ has run or been declined (`open-memex init` wires editors), gated by the
552
+ existing `.init.json` first-run marker — stderr keeps the MCP stdio protocol
553
+ (stdout) intact, so even `open-memex mcp` spawned by an editor carries it
554
+ safely. `init`/`uninstall` are excluded. The bare-`open-memex` interactive
555
+ offer on a TTY (D50) is unchanged. *Rationale: the reminder must live in a
556
+ channel the project controls — the CLI — not in npm script output.
557
+ Reported 2026-10-01.*
558
+
559
+ - **F29** — Copilot review fixes on PR #11 (0.6.0-alpha.7). (a) The lockfile
560
+ carried a stray `"version": "0.6.0-alpha.1"` key as a direct child of
561
+ `packages` (left by the D50 version bump; hand-edited bumps preserved it) —
562
+ `npm ls --package-lock-only` failed on it. Removed; version bumps now go
563
+ through `npm pkg set` so npm owns the lockfile format. (b) D53 missed the
564
+ shared `TOOL_DESCRIPTIONS.memory_status`: it still told agents to call the
565
+ tool "at session start and at task checkpoints" — the polling this change
566
+ retires. Now: session start, server-reported drafts, or explicit "sync
567
+ memory". Same staleness removed from the `source` field hint. (c) Onboarding
568
+ strings (postinstall note, first-run nudge, bare-CLI offer) now mention
569
+ Visual Studio auto-detection for solution projects instead of listing only
570
+ three editors. *Lesson: never hand-edit version fields in package-lock.json.
571
+ Reported 2026-10-01.*
572
+ *Status (2026-11-02): 已实现 — `src/submit.ts:163` `outboxDraftCount()`.*
573
+
574
+ - **D54** — Agent Skills support (0.6.0-alpha.8). Ship a bundled
575
+ `open-memex` skill (`skills/open-memex/SKILL.md`: frontmatter + CLI guide —
576
+ proactive save, search, scope routing, outbox→submit flow) inside the npm
577
+ package. `init` copies it (not symlinks — Windows needs no Developer Mode)
578
+ into each wired editor's user-level skills dir: VS Code →
579
+ `~/.copilot/skills/open-memex/`, Cursor → `~/.cursor/skills/open-memex/`,
580
+ opencode → `~/.config/opencode/skills/open-memex/`; Visual Studio has no
581
+ skills concept and is skipped. User-level by design (D46: init once). An
582
+ existing skill is never clobbered silently — kept unless `--force`.
583
+ `uninstall` removes only the `open-memex` skill directory. The skill tells
584
+ agents to prefer MCP tools (`memory_add` etc.) when available and fall back
585
+ to the CLI otherwise (with the `npx -y open-memex@latest` prefix when the
586
+ CLI isn't on PATH). *Rationale: skill-aware agents get memory with zero MCP
587
+ configuration; the skill is the CLI-shaped complement to the MCP server.
588
+ Requested by Stone 2026-10-01 after the Agent Skills ecosystem suggestion.*
589
+
590
+ - **F30** — Sweep pre-rename `my-o-memory` leftovers (0.6.0-alpha.9). The
591
+ my-o-memory → open-memex rename left editor configs behind that still load
592
+ the OLD plugin/server, which writes to the OLD data dir — silently splitting
593
+ the user's memories in two (found live on Stone's work machine 2026-10-01:
594
+ the old opencode plugin sat above the new one in `opencode.json`, so
595
+ opencode and the CLI wrote to different data roots). `init` now drops stale
596
+ `my-o-memory` plugin entries and `my-o-memory` MCP server keys wherever it
597
+ touches a config (opencode global plugin list, per-project `opencode.jsonc`,
598
+ `.mcp.json`, VS Code/Cursor `mcp.json` incl. `--global`), even on the
599
+ "kept" path; JSONC files it can't parse get a manual-removal hint.
600
+ `uninstall` sweeps the same leftovers. `doctor` gains a read-only
601
+ `legacy my-o-memory` check: fails when a legacy data dir exists next to the
602
+ data root, when a user-level config still references `my-o-memory`, or when
603
+ `MY_O_MEMORY_HOME` points at a pre-rename dir. *Lesson: a package rename
604
+ must clean up its own old wiring — the old entry and the new entry are never
605
+ both valid. Reported 2026-10-01.*
606
+ *Status (2026-11-02): 已实现 — `skills/open-memex/SKILL.md` 存在于包内.*
607
+
608
+ - **D55** — opencode's native plugin supersedes the Agent Skill
609
+ (0.6.0-alpha.10). Real-world feedback (Stone 2026-10-01): with both the
610
+ native plugin's `memory_*` tools and the D54 skill installed, opencode's
611
+ agent turned chatty — two overlapping instruction sets plus a "use MCP or
612
+ CLI?" choice on every memory action. No data corruption (identical saves
613
+ dedupe), but the UX regressed from "one tool call and done" to narration.
614
+ `init` no longer installs the skill for opencode when the native plugin is
615
+ wired (`--global`), and removes a previously installed one; the per-project
616
+ plain-MCP mode keeps the skill as the no-tools fallback. VS Code/Cursor
617
+ keep the skill — their MCP wiring is more fragile (server-start failures,
618
+ policy blocks), so the fallback still earns its keep, and the skill already
619
+ tells agents to prefer MCP tools when available. *Lesson: don't ship two
620
+ overlapping integrations for the same editor — the agent pays the
621
+ duplication cost in chatter. Reported 2026-10-01.*
622
+ *Status (2026-11-02): 已实现 — `src/init.ts:920-924`(opencode 有 native plugin 时不装 skill,并移除已装的).*
623
+ - **D56** — question-shaped searches and host parity, said out loud
624
+ (0.6.1-alpha.1). Two-persona review (Stone 2026-10-03) converged on small,
625
+ honest fixes rather than new machinery. (1) Retrieval already OR-ed terms
626
+ and ranked with bm25, but fed whole questions ("how do we configure…",
627
+ "中文记忆怎么检索") straight into FTS — question words matched everything
628
+ and diluted ranking. Query construction now filters a small EN/CJK
629
+ function-word set, dedupes, and caps terms at 24 per side, with a
630
+ never-empty fallback (query.ts; partially answers the retrieval-robustness
631
+ open question — layers 2 agent-side expansion / 3 capture-time aliasing
632
+ remain open, embeddings stay reserved). (2) The plugin(5)/MCP(11) tool
633
+ asymmetry is now stated in the six MCP-only tool descriptions themselves,
634
+ with the CLI equivalent named, so an agent looking for `memory_status`
635
+ inside opencode finds the answer instead of assuming breakage (the
636
+ host-parity open question's "document it" option; true parity undecided).
637
+ (3) `init`'s closing lines gain a one-line privacy statement at the moment
638
+ of maximum doubt: memories live only on this machine, personal ones never
639
+ leave it, nothing is uploaded.
640
+ *Status (2026-11-02): 已实现 — (1) `src/retrieve/query.ts:33` `MAX_TERMS = 24`、function-word 过滤.*
641
+
642
+ - **D57** — explainable search, a memory audit, and the concurrency posture
643
+ written down (0.6.1-alpha.2; addresses most of the retrieval-explainability
644
+ / memory-health open question and establishes the concurrent-sessions
645
+ behavior it asked for). (1) `open-memex search --explain` prints the
646
+ constructed FTS expression, per-hit bm25 score, and how many matches
647
+ lifecycle hid (superseded vs retracted/archived), so a miss is diagnosable
648
+ — bad query, stale memory, or chain-hidden — without reading the index.
649
+ (2) New `open-memex audit` (read-only; doctor checks the environment, this
650
+ checks the memories): near-duplicate active pairs (same ≥ 0.8 Jaccard as
651
+ write-time dedup), actives untouched for 90+ days, broken supersede chains,
652
+ personal files found inside the in-repo memory dir (iron-rule breach), and
653
+ index/file drift. Reports only; fixes stay with `supersede` / `forget` by
654
+ hand. (3) Concurrency, measured: every process opens its own connection to
655
+ one WAL index; memory files are per-memory ULIDs, so concurrent writes to
656
+ *different* memories never collide on disk. SQLite was the gap — no
657
+ `busy_timeout` was set, so better-sqlite3 silently tolerated 5s while
658
+ bun:sqlite (opencode plugin) timed out at 0 and failed instantly under any
659
+ overlapping write. Now unified at `PRAGMA busy_timeout = 5000` in `db()`.
660
+ Past the timeout the CLI prints one plain line ("store is busy … nothing
661
+ was lost") instead of a stack trace — and nothing *is* lost: the memory
662
+ file is written before the index update, so the next sync reconciles it
663
+ (verified end-to-end: a write blocked 8s still lands once the lock frees).
664
+ Memory file writes are tmp+rename, so a concurrent reader never sees a
665
+ torn file. Same-memory concurrent edits remain last-writer-wins (accepted:
666
+ different processes editing the same memory simultaneously is a human
667
+ conflict, not a storage one). `doctor` reports the live locking settings.
668
+ *Status (2026-11-02): 已实现 — (1) `src/cli.ts:114-120` `search --explain`.*
669
+
670
+ - **D58** — the opencode plugin must never runtime-import the host SDK
671
+ (0.6.1-alpha.3). Field report: after a global `npm i -g open-memex`, the
672
+ plugin was configured in `~/.config/opencode/opencode.jsonc` but silently
673
+ inactive — no memory tools, no error, nothing in opencode's log. Bisected
674
+ with the real host (opencode 1.18.34) and a minimal plugin: a bare
675
+ `file://` entry loads fine; adding `import { tool } from
676
+ "@opencode-ai/plugin/tool"` makes opencode skip the plugin without a
677
+ trace. That import only ever resolved from a source checkout (where
678
+ `npm install` provides the devDependency); from a global install's
679
+ location nothing provides the module and the host does not resolve it
680
+ for file:// plugins. The helper is a runtime identity (`return input`),
681
+ so the fix is a local same-signature stand-in in `tools/memory.ts` —
682
+ types still come from the SDK (type-only imports erase at runtime), and
683
+ the plugin now depends only on real runtime dependencies. Verified in
684
+ the real host against a global-install-shaped tree: all five tools
685
+ register. Rule going forward: plugin code imports host SDK types only;
686
+ runtime imports must resolve from the package's own dependencies.
687
+ *Status (2026-11-02): 已实现 — `src/tools/memory.ts:2` 仅 `import type`(`@opencode-ai/plugin`).*
688
+
689
+ - **D59** — `doctor` patrols the plugin entry it used to take on faith
690
+ (0.6.2-alpha.1). D58's failure was invisible to every existing check:
691
+ `doctor` verified the MCP server end-to-end but never looked at the
692
+ opencode plugin entry, so a configured-but-dead plugin passed all
693
+ checks. The new `opencode plugin` check reads the user-level opencode
694
+ configs (`opencode.json` + `opencode.jsonc`), attributes entries to
695
+ this plugin by package path or the `[open-memex]` marker (source
696
+ checkouts live anywhere), and fails when (a) the entry's target file
697
+ does not exist — with the `init --force` re-point command named — or
698
+ (b) the entry's relative-import closure runtime-imports
699
+ `@opencode-ai/plugin`, the exact D58 death. It checks only what can be
700
+ attributed; per-project and MCP wiring are out of scope.
701
+ *Status (2026-11-02): 已实现 — `src/doctor.ts:191` 起 `opencode plugin` 检查(入口文件存在 + 导入闭包不 runtime-import host SDK).*
702
+
703
+ - **D60** — one plugin serves both opencode generations (0.7.0-alpha.1).
704
+ Opencode 2 changes the plugin contract end to end: config reads
705
+ `plugins` (directories or `{package}` objects) instead of v1's
706
+ `plugin` file entries, a v1-style file entry only earns a log warning
707
+ ("configured plugin path must be a directory") and is silently skipped
708
+ — the D58 death in a new shape; and the plugin value itself is a
709
+ structurally decoded `{ id, setup(ctx) }` rather than the v1 server
710
+ factory. A single `open-memex init --client opencode --global` now
711
+ writes both keys (`plugin` file URL and `plugins` directory): each
712
+ host loads from its own key — verified: opencode 1.18.34 ignores the
713
+ `plugins` array with a config-normalization warning, and opencode 2
714
+ warns per `plugin` file entry but loads the directory entry — so users on either generation get a
715
+ working plugin from the same install. `src/index.ts` default-exports
716
+ `{ id, setup, server }`: v2 calls `setup`, v1 calls `server`, the
717
+ shared logic (bootstrap, keyword capture, one-time injection) lives in
718
+ `src/plugin-core.ts`. Cost of the bridge on the v1 side: v1 hosts
719
+ older than 1.18.29 only invoke function default exports and would
720
+ skip this object; 1.18.29+ accepts it — the README states the new
721
+ minimum. The v2 adapter (src/opencode-v2.ts) obeys D58's rule — no
722
+ runtime `@opencode/plugin` import (a devDependency again); the
723
+ context is duck-typed from the 2.0 surface, tool arg shapes compile
724
+ from the same zod shapes via `z.toJSONSchema`, and hooks map
725
+ one-to-one (session `prompt` → keyword capture, session `context` →
726
+ first-turn injection). One registration subtlety cost real debugging
727
+ time and is worth recording: on 2.0.1 a plugin tool added without
728
+ options is exposed to the model only in code mode — callable through
729
+ an `execute` meta-tool that runs model-written JS
730
+ (`tools.memory_search(...)`) — and a model that instead calls the
731
+ tool by name gets a host-side "Unknown tool" error, so whether the
732
+ memory tools work at all depends on the model's calling style. Each
733
+ tool therefore registers with `options: { codemode: false }`, which
734
+ restores plain function calling (verified: direct calls execute
735
+ first try). The D59 doctor check extends to both keys:
736
+ v2 entries are checked for an existing, resolvable entry file and the
737
+ closure scan now covers `@opencode/plugin` too, plus a generation
738
+ advisory — when the installed host and the config point at different
739
+ generations, doctor fails and names the fix (`init --force`; package-
740
+ name entries installed via `opencode plugin add` are recorded but not
741
+ path-checked). Field-verified on real hosts 1.18.34 and 2.0.1.
742
+ *Status (2026-11-02): 已实现 — `src/index.ts:54` 默认导出 `{ id, setup, server }`.*
743
+
744
+ - **D61 — proactive capture cluster: propose posture, a shared
745
+ memorability rubric, and capture-time aliasing (retrieval layer 3).**
746
+ Builds on the "proactive capture" open question below and the
747
+ CHECKPOINT_PROACTIVITY / MEMORY_VISIBILITY notes. Three pieces,
748
+ shipped together because they are one user-visible behavior — the
749
+ agent capturing well without being asked each time:
750
+ (1) **Posture: propose, not auto-draft.** When the agent finishes a
751
+ task the user would describe in one sentence, it proposes 1–3 short
752
+ candidate memories in the conversation and saves only what the user
753
+ approves (approved inferences are saved with `source: "inference"`,
754
+ the §3.5 convention). The guidance is text, not mechanism — the same
755
+ rubric written into the bundled skill, the AGENTS.md memory-hygiene
756
+ footer, the MCP handshake instructions, the `memory_add` tool
757
+ description, and a one-line summary in the injected context block —
758
+ with throttling rules (task end / decision / gotcha moments only, no
759
+ mid-task interruptions, never re-propose a declined candidate). The
760
+ auto-draft posture (write first, surface later in bulk) is deferred
761
+ until memory visibility ships: without an inventory the user can
762
+ read, silent drafting reads as surveillance, so D61 deliberately
763
+ does not build it.
764
+ (2) **Rubric.** One memorability standard, shared by this live
765
+ capture path and the future retrospective-distillation group:
766
+ worth saving — decisions and their reasons, preferences,
767
+ conventions, gotchas, approaches tried and abandoned, and
768
+ `reference` memories pointing at authoritative docs; not worth
769
+ saving — one-off task details and anything re-derivable from the
770
+ code. Retrieval robustness layer 2 (agent-side query expansion:
771
+ decompose into concepts, 2–3 phrasings each, cross-language, check
772
+ the other scope) ships as guidance in the same texts, on top of the
773
+ D56 server-side layer 1.
774
+ (3) **Capture-time aliases (layer 3).** When a memory is saved, the
775
+ agent attaches up to 4 aliases — alternate phrasings, synonyms,
776
+ equivalents in the user's other language — stored in a new optional
777
+ frontmatter field `aliases` (additive; files without it parse
778
+ unchanged, `schema_version` stays 2) and indexed in their own FTS
779
+ column (index schema 6→7, rebuilt from markdown automatically).
780
+ Gated by a new `captureAliases` config flag (init asks once, default
781
+ on, `config set captureAliases off` opts out): when off, aliases
782
+ passed by agents are dropped and the alias guidance disappears from
783
+ the MCP handshake. Turning it off never rewrites existing memory
784
+ files — aliases already stored stay stored and searchable, and
785
+ supersede keeps carrying them forward; the flag gates new captures
786
+ only (no silent data destruction). Aliases pass through the same
787
+ secret redaction as memory content before they are stored, and a
788
+ malformed alias list (blanks, more than 4) is normalized silently —
789
+ never a tool-call error.
790
+ Keyword capture (no agent in the loop) leaves
791
+ aliases empty rather than inventing them; `supersede` carries
792
+ aliases forward unless the caller replaces them. Aliases are
793
+ normalized (trim, case-insensitive dedupe, cap 4) and bad ones cost
794
+ nothing — they rank as bm25 noise, never an error. Retrospective
795
+ distillation over host transcripts stays its own group; it will
796
+ reuse this rubric.
797
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0(2026-10-04)"Proactive capture: checkpoint proposals and aliases".*
798
+
799
+ - **D62 — environment variable names grow current-name aliases.** The
800
+ data-root and config-path overrides predate the rename and kept the
801
+ old package's name (`MY_O_MEMORY_HOME`, `MY_O_MEMORY_CONFIG`) — a
802
+ stale-looking name is a trap for users and agents scripting against
803
+ the current one. `OPEN_MEMEX_HOME` / `OPEN_MEMEX_CONFIG` are now the
804
+ preferred names; the legacy names still work as fallbacks (new name
805
+ wins when both are set), so existing setups and scripts never break.
806
+ The data root itself does not move — only the variable names change.
807
+ `doctor`'s storage check notes when the root arrived via the legacy
808
+ variable, and its pre-rename-dir leftovers check reads whichever
809
+ variable is in effect.
810
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "Environment variable names (D62)".*
811
+
812
+ - **D63 — correctness fixes from a whole-project external review.** Six
813
+ verified silent-wrong-answer bugs, fixed as one batch: (1) VS init
814
+ dropped the parsed `.mcp.json` instead of merging it, wiping other
815
+ servers; (2) forget reported success when unlink failed — only ENOENT
816
+ is success now, both in the tool op and the CLI; (3) the config
817
+ loader's regex comment-stripper was not string-aware and corrupted
818
+ redact patterns (`src/**/secrets` → `srcsecrets`) — replaced with a
819
+ string-aware scanner now shared with doctor (one parser, not two);
820
+ (4) `loadConfig` enforces the `memoryDir` no-escape invariant on
821
+ hand-edited files, falling back to the default with a warning;
822
+ (5) `migrate` rewrites `scope`/`visibility` with the key, and
823
+ conflict resolution compares parsed timestamps (lexicographic
824
+ RFC-3339 order breaks at fractional seconds); (6) bundle import
825
+ enforces staging-dir containment (resolve + realpath), rejecting
826
+ `../` and symlink escapes. Rule going forward: any behavior that can
827
+ fail must fail loudly in its return value; "already gone" is the only
828
+ swallowed delete error.
829
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "Correctness fixes from the whole-project review (D63)",六项逐条列出并注明各有回归测试.*
830
+
831
+ - **D64 — second batch from the same review: stale answers, stranded
832
+ files, and holes between surfaces.** (1) The opencode plugin hosts
833
+ synced the index only at bootstrap, so memories written by the CLI or
834
+ another client stayed invisible all session (and exact duplicates
835
+ accumulated); plugin tool calls now reconcile from disk first,
836
+ mirroring the MCP server's per-call sync. (2) Superseding a published
837
+ memory reset `review_state` to `draft` in the repo, where submit
838
+ could not reach it and promote refuses drafts — the replacement now
839
+ re-enters at `proposed` whenever the old memory had entered review.
840
+ (3) Every memory-file rewrite now goes through the atomic
841
+ tmp+rename helper (D57 covered creates only); a torn read mid-rewrite
842
+ previously parsed as a deletion. (4) `setStatus` refuses
843
+ `retracted → active`: retraction is one-way through this path, or
844
+ withdrawn content silently returns to recall. (5) Propose copies get
845
+ `visibility: internal` instead of inheriting `private`, which export
846
+ excludes by default — the team copy no longer vanishes from bundles.
847
+ (6) `opencodeGlobalConfigPath` resolves whichever of `.json`/`.jsonc`
848
+ actually exists, as init's writer does; uninstall no longer reports
849
+ "nothing to remove" while leaving the plugin entry behind.
850
+ (7) `doctor` now checks all eleven MCP tool names (it checked the
851
+ plugin's five) and flags v1 memories stranded under `memories/user/`,
852
+ which v2 read paths cannot see. (8) `memory_status` output is capped
853
+ per section with an "… and N more" line; `memory_list` accepts
854
+ `scope: both`; `forget` says when the deleted file lived in the repo
855
+ (commit the deletion); the Copilot instructions and the MCP handshake
856
+ now tell the agent the same thing about when to call
857
+ `memory_status`; the AGENTS.md distillation footer teaches
858
+ `source: "inference"` like every other surface; `where` prints the
859
+ config path it always promised. Standing rule reinforced: any surface
860
+ that answers a question must be reading current truth, and every
861
+ workflow state must have a next step.
862
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "P1 fixes: stale answers and stranded files (D64)",八项逐条列出.*
863
+
864
+ - **D65 — keyword capture: natural phrasings fell through.** Default-pattern
865
+ fixes found while verifying a review claim: (1) `帮我记住…` — arguably the
866
+ most natural Chinese phrasing — matched no pattern at all; it now captures
867
+ to personal, following the established 我-rule (same as 替我记), while
868
+ `帮我们记住…` still routes project. (2) A leading `请` defeated every
869
+ 记住-led pattern (`请记住我…`, `请记住:…`, `请记住(个人)…`); the
870
+ `(?:请)?` prefix the 记一下 patterns already had is now uniform.
871
+ (3) English `remember to …` left a stray leading "to" in the captured
872
+ body; the pattern consumes it (with backtracking verified so
873
+ "remember Toronto…" is not mangled). Patterns are code defaults, so
874
+ upgrades pick these up automatically unless the user customized the
875
+ pattern lists. Deliberately NOT changed: multi-line paste triggering
876
+ and the secret-masking windows stay as they are — narrowing them is a
877
+ capture-recall tradeoff that needs an explicit decision, not a drive-by.
878
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "Keyword capture gaps (D65)".*
879
+
880
+ - **D66 — follow-up review of the D63–D65 stack.** (1) The 帮/替
881
+ keyword family is rebuilt around full verb phrases: an optional `请`,
882
+ `记` + optional `住|录` + optional `一下`, then a separator boundary —
883
+ `请帮我记住:…` captures (D65's new pattern lacked its own `请`),
884
+ `帮我记录一下:…` saves `周五不发布` instead of the mid-word garbage
885
+ `录一下:…`, and `帮我记得…` does not fire. `help me remember: …`
886
+ joins the personal patterns. Still deliberately unchanged: shortening
887
+ the ≥3-char content floor (it eats `记一下这个`-type captures, but
888
+ lowering it invites junk) and adding narrative triggers like `记得…` /
889
+ `remind me to…` (imperative-vs-narration ambiguity) — both need an
890
+ explicit decision. (2) `sync-status` CLI shows the full list; the
891
+ 20-line cap binds only agent renders, whose "… and N more" line names
892
+ the CLI. `list --scope both` reaches CLI parity with the tool, and
893
+ `status --help` documents the retracted one-way door. (3) The test
894
+ suite is Windows-safe (probe imports are `file://` URLs, the uninstall
895
+ test sets `USERPROFILE` since `os.homedir()` ignores `HOME` there)
896
+ and refuses to run against a stale `dist/`. (4) Sync-error posture is
897
+ now a stated asymmetry: the MCP adapter lets pre-call sync errors
898
+ propagate as tool errors; the plugin adapter logs them at debug and
899
+ answers from a possibly-stale index rather than taking the tools
900
+ down. (5) §19's legacy-paths text now names the shipped locations;
901
+ historical decision entries keep their as-decided wording.
902
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "Review follow-ups (D66)".*
903
+
904
+ - **D67 — keyword capture: a trigger must be a statement to the store.**
905
+ Three rulings, all from the D66 review's open items plus one bug D66
906
+ introduced. (1) **The boundary guard guards the bare verb only.** D66 put
907
+ a separator requirement *after* the whole verb phrase, which killed the
908
+ commonest Chinese form — `帮我记一下这个配置`, `帮我记住这个配置`,
909
+ `替我记一下我住在杭州`, `帮我们记一下这个约定` all stopped matching, because
910
+ the noun follows 记一下/记住 directly. The guard now applies only to a
911
+ bare 记: `记` + (`住`|`录`, never followed by a verb continuation like
912
+ 得/着) + optional `一下`, or a separator. So mid-word garbage (`帮我记得带伞`
913
+ → `带伞`) is still impossible while the natural form captures. (2) **The
914
+ ≥3-char body floor stays, but stops being silent.** A trigger that yields
915
+ `这个` or `OK` is a match on the trigger, not a memory, and a 2-char memory
916
+ is noise in every later injection — so the floor is deliberately *not*
917
+ lowered (a script-aware floor is the escape hatch if short Latin bodies
918
+ ever matter). What changed is honesty: `capture --dry-run` prints the
919
+ rejection with the reason, and `logLevel: debug` logs it, so "nothing
920
+ happened" is never a mystery. A rejected **personal** match also keeps
921
+ its line claimed — otherwise `记住我:OK` fell through to the generic
922
+ 记住 and was saved as the nonsense project memory `我:OK`. (3) **Narrative
923
+ forms are not triggers.** `记得…`, `remind me to…`, `I always forget to…`
924
+ stay out: they are imperatives aimed at the agent, they are the most
925
+ frequent sentences in any conversation that mentions memory, and a false
926
+ trigger writes permanent state nobody reviewed — while a missed trigger
927
+ costs one sentence. The asymmetry is deliberate: precision over recall.
928
+ For the two ambiguous forms already in the list, an explicit marker now
929
+ separates narration from instruction: `别忘了:…` / `don't forget: …` /
930
+ `don't forget that …` capture; bare `别忘了带伞` / `don't forget the wifi
931
+ password` do not. The `note` family is untouched — `note the API is v2`
932
+ was never ambiguous. (4) Test/tooling honesty: `test-full.ts` guards the
933
+ built `dist/` with a content fingerprint (`scripts/build-stamp.mjs`)
934
+ rather than mtimes — `git checkout` rewrites mtimes, so a branch switch
935
+ could leave an older-branch dist looking fresh — and the agent-facing
936
+ `memory_status` cap is pinned again (20 entries per section plus a
937
+ "full list: open-memex sync-status" pointer) after D66's CLI-parity test
938
+ had dropped that coverage.
939
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "Keyword capture: what counts as a trigger (D67)".*
940
+
941
+ - **D68 — memory visibility: the inventory is a protocol surface.** Group 3-C
942
+ (design: `docs/memory-visibility-design.md` v2). `memory_list` output
943
+ becomes a numbered, structured inventory (`[type] id=… created=…
944
+ source=…`, state tags for project scopes; `created=` is when the fact
945
+ was learned, `updated=` shown only when it moved materially later). The
946
+ raw enums stay in the data; plain-language renderings live in the
947
+ guidance surfaces (tool descriptions, MCP handshake, SKILL.md,
948
+ distill-agents footer) so agents rephrase in the conversation's
949
+ language. New input `include: "active" | "all"` (default `active`) —
950
+ a deliberate behavior change: superseded versions and retracted /
951
+ archived memories leave the default listing (audit view via `all`).
952
+ Every listing states its true total; truncation is disclosed, never
953
+ silent (the D66 lesson applied to this surface). `open-memex
954
+ inventory` renders the same data layer as text (default) or JSON
955
+ (`open-memex-inventory/1`); a report containing personal memories
956
+ refuses to be written inside a git working tree without
957
+ `--allow-personal`. `memory_forget` gains `soft` (CLI `forget
958
+ --soft`): retraction as a first-class tool action — hidden from lists
959
+ and search, file kept, still one-way per D64 (restoring the fact means
960
+ saving it again; no un-hide, no undo, no recycle bin). Deletion stays
961
+ a confirmed conversation: agents re-list before acting on a number
962
+ (numbers are only valid for the listing just produced) and read the
963
+ entry back before deleting. The HTML rendering of the same data layer
964
+ follows as a separate change; auto-draft stays gated on the unlock
965
+ conditions in the design doc.
966
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "Memory visibility: see it, hide it, delete it (D68)" 及同版 "Inventory HTML report (D68 follow-up)".*
967
+ - **D69 — inventory HTML rendering lands (3-C complete on the visibility side).**
968
+ `open-memex inventory --format html` renders the D68 data layer into a
969
+ single local page: scopes grouped, outbox drafts in their own section,
970
+ replaced/hidden history folded with supersede-chain pointers, all
971
+ content escaped, filter box is local show/hide (no innerHTML, no
972
+ network). Default output is the data dir's `inventory.html`; the D68
973
+ worktree refusal applies unchanged. Sections fold above 50 current
974
+ entries. With this, the 3-C visibility surfaces are complete (agent
975
+ inventory in chat, text/JSON reports, HTML page; hide + confirmed
976
+ delete as the correction actions). Auto-draft remains gated on the
977
+ unlock conditions in `docs/memory-visibility-design.md`.
978
+ *Note (2026-11-02): entry restored verbatim from commit 8b11aed (2026-10-03) — it was dropped from the log during a later rebase/merge.*
979
+ *Status (2026-11-02): 已实现 — 0.7.0-alpha.10 (commit 8b11aed); src/inventory-html.ts.*
980
+
981
+ - **D74 — the Node floor is 22.14, because the driver sets it, not us.** D72
982
+ moved the Node driver to `better-sqlite3` 13 (the N-API rewrite) to stop the
983
+ Node 24.19+ exit-path abort. That upgrade carried an unstated requirement:
984
+ v13 is compiled against **Node-API 10**, and Node only gained Node-API 10 in
985
+ **22.14.0**. Below that floor `require("better-sqlite3")` succeeds and then
986
+ `new Database()` segfaults the process — no message, no stack, exit 139 on
987
+ macOS/Linux, `0xC0000005` on Windows. Measured on win32-x64: Node 22.12.0
988
+ dies on the first open, Node 22.23.3 and 24.20.0 work; Node 20 can never work
989
+ with v13, since Node-API 10 never landed on that line (EoL regardless). This
990
+ is upstream and still open — WiseLibs/better-sqlite3#1514, plus #1516 for the
991
+ separate `npm ci` gyp problem on Windows, where `gypfile: false` does not stop
992
+ npm from shelling out to node-gyp. `engines.node` had been `>=22.6`, which was
993
+ the `--experimental-strip-types` floor — a real but *different* constraint
994
+ that predated the driver bump; leaving it would have shipped a package whose
995
+ declared support window crashes on its own dependency. Three changes:
996
+ (1) `engines.node` is `>=22.14.0`, and the two floors are documented as two
997
+ floors rather than merged into one number; (2) `loadDatabase` refuses below
998
+ the new floor and throws the actionable message (upgrade Node, or pin
999
+ `better-sqlite3@^12.11.1` — v12 is unaffected), because a crash no in-process
1000
+ `try`/`catch` can report is the worst possible failure mode for a CLI;
1001
+ (3) `doctor` reports the floor *and* probes the driver in a **child process**,
1002
+ since a segfault cannot be caught in-process — the probe resolves the driver
1003
+ from this package's own directory, because `doctor` routinely runs with cwd
1004
+ set to a user project where a bare `require` finds nothing. The version
1005
+ comparison lives in `src/runtime-floor.ts`, pure and unit-tested, because the
1006
+ boundary is a fact to be tested (22.13.9 below, 22.14.0 exactly at, 22.23.3
1007
+ and 24.20.0 above) rather than a constant to be trusted. Deliberately NOT
1008
+ done: pinning back to v12 (that re-opens D72's Node 24 abort), or attempting
1009
+ to fix either upstream bug here.
1010
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.1(2026-10-04)"The Node floor is 22.14, because the driver says so (D74)".*
1011
+
1012
+ - **D73 — one user statement, one memory: the keyword hook hands off to the
1013
+ agent.** The keyword hook and the agent are two writers for one user turn,
1014
+ and only one of them knows the sentence is already stored. Observed
1015
+ 2026-10-04: a single `remember this folder is for my spark tank ideas …
1016
+ shared memory across agents and employees` produced **three** memories — one
1017
+ `source: keyword` verbatim capture plus two `source: tool` paraphrases the
1018
+ agent wrote because it could see the chat transcript but not the store. The
1019
+ existing §3.4 guard could not catch it: token Jaccard scored those
1020
+ paraphrases 0.21–0.38 against the capture, below the 0.8 near-dup bar, and
1021
+ `open-memex audit` reported zero near-dup pairs, so the store looked healthy
1022
+ while holding three copies of one statement (retrieval then returns all
1023
+ three). Two mechanisms, deliberately layered:
1024
+ **(a) hand-off note** — `captureFromText` records each capture against the
1025
+ host session id (`chat.message` / v2 `prompt`, both of which carry one), and
1026
+ the system-context hook (`experimental.chat.system.transform` / v2
1027
+ `context`) pushes a short block naming what was already stored, delivered
1028
+ once per capture and pruned after the turn window. The agent can now avoid
1029
+ the duplicate write it had no way to see. In-memory only, like
1030
+ `injectedSessions`: never persisted, gone on restart.
1031
+ **(b) turn-echo guard** — `memory_add` additionally refuses a write that
1032
+ overlaps a `source: keyword`/`user` memory created in the same scope within
1033
+ the last 10 minutes, returning the stored id and pointing at
1034
+ `memory_supersede`. This is the deterministic backstop for the case where
1035
+ (a) is ignored. It is deliberately scoped and high-barred, because lexical
1036
+ overlap **cannot** separate an agent's gloss from a genuinely new fact: in
1037
+ the same measured set, the agent's gloss scored 0.211 and a distinct fact
1038
+ the same sentence happened to contain scored 0.214. So the bar sits at
1039
+ 0.28 — wholesale re-saves of the captured sentence measure 0.29–0.36 and are
1040
+ refused; anything below is left to (a) and the agent's judgment, and a
1041
+ refusal always names the stored id so the caller can rephrase to the new
1042
+ part or supersede. Agent-authored `source: tool` saves keep the old 0.8
1043
+ near-dup *notice* and are never refused. The refused case is recoverable by
1044
+ construction (supersede, or a follow-up add carrying only the new
1045
+ information), and no D14-style masking, dedup, or lifecycle rule changes.
1046
+ What is deliberately NOT done: no fuzzy-matching upgrade (D73 measures why a
1047
+ better metric still cannot decide "new information"), no auto-merging of the
1048
+ agent's gloss into the capture, and no transcript store (the replay-distillation
1049
+ open question owns that).
1050
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "One thing you said is one memory (D73)".*
1051
+
1052
+ - **D72 — the Node SQLite driver moves to the N-API line.** The D70 suite was stable on Windows and failed in shifting clusters on Linux under Node 24.20: individual CLI processes intermittently died with `SIGABRT` in `Statement::~Statement()` (`RemoveEnvironmentCleanupHook ... Assertion failed: (env) != nullptr`) and lost their stdout, so unrelated supersede / submit / inventory checks failed depending on which process the GC reaped. The work itself had always landed; only the exit path was broken. Root cause is upstream: Node 24.19 changed `node::ObjectWrap` cleanup-hook registration, and `better-sqlite3` <13 (raw `node::ObjectWrap`) can finalize a prepared statement from a GC callback with no Environment entered. `better-sqlite3` 13 is the N-API rewrite and removes that path; it still supports Node ≥22, and every API this repo uses (`Database`, `prepare`, `exec`, `pragma`-style PRAGMAs, `close`) is unchanged. The suite's crash-retry shim stays as belt-and-braces for older installs, but the shipped driver no longer needs it on current Node. Verified: three consecutive Linux `test-full` runs at 114/114 plus a 40-command add/list/search loop with zero aborts (was ~50% per process).
1053
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "Node 24 CLI aborts: SQLite driver moves to the N-API line (D72)".*
1054
+
1055
+ - **D71 — the scope seed is the folder opened, never a filesystem root.**
1056
+ OpenCode v1 hands the plugin two roots: `worktree` (the repo root — but
1057
+ the filesystem root itself, `C:\` or `/`, when the opened folder is not a
1058
+ git repo) and `directory` (the folder actually opened). The v1 adapter
1059
+ preferred `worktree`, so every non-git folder on a drive seeded its scope
1060
+ on the drive root and collapsed into one shared
1061
+ `project__workspace__<hash of the root>` bucket — a `c:\temp` project
1062
+ landing in `project__workspace__3dc8472eaebe` (seed `c:\`) is what
1063
+ surfaced it. `pickScopeRoot` (src/scope.ts) now takes `worktree` only when
1064
+ it is a real directory below the filesystem root, else `directory`. The
1065
+ repo-root behavior is unchanged: a real worktree still wins, so opening a
1066
+ repo subfolder keeps the repo's scope. Memories already written under a
1067
+ root-seeded key stay where they are (no auto-migration, per the existing
1068
+ rule); `open-memex scopes` shows the stray bucket and
1069
+ `open-memex migrate --from <old-key>` moves them. The v2 adapter already
1070
+ seeded on the opened directory and is unaffected.
1071
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "Non-git folders shared one scope bucket (D71)".*
1072
+
1073
+ - **D70 — visibility follow-ups: one number, one guard, one truth.** The
1074
+ 3-C review of D68/D69 found the surfaces honest individually and
1075
+ inconsistent with each other. (1) **Every visibility surface discloses
1076
+ truncation.** `memory_list` did; `open-memex list` — the command a
1077
+ sceptical user runs first — silently showed 20 of 25. It now renders
1078
+ the same structured line as the tool and states how many entries it
1079
+ dropped, naming the command that shows everything. (2) **Numbers are
1080
+ unique within a listing.** Ordinals ran per scope, so a single
1081
+ `scope: both` output contained two `#1`s and "delete #3" was a guess;
1082
+ the counter now runs across every section of one listing (tool, CLI and
1083
+ the text report). (3) **A correction that touches the repo says so.**
1084
+ The hard delete already did (D64); the soft hide did not, so a
1085
+ retraction of an in-repo memory read as "hidden" while it was only a
1086
+ local working-tree edit — the team still had the memory. Both surfaces
1087
+ now name the commit and push. (4) **The report guard fails closed and
1088
+ exists once.** `isInsideWorkTree` ran `git -C` on the output's parent
1089
+ directory, so a not-yet-created directory made the check throw and
1090
+ report "not in a worktree" — a fail-open on the one path where personal
1091
+ memories would ride a commit; it now resolves the nearest existing
1092
+ ancestor, reports a missing directory as itself, and both formats share
1093
+ a single refusal helper instead of two copies. (5) **`open-memex-inventory/2`**
1094
+ drops the absolute `file` path: the JSON renderer exists to be handed to
1095
+ an agent, i.e. pasted into a cloud conversation, and it carried the
1096
+ user's home directory. (6) Smaller honesty fixes: an empty scope is
1097
+ reported as `(0)` instead of vanishing; only the HTML audit view loads
1098
+ the hidden rows themselves (text/json pay for counts); the page's
1099
+ "no network requests" claim is now enforced by a `default-src 'none'`
1100
+ CSP rather than asserted; and `countList`'s comment states its one known
1101
+ divergence (a self-healed dangling chain pointer) instead of claiming
1102
+ equivalence. Deliberately NOT done, pending a decision: HTML i18n and a
1103
+ size cap for very large stores.
1104
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.0 "Visibility follow-ups: one number, one guard, one truth (D70)".*
1105
+
1106
+ - **D75 — closed questions leave the list; competitor-inspired directions enter it (2026-10-04).** The Open Questions section is a working list, not an archive: the entries decided in D56 (host parity), D57 (retrieval explainability / memory health), D61 (checkpoint proactivity, capture criteria, retrieval layers 2–3), and D68 (memory visibility), plus the retrieval-robustness entry whose three cheap layers all shipped, are removed; the decisions remain the record. A same-day scan of five Glama-listed memory servers (auxly-memory-cli, agent-memory, remnic, Agent-Memory-Bridge, memtomem, memryzed) confirmed the current wedge — proactive in-session capture + one memory shared across editors + PR-based team sharing — appears in none of them whole. Borrowable directions are recorded instead: four new open questions (retrieval evaluation gate, per-client trust levels, cold-start import, session working state) and one roadmap candidate (`doctor` mis-registration check). Nothing here commits implementation; each direction needs its own design pass.
1107
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.3 "Design doc maintenance (D75)".*
1108
+
1109
+ - **D76 — tool annotations must tell the truth (2026-10-05).** `memory_pr_status` declared `readOnlyHint: true` while `apply=true` writes local review states (caught by Glama's TDQS evaluation of v0.7.2, 4.0/5). Structured hints are part of the protocol surface: all 11 tools now declare read-only / destructive / open-world hints that match their behavior, descriptions route between sibling tools instead of leaving agents to guess, and `scripts/smoke-mcp.ts` guards the pr_status combination. Description honesty is held to the same standard as behavior: ranking claims, defaults, and error semantics in tool text must match the code.
1110
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.7.3 "Tool-definition quality pass (Glama TDQS 4.0/5 on v0.7.2): D76".*
1111
+
1112
+ - **D77 — measure usefulness by reuse, not storage (2026-10-07).** The Spark Tank submission commits the metric: "measured by reuse — fewer repeated questions, less context-prep time, approved memories reused by non-authors — not by memory count." Three layers, in build order: (1) **Offline retrieval eval.** A synthetic fixture (memories + queries with gold ids) run against the FTS5 baseline; publish recall@k/MRR in the README. This also answers the D75 "retrieval evaluation gate" open question — the number gates any future semantic-layer decision (reference points: agentmemory's published LongMemEval-S R@5 95.2%; lotargo/memory_plugin's BM25-only vs hybrid table). Later, run the MemoryAgentBench harness for directly comparable numbers (Knowl 90 / Mem0 18 / MIRIX 14 / Zep 7). (2) **Online reuse counters.** Per memory: `retrieved_count` (returned by search/list/first-turn injection) and `useful_count`, split into `useful_self` (author's own reuse — the personal-utility story) and `useful_team` (reuse of published project memories across sessions — the Spark Tank "reused by non-authors" story; no identity system needed: published state plus session diversity is the proxy). Both count as useful; reporting them separately keeps the team-knowledge claim honest. Explicit confirmation: a `memory_useful` tool call, human approve at review; behavioral: supersede/promote referencing it. Passive surfacing must never refresh usefulness — the opencode-memory lesson: unguarded exposure creates a self-reinforcing retrieval loop. Derived: `reuse_rate = useful / retrieved`; "zombie memories" (retrieved but never confirmed useful) surface in `memory_status` as decay/prune candidates. Counters live in SQLite, not frontmatter; local-only. (3) **Status surfaces.** `memory_status` gains a reuse report: top reused, zero-reuse list, per-scope reuse rate — feeding the Spark Tank pilot metrics. Moat note: competitors' "useful" is agent self-reported; our review ladder gives a human-grounded signal — approved/published means a human already said it is worth sharing. **Priority: this is the next build after 0.7.3** — fixture eval first (1–2 days, publishable number), then counters + `memory_useful`, then the status report, then the external bench.
1113
+ *Status (2026-11-03): 部分实现 — 第 1 层 eval 已发;第 2 层已实现(0.9.0-alpha.2:`memory_usage` 表(独立于可重建索引,跨 rebuild 存活)+ `retrieved_count`/`useful_self`/`useful_team` + `memory_useful` 工具与 `open-memex useful` CLI;分类代理:personal 或未评审项目草稿→self,approved/published 项目记忆→team;supersede 与评审 approve 各自动计一次 useful;曝光只走 search/list/injection 的显式 `record` 开关);第 3 层(reuse 报告)未实现.*
1114
+
1115
+ - **D78 — pre-submit curation: human-on-the-loop, not in-the-loop (2026-10-07).** Fragmented captures must be organized before submit, but the submitter's patience is the scarce resource — every manual gate lowers the submit rate, so curation defaults to automatic and the human handles exceptions. Confidence tiers: **auto-apply** (exact duplicates, trivial fragments, inferred type/tags, title normalization); **batch-confirm** (semantic merges, splits — one summary screen, one tap to accept or undo, never per-item approval); **explicit human decision** (dropping substantive content, and submit itself — the D-hard boundary "project scope never auto-submits" stands: automation covers organizing, sharing stays human). The safety net is the supersede chain: every auto-merge preserves provenance and is undoable, so pre-approval is replaced by reversibility (undo-send, not confirm-dialog). Trigger: no new step to remember — `submit` becomes curate+submit in one command, with the curation summary attached to the PR description; session wrap-up is the alternative hook (batch-silent, per the D61 checkpoint posture). Closed loop: human undos feed back into confidence thresholds, consuming the D77 `useful_count` signals. This revises the earlier review-ladder instinct of per-item approval: the human moves from in-the-loop to on-the-loop.
1116
+ *Status (2026-11-02): 未实现 — 纯设计条目:confidence 三档(auto-apply / batch-confirm / explicit human)、`submit` 变 curate+submit、undo-send 替代 pre-approval 均无代码.*
1117
+
1118
+ - **D79 — query-time synonym expansion with a second-chance round (2026-10-07).** Fourth retrieval layer after D56 (query construction) and D61 (agent-side expansion guidance, capture-time aliases): a curated, checked-in synonym map (`src/retrieve/synonyms.ts` — EN dev-domain groups plus ZH groups, bidirectional) applied at query time. `search()` runs round one unchanged; when it returns fewer candidates than requested, round two re-runs with synonym variants OR-ed in and fills only the gaps — round-one ids and scores are never diluted by the expansion. Deliberately not embeddings and not an LLM call: deterministic, auditable, zero dependencies; a bad synonym is a visible line in the file, not a silent vector. `SearchStats.secondRound` records whether the round ran (surfaced in `search --explain`). Eval proof: 3 synonym-only fixture queries are unanswerable in round one by construction (their words appear in no memory); round two answers 2 of 3 at rank –2. Baseline with the round: recall@1 0.81, recall@5 0.95, MRR 0.87 over 37 queries. Follow-ups, not in this change: feedback-weighted ranking once D77 counters land; the embeddings gate decision against these numbers; reranker evaluation. **Update (2026-10-07, LongMemEval-S):** measured on 470 questions (recall_any@k protocol, per-question isolated corpora): R@1 86.0% / R@5 97.0% / R@10 98.3% / MRR 0.909 — ahead of agentmemory’s published BM25-only (86.2% / 94.6% / 0.715) and level with their BM25+vector (95.2% / 98.6% / 0.882). But the second round fired on **0 of 470** queries: the `raw.length < limit` trigger never trips once the corpus fills the page — the round as designed is a thin-corpus fallback, not a scale answer. A pooled 22k-memory stress run drops R@5 to 40.6% (the lexical ceiling, now measured instead of asserted). Consequence: the trigger needs a redesign (score/coverage-based, or always-expand-with-fusion) before the round can claim the scale story; the pooled number is the baseline an embedding layer must beat. **Ablation (2026-10-07, same bench):** OFAT over the lexical factors, limit=10, effect on MRR: OR semantics **+0.652** (AND collapses to 0.257 — the load-bearing wall); prefix matching **-0.010** (disabling it lifts R@1 86.0%→87.9% — mildly harmful, needs a second dataset before acting); stopword filtering **+0.005** (keep: cheap, principled); synonym round **0.000** at every limit and scale tested. Limit sweep: R@1 is invariant to limit (86.0% at 1–50); returns flatten at limit 5 (R@5 97.0%, +1.3pp to go to 50); round-2 fired 10/470 at limit=50 and rescued nothing (identical to no-synonyms). Pooled 22k at limit=50: R@5 still 40.6%, round-2 fired 0. Reading: the lexical lemon is squeezed — OR does the work, the rest is ±0.01. The next gains must come from ranking under distractors (embedding/reranker layer), not more lexical tweaks. Rescue experiment (same day): fallback-append vs always-expand+RRF-fusion, 470q, stratified by query–gold overlap — **zero rescues** under either design, at either scale; not one question changes outcome. The 8 residual misses are reasoning problems (preference/multi-hop/temporal), not vocabulary gaps. The round’s value lives in a mismatch slice the public data barely contains (proven on constructed queries: 2 of 3 rescued). Keep the curated map; stop spending design budget on the trigger. (Superseded same day: index-time expansion, see backlog.)
1119
+ *Status (2026-11-02): 已废弃 — 按子句状态:query-time 第二轮机制**已废弃**(D80 的 index-time expansion 取代).*
1120
+ - **D80 — index-time synonym/translation expansion (2026-10-07).** Supersedes D79's query-time second round (removed from `search()`; `SearchStats.secondRound` gone): the curated map (`src/retrieve/synonyms.ts` — EN dev-domain groups, ZH groups and EN↔ZH translation pairs merged into one bidirectional group list) is applied at sync/index time. `writeRow` expands each memory's keywords via `expansionVariantsForDoc()` and appends the variants to the indexed `aliases` column (FTS and CJK-bigram columns both pick them up), so any related word matches in a plain round-1 query. Query side: single FTS round, no trigger, no second chance. Keyword-centric per Stone ("重要的是关键词"): Latin content terms (same stopword filter as the query builder, so both sides agree on what a keyword is) + CJK substring matching + multi-word Latin phrases (`regression test`); variants already present in the text are skipped; capped at 32 per memory to bound index growth. Derived at sync time — the Markdown file stays the source of truth; a map update needs a reindex to backfill. *Rationale: the precise slice (exact EN↔ZH pairs like 单点登录/SSO) must never be missed, and embeddings are fuzzy where the map is exact; paying the cost once at write time keeps every query simple and trigger-free.* Eval on the 41-query cross-lingual fixture: recall@1 0.732 → 0.756, recall@5 0.854 → **0.976**, MRR 0.791 → **0.859** — all 5 EN↔ZH vocabulary misses rescued at rank 1–3. Known trade-off: a single-keyword query can rank an aliases-only hit below shorter docs sharing the variant (`how do we ship`: rank 2 → 8 — its hit is 1 of 15 variants on a long aliases field); accepted, the old rank depended on the fragile thin-corpus trigger. `expandQueryWithSynonyms` kept as a bench-only export.
1121
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.8.0 "Index-time synonym/translation expansion (D80, supersedes D79)".*
1122
+ - **D81 — user-defined alias vocabulary as query-time expansion (2026-10-07).** Stone: an alias should be a *kind of memory* — defined once, remembered forever. Any memory type may carry `alias:` (the nickname, e.g. 香蕉计划) and `target:` (what it refers to, e.g. 支付系统重构项目) frontmatter; the alias memory defines vocabulary once per scope. At query time (`src/retrieve/alias-memory.ts`), query terms are looked up against the alias registry — one cheap `SELECT` per `search()` call over rows with non-empty alias+target (trigger A: exact registry hit, never a count heuristic; the D79 0/470 trigger is not repeated). On a hit the query is rewritten with the other side of the relation — bidirectional (alias→target and target→alias), depth < 3, cycle-safe — and re-run as round 2 (round 3 for chains). Rounds merge by normalized-max (`mergeRounds`): each round's BM25 scores are divided by that round's best (raw cross-round scores are incomparable — °C vs °F), then final = max, so an alias-side champion competes evenly with a literal-side champion — alias hits are never down-weighted for coming from a later round. Merged pool is re-ranked then cut to [1.5K, 2K] (Stone) — never back to K, or round-2 hits would be starved the way D79's slice-to-K starved them. No reindex when an alias changes (query-time). Scope-aware: a project codename stays in its project. *Rationale: D80's curated map is static and shared — personal vocabulary (小宝贝, 香蕉计划) doesn't belong in it; per-memory D61 aliases don't propagate to new memories. Alias memories close the gap: user-defined, scope-aware, effective immediately.* v1: user-explicit creation only (`memory_add` alias/target params, CLI `--alias`/`--target`, frontmatter edit); agent-proposed aliases deferred. D81 also rewords the init `captureAliases` prompt (it is not the synonym switch — D80's expansion always applies). Eval: 3 new fixture queries (香蕉计划↔支付系统重构项目 both directions + the alias memory itself), 44 queries total: recall@1 0.750, recall@5 **0.977** (43/44), MRR 0.857 — the single miss remains `how do we ship` (known D80 trade-off).
1123
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.8.0 "User-defined alias vocabulary as query-time expansion (D81)".*
1124
+
1125
+
1126
+ - **D82 — closed `type` taxonomy on search/list (2026-10-07).** Follow-up deferred from the TDQS pass (#50), closes issue #51: `memory_search` / `memory_list` `type` is now `z.enum(MEMORY_TYPE_TAXONOMY)` instead of `z.string()` — a misspelled type (`"decisions"`) is rejected at the schema (MCP -32602) instead of returning zero results the agent can't distinguish from "no memories of that type". Hard rejection, not a soft "no matches" message: closed taxonomy + fail-fast. Existing rows with non-taxonomy types are possible (the frontmatter parser only coerces the v1 `instruction` → `knowledge` case) and are unaffected — they still surface in unfiltered search/list, they just can't be addressed by a type filter. The opencode plugin shares the same args objects, so both surfaces tighten together; `scripts/smoke-mcp.ts` guards the rejection. `memory_submit` keeps `destructiveHint: false` — settled in the #50 review (the outbox unlink happens after the repo copy is committed and hash-verified, so it's recoverable from git); recorded here so it isn't re-litigated.
1127
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.8.1 "memory_search / memory_list type is now a closed enum (D82, closes #51)".*
1128
+
1129
+ - **D83 — D80 expansions get their own index column (2026-10-07).** Design follow-up to issue #56 (deferred from the D80 review): the curated index-time variants (`expansionVariantsForDoc`) move out of the `aliases` column into a dedicated `expansions` column — on `memories`, on `memories_fts`, and in the ai/ad/au triggers. `writeRow` stores user/authored aliases in `aliases` and derived variants in `expansions` (still filtered against the supplied set, still never written to Markdown); the `cjk` bigram column keeps covering body + tags + aliases + expansions so CJK variants stay substring-searchable. Retrieval: the FTS MATCH set gains the column with its own bm25 weight (at or below `aliases` — the fixture is the gate, tune don't guess); `SearchHit.aliases` and the `(aka: …)` attribution surface only user-authored aliases; `search --explain` reports which column matched (alias vs expansion). Migration: `SCHEMA_VERSION` 8 → 9; the bump triggers `rebuildIndexSchema`, which repopulates from Markdown — safe because expansions are derived and Markdown is untouched.
1130
+ *Update (2026-10-07, implemented and measured):* the `how do we ship` rank did **not** improve (still 8) — the dilution for expansion-column matches is inherent to per-column BM25 length norm (32 variants in their own column dilute about as much as 36 did in the shared one), not to the mixing. What the split fixed is provenance (`(aka:)` / `SearchHit.aliases` are user-authored again) and the dilution of deliberate user aliases (a ≤4-term column now scores cleanly). Regression gate passed: `retrieval-eval` R@1 0.750 / R@5 0.977 / MRR 0.857, identical to pre-split; v8→v9 migration verified on a scratch DB (merged aliases re-split correctly, `user_version` 9). *Rationale: an agent reading `(aka: …)` must be able to trust it means "alternate phrasings someone attached to this memory", and a 32-variant derived list must not dilute the weight of 4 deliberate ones.*
1131
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.8.1 "D83 (implemented, for #56)".*
1132
+ - **D84 — `limit` is a cap on the return, never a hint (2026-10-07).** Correction to D81's cut rule, raised by the review of #52. D81 widened the merged alias pool to `[1.5K, 2K]` and passed that widened value to `resolveVisible` as the slice — so when an alias round fired, `search()` returned up to **2× `limit`** rows to every caller (`memory_search`, the MCP tool, `cli search`), with nothing in `--explain` saying so. The pool stays wider than `limit` — each round already over-fetches by `fetchLimit`, and the starvation D79's slice-to-K caused is real and still prevented — but the *return* is cut to `limit`. (D81's `1.5K` line was also dead: `max(min(pool,2K), min(pool,1.5K))` is always `min(pool,2K)`, so the documented band never existed; it is gone.) No ranking change — the merge sorts before any cut, so top-k is byte-identical; `scripts/retrieval-eval.ts` unchanged at R@1 0.750 / R@5 0.977 / MRR 0.857. *Rationale: `limit` is a contract on what a caller receives. Headroom belongs inside the ranking, not in the result set — an agent paying 2× the tool-result tokens on alias-touching queries has no way to see that it happened.*
1133
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.8.1 "fix: search() honours the caller's limit again (#53)".*
1134
+ - **D86 — the `expansions` BM25 weight, set by the fixture (2026-10-07).** Closes the two D83 clauses that were written into the decision log but never landed in code (`00c4d2d` shipped `bm25(memories_fts)` with no weight vector, and left `--explain` reporting only `fts:` / `candidates:` / `alias rounds:`). (1) **Weight vector** — `bm25(memories_fts, …)` now takes an explicit `[content, tags, aliases, expansions, type, cjk]`, with `expansions` at **0.75** (`src/retrieve/weights.ts`, kept out of `search.ts` so `smoke-pure.ts` keeps its no-sqlite guarantee). The measurement that sets it: on equal-length docs at weight 1.0, a direct body match and an expansion-only match score **identically** (`-3.983` vs `-3.983`) — the preference was being decided by tiebreak, not by the ranking function. Any weight < 1.0 breaks that tie toward the body. `0.75` is the *highest* weight the checked-in fixture cannot distinguish from 1.0 (sweep: 1.0 / 0.9 / 0.75 all yield R@1 0.750 / R@5 0.977 / MRR 0.857; 0.5 already costs MRR; below 0.35 R@5 breaks), so the ordering guarantee is free and the fixture remains the gate — retune by re-running the sweep, never by intuition. `SearchHit.matchedVia` (`body` | `alias` | `expansion` | `other`) is computed from the same per-column highlights the attribution already used. (2) **`--explain` attribution** — prints `matched via: body=N alias=N expansion=N other=N` alongside the active weights, so a surprising rank is traceable to the column that caused it. *Rationale: D83 promised the split would make the two columns distinguishable; on equal-weight columns they were not distinguishable at all, so the split bought provenance without buying ranking. This is the missing half.* **Explicit non-goal:** this does *not* repair D80's `how do we ship` rank-8 case — that is per-column length norm (one variant among many in a long `expansions` field), not a weighting problem. Fixing that means narrowing *what* lands in the column, not re-weighting it. Fixture unchanged: R@1 0.750 / R@5 0.977 / MRR 0.857.
1135
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.8.1 "D83 follow-up: the two D83 clauses that shipped as design but not as code".*
1136
+ - **D85 — the alias registry is indexed, not cached (2026-10-07).** From the same review (#55). D81's `loadAliasEntries` runs on **every** `search()` call over `alias <> '' AND target <> ''` — a full table scan on a corpus that may be tens of thousands. Added `idx_memories_alias ON memories(scope_key) WHERE alias <> '' AND target <> ''` to `TABLE_SCHEMA`. Two deliberate choices: (1) **no `SCHEMA_VERSION` bump** — `TABLE_SCHEMA` executes on every db open, not only on rebuild, so `CREATE INDEX IF NOT EXISTS` is idempotent and existing installs pick it up on next open with no rebuild; this also keeps the bump free for D83's 8 → 9 schema change. (2) **No result cache** — the registry must be re-read per query so a newly saved alias memory applies on the very next query (D81's freshness property). An index accelerates the lookup without caching results; those two concerns are separable and this resolves only the first. Measured at 5k memories: 971ms → 39ms per 2000 scoped lookups (~25×), `EXPLAIN QUERY PLAN` confirms `SEARCH memories USING INDEX idx_memories_alias`. Note the *unscoped* variant of the query still prefers `idx_memories_status`; `search()` always passes `scopeKeys`, so the partial index is what ships. *Rationale: the alias table is tiny by construction — one row per defined nickname per scope — so its lookup cost must be proportional to aliases defined, not to store size.*
1137
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.8.1 "perf: partial index on the alias registry (#55)".*
1138
+ - **D87 — stale stores migrate before the schema is created (2026-10-28).** D85's "no `SCHEMA_VERSION` bump" reasoning was wrong for one population: stores created before D81 (`SCHEMA_VERSION` 7, ≤0.7.x) have no `alias`/`target` columns, and `CREATE TABLE IF NOT EXISTS` adds no columns to an existing table — so `CREATE INDEX IF NOT EXISTS idx_memories_alias ... WHERE alias <> ''` throws `no such column: alias` inside `db()` before the `userVersion < SCHEMA_VERSION` rebuild check ever runs, wedging every open (CLI, MCP, plugin) on that store. Reproduced with a faithful v7 fixture: current code throws exactly that error. Fix, ordering only: in `db()`, when the `memories` table exists but the version is old, `rebuildIndexSchema()` runs *before* `TABLE_SCHEMA`/`FTS_SCHEMA` are executed (the table exists, so rebuild's `DELETE` is valid); fresh stores still fall through to creation and the existing post-create version check is unchanged. No version bump — the guard is ordered before creation, so version 9 still covers the migration, and no new mechanism was needed. Regression test in `test-full.ts` §9 builds a v7 store and asserts the open succeeds, `user_version = 9`, and the three columns are present. The D85 comment in `db.ts` carries a correction note. *Rationale: the wipe-and-repopulate migration only works if it runs before the schema that assumes its result; the bug was ordering, not a missing mechanism.*
1139
+ *Status (2026-11-02): 已实现 — CHANGELOG 0.8.2(2026-10-28)"fix: a pre-D81 index store (SCHEMA_VERSION 7, ≤0.7.x) no longer wedges every open (D87)".*
1140
+
1141
+ - **D88 — knowledge graph & compiled wiki as a derived layer (2026-10-31).** A graph + LLM-maintained wiki (§20, v0.3 candidate) compiles knowledge from memories so it accumulates instead of being re-derived on every query. The graph/wiki is derived and rebuildable from raw memory files; it never touches the source of truth. Edges are typed (`relates-to` / `supports` / `contradicts` / `derived-from` / `supersedes`) with EXTRACTED/INFERRED provenance + confidence; inferred edges are always marked. Lint runs automatically before promotion and only reports (never auto-resolves). Semantic extraction of docs is confirmed at init (on/off); once on, the default backend is the API (most machines have no local model), local model via config. Compiled pages are Markdown files. *Rationale: RAG re-computes and never accumulates; a compiled graph/wiki makes knowledge compound, and the derived layer does not touch the source of truth (raw memory files), consistent with D1 and Principle 7. Graphify is the working implementation of this pattern on codebases (measured on muse-thinktank 2026-10-31: curated graph, 1029 nodes, edges tagged EXTRACTED/INFERRED with confidence); Karpathy's LLM Wiki is the original statement of the pattern (three layers / three operations).*
1142
+ *Status (2026-11-02): 未实现 — 纯设计条目(2026-10-31):typed edges + EXTRACTED/INFERRED provenance、promotion 前 lint、init 时确认语义抽取开关、API 默认后端、编译产物为 Markdown.*
1143
+
1144
+ - **D89 — session working state note (2026-11-02).** Closes the "Session working state" open question (open since 2026-10-04, deferred "until there is signal that users lose work context, not just facts"). The signal is Stone's 2026-11-02 request, following the Muse working-state comparison: durable knowledge is not enough — an interrupted task needs its working state to resume. Design adopted (§3.6): one ephemeral per-project Markdown note, agent-written at wrap-up, surfaced at session start alongside injection, outside the review ladder, 7-day default TTL. Answers the open sub-questions: contents are task summary / open files / last commands / where the work stands / next step; the writer is the agent at Stop (explicit user command where no Stop hook exists); the overlap with retrospective distillation is resolved by routing through the D61 checkpoint-proposal flow (the note is raw material, the ladder is the gate). Doc-level decision only — no code in this change; implementation is deferred to the §18 near-term backlog.
1145
+ *Status (2026-11-03): 已实现(0.9.0-alpha.1)— §3.6 落地:`src/working-state.ts`(写入/读取/过期/浮现块,`atomicWriteTextSync`、`redact` 照用)、`memory_workingstate`(第 12 个工具,插件与 MCP 同批)、会话开始浮现 `surfaceWorkingStateOnce`(插件两代适配器)、`audit` 增加 `workingStateExpired`、`open-memex wstate`(--clear)、配置 `workingStateEnabled`/`workingStateTtlDays`。**对原文的一个条款级修正**:opencode 插件 API 没有宿主 Stop 钩子(按已装 @opencode-ai/plugin 类型实地核对,Hooks 无 stop;SDK 事件里的 `session.idle` 每轮都触发,无法区分会话结束,也不生成内容),所以 opencode 的写入路径按 D"otherwise on an explicit user command"分支落地为 **指令 + 工具**——浮现块/工具描述/MCP 握手一致教 agent 在用户收尾信号时刷新;Claude Code 的 Stop 钩子归 Phase 2C 原生插件。权宜取舍(可接受):写笔记不过评审阶梯(从不入存储),`clear` 无墓碑直接删——§3.6 明说这是过期草稿。*
1146
+ - **D90 — working-state note implementation & write-path correction (2026-11-03).** Supersedes D89's Stop-hook assumption where reality differs: the opencode plugin surface (checked `@opencode-ai/plugin` Hooks today) has no `stop` hook, and the SDK `session.idle` event fires after every turn with no content the plugin could write — so the write path on opencode is instruction + tool (session-start block and tool description teach the agent to refresh the note when the user signals wrap-up), exactly the "explicit user command" branch D89 already allowed. The full feature lands: `memory_workingstate` as the 12th tool on both hosts (ops.ts once), session-start surfacing `surfaceWorkingStateOnce` (once per session, same in-memory Set discipline as injection), `audit` gains `workingStateExpired` (reports only, never auto-deletes — D57 posture), CLI `wstate` / `wstate --clear`, config `workingStateEnabled` (default on) + `workingStateTtlDays` (default 7, flat keys — the `loadConfig` merge is shallow, so nested objects would drop fields). The note passes through `redact()` on write (agent-composed command recall can quote credentials) and uses `atomicWriteTextSync` like every write path. A per-note `ttl_days` frontmatter frees the human edit from later config changes. `clear` has no tombstone — acceptable, per §3.6 the note is expired scratch. Claude Code's Stop hook arrives with the Phase 2C native plugin.