open-memex 0.8.2-alpha.2 → 0.9.0-alpha.1
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.
- package/AGENTS.md +18 -5
- package/CHANGELOG.md +6 -0
- package/README.md +32 -13
- package/README.zh-CN.md +22 -11
- package/dist/.build-stamp +1 -1
- package/dist/cli.js +54 -6
- package/dist/config.js +9 -0
- package/dist/doctor.js +3 -2
- package/dist/index.js +6 -1
- package/dist/init.js +8 -3
- package/dist/mcp.js +17 -5
- package/dist/opencode-v2.js +6 -2
- package/dist/plugin-core.js +28 -1
- package/dist/store/audit.js +14 -0
- package/dist/tools/memory.js +11 -2
- package/dist/tools/ops.js +68 -0
- package/dist/working-state.js +118 -0
- package/docs/CONCEPTS.md +16 -0
- package/docs/CONCEPTS.zh-CN.md +13 -0
- package/docs/V2-DESIGN.md +42 -1039
- package/docs/design/decisions.md +1146 -0
- package/docs/design/knowledge-graph.md +86 -0
- package/package.json +1 -1
- package/scripts/smoke-mcp.ts +29 -2
- package/scripts/smoke-pure.ts +70 -0
- package/server.json +2 -2
- package/skills/open-memex/SKILL.md +10 -0
- package/src/cli.ts +60 -6
- package/src/config.ts +16 -0
- package/src/doctor.ts +3 -2
- package/src/index.ts +6 -0
- package/src/init.ts +8 -3
- package/src/mcp.ts +23 -4
- package/src/opencode-v2.ts +7 -2
- package/src/plugin-core.ts +32 -1
- package/src/store/audit.ts +20 -0
- package/src/tools/memory.ts +13 -1
- package/src/tools/ops.ts +87 -0
- 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
|
|
15
|
+
- **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same twelve 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
|
|
|
@@ -36,7 +36,8 @@ npm run cli -- where | list | search "q" | add ... | forget <id> | reindex
|
|
|
36
36
|
npm run cli -- <command> --help # per-command help (AI assistants discover flags this way)
|
|
37
37
|
npm run cli -- sync-status # last sync time/kind + outbox drafts + repo review states + uncommitted files
|
|
38
38
|
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)
|
|
39
|
+
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)
|
|
40
|
+
npm run cli -- wstate [--clear] # show/clear the session working-state note (D89 §3.6; the file it prints is editable directly)
|
|
40
41
|
npm run cli -- pull # fetch + fast-forward only (explicit; diverged = clean failure, never force-merge)
|
|
41
42
|
npm run cli -- push # push current branch to remote (explicit only; open-memex never auto-pushes)
|
|
42
43
|
npm run cli -- export [--scope project|personal|both] [--all] [-o <file>] # portable .tar.gz bundle (markdown + manifest); private excluded unless --all
|
|
@@ -171,11 +172,22 @@ D67 rules for any new pattern: a trigger must be a **statement to the store**, n
|
|
|
171
172
|
|
|
172
173
|
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
174
|
|
|
175
|
+
**Working-state note (D89, §3.6) — scratch, not memory.** One ephemeral
|
|
176
|
+
per-project note at `<data root>/working-state/<scope_key>.md` (src/working-state.ts);
|
|
177
|
+
`memory_workingstate` (12th tool, both hosts) reads/writes/clears it, the
|
|
178
|
+
session-start block (`surfaceWorkingStateOnce`) surfaces it next to the
|
|
179
|
+
injection, `audit` reports expired notes, `cli wstate` is the human surface.
|
|
180
|
+
It never enters `memories/` or the index — keep it that way: anything worth
|
|
181
|
+
keeping routes through the checkpoint-proposal flow. opencode has no Stop
|
|
182
|
+
hook today, so the write path is instruction + tool; the tool description,
|
|
183
|
+
the surfaced block, the MCP handshake, `init` instructions and the skill must
|
|
184
|
+
keep saying the same thing.
|
|
185
|
+
|
|
174
186
|
## Design constraints — read the frozen design first
|
|
175
187
|
|
|
176
|
-
`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through
|
|
188
|
+
`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
189
|
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
|
|
190
|
+
built this way" (principles, iron rules, the append-only decision log in `docs/design/decisions.md`, currently D1–D88). Before changing
|
|
179
191
|
architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
|
|
180
192
|
schema, MCP tools, CLI contract), read the relevant design section — the decision
|
|
181
193
|
log records what was already considered and rejected.
|
|
@@ -201,10 +213,11 @@ breaking v1→v2 transition) shipped with 0.3.0. Full rules: `CONTRIBUTING.md`.
|
|
|
201
213
|
- **Docs ship with code.** Every code change updates the docs it affects in the same commit:
|
|
202
214
|
new/changed tools → `README.md` + `README.zh-CN.md` tool tables + MCP section (keep both
|
|
203
215
|
languages in sync); behavior changes → both READMEs
|
|
204
|
-
and the frozen
|
|
216
|
+
and the frozen design (append a `D<n>` decision entry to `docs/design/decisions.md`, never rewrite history);
|
|
205
217
|
new commands → README CLI sections + this file's Commands. A change without its docs
|
|
206
218
|
is not done. Anything deferred as "later" goes into the near-term backlog in
|
|
207
219
|
`docs/V2-DESIGN.md` §18 the same day — unwritten later means never.
|
|
220
|
+
- **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
221
|
- **Measurement before mechanism.** A retrieval change lands its fixture +
|
|
209
222
|
baseline number in a commit with no retrieval change at all, so the delta is
|
|
210
223
|
unambiguous. `scripts/retrieval-eval.ts` is the gate: no retrieval PR merges
|
package/CHANGELOG.md
CHANGED
|
@@ -9,6 +9,12 @@ the `@alpha` tag are development snapshots and are not listed individually.
|
|
|
9
9
|
|
|
10
10
|
## [Unreleased]
|
|
11
11
|
|
|
12
|
+
## [0.9.0-alpha.1] - 2026-11-03
|
|
13
|
+
|
|
14
|
+
- 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.
|
|
15
|
+
|
|
16
|
+
## [0.8.2] - 2026-10-28
|
|
17
|
+
|
|
12
18
|
- 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
19
|
- 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
20
|
|
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` |
|
|
141
|
-
| VS Code (Copilot) | `open-memex init --client vscode` | All
|
|
142
|
-
| Cursor | `open-memex init --client cursor` | All
|
|
143
|
-
| Claude Code | `claude mcp add open-memex -- open-memex mcp` | All
|
|
144
|
-
| Visual Studio 2022 17.14+ / 2026 | `open-memex init --client visualstudio` | All
|
|
145
|
-
| Codex and other MCP clients | `open-memex mcp --print-config` | All
|
|
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
|
|
152
|
-
and the 6 extra workflow tools, so the "
|
|
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
|
|
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
|
|
448
|
-
|
|
447
|
+
The MCP server exposes twelve tools; the opencode native plugin exposes the
|
|
448
|
+
six 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,7 @@ 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 |
|
|
458
459
|
| `memory_status` | Show the sync queue: outbox drafts, repo review states, uncommitted files |
|
|
459
460
|
| `memory_submit` | Move named drafts into the repo memory dir (local branch + commit) |
|
|
460
461
|
| `memory_propose` | Copy personal memories into the project scope as review candidates |
|
|
@@ -833,7 +834,8 @@ Maintenance:
|
|
|
833
834
|
open-memex where # show storage + config paths
|
|
834
835
|
open-memex scopes # list project scopes with memory counts
|
|
835
836
|
open-memex reindex # rebuild the SQLite index from markdown
|
|
836
|
-
open-memex audit # memory health: duplicate pairs, stale memories, broken chains
|
|
837
|
+
open-memex audit # memory health: duplicate pairs, stale memories, broken chains, expired working-state notes
|
|
838
|
+
open-memex wstate # show the session working-state note (--clear deletes it)
|
|
837
839
|
open-memex migrate --to-v2 [--dry-run] # v1 data → v2 (renames user scope to personal)
|
|
838
840
|
```
|
|
839
841
|
|
|
@@ -844,6 +846,23 @@ prefix every command with `node --experimental-strip-types src/cli.ts` (or
|
|
|
844
846
|
`npm run cli -- <command>` for simple cases — npm swallows unknown `--flag`
|
|
845
847
|
args, so prefer direct `node`).
|
|
846
848
|
|
|
849
|
+
## Session working state
|
|
850
|
+
|
|
851
|
+
Beyond durable knowledge, the agent can leave **one ephemeral working-state
|
|
852
|
+
note per project** (§3.6, D89): task summary, open files, last commands, where
|
|
853
|
+
the work stands, next step. Written by the agent at wrap-up via the
|
|
854
|
+
`memory_workingstate` tool — opencode has no Stop hook today, so "wrap-up"
|
|
855
|
+
means when the user signals the session or task is ending (the Claude Code
|
|
856
|
+
path arrives with the native plugin work). The note surfaces automatically at
|
|
857
|
+
session start so an interrupted task can resume; it is scratch state, never a
|
|
858
|
+
memory, and expires after 7 days (configurable) — `audit` reports expired
|
|
859
|
+
notes, humans edit the plain file directly.
|
|
860
|
+
|
|
861
|
+
```sh
|
|
862
|
+
open-memex wstate # show the note (age + expiry)
|
|
863
|
+
open-memex wstate --clear # delete it
|
|
864
|
+
```
|
|
865
|
+
|
|
847
866
|
## MCP server
|
|
848
867
|
|
|
849
868
|
The same memory tools over the Model Context Protocol, via a stdio server —
|
|
@@ -931,7 +950,7 @@ config: if it has comments, add the `"plugin"` line manually.
|
|
|
931
950
|
Checks the Node version, config source, scope resolution for the current
|
|
932
951
|
directory, and storage writability; verifies VS Code hasn't disabled MCP;
|
|
933
952
|
then boots a real MCP server and runs `initialize` + `tools/list` against
|
|
934
|
-
it — all
|
|
953
|
+
it — all twelve tools must show up. It also reports pre-rename `my-o-memory`
|
|
935
954
|
leftovers if any editor config still references the old package name.
|
|
936
955
|
|
|
937
956
|
## 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` |
|
|
105
|
-
| VS Code(Copilot) | `open-memex init --client vscode` | 经 MCP 全
|
|
106
|
-
| Cursor | `open-memex init --client cursor` | 经 MCP 全
|
|
107
|
-
| Claude Code | `claude mcp add open-memex -- open-memex mcp` | 经 MCP 全
|
|
108
|
-
| Visual Studio 2022 17.14+ / 2026 | `open-memex init --client visualstudio` | 经 MCP 全
|
|
109
|
-
| Codex 与其他 MCP 客户端 | `open-memex mcp --print-config` | 经 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 插件是真正的内置第一轮注入。[助手拿到的工具](#助手拿到的工具)一节列出了
|
|
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。你会得到
|
|
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
|
|
289
|
+
MCP 服务器暴露十二个工具;opencode 原生插件暴露其中六个核心的(标 ●)。另外六个是团队评审工作流工具——只有当你通过 Git 共享记忆时才用得上。
|
|
290
290
|
|
|
291
291
|
| 工具 | 做什么 |
|
|
292
292
|
|---|---|
|
|
@@ -295,6 +295,7 @@ 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)——让被中断的任务得以续接;只是草稿状态,永远不会成为记忆 |
|
|
298
299
|
| `memory_status` | 显示同步队列:outbox 草稿、仓库评审状态、未提交文件 |
|
|
299
300
|
| `memory_submit` | 把指定的草稿移进仓库记忆目录(本地分支 + 提交) |
|
|
300
301
|
| `memory_propose` | 把个人记忆复制到项目作用域,作为评审候选 |
|
|
@@ -558,12 +559,22 @@ open-memex resolve [id-or-path]
|
|
|
558
559
|
open-memex where # 显示存储与配置路径
|
|
559
560
|
open-memex scopes # 列出各项目作用域及记忆计数
|
|
560
561
|
open-memex reindex # 从 markdown 重建 SQLite 索引
|
|
561
|
-
open-memex audit #
|
|
562
|
+
open-memex audit # 记忆健康检查:近重复对、陈旧记忆、断裂的取代链、过期的工作状态笔记
|
|
563
|
+
open-memex wstate # 显示工作状态笔记(--clear 删除)
|
|
562
564
|
open-memex migrate --to-v2 [--dry-run] # v1 数据 → v2(把 user 作用域改名为 personal)
|
|
563
565
|
```
|
|
564
566
|
|
|
565
567
|
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
568
|
|
|
569
|
+
## 工作状态笔记
|
|
570
|
+
|
|
571
|
+
除了耐久知识之外,助手还可以给每个项目留下**一份临时工作状态笔记**(§3.6,D89):任务摘要、打开的文件、最后的命令、进度在哪、下一步。由助手在收尾时通过 `memory_workingstate` 工具写——opencode 目前没有 Stop 钩子,所以"收尾"指用户发出会话或任务结束的信号(Claude Code 路径等原生插件工作再做)。笔记会在会话开始时自动浮现,让被中断的任务得以续接;它只是草稿状态、永远不会成为记忆,7 天后过期(可配置)——`audit` 报告过期笔记,人可以直接编辑这个纯文本文件。
|
|
572
|
+
|
|
573
|
+
```sh
|
|
574
|
+
open-memex wstate # 显示笔记(含年龄与到期)
|
|
575
|
+
open-memex wstate --clear # 删除
|
|
576
|
+
```
|
|
577
|
+
|
|
567
578
|
## MCP 服务器
|
|
568
579
|
|
|
569
580
|
同一组记忆工具,走 Model Context Protocol、经 stdio 服务器提供——不需要任何宿主专用插件。任何 MCP 客户端都能用 open-memex。
|
|
@@ -607,7 +618,7 @@ Windows 上已加载的 DLL 是锁定的:如果 open-memex 的 MCP 服务器
|
|
|
607
618
|
你的编辑器配置里有注释(JSONC)或 JSON 不合法,open-memex 永不重写它无法安全解析的文件。`init` 已经把要加的确切片段打印出来了——手动粘贴进去就好。opencode 配置同理:有注释时,手动把 `"plugin"` 那一行加上。
|
|
608
619
|
|
|
609
620
|
**感觉有问题——跑 `open-memex doctor`。**
|
|
610
|
-
它检查 Node 版本、配置来源、当前目录的作用域解析、存储可写性,并确认 VS Code 没有把 MCP 禁用;然后启动一个真实 MCP 服务器,对它跑 `initialize` + `tools/list
|
|
621
|
+
它检查 Node 版本、配置来源、当前目录的作用域解析、存储可写性,并确认 VS Code 没有把 MCP 禁用;然后启动一个真实 MCP 服务器,对它跑 `initialize` + `tools/list`——十二个工具必须全部出现。它还会报告改名之前遗留的 `my-o-memory` 引用(如果某编辑器配置里还留着旧包名的话)。
|
|
611
622
|
|
|
612
623
|
## 常见问题
|
|
613
624
|
|
package/dist/.build-stamp
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
6d4e1da51acc88be93fb2cbfe2098c79e3d55b7332eda52f6597167758aa46fa
|
package/dist/cli.js
CHANGED
|
@@ -16,6 +16,7 @@ import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, normalizeAliases, }
|
|
|
16
16
|
import { loadConfig, configSource } from "./config.js";
|
|
17
17
|
import { paths, projectRoot, isInRepoMemoryFile } from "./paths.js";
|
|
18
18
|
import { redact } from "./redact.js";
|
|
19
|
+
import { readWorkingState, clearWorkingState, workingStatePath } from "./working-state.js";
|
|
19
20
|
import { resolveMcpCommand } from "./init.js";
|
|
20
21
|
import fs from "node:fs";
|
|
21
22
|
import path from "node:path";
|
|
@@ -387,7 +388,7 @@ Example:
|
|
|
387
388
|
doctor: `Environment health check: Node version, config source, scope resolution,
|
|
388
389
|
storage writability, VS Code MCP enablement (settings.json + system policy),
|
|
389
390
|
then boots a real MCP server and runs initialize + tools/list against it —
|
|
390
|
-
all
|
|
391
|
+
all twelve tools must show up.
|
|
391
392
|
|
|
392
393
|
Usage: open-memex doctor
|
|
393
394
|
|
|
@@ -395,8 +396,8 @@ Example:
|
|
|
395
396
|
open-memex doctor`,
|
|
396
397
|
audit: `Memory health audit (read-only, reports never mutates): near-duplicate
|
|
397
398
|
pairs among active memories, stale actives untouched for 90+ days, broken
|
|
398
|
-
supersede chains, personal files found inside the repo memory dir,
|
|
399
|
-
|
|
399
|
+
supersede chains, personal files found inside the repo memory dir, index/file
|
|
400
|
+
drift, and expired working-state notes (D89).
|
|
400
401
|
|
|
401
402
|
Usage: open-memex audit [--scope project|personal|both]
|
|
402
403
|
|
|
@@ -405,6 +406,18 @@ Flags:
|
|
|
405
406
|
|
|
406
407
|
Example:
|
|
407
408
|
open-memex audit --scope both`,
|
|
409
|
+
wstate: `Show the project's session working-state note (D89, §3.6) — the
|
|
410
|
+
ephemeral scratch note the agent refreshes at wrap-up so an interrupted task
|
|
411
|
+
can resume. The file itself is plain Markdown and editable directly.
|
|
412
|
+
|
|
413
|
+
Usage: open-memex wstate [--clear]
|
|
414
|
+
|
|
415
|
+
Flags:
|
|
416
|
+
--clear delete the note (no tombstone — it is scratch, not knowledge)
|
|
417
|
+
|
|
418
|
+
Examples:
|
|
419
|
+
open-memex wstate
|
|
420
|
+
open-memex wstate --clear`,
|
|
408
421
|
};
|
|
409
422
|
function usage(exitCode = 1) {
|
|
410
423
|
console.log(`open-memex CLI
|
|
@@ -431,6 +444,7 @@ Usage:
|
|
|
431
444
|
open-memex pr-status [--apply]
|
|
432
445
|
open-memex reindex
|
|
433
446
|
open-memex audit [--scope project|personal|both]
|
|
447
|
+
open-memex wstate [--clear]
|
|
434
448
|
open-memex scopes
|
|
435
449
|
open-memex migrate [--from <key>] [--to <key>]
|
|
436
450
|
[--dry-run] [--on-conflict newer|overwrite|skip]
|
|
@@ -463,8 +477,8 @@ first-turn injection); \`--yes\` accepts all defaults, and non-terminal runs nev
|
|
|
463
477
|
\`open-memex config set <key> <value>\` changes those settings after install.
|
|
464
478
|
|
|
465
479
|
Once installed globally (\`npm i -g open-memex\`) the \`open-memex\` command is
|
|
466
|
-
available directly: \`open-memex mcp\` starts the stdio MCP server (
|
|
467
|
-
the opencode plugin's
|
|
480
|
+
available directly: \`open-memex mcp\` starts the stdio MCP server (12 tools, a superset of
|
|
481
|
+
the opencode plugin's six memory_* tools); \`open-memex mcp --print-config <client>\`
|
|
468
482
|
prints a copy-paste MCP client config snippet.
|
|
469
483
|
|
|
470
484
|
Scope defaults to \`project\` (derived from cwd's git remote or path).
|
|
@@ -656,6 +670,35 @@ async function main() {
|
|
|
656
670
|
}
|
|
657
671
|
const cfg = loadConfig();
|
|
658
672
|
const project = resolveProjectScope(process.cwd());
|
|
673
|
+
// §3.6 (D89): human convenience surface for the working-state note —
|
|
674
|
+
// print it (with age/expiry) or delete it on request. The file itself is
|
|
675
|
+
// always editable directly; audit reports expired notes either way.
|
|
676
|
+
if (cmd === "wstate") {
|
|
677
|
+
const flags = parseFlags(rest);
|
|
678
|
+
if (flags["clear"] === "true") {
|
|
679
|
+
const gone = clearWorkingState(project.key);
|
|
680
|
+
console.log(gone
|
|
681
|
+
? `working-state note cleared (${project.key})`
|
|
682
|
+
: "nothing to clear — the note is still on disk; delete it manually if it exists");
|
|
683
|
+
return;
|
|
684
|
+
}
|
|
685
|
+
const note = readWorkingState(project.key, cfg.workingStateTtlDays);
|
|
686
|
+
if (!note) {
|
|
687
|
+
console.log(`no working-state note for ${project.key} — the agent writes one at wrap-up (memory_workingstate); you can edit the file directly`);
|
|
688
|
+
return;
|
|
689
|
+
}
|
|
690
|
+
if (!cfg.workingStateEnabled) {
|
|
691
|
+
console.log("(working state is disabled in config — workingStateEnabled=false)");
|
|
692
|
+
}
|
|
693
|
+
console.log(note.expired
|
|
694
|
+
? `EXPIRED — ${note.ageDays} day(s) old, ttl ${note.ttlDays} (ignored at session start; ` +
|
|
695
|
+
`audit keeps reporting it until the next wrap-up write or 'wstate --clear')`
|
|
696
|
+
: `updated ${note.ageDays} day(s) ago — expires after ${note.ttlDays} day(s)`);
|
|
697
|
+
console.log();
|
|
698
|
+
console.log(note.content || "(empty note)");
|
|
699
|
+
console.log(`\nfile: ${workingStatePath(project.key)}`);
|
|
700
|
+
return;
|
|
701
|
+
}
|
|
659
702
|
// `migrate --to-v2` is a pure file operation (V2-DESIGN §19) — it runs
|
|
660
703
|
// before the index is opened so it also works where the DB driver
|
|
661
704
|
// isn't available.
|
|
@@ -752,6 +795,11 @@ async function main() {
|
|
|
752
795
|
for (const f of r.personalInRepo)
|
|
753
796
|
console.log(` ${f}`);
|
|
754
797
|
console.log(` index drift: ${r.drift.filesNotIndexed} files not indexed, ${r.drift.rowsMissingFiles} rows missing files`);
|
|
798
|
+
// D89: expired working-state notes — reports only, never auto-deletes.
|
|
799
|
+
console.log(` expired working-state notes: ${r.workingStateExpired.length}`);
|
|
800
|
+
for (const w of r.workingStateExpired) {
|
|
801
|
+
console.log(` ${w.filePath} — ${w.ageDays} days old (ttl ${w.ttlDays}); 'wstate --clear' or the next wrap-up write refreshes`);
|
|
802
|
+
}
|
|
755
803
|
return;
|
|
756
804
|
}
|
|
757
805
|
// `config` prints the effective configuration (defaults + file). No DB needed.
|
|
@@ -823,7 +871,7 @@ async function main() {
|
|
|
823
871
|
}
|
|
824
872
|
return;
|
|
825
873
|
}
|
|
826
|
-
// `mcp` starts the stdio MCP server (
|
|
874
|
+
// `mcp` starts the stdio MCP server (12 tools; the opencode plugin exposes 6).
|
|
827
875
|
// Branched before db() — runMcpServer() does its own init, and stdout must
|
|
828
876
|
// stay clean for the MCP protocol.
|
|
829
877
|
if (cmd === "mcp") {
|
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
|
|
16
|
+
// D64: the MCP server exposes twelve tools; checking only the six 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,7 @@ const EXPECTED_TOOLS = [
|
|
|
21
21
|
"memory_list",
|
|
22
22
|
"memory_supersede",
|
|
23
23
|
"memory_forget",
|
|
24
|
+
"memory_workingstate",
|
|
24
25
|
"memory_status",
|
|
25
26
|
"memory_submit",
|
|
26
27
|
"memory_propose",
|
|
@@ -393,7 +394,7 @@ function opencodePluginCheck() {
|
|
|
393
394
|
return { name, ok: false, detail: String(err) };
|
|
394
395
|
}
|
|
395
396
|
}
|
|
396
|
-
/** Spawn the real MCP server, handshake, and verify the
|
|
397
|
+
/** Spawn the real MCP server, handshake, and verify the twelve tools list. */
|
|
397
398
|
function mcpCheck() {
|
|
398
399
|
const name = "mcp";
|
|
399
400
|
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\`, \`
|
|
55
|
-
\`memory_promote\`, \`memory_resolve\`, \`memory_pr_status\` —
|
|
56
|
-
these full names.
|
|
54
|
+
\`memory_forget\`, \`memory_workingstate\`, \`memory_status\`, \`memory_submit\`,
|
|
55
|
+
\`memory_propose\`, \`memory_promote\`, \`memory_resolve\`, \`memory_pr_status\` —
|
|
56
|
+
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,11 @@ 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.
|
|
88
93
|
|
|
89
94
|
## Syncing project memories for review (D26)
|
|
90
95
|
|
package/dist/mcp.js
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Exposes the memory tools as the opencode plugin
|
|
5
5
|
* (memory_add / memory_search / memory_list / memory_supersede /
|
|
6
|
-
* memory_forget, plus memory_status / memory_submit /
|
|
7
|
-
* memory_promote / memory_resolve / memory_pr_status)
|
|
6
|
+
* memory_forget, plus memory_workingstate + memory_status / memory_submit /
|
|
7
|
+
* memory_propose / memory_promote / memory_resolve / memory_pr_status)
|
|
8
|
+
* over the Model Context Protocol, so any MCP client —
|
|
8
9
|
* VS Code Copilot Chat, Cursor, Claude Code, etc. — can use open-memex
|
|
9
10
|
* without a host-specific plugin.
|
|
10
11
|
*
|
|
@@ -28,7 +29,7 @@ import { loadConfig } from "./config.js";
|
|
|
28
29
|
import { resolveProjectScope, PERSONAL_SCOPE } from "./scope.js";
|
|
29
30
|
import { db } from "./store/db.js";
|
|
30
31
|
import { syncScope } from "./store/sync.js";
|
|
31
|
-
import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, statusMemories, submitMemoriesOp, proposeMemoriesOp, promoteMemoryOp, resolveMemoryOp, prStatusOp, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, memoryStatusArgs, memorySubmitArgs, memoryProposeArgs, memoryPromoteArgs, memoryResolveArgs, memoryPrStatusArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./tools/ops.js";
|
|
32
|
+
import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, statusMemories, submitMemoriesOp, proposeMemoriesOp, promoteMemoryOp, resolveMemoryOp, prStatusOp, workingStateMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, memoryStatusArgs, memorySubmitArgs, memoryProposeArgs, memoryPromoteArgs, memoryResolveArgs, memoryPrStatusArgs, memoryWorkingStateArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./tools/ops.js";
|
|
32
33
|
import { outboxDraftCount } from "./submit.js";
|
|
33
34
|
// Server version tracks package.json — never hardcode it here again.
|
|
34
35
|
// package.json sits two levels above this file in both layouts
|
|
@@ -52,8 +53,9 @@ const SERVER_VERSION = (() => {
|
|
|
52
53
|
*/
|
|
53
54
|
const SERVER_INSTRUCTIONS = `You are connected to an open-memex local memory MCP server.
|
|
54
55
|
Its tools are memory_add, memory_search, memory_list, memory_supersede,
|
|
55
|
-
memory_forget, memory_status, memory_submit,
|
|
56
|
-
memory_resolve, memory_pr_status — always call
|
|
56
|
+
memory_forget, memory_workingstate, memory_status, memory_submit,
|
|
57
|
+
memory_propose, memory_promote, memory_resolve, memory_pr_status — always call
|
|
58
|
+
them by these full names.
|
|
57
59
|
|
|
58
60
|
- The server tells you when project outbox drafts are waiting for review —
|
|
59
61
|
in tool results, and in these session-start instructions. When it does,
|
|
@@ -102,6 +104,11 @@ memory_resolve, memory_pr_status — always call them by these full names.
|
|
|
102
104
|
about the user that hold across all projects. When a saved fact becomes
|
|
103
105
|
outdated, call memory_supersede (find the old memory's id with memory_search
|
|
104
106
|
first) instead of adding a duplicate.
|
|
107
|
+
- When the user signals the session or task is wrapping up, call
|
|
108
|
+
memory_workingstate (action=write) with a short note: task summary, open
|
|
109
|
+
files, last commands, where the work stands, next step — so an interrupted
|
|
110
|
+
task can resume. It is scratch state, not knowledge: do not save it as a
|
|
111
|
+
memory; durable conclusions still follow the propose-first flow above.
|
|
105
112
|
`;
|
|
106
113
|
/** Adapt a framework-agnostic op result to an MCP tool response. */
|
|
107
114
|
function toMcp(p) {
|
|
@@ -216,6 +223,11 @@ export async function runMcpServer() {
|
|
|
216
223
|
inputSchema: z.object(memoryPrStatusArgs),
|
|
217
224
|
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
|
|
218
225
|
}, withSync((args) => toMcp(prStatusOp(args))));
|
|
226
|
+
server.registerTool("memory_workingstate", {
|
|
227
|
+
description: TOOL_DESCRIPTIONS.memory_workingstate,
|
|
228
|
+
inputSchema: z.object(memoryWorkingStateArgs),
|
|
229
|
+
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
|
|
230
|
+
}, withSync((args) => toMcp(workingStateMemory(getScope, cfg, args))));
|
|
219
231
|
const transport = new StdioServerTransport();
|
|
220
232
|
await server.connect(transport);
|
|
221
233
|
}
|
package/dist/opencode-v2.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
-
import { PLUGIN_ID, bootstrapPlugin, captureFromText, captureHandoff, injectOnce, } from "./plugin-core.js";
|
|
2
|
+
import { PLUGIN_ID, bootstrapPlugin, captureFromText, captureHandoff, injectOnce, surfaceWorkingStateOnce, } from "./plugin-core.js";
|
|
3
3
|
import { makeTools } from "./tools/memory.js";
|
|
4
|
-
/** Register the
|
|
4
|
+
/** Register the six memory tools on a v2 host. */
|
|
5
5
|
async function registerTools(ctx, state) {
|
|
6
6
|
const tools = makeTools(() => state.scope, state.cfg);
|
|
7
7
|
await ctx.tool.transform((editor) => {
|
|
@@ -35,6 +35,10 @@ export const v2Plugin = {
|
|
|
35
35
|
injectOnce(sessionID, state, (block) => {
|
|
36
36
|
ev.system.push({ type: "text", text: block });
|
|
37
37
|
});
|
|
38
|
+
// D89: the working-state note rides the same one-time pass.
|
|
39
|
+
surfaceWorkingStateOnce(sessionID, state, (block) => {
|
|
40
|
+
ev.system.push({ type: "text", text: block });
|
|
41
|
+
});
|
|
38
42
|
// D73: tell the agent what the keyword hook already stored this turn.
|
|
39
43
|
const handoff = captureHandoff(sessionID, state);
|
|
40
44
|
if (handoff)
|
package/dist/plugin-core.js
CHANGED
|
@@ -5,6 +5,7 @@ import { syncScope, upsertFromFile } from "./store/sync.js";
|
|
|
5
5
|
import { scopeHasFiles } from "./store/migrate.js";
|
|
6
6
|
import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
|
|
7
7
|
import { buildContextBlock } from "./retrieve/inject.js";
|
|
8
|
+
import { workingStateBlock } from "./working-state.js";
|
|
8
9
|
import { detectKeywords } from "./capture/keywords.js";
|
|
9
10
|
import { formatHandoffBlock, freshCaptures, } from "./capture/handoff.js";
|
|
10
11
|
import { findDuplicates } from "./store/lifecycle.js";
|
|
@@ -45,7 +46,7 @@ export function bootstrapPlugin(root) {
|
|
|
45
46
|
catch (err) {
|
|
46
47
|
console.error("[open-memex] init failed:", err);
|
|
47
48
|
}
|
|
48
|
-
return { cfg, scope, injectedSessions: new Set(), captures: new Map() };
|
|
49
|
+
return { cfg, scope, injectedSessions: new Set(), workingStateSessions: new Set(), captures: new Map() };
|
|
49
50
|
}
|
|
50
51
|
/**
|
|
51
52
|
* Keyword capture (§ capture): scan one user message for "remember …"
|
|
@@ -181,3 +182,29 @@ export function injectOnce(sessionID, state, push) {
|
|
|
181
182
|
}
|
|
182
183
|
return false;
|
|
183
184
|
}
|
|
185
|
+
/**
|
|
186
|
+
* §3.6 (D89): surface the working-state note once per session, alongside
|
|
187
|
+
* the context injection. Scratch state, not knowledge — the block itself
|
|
188
|
+
* says what it is. Exactly-once uses the same in-memory Set discipline as
|
|
189
|
+
* `injectOnce` (not persisted; restarting the host re-surfaces). Expired
|
|
190
|
+
* or missing notes surface nothing.
|
|
191
|
+
*/
|
|
192
|
+
export function surfaceWorkingStateOnce(sessionID, state, push) {
|
|
193
|
+
const { cfg, scope } = state;
|
|
194
|
+
if (!cfg.workingStateEnabled)
|
|
195
|
+
return false;
|
|
196
|
+
if (state.workingStateSessions.has(sessionID))
|
|
197
|
+
return false;
|
|
198
|
+
state.workingStateSessions.add(sessionID);
|
|
199
|
+
try {
|
|
200
|
+
const block = workingStateBlock(scope.key, scope.projectName, cfg);
|
|
201
|
+
if (block) {
|
|
202
|
+
push(block);
|
|
203
|
+
return true;
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
catch (err) {
|
|
207
|
+
console.error("[open-memex] working-state surfacing failed:", err);
|
|
208
|
+
}
|
|
209
|
+
return false;
|
|
210
|
+
}
|
package/dist/store/audit.js
CHANGED
|
@@ -4,6 +4,7 @@ import { readMemoryFile, iterInRepoMemoryFiles, iterMemoryFiles, } from "./markd
|
|
|
4
4
|
import { similarity, NEAR_DUP_THRESHOLD } from "./lifecycle.js";
|
|
5
5
|
import { projectRoot } from "../paths.js";
|
|
6
6
|
import { loadConfig } from "../config.js";
|
|
7
|
+
import { readWorkingState, workingStatePath } from "../working-state.js";
|
|
7
8
|
// Memory health audit (D57). Read-only: reports, never mutates.
|
|
8
9
|
// Checks, per open question "retrieval explainability & memory health":
|
|
9
10
|
// - near-duplicate pairs among active memories (same dedup yardstick
|
|
@@ -90,6 +91,18 @@ export function runAudit(scopeKeys) {
|
|
|
90
91
|
filesNotIndexed++;
|
|
91
92
|
}
|
|
92
93
|
}
|
|
94
|
+
// D89: expired working-state notes. Reports only, never auto-deletes
|
|
95
|
+
// (D57 posture) — the next wrap-up write overwrites them.
|
|
96
|
+
const cfg = loadConfig();
|
|
97
|
+
const workingStateExpired = scopeKeys
|
|
98
|
+
.map((key) => ({ key, note: readWorkingState(key, cfg.workingStateTtlDays) }))
|
|
99
|
+
.filter((e) => Boolean(e.note?.expired))
|
|
100
|
+
.map((e) => ({
|
|
101
|
+
scopeKey: e.key,
|
|
102
|
+
filePath: workingStatePath(e.key),
|
|
103
|
+
ageDays: e.note.ageDays,
|
|
104
|
+
ttlDays: e.note.ttlDays,
|
|
105
|
+
}));
|
|
93
106
|
return {
|
|
94
107
|
totalMemories: inScope.length,
|
|
95
108
|
duplicatePairs: pairs,
|
|
@@ -97,5 +110,6 @@ export function runAudit(scopeKeys) {
|
|
|
97
110
|
brokenChains,
|
|
98
111
|
personalInRepo,
|
|
99
112
|
drift: { filesNotIndexed, rowsMissingFiles },
|
|
113
|
+
workingStateExpired,
|
|
100
114
|
};
|
|
101
115
|
}
|