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
package/AGENTS.md CHANGED
@@ -12,7 +12,7 @@ via `prepublishOnly` — Node refuses `--experimental-strip-types` for files und
12
12
 
13
13
  - **opencode host** loads `src/index.ts` under embedded **Bun**. SQLite here is `bun:sqlite` (built-in).
14
14
  - **CLI** (`src/cli.ts`) and smoke tests run under **Node 22+** with `--experimental-strip-types`. SQLite here is `better-sqlite3` (native module).
15
- - **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same eleven memory tools to any MCP client (VS Code Copilot, Cursor, Claude Code). **stdout is the protocol channel — never log to stdout in `mcp.ts`; diagnostics go to stderr.**
15
+ - **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same thirteen memory tools to any MCP client (VS Code Copilot, Cursor, Claude Code). **stdout is the protocol channel — never log to stdout in `mcp.ts`; diagnostics go to stderr.**
16
16
 
17
17
  `src/store/db.ts` picks the backend at runtime by sniffing `globalThis.Bun`. Both backends share the same surface (`new Database(path)`, `.exec`, `.prepare().run/all/get`, `.close`). Any DB code you write must stay on that common subset — do not import `better-sqlite3` or `bun:sqlite` directly outside `db.ts`. The Node driver is pinned to the `better-sqlite3` 13 N-API line (D72): the pre-13 `node::ObjectWrap` build aborts intermittently on Node 24.19+ when a prepared statement is finalized by GC.
18
18
 
@@ -33,10 +33,12 @@ Consequences:
33
33
  npm install # once
34
34
  npm run typecheck # tsc --noEmit — the only lint/type gate
35
35
  npm run cli -- where | list | search "q" | add ... | forget <id> | reindex
36
+ npm run cli -- useful <id...> # D77-L2: explicit useful signal + cumulative counters
36
37
  npm run cli -- <command> --help # per-command help (AI assistants discover flags this way)
37
38
  npm run cli -- sync-status # last sync time/kind + outbox drafts + repo review states + uncommitted files
38
39
  npm run cli -- inventory [--format text|json|html] [--scope both] # what is remembered, in the open (D68); personal-bearing output refused inside a git worktree without --allow-personal
39
- npm run cli -- audit [--scope project|personal|both] # memory health: near-dup pairs, stale actives, broken chains, personal-in-repo (read-only)
40
+ npm run cli -- audit [--scope project|personal|both] # memory health: near-dup pairs, stale actives, broken chains, personal-in-repo, expired working-state notes (read-only)
41
+ npm run cli -- wstate [--clear] # show/clear the session working-state note (D89 §3.6; the file it prints is editable directly)
40
42
  npm run cli -- pull # fetch + fast-forward only (explicit; diverged = clean failure, never force-merge)
41
43
  npm run cli -- push # push current branch to remote (explicit only; open-memex never auto-pushes)
42
44
  npm run cli -- export [--scope project|personal|both] [--all] [-o <file>] # portable .tar.gz bundle (markdown + manifest); private excluded unless --all
@@ -124,6 +126,8 @@ Layout: `memories/<scope_key>/<id>.md` (YAML frontmatter + body) + `index.db` (S
124
126
 
125
127
  **Markdown files are the source of truth; `index.db` is rebuildable.** `syncScope()` (in `src/store/sync.ts`) reconciles the two by mtime on plugin load and before every CLI read. When adding new frontmatter fields, update `Frontmatter` in `src/store/markdown.ts`, the `memories` table in `src/store/db.ts`, and `upsertFromFile` in `src/store/sync.ts` together, and bump the reindex path.
126
128
 
129
+ D77-L2 counters are the one deliberate exception: `memory_usage` (in `index.db`, owned by `src/store/usage.ts`) holds `retrieved_count` / `useful_self` / `useful_team` keyed by memory id, is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema, and is NOT dropped by `rebuildIndexSchema` — accumulated telemetry has no Markdown source to rebuild from. They never go into frontmatter and never leave the machine. Only `memory_useful` (explicit), a human approve at review, and a supersede raise the useful side; passive retrieval (search/list/injection, opt-in via `record: true`) raises only `retrieved_count` — never "fix" this by counting exposure as useful.
130
+
127
131
  ## Scope keys
128
132
 
129
133
  - `personal` scope key is literal `"personal"` (v1 called this `user`; renamed in v2, design §19).
@@ -171,11 +175,22 @@ D67 rules for any new pattern: a trigger must be a **statement to the store**, n
171
175
 
172
176
  Context injection happens exactly once per session in `experimental.chat.system.transform`, guarded by an in-memory `Set<sessionID>` in `src/index.ts`. It is not persisted — restarting opencode re-injects on the next first turn.
173
177
 
178
+ **Working-state note (D89, §3.6) — scratch, not memory.** One ephemeral
179
+ per-project note at `<data root>/working-state/<scope_key>.md` (src/working-state.ts);
180
+ `memory_workingstate` (12th tool, both hosts) reads/writes/clears it, the
181
+ session-start block (`surfaceWorkingStateOnce`) surfaces it next to the
182
+ injection, `audit` reports expired notes, `cli wstate` is the human surface.
183
+ It never enters `memories/` or the index — keep it that way: anything worth
184
+ keeping routes through the checkpoint-proposal flow. opencode has no Stop
185
+ hook today, so the write path is instruction + tool; the tool description,
186
+ the surfaced block, the MCP handshake, `init` instructions and the skill must
187
+ keep saying the same thing.
188
+
174
189
  ## Design constraints — read the frozen design first
175
190
 
176
- `docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D74; open questions tracked at the end of the doc). Per its §12:
191
+ `docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D88 — log in `docs/design/decisions.md`; open questions tracked at the end of the doc). Per its §12:
177
192
  AGENTS.md answers "how should AI work here"; the design doc answers "why is it
178
- built this way" (principles, iron rules, the append-only decision log, currently D1–D74). Before changing
193
+ built this way" (principles, iron rules, the append-only decision log in `docs/design/decisions.md`, currently D1–D88). Before changing
179
194
  architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
180
195
  schema, MCP tools, CLI contract), read the relevant design section — the decision
181
196
  log records what was already considered and rejected.
@@ -201,10 +216,11 @@ breaking v1→v2 transition) shipped with 0.3.0. Full rules: `CONTRIBUTING.md`.
201
216
  - **Docs ship with code.** Every code change updates the docs it affects in the same commit:
202
217
  new/changed tools → `README.md` + `README.zh-CN.md` tool tables + MCP section (keep both
203
218
  languages in sync); behavior changes → both READMEs
204
- and the frozen `docs/V2-DESIGN.md` (append a `D<n>` decision entry, never rewrite history);
219
+ and the frozen design (append a `D<n>` decision entry to `docs/design/decisions.md`, never rewrite history);
205
220
  new commands → README CLI sections + this file's Commands. A change without its docs
206
221
  is not done. Anything deferred as "later" goes into the near-term backlog in
207
222
  `docs/V2-DESIGN.md` §18 the same day — unwritten later means never.
223
+ - **Design-doc status lines stay current.** The per-entry `*Status*` lines in `docs/design/decisions.md`, the §18 phase statuses and the Open Questions statuses in `docs/V2-DESIGN.md` are updated in the same PR that changes the implementation status — a feature shipping without its status line is not done. Status vocabulary: 已实现 / 部分实现 / 未实现 / 已废弃 / 待核实.
208
224
  - **Measurement before mechanism.** A retrieval change lands its fixture +
209
225
  baseline number in a commit with no retrieval change at all, so the delta is
210
226
  unambiguous. `scripts/retrieval-eval.ts` is the gate: no retrieval PR merges
package/CHANGELOG.md CHANGED
@@ -9,6 +9,16 @@ the `@alpha` tag are development snapshots and are not listed individually.
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
+ ## [0.9.0-alpha.2] - 2026-11-03
13
+
14
+ - D77-L2: measure usefulness by reuse (the D77 counters, layer 2). Each memory now carries local counters in a `memory_usage` table beside the rebuildable index (D77: counters live in SQLite, never in frontmatter, never off the machine): `retrieved_count` — incremented when a memory is actually returned by `memory_search`, `memory_list`, the CLI `search`/`list`, or the session-start injection — and the useful split, `useful_self` (personal memories and unpublished project drafts) vs `useful_team` (approved/published project memories). Only explicit signals raise the useful side: the new **`memory_useful`** tool (thirteenth MCP tool, seventh on the opencode plugin; also `open-memex useful <id...>`), a human approve at review (`promote` to approved), and a supersede. Passive exposure never counts as useful — the tool description, MCP handshake, READMEs, skill, and AGENTS.md all state the restraint so an agent that reads only one still behaves. `memory_usage` is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema and survives `rebuildIndexSchema` (ids come from the files); hard forget prunes the row, branch-switch removals do not. `memory_useful` returns counts plus `reuse_rate` (useful / retrieved, `n/a` when never retrieved). The D77-L3 reuse report (top reused, zero-reuse zombies, per-scope rates) remains open.
15
+
16
+ ## [0.9.0-alpha.1] - 2026-11-03
17
+
18
+ - Session working-state note (D89 → D90, new minor line): one ephemeral per-project Markdown note for resuming an interrupted task — task summary, open files, last commands, where the work stands, next step. The agent writes it at wrap-up via the new **`memory_workingstate`** tool (now the **twelve** tools on both the opencode plugin and the MCP server), it surfaces once at session start next to the first-turn injection (framed as scratch, never knowledge), it never enters `memories/` or the retrieval index or the review ladder, and anything in it worth keeping goes through the normal propose-first flow. TTL defaults to 7 days (`workingStateTtlDays`; `workingStateEnabled` gates the whole feature — both flat keys, settable via `config set`). Expired notes stay silent at session start and are reported by `open-memex audit`; `open-memex wstate` (`--clear`) is the human surface. The write passes through `redact()` and `atomicWriteTextSync` like every path. One correction to D89's wording, recorded as D90: the opencode plugin API has no Stop hook, so the opencode write path is the instruction + tool branch (the agent refreshes the note when the user signals wrap-up); Claude Code's Stop hook waits for the Phase 2C native plugin.
19
+
20
+ ## [0.8.2] - 2026-10-28
21
+
12
22
  - fix: the legacy-scope warning on plugin load now suggests the migrate command with an explicit `--to <current-scope>`. Without it, `--to` defaults to the scope of the directory the command runs from, so running the suggested command from the open-memex checkout would move the memories into the wrong scope. No behavior change: the warning condition and the migrate contract are untouched.
13
23
  - fix: a pre-D81 index store (SCHEMA_VERSION 7, ≤0.7.x) no longer wedges every open with `no such column: alias` (D87). D85's partial index references the `alias`/`target` columns D81 added, and `CREATE TABLE IF NOT EXISTS` adds no columns to an existing table — so the index creation threw inside `db()` before the version-check rebuild could run. `db()` now rebuilds a stale table *before* creating the schema; the Markdown files are the source of truth, so the rebuild is lossless. Regression test in `scripts/test-full.ts` §9 builds a faithful v7 store and asserts the open succeeds and the schema lands at version 9.
14
24
 
package/README.md CHANGED
@@ -137,19 +137,19 @@ depends on which path an editor uses:
137
137
 
138
138
  | Editor | Setup | Tools | Session-start recall | Keyword auto-capture |
139
139
  |---|---|---|---|---|
140
- | opencode (native plugin, recommended) | `open-memex init --client opencode --global` | 5 core tools | Built in — first turn of every session | Yes — `remember …`, `记住…` |
141
- | VS Code (Copilot) | `open-memex init --client vscode` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
142
- | Cursor | `open-memex init --client cursor` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
143
- | Claude Code | `claude mcp add open-memex -- open-memex mcp` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
144
- | Visual Studio 2022 17.14+ / 2026 | `open-memex init --client visualstudio` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
145
- | Codex and other MCP clients | `open-memex mcp --print-config` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
140
+ | opencode (native plugin, recommended) | `open-memex init --client opencode --global` | 6 core tools | Built in — first turn of every session | Yes — `remember …`, `记住…` |
141
+ | VS Code (Copilot) | `open-memex init --client vscode` | All 12 via MCP | Via MCP guidance* | No — the agent saves when you ask |
142
+ | Cursor | `open-memex init --client cursor` | All 12 via MCP | Via MCP guidance* | No — the agent saves when you ask |
143
+ | Claude Code | `claude mcp add open-memex -- open-memex mcp` | All 12 via MCP | Via MCP guidance* | No — the agent saves when you ask |
144
+ | Visual Studio 2022 17.14+ / 2026 | `open-memex init --client visualstudio` | All 12 via MCP | Via MCP guidance* | No — the agent saves when you ask |
145
+ | Codex and other MCP clients | `open-memex mcp --print-config` | All 12 via MCP | Via MCP guidance* | No — the agent saves when you ask |
146
146
 
147
147
  \* MCP has no hard session-start hook, so open-memex sends the agent guidance in
148
148
  the MCP handshake (including how many drafts are waiting) and `init` writes the
149
149
  fuller version into the editor's instruction files. In practice agents follow
150
150
  it; the opencode plugin is the only path with true built-in first-turn
151
- injection. The [Tools](#tools-the-agent-gets) section lists the 5 core tools
152
- and the 6 extra workflow tools, so the "5 vs 11" split is explicit.
151
+ injection. The [Tools](#tools-the-agent-gets) section lists the 6 core tools
152
+ and the 6 extra workflow tools, so the "6 vs 12" split is explicit.
153
153
 
154
154
  All editors on the same machine read and write the **same** memory — a
155
155
  constraint captured in VS Code is respected in opencode; a lesson learned in
@@ -265,7 +265,7 @@ open-memex init --client opencode --global --yes
265
265
 
266
266
  Merges the native plugin into your user-level `~/.config/opencode/opencode.json`
267
267
  (or `opencode.jsonc` if that's the file you already have) — one-time, every
268
- project picks it up, no per-project init. You get the 5 core tools, keyword
268
+ project picks it up, no per-project init. You get the 6 core tools, keyword
269
269
  auto-capture, and first-turn context injection. (A config file with comments is
270
270
  left untouched — `init` prints the line to add by hand.)
271
271
 
@@ -444,8 +444,8 @@ If a secret slips through anyway, `open-memex forget <id>` deletes the memory.
444
444
 
445
445
  ## Tools the agent gets
446
446
 
447
- The MCP server exposes eleven tools; the opencode native plugin exposes the
448
- five core ones (marked ●). The other six are the team-review workflow tools —
447
+ The MCP server exposes thirteen tools; the opencode native plugin exposes the
448
+ seven core ones (marked ●). The other six are the team-review workflow tools —
449
449
  they only matter once you share memories through Git.
450
450
 
451
451
  | Tool | What it does |
@@ -455,6 +455,8 @@ they only matter once you share memories through Git.
455
455
  | ● `memory_list` | List memories in a scope (`project`, `personal`, or `both`) as a numbered inventory; `include=all` is the audit view |
456
456
  | ● `memory_supersede` | Replace a memory with a newer version (keeps a supersede chain) |
457
457
  | ● `memory_forget` | Delete a memory by id (`soft=true` hides it instead — retracted, one-way) |
458
+ | ● `memory_workingstate` | Read/write/clear the per-project working-state note (§3.6, D89) — resumes an interrupted task; scratch state, never a memory |
459
+ | ● `memory_useful` | Mark a memory as useful (D77) — explicit confirmation only; exposure is counted separately as `retrieved_count` |
458
460
  | `memory_status` | Show the sync queue: outbox drafts, repo review states, uncommitted files |
459
461
  | `memory_submit` | Move named drafts into the repo memory dir (local branch + commit) |
460
462
  | `memory_propose` | Copy personal memories into the project scope as review candidates |
@@ -466,6 +468,19 @@ So an MCP-connected editor always has the full set; opencode's plugin covers
466
468
  capture and recall, and anything workflow-shaped goes through the CLI or an
467
469
  MCP-connected editor.
468
470
 
471
+ **Usefulness is measured by reuse, not storage (D77).** Every memory carries
472
+ local counters: `retrieved_count` — how often it was actually handed to the
473
+ agent (search results, lists, the session-start injection) — and useful
474
+ counts, split into `useful_self` (personal memories, unpublished project
475
+ drafts) and `useful_team` (approved/published project memories). Only
476
+ explicit signals raise the useful side: `memory_useful` when a person
477
+ confirms it paid off, a human approval at review, or a supersede. Passive
478
+ exposure never counts as useful — a memory that merely showed up in results
479
+ has shown nothing yet. Same-side CLI surface: `open-memex useful <id...>`.
480
+ Counters live in the local SQLite index only (never in the Markdown files,
481
+ never off this machine); the reuse report (top reused, zero-reuse zombies,
482
+ per-scope rates) rides the D77-L3 follow-up.
483
+
469
484
  ## Memory types
470
485
 
471
486
  Every memory has a `type` (what it is) and `tags` (what it's about). Eleven
@@ -833,7 +848,8 @@ Maintenance:
833
848
  open-memex where # show storage + config paths
834
849
  open-memex scopes # list project scopes with memory counts
835
850
  open-memex reindex # rebuild the SQLite index from markdown
836
- open-memex audit # memory health: duplicate pairs, stale memories, broken chains
851
+ open-memex audit # memory health: duplicate pairs, stale memories, broken chains, expired working-state notes
852
+ open-memex wstate # show the session working-state note (--clear deletes it)
837
853
  open-memex migrate --to-v2 [--dry-run] # v1 data → v2 (renames user scope to personal)
838
854
  ```
839
855
 
@@ -844,6 +860,23 @@ prefix every command with `node --experimental-strip-types src/cli.ts` (or
844
860
  `npm run cli -- <command>` for simple cases — npm swallows unknown `--flag`
845
861
  args, so prefer direct `node`).
846
862
 
863
+ ## Session working state
864
+
865
+ Beyond durable knowledge, the agent can leave **one ephemeral working-state
866
+ note per project** (§3.6, D89): task summary, open files, last commands, where
867
+ the work stands, next step. Written by the agent at wrap-up via the
868
+ `memory_workingstate` tool — opencode has no Stop hook today, so "wrap-up"
869
+ means when the user signals the session or task is ending (the Claude Code
870
+ path arrives with the native plugin work). The note surfaces automatically at
871
+ session start so an interrupted task can resume; it is scratch state, never a
872
+ memory, and expires after 7 days (configurable) — `audit` reports expired
873
+ notes, humans edit the plain file directly.
874
+
875
+ ```sh
876
+ open-memex wstate # show the note (age + expiry)
877
+ open-memex wstate --clear # delete it
878
+ ```
879
+
847
880
  ## MCP server
848
881
 
849
882
  The same memory tools over the Model Context Protocol, via a stdio server —
@@ -931,7 +964,7 @@ config: if it has comments, add the `"plugin"` line manually.
931
964
  Checks the Node version, config source, scope resolution for the current
932
965
  directory, and storage writability; verifies VS Code hasn't disabled MCP;
933
966
  then boots a real MCP server and runs `initialize` + `tools/list` against
934
- it — all eleven tools must show up. It also reports pre-rename `my-o-memory`
967
+ it — all thirteen tools must show up. It also reports pre-rename `my-o-memory`
935
968
  leftovers if any editor config still references the old package name.
936
969
 
937
970
  ## FAQ
package/README.zh-CN.md CHANGED
@@ -101,14 +101,14 @@ open-memex 用两种方式接编辑器:原生的 **opencode 插件**,和标
101
101
 
102
102
  | 编辑器 | 设置方式 | 工具 | 会话开始时回想 | 关键词自动捕获 |
103
103
  |---|---|---|---|---|
104
- | opencode(原生插件,推荐) | `open-memex init --client opencode --global` | 5 个核心工具 | 内置——每个会话第一轮 | 有——`remember …`、`记住…` |
105
- | VS Code(Copilot) | `open-memex init --client vscode` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
106
- | Cursor | `open-memex init --client cursor` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
107
- | Claude Code | `claude mcp add open-memex -- open-memex mcp` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
108
- | Visual Studio 2022 17.14+ / 2026 | `open-memex init --client visualstudio` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
109
- | Codex 与其他 MCP 客户端 | `open-memex mcp --print-config` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
104
+ | opencode(原生插件,推荐) | `open-memex init --client opencode --global` | 6 个核心工具 | 内置——每个会话第一轮 | 有——`remember …`、`记住…` |
105
+ | VS Code(Copilot) | `open-memex init --client vscode` | 经 MCP 全 12 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
106
+ | Cursor | `open-memex init --client cursor` | 经 MCP 全 12 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
107
+ | Claude Code | `claude mcp add open-memex -- open-memex mcp` | 经 MCP 全 12 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
108
+ | Visual Studio 2022 17.14+ / 2026 | `open-memex init --client visualstudio` | 经 MCP 全 12 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
109
+ | Codex 与其他 MCP 客户端 | `open-memex mcp --print-config` | 经 MCP 全 12 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
110
110
 
111
- \* MCP 没有硬性的会话开始钩子,所以 open-memex 在 MCP 握手中把引导发给助手(包括有多少草稿在等同步),`init` 还会把完整版写进编辑器的指令文件。实践中助手会遵循这些引导;只有 opencode 插件是真正的内置第一轮注入。[助手拿到的工具](#助手拿到的工具)一节列出了 5 个核心工具和另外 6 个工作流工具,"5 个 vs 11 个"的切分在那里写明白。
111
+ \* MCP 没有硬性的会话开始钩子,所以 open-memex 在 MCP 握手中把引导发给助手(包括有多少草稿在等同步),`init` 还会把完整版写进编辑器的指令文件。实践中助手会遵循这些引导;只有 opencode 插件是真正的内置第一轮注入。[助手拿到的工具](#助手拿到的工具)一节列出了 6 个核心工具和另外 6 个工作流工具,"6 个 vs 12 个"的切分在那里写明白。
112
112
 
113
113
  同一台机器上的所有编辑器读写的是**同一份**记忆——在 VS Code 里捕获的一条约束,在 opencode 里会被遵守;在 Cursor 里学到的教训,会出现在 Claude Code 面前。(不同机器之间不自动同步,见[常见问题](#常见问题)。)
114
114
 
@@ -191,7 +191,7 @@ open-memex init --client cursor
191
191
  open-memex init --client opencode --global --yes
192
192
  ```
193
193
 
194
- 把原生插件并入你的用户级 `~/.config/opencode/opencode.json`(如果你已有的是 `opencode.jsonc`,就并进那个)——一次设置,每个项目都生效,不用逐项目 init。你会得到 5 个核心工具、关键词自动捕获和第一轮上下文注入。(配置文件里有注释时它不会动,`init` 会打印要手动加的那一行。)
194
+ 把原生插件并入你的用户级 `~/.config/opencode/opencode.json`(如果你已有的是 `opencode.jsonc`,就并进那个)——一次设置,每个项目都生效,不用逐项目 init。你会得到 6 个核心工具、关键词自动捕获和第一轮上下文注入。(配置文件里有注释时它不会动,`init` 会打印要手动加的那一行。)
195
195
 
196
196
  同一套安装同时支持两个 opencode 世代:`init` 会同时写入 opencode 1 的写法(`"plugin"`)和 opencode 2 的写法(`"plugins"`),每个宿主只读自己的那把。opencode 1 要求 **1.18.29 或更新版本**。接线和已装宿主版本对不上,`open-memex doctor` 会报出来。
197
197
 
@@ -286,7 +286,7 @@ open-memex capture --dry-run "…"
286
286
 
287
287
  ## 助手拿到的工具
288
288
 
289
- MCP 服务器暴露十一个工具;opencode 原生插件暴露其中五个核心的(标 ●)。另外六个是团队评审工作流工具——只有当你通过 Git 共享记忆时才用得上。
289
+ MCP 服务器暴露十三个工具;opencode 原生插件暴露其中七个核心的(标 ●)。另外六个是团队评审工作流工具——只有当你通过 Git 共享记忆时才用得上。
290
290
 
291
291
  | 工具 | 做什么 |
292
292
  |---|---|
@@ -295,6 +295,8 @@ MCP 服务器暴露十一个工具;opencode 原生插件暴露其中五个核
295
295
  | ● `memory_list` | 以编号清单列出某个作用域(`project`、`personal` 或 `both`)的记忆;`include=all` 是审计视图 |
296
296
  | ● `memory_supersede` | 用新版本替换一条记忆(保留 supersede 链) |
297
297
  | ● `memory_forget` | 按 id 删除一条记忆(`soft=true` 改为隐藏——retracted,单向) |
298
+ | ● `memory_workingstate` | 读/写/清除每项目的工作状态笔记(§3.6,D89)——让被中断的任务得以续接;只是草稿状态,永远不会成为记忆 |
299
+ | ● `memory_useful` | 确认一条记忆有用(D77)——只认显式确认;被动的搜索/列表出现只计入 `retrieved_count`,绝不算有用 |
298
300
  | `memory_status` | 显示同步队列:outbox 草稿、仓库评审状态、未提交文件 |
299
301
  | `memory_submit` | 把指定的草稿移进仓库记忆目录(本地分支 + 提交) |
300
302
  | `memory_propose` | 把个人记忆复制到项目作用域,作为评审候选 |
@@ -304,6 +306,8 @@ MCP 服务器暴露十一个工具;opencode 原生插件暴露其中五个核
304
306
 
305
307
  所以 MCP 接入的编辑器永远是全套;opencode 插件主攻捕获与回想,工作流类的事走 CLI 或 MCP 接入的编辑器。
306
308
 
309
+ **有用性靠复用来衡量,不靠存储量(D77)。** 每条记忆带本地计数器:`retrieved_count`——它真正被递交给助手的次数(搜索结果、清单、会话开始注入);有用计数则拆成 `useful_self`(个人记忆、未评审的项目草稿)和 `useful_team`(approved/published 的项目记忆)。只有显式信号会抬升有用侧:`memory_useful`(人确认它帮上忙时)、评审中的人为 approve、或一次 supersede。被动曝光永远不算有用——记忆只是出现在结果里,还不能说明任何事。同侧的人用入口:`open-memex useful <id...>`。计数器只存在本地 SQLite 索引里(不进 Markdown 文件、不出这台机器);复用报告(复用最多、零复用的"僵尸"、各作用域复用率)由 D77-L3 后续跟进。
310
+
307
311
  ## 记忆类型
308
312
 
309
313
  每条记忆有一个 `type`(它是什么)和 `tags`(它关于什么)。内置十一种类型:
@@ -558,12 +562,22 @@ open-memex resolve [id-or-path]
558
562
  open-memex where # 显示存储与配置路径
559
563
  open-memex scopes # 列出各项目作用域及记忆计数
560
564
  open-memex reindex # 从 markdown 重建 SQLite 索引
561
- open-memex audit # 记忆健康检查:近重复对、陈旧记忆、断裂的取代链
565
+ open-memex audit # 记忆健康检查:近重复对、陈旧记忆、断裂的取代链、过期的工作状态笔记
566
+ open-memex wstate # 显示工作状态笔记(--clear 删除)
562
567
  open-memex migrate --to-v2 [--dry-run] # v1 数据 → v2(把 user 作用域改名为 personal)
563
568
  ```
564
569
 
565
570
  CLI 在 Node 22 下运行。从源码 checkout 跑时用内置的实验性 TypeScript 加载器(免构建步骤);发布到 npm 的包是预编译好的 JS(发版时 `npm run build`)。从源码 checkout 时,每条命令前面加 `node --experimental-strip-types src/cli.ts`(简单情况可用 `npm run cli -- <command>`——npm 会吞掉不认识的 `--flag` 参数,所以优先用直连 `node`)。
566
571
 
572
+ ## 工作状态笔记
573
+
574
+ 除了耐久知识之外,助手还可以给每个项目留下**一份临时工作状态笔记**(§3.6,D89):任务摘要、打开的文件、最后的命令、进度在哪、下一步。由助手在收尾时通过 `memory_workingstate` 工具写——opencode 目前没有 Stop 钩子,所以"收尾"指用户发出会话或任务结束的信号(Claude Code 路径等原生插件工作再做)。笔记会在会话开始时自动浮现,让被中断的任务得以续接;它只是草稿状态、永远不会成为记忆,7 天后过期(可配置)——`audit` 报告过期笔记,人可以直接编辑这个纯文本文件。
575
+
576
+ ```sh
577
+ open-memex wstate # 显示笔记(含年龄与到期)
578
+ open-memex wstate --clear # 删除
579
+ ```
580
+
567
581
  ## MCP 服务器
568
582
 
569
583
  同一组记忆工具,走 Model Context Protocol、经 stdio 服务器提供——不需要任何宿主专用插件。任何 MCP 客户端都能用 open-memex。
@@ -607,7 +621,7 @@ Windows 上已加载的 DLL 是锁定的:如果 open-memex 的 MCP 服务器
607
621
  你的编辑器配置里有注释(JSONC)或 JSON 不合法,open-memex 永不重写它无法安全解析的文件。`init` 已经把要加的确切片段打印出来了——手动粘贴进去就好。opencode 配置同理:有注释时,手动把 `"plugin"` 那一行加上。
608
622
 
609
623
  **感觉有问题——跑 `open-memex doctor`。**
610
- 它检查 Node 版本、配置来源、当前目录的作用域解析、存储可写性,并确认 VS Code 没有把 MCP 禁用;然后启动一个真实 MCP 服务器,对它跑 `initialize` + `tools/list`——十一个工具必须全部出现。它还会报告改名之前遗留的 `my-o-memory` 引用(如果某编辑器配置里还留着旧包名的话)。
624
+ 它检查 Node 版本、配置来源、当前目录的作用域解析、存储可写性,并确认 VS Code 没有把 MCP 禁用;然后启动一个真实 MCP 服务器,对它跑 `initialize` + `tools/list`——十三个工具必须全部出现。它还会报告改名之前遗留的 `my-o-memory` 引用(如果某编辑器配置里还留着旧包名的话)。
611
625
 
612
626
  ## 常见问题
613
627
 
package/dist/.build-stamp CHANGED
@@ -1 +1 @@
1
- eecf9dc5edc92158b13259175a22b0f40b5081d2768aaac87a1695a0ca34f0a4
1
+ a8f61bc31b972df3523d0cebe5e6664a9adc28108162385725a004ee6b116656
package/dist/cli.js CHANGED
@@ -10,12 +10,14 @@ import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatR
10
10
  import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.js";
11
11
  import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.js";
12
12
  import { search, list, countList, hitStateLabel } from "./retrieve/search.js";
13
+ import { recordUseful, getUsage, reuseRate, usefulCount, usefulKindFor, deleteUsage } from "./store/usage.js";
13
14
  import { DEFAULT_EXPANSIONS_WEIGHT } from "./retrieve/weights.js";
14
15
  import { formatInventoryLine, truncationNote } from "./retrieve/display.js";
15
16
  import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, normalizeAliases, } from "./store/markdown.js";
16
17
  import { loadConfig, configSource } from "./config.js";
17
18
  import { paths, projectRoot, isInRepoMemoryFile } from "./paths.js";
18
19
  import { redact } from "./redact.js";
20
+ import { readWorkingState, clearWorkingState, workingStatePath } from "./working-state.js";
19
21
  import { resolveMcpCommand } from "./init.js";
20
22
  import fs from "node:fs";
21
23
  import path from "node:path";
@@ -143,6 +145,17 @@ Retraction is one-way: a retracted memory cannot be set back to active
143
145
 
144
146
  Example:
145
147
  open-memex status 01ABC deprecated`,
148
+ useful: `Mark a memory as useful (D77): record that it demonstrably paid
149
+ off. Useful is split automatically — useful_self for personal memories and
150
+ unpublished project drafts, useful_team for approved/published project
151
+ memories. Only explicit confirmation counts; passive retrieval (search/
152
+ list/injection) is counted separately as retrieved_count, never as useful.
153
+ A supersede or a human approval also records a useful signal on its own.
154
+
155
+ Usage: open-memex useful <id...>
156
+
157
+ Example:
158
+ open-memex useful 01ABC`,
146
159
  forget: `Delete a memory by id. With --soft, hide it instead: the memory
147
160
  is retracted (out of lists and search, file kept). Retraction is one-way —
148
161
  save the content as a new memory to bring it back. If the memory lives in
@@ -387,7 +400,7 @@ Example:
387
400
  doctor: `Environment health check: Node version, config source, scope resolution,
388
401
  storage writability, VS Code MCP enablement (settings.json + system policy),
389
402
  then boots a real MCP server and runs initialize + tools/list against it —
390
- all eleven tools must show up.
403
+ all thirteen tools must show up.
391
404
 
392
405
  Usage: open-memex doctor
393
406
 
@@ -395,8 +408,8 @@ Example:
395
408
  open-memex doctor`,
396
409
  audit: `Memory health audit (read-only, reports never mutates): near-duplicate
397
410
  pairs among active memories, stale actives untouched for 90+ days, broken
398
- supersede chains, personal files found inside the repo memory dir, and
399
- index/file drift.
411
+ supersede chains, personal files found inside the repo memory dir, index/file
412
+ drift, and expired working-state notes (D89).
400
413
 
401
414
  Usage: open-memex audit [--scope project|personal|both]
402
415
 
@@ -405,6 +418,18 @@ Flags:
405
418
 
406
419
  Example:
407
420
  open-memex audit --scope both`,
421
+ wstate: `Show the project's session working-state note (D89, §3.6) — the
422
+ ephemeral scratch note the agent refreshes at wrap-up so an interrupted task
423
+ can resume. The file itself is plain Markdown and editable directly.
424
+
425
+ Usage: open-memex wstate [--clear]
426
+
427
+ Flags:
428
+ --clear delete the note (no tombstone — it is scratch, not knowledge)
429
+
430
+ Examples:
431
+ open-memex wstate
432
+ open-memex wstate --clear`,
408
433
  };
409
434
  function usage(exitCode = 1) {
410
435
  console.log(`open-memex CLI
@@ -416,6 +441,7 @@ Usage:
416
441
  open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
417
442
  open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
418
443
  open-memex status <id> active|deprecated|retracted|archived
444
+ open-memex useful <id...>
419
445
  open-memex forget <id> [--soft]
420
446
  open-memex propose <id...> --to project [--local-approve]
421
447
  open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
@@ -431,6 +457,7 @@ Usage:
431
457
  open-memex pr-status [--apply]
432
458
  open-memex reindex
433
459
  open-memex audit [--scope project|personal|both]
460
+ open-memex wstate [--clear]
434
461
  open-memex scopes
435
462
  open-memex migrate [--from <key>] [--to <key>]
436
463
  [--dry-run] [--on-conflict newer|overwrite|skip]
@@ -463,8 +490,8 @@ first-turn injection); \`--yes\` accepts all defaults, and non-terminal runs nev
463
490
  \`open-memex config set <key> <value>\` changes those settings after install.
464
491
 
465
492
  Once installed globally (\`npm i -g open-memex\`) the \`open-memex\` command is
466
- available directly: \`open-memex mcp\` starts the stdio MCP server (11 tools, a superset of
467
- the opencode plugin's five memory_* tools); \`open-memex mcp --print-config <client>\`
493
+ available directly: \`open-memex mcp\` starts the stdio MCP server (13 tools, a superset of
494
+ the opencode plugin's seven memory_* tools); \`open-memex mcp --print-config <client>\`
468
495
  prints a copy-paste MCP client config snippet.
469
496
 
470
497
  Scope defaults to \`project\` (derived from cwd's git remote or path).
@@ -656,6 +683,35 @@ async function main() {
656
683
  }
657
684
  const cfg = loadConfig();
658
685
  const project = resolveProjectScope(process.cwd());
686
+ // §3.6 (D89): human convenience surface for the working-state note —
687
+ // print it (with age/expiry) or delete it on request. The file itself is
688
+ // always editable directly; audit reports expired notes either way.
689
+ if (cmd === "wstate") {
690
+ const flags = parseFlags(rest);
691
+ if (flags["clear"] === "true") {
692
+ const gone = clearWorkingState(project.key);
693
+ console.log(gone
694
+ ? `working-state note cleared (${project.key})`
695
+ : "nothing to clear — the note is still on disk; delete it manually if it exists");
696
+ return;
697
+ }
698
+ const note = readWorkingState(project.key, cfg.workingStateTtlDays);
699
+ if (!note) {
700
+ console.log(`no working-state note for ${project.key} — the agent writes one at wrap-up (memory_workingstate); you can edit the file directly`);
701
+ return;
702
+ }
703
+ if (!cfg.workingStateEnabled) {
704
+ console.log("(working state is disabled in config — workingStateEnabled=false)");
705
+ }
706
+ console.log(note.expired
707
+ ? `EXPIRED — ${note.ageDays} day(s) old, ttl ${note.ttlDays} (ignored at session start; ` +
708
+ `audit keeps reporting it until the next wrap-up write or 'wstate --clear')`
709
+ : `updated ${note.ageDays} day(s) ago — expires after ${note.ttlDays} day(s)`);
710
+ console.log();
711
+ console.log(note.content || "(empty note)");
712
+ console.log(`\nfile: ${workingStatePath(project.key)}`);
713
+ return;
714
+ }
659
715
  // `migrate --to-v2` is a pure file operation (V2-DESIGN §19) — it runs
660
716
  // before the index is opened so it also works where the DB driver
661
717
  // isn't available.
@@ -752,6 +808,11 @@ async function main() {
752
808
  for (const f of r.personalInRepo)
753
809
  console.log(` ${f}`);
754
810
  console.log(` index drift: ${r.drift.filesNotIndexed} files not indexed, ${r.drift.rowsMissingFiles} rows missing files`);
811
+ // D89: expired working-state notes — reports only, never auto-deletes.
812
+ console.log(` expired working-state notes: ${r.workingStateExpired.length}`);
813
+ for (const w of r.workingStateExpired) {
814
+ console.log(` ${w.filePath} — ${w.ageDays} days old (ttl ${w.ttlDays}); 'wstate --clear' or the next wrap-up write refreshes`);
815
+ }
755
816
  return;
756
817
  }
757
818
  // `config` prints the effective configuration (defaults + file). No DB needed.
@@ -823,7 +884,7 @@ async function main() {
823
884
  }
824
885
  return;
825
886
  }
826
- // `mcp` starts the stdio MCP server (11 tools; the opencode plugin exposes 5).
887
+ // `mcp` starts the stdio MCP server (12 tools; the opencode plugin exposes 6).
827
888
  // Branched before db() — runMcpServer() does its own init, and stdout must
828
889
  // stay clean for the MCP protocol.
829
890
  if (cmd === "mcp") {
@@ -869,6 +930,7 @@ async function main() {
869
930
  type: flags.type,
870
931
  limit: flags.limit ? Number(flags.limit) : undefined,
871
932
  include,
933
+ record: true,
872
934
  });
873
935
  const total = countList(s.key, { type: flags.type, include });
874
936
  if (scopes.length > 1) {
@@ -912,6 +974,7 @@ async function main() {
912
974
  limit: flags.limit ? Number(flags.limit) : undefined,
913
975
  type: flags.type,
914
976
  stats,
977
+ record: true,
915
978
  });
916
979
  if (explain && stats) {
917
980
  console.log(`fts: ${stats.ftsQuery || "(empty query)"}`);
@@ -1120,9 +1183,43 @@ async function main() {
1120
1183
  }
1121
1184
  }
1122
1185
  deleteFromIndex(id);
1186
+ // D77-L2: hard forget prunes the usage row with the memory (the tool
1187
+ // path does the same); branch-switch removals go through syncScope and
1188
+ // keep counters for that reason.
1189
+ deleteUsage(id);
1123
1190
  console.log(`deleted ${id}`);
1124
1191
  return;
1125
1192
  }
1193
+ if (cmd === "useful") {
1194
+ // D77-L2: the explicit confirmation route for humans. Auto-split like
1195
+ // the memory_useful tool; unknown ids fail that id without touching
1196
+ // the rest of the batch.
1197
+ const ids = rest;
1198
+ if (ids.length === 0)
1199
+ usage();
1200
+ syncScope(project.key, "cli");
1201
+ syncScope(PERSONAL_SCOPE.key, "cli");
1202
+ let notFound = 0;
1203
+ for (const id of ids) {
1204
+ const row = db()
1205
+ .prepare(`SELECT scope, review_state FROM memories WHERE id = ?`)
1206
+ .get(id);
1207
+ if (!row) {
1208
+ console.error(`not found: ${id}`);
1209
+ notFound++;
1210
+ continue;
1211
+ }
1212
+ const kind = usefulKindFor(row.scope, row.review_state);
1213
+ recordUseful(id, kind, "tool");
1214
+ const u = getUsage(id);
1215
+ const rate = reuseRate(u);
1216
+ const useful = usefulCount(u);
1217
+ console.log(`useful (${kind}) ${id} — retrieved: ${u.retrieved_count}, useful_self: ${u.useful_self}, useful_team: ${u.useful_team}, reuse_rate: ${rate === null ? "n/a" : rate.toFixed(2)} (useful ${useful}/${u.retrieved_count})`);
1218
+ }
1219
+ if (notFound > 0)
1220
+ process.exit(1);
1221
+ return;
1222
+ }
1126
1223
  /** Positional args with flags (and their values) skipped. */
1127
1224
  function positionalArgs(argv) {
1128
1225
  const out = [];
package/dist/config.js CHANGED
@@ -7,6 +7,8 @@ export const DEFAULT_CONFIG = {
7
7
  injectOnFirstTurn: true,
8
8
  keywordCaptureEnabled: true,
9
9
  captureAliases: true,
10
+ workingStateEnabled: true,
11
+ workingStateTtlDays: 7,
10
12
  keywordPatterns: [
11
13
  "^\\s*remember(?!\\s+for\\s+me)(?:\\s+that|\\s+to)?[:,]?\\s+(.+)$",
12
14
  "^\\s*(?:please\\s+)?note(?:\\s+that)?[:,]?\\s+(.+)$",
@@ -150,6 +152,13 @@ export const SETTABLE_KEYS = {
150
152
  injectOnFirstTurn: toBool,
151
153
  keywordCaptureEnabled: toBool,
152
154
  captureAliases: toBool,
155
+ workingStateEnabled: toBool,
156
+ workingStateTtlDays: (v) => {
157
+ const n = toNonNegInt(v);
158
+ if (n < 1)
159
+ throw new Error("must be a positive integer (days)");
160
+ return n;
161
+ },
153
162
  memoryDir: toRelativeDir,
154
163
  "sync.autoPull": toBool,
155
164
  logLevel: (v) => {
package/dist/doctor.js CHANGED
@@ -13,7 +13,7 @@ import { resolveCwdScope } from "./scope.js";
13
13
  import { MIN_NODE_VERSION, nativeDriverFloorMessage, nodeSupportsNativeDriver, } from "./runtime-floor.js";
14
14
  import { db, backendName } from "./store/db.js";
15
15
  import { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.js";
16
- // D64: the MCP server exposes eleven tools; checking only the five the
16
+ // D64: the MCP server exposes thirteen tools; checking only the seven the
17
17
  // opencode plugin carries let a half-registered server pass as healthy.
18
18
  const EXPECTED_TOOLS = [
19
19
  "memory_add",
@@ -21,6 +21,8 @@ const EXPECTED_TOOLS = [
21
21
  "memory_list",
22
22
  "memory_supersede",
23
23
  "memory_forget",
24
+ "memory_useful",
25
+ "memory_workingstate",
24
26
  "memory_status",
25
27
  "memory_submit",
26
28
  "memory_propose",
@@ -393,7 +395,7 @@ function opencodePluginCheck() {
393
395
  return { name, ok: false, detail: String(err) };
394
396
  }
395
397
  }
396
- /** Spawn the real MCP server, handshake, and verify the five tools list. */
398
+ /** Spawn the real MCP server, handshake, and verify the twelve tools list. */
397
399
  function mcpCheck() {
398
400
  const name = "mcp";
399
401
  return new Promise((resolve) => {
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { PLUGIN_ID, bootstrapPlugin, captureFromText, captureHandoff, injectOnce, } from "./plugin-core.js";
1
+ import { PLUGIN_ID, bootstrapPlugin, captureFromText, captureHandoff, injectOnce, surfaceWorkingStateOnce, } from "./plugin-core.js";
2
2
  import { pickScopeRoot } from "./scope.js";
3
3
  import { makeTools } from "./tools/memory.js";
4
4
  import { v2Plugin } from "./opencode-v2.js";
@@ -32,6 +32,11 @@ const server = async ({ worktree, directory }) => {
32
32
  injectOnce(sessionID, state, (block) => {
33
33
  output.system.push(block);
34
34
  });
35
+ // D89: the working-state note rides the same one-time pass — with a
36
+ // fresh note it surfaces even when the memory lists are empty.
37
+ surfaceWorkingStateOnce(sessionID, state, (block) => {
38
+ output.system.push(block);
39
+ });
35
40
  // D73: runs on every request, so the note lands on the very turn whose
36
41
  // message the hook just captured. Delivered once per capture.
37
42
  const handoff = captureHandoff(sessionID, state);
package/dist/init.js CHANGED
@@ -51,9 +51,9 @@ const INSTRUCTIONS = `${MARKER}
51
51
 
52
52
  You have a local memory MCP server (\`open-memex\`). Its tools are
53
53
  \`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`,
54
- \`memory_forget\`, \`memory_status\`, \`memory_submit\`, \`memory_propose\`,
55
- \`memory_promote\`, \`memory_resolve\`, \`memory_pr_status\` — always call them by
56
- these full names.
54
+ \`memory_forget\`, \`memory_useful\`, \`memory_workingstate\`, \`memory_status\`,
55
+ \`memory_submit\`, \`memory_propose\`, \`memory_promote\`, \`memory_resolve\`,
56
+ \`memory_pr_status\` — always call them by these full names.
57
57
 
58
58
  - The server tells you when project outbox drafts are waiting for review — in
59
59
  tool results. When it does (or when the user asks), call \`memory_status\`
@@ -85,6 +85,16 @@ these full names.
85
85
  about the user that hold across all projects. When a saved fact becomes
86
86
  outdated, call \`memory_supersede\` (find the old memory's id with
87
87
  \`memory_search\` first) instead of adding a duplicate.
88
+ - When the user signals the session or task is wrapping up, refresh the
89
+ working-state note: call \`memory_workingstate\` (action=write) with a short
90
+ note — task summary, open files, last commands, where the work stands, next
91
+ step — so an interrupted task can resume in a fresh session. It is scratch
92
+ state, not durable knowledge: never save it as a memory.
93
+ - When a person confirms a memory was useful, or accepts work that clearly
94
+ relied on one, call \`memory_useful\` on it. NEVER call it just because a
95
+ memory appeared in search results or the session-start block: passive
96
+ exposure is counted separately and never counts as useful. Superseding a
97
+ memory or approving it at review already records its useful signal.
88
98
 
89
99
  ## Syncing project memories for review (D26)
90
100