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.
- package/AGENTS.md +21 -5
- package/CHANGELOG.md +10 -0
- package/README.md +46 -13
- package/README.zh-CN.md +25 -11
- package/dist/.build-stamp +1 -1
- package/dist/cli.js +103 -6
- package/dist/config.js +9 -0
- package/dist/doctor.js +4 -2
- package/dist/index.js +6 -1
- package/dist/init.js +13 -3
- package/dist/mcp.js +28 -5
- package/dist/opencode-v2.js +6 -2
- package/dist/plugin-core.js +28 -1
- package/dist/retrieve/inject.js +6 -0
- package/dist/retrieve/search.js +13 -2
- package/dist/review.js +7 -0
- package/dist/store/audit.js +14 -0
- package/dist/store/db.js +19 -0
- package/dist/store/lifecycle.js +8 -0
- package/dist/store/usage.js +151 -0
- package/dist/tools/memory.js +21 -2
- package/dist/tools/ops.js +123 -1
- 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 +66 -66
- package/scripts/smoke-mcp.ts +67 -4
- package/scripts/smoke-pure.ts +70 -0
- package/scripts/test-full.ts +83 -0
- package/server.json +2 -2
- package/skills/open-memex/SKILL.md +19 -0
- package/src/cli.ts +111 -6
- package/src/config.ts +16 -0
- package/src/doctor.ts +4 -2
- package/src/index.ts +6 -0
- package/src/init.ts +13 -3
- package/src/mcp.ts +41 -4
- package/src/opencode-v2.ts +7 -2
- package/src/plugin-core.ts +32 -1
- package/src/retrieve/inject.ts +7 -0
- package/src/retrieve/search.ts +19 -3
- package/src/review.ts +6 -0
- package/src/store/audit.ts +20 -0
- package/src/store/db.ts +20 -0
- package/src/store/lifecycle.ts +9 -0
- package/src/store/usage.ts +178 -0
- package/src/tools/memory.ts +26 -1
- package/src/tools/ops.ts +158 -1
- 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 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
|
|
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
|
|
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
|
|
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` |
|
|
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 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
|
|
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` |
|
|
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,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
|
|
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
|
-
|
|
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
|
|
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,
|
|
399
|
-
|
|
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 (
|
|
467
|
-
the opencode plugin's
|
|
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 (
|
|
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
|
|
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
|
|
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\`, \`
|
|
55
|
-
\`
|
|
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
|
|