open-memex 0.6.1 → 0.6.2

package/AGENTS.md

@@ -64,7 +64,9 @@ resolves the server command
 at init time — npx fallback when no durable bin is on PATH, D17),
 `open-memex config` prints the effective config, `open-memex capture --dry-run "text"`
 previews keyword capture without writing, `open-memex doctor` runs health checks
-(node version, config, scope resolution, storage writability, VS Code MCP enablement, MCP handshake).
+(node version, config, scope resolution, storage writability, SQLite locking,
+opencode plugin entry (target exists + no host-SDK runtime imports, D59),
+VS Code MCP enablement, MCP handshake).
 `open-memex init` with no --client auto-detects and wires every installed editor
 (`--yes` skips, scripts never prompt); `open-memex config set <key> <value>` edits settings after install.
 `npm install -g` prints a pointer to `open-memex init` via a postinstall script

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to open-memex are recorded here. Entries are grouped by
+the design decision (D<n>) that drove them, matching the
+[GitHub Releases](https://github.com/stoneskin/open-memex/releases); the
+rationale behind each decision lives in the decision log in
+[docs/V2-DESIGN.md](docs/V2-DESIGN.md). Pre-release builds published under
+the `@alpha` tag are development snapshots and are not listed individually.
+
+## [Unreleased]
+
+## [0.6.1] - 2026-10-03
+
+## Question-shaped search, host parity said out loud (D56)
+
+- Search no longer feeds whole questions straight into full-text: query construction filters English/CJK function words, dedupes terms, and caps them — asking "how do we configure…" or "中文记忆怎么检索" now ranks the right memory first instead of matching everything
+- The six MCP-only tools now say so in their own descriptions and name the CLI equivalent, so opencode plugin users see the asymmetry is by design instead of assuming breakage
+- `init`'s closing lines state the privacy model in plain words: memories live only on this machine, personal ones never leave it, nothing is uploaded
+
+## Search explainability and memory audit (D57)
+
+- `open-memex search "deploy" --explain` shows the constructed FTS expression, per-hit scores, and how many matches lifecycle hid (superseded vs retracted/archived) — a miss is now diagnosable
+- New `open-memex audit` (read-only; `doctor` checks the environment, this checks the memories): near-duplicate active pairs, memories untouched for 90+ days, broken supersede chains, personal files found inside the repo memory dir, index/file drift
+- Concurrency posture measured and hardened: WAL everywhere, `busy_timeout` unified at 5s across backends (the opencode plugin's bun:sqlite defaulted to 0 — any overlapping write failed instantly), memory files written via tmp+rename, lock timeouts reported in one plain line, `doctor` reports the live locking settings
+
+## Critical fix: opencode plugin silently dead on global installs (D58)
+
+- After a global `npm i -g open-memex`, the opencode plugin was configured but silently inactive — no memory tools, no error, nothing in the log. Root cause: the plugin runtime-imported the host SDK (`@opencode-ai/plugin` is a devDependency; nothing resolves it from a global install, and opencode skips the plugin without a trace). The import is gone — the SDK helper is a runtime identity, now a local stand-in. **If your opencode shows no memory tools, update to 0.6.1.**
+
+## [0.6.0] - 2026-10-02
+
+## First-run onboarding (D50, D51, F28)
+
+- `open-memex init` is now a guided first run: the postinstall note points at init, every CLI entry prints a one-line stderr nudge until init has run or been declined (stderr keeps the MCP stdio protocol intact), and init ends with a next-step hint (`open-memex add` + ask the agent what it remembers)
+- Bare `open-memex` on a machine where init never completed offers to run it on a TTY; init/uninstall maintain a `.init.json` first-run marker so the offer is asked once
+
+## Agent prompt clarity (D52)
+
+- MCP tool descriptions rewritten for clarity
+
+## Push-not-poll outbox (D53)
+
+- New project memories land in a local outbox (invisible to git); `open-memex sync-status` shows drafts waiting and `open-memex submit` publishes them — the agent checks on demand instead of polling
+
+## Agent Skills (D54, D55)
+
+- New bundled `open-memex` skill (`skills/open-memex/SKILL.md`): teaches skill-aware agents the CLI (save/search/scope rules/outbox flow), preferring MCP tools when available; `init` installs it per editor, `uninstall` removes it
+- opencode with the native plugin wired no longer gets the skill — the plugin already provides memory tools, and the duplicated guidance made the agent chatty
+
+## Rename leftovers swept (F30)
+
+- The my-o-memory → open-memex rename left editor configs loading the OLD plugin/server, silently splitting memories across two data dirs; `init`/`uninstall` now drop stale `my-o-memory` entries wherever they touch a config, and `doctor` reports leftovers via a read-only `legacy my-o-memory` check
+
+## Fixes (F29)
+
+- Copilot review fixes, package-lock.json repair, Visual Studio onboarding strings
+
+## [0.5.1] - 2026-10-01
+
+## Docs review (F1–F27)
+
+- Full documentation pass: stale versions corrected (README now shows 0.5.0), roadmap extended with 0.5.0 (D45–D49), branch rules updated after the V2 branch retirement, MCP server tool count fixed to 11, USER-GUIDE cleaned of V2-dev leftovers
+
+## `mcp --help` accuracy (F27)
+
+- `--help` now states the MCP server exposes 11 tools (a superset of the opencode plugin's five `memory_*` tools); install hints point at the stable line instead of `@alpha`
+
+## doctor: VS Code MCP-disabled check
+
+- `open-memex doctor` now fails with a clear message when VS Code has MCP disabled — via `chat.mcp.enabled: false` in user/project `settings.json`, or a Windows registry policy (`HKLM/HKCU\SOFTWARE\Policies\Microsoft\VSCode`)
+
+## [0.5.0] - 2026-09-30
+
+## One config for every project (D45)
+
+- `open-memex init --global`: writes editor wiring once at user level — one setup, every project covered
+- `npm install -g open-memex` puts the command in your PATH; `init --global` wires your editors. README install chapter rewritten to keep the two straight
+
+## Smarter init (D46 / D47)
+
+- Bare `open-memex init` auto-detects installed editors and wires all of them — no more "which client?" for every project
+- Non-strict-JSON configs (JSONC comments, trailing commas): init leaves the file untouched and prints a ready-to-paste snippet instead
+
+## uninstall (D48)
+
+- New `open-memex uninstall [--client ...] [--global] [--yes]`: removes wiring symmetrically with init, never touches memory data
+
+## Empty-file fix (D49)
+
+- Empty or whitespace-only config files are treated as blank, not corrupt — init writes into them directly (previously refused with "not valid JSON")
+
+## Docs
+
+- FAQ merged into the bilingual README (EN + zh-CN); install chapter rewritten; full `init` synopsis documented
+
+## [0.4.1] - 2026-09-29
+
+- Patch release on the 0.4.0 line (published to npm; no GitHub Release was created at the time).
+
+## [0.4.0] - 2026-09-29
+
+## Team sync via git
+
+- Draft outbox (`appdata project/`) → `sync-status` → `submit` → `promote` / `resolve`: shared memory flows through git branches and PR review, just like code
+- Fast-forward-only pulls, no auto-push — conflicts stop and ask, never overwrite
+- `memory_status` checkpoints: after commits, work chunks, and memory actions
+
+## Portable archives
+
+- `export` / `import`: `.tar.gz` + `manifest.json`; `visibility: private` excluded by default, `--all` for full migration
+
+## Capture loop closed (D42/D43)
+
+- §3.5 checkpoint distillation taught in the MCP handshake instructions and `init`-written instruction files: the agent proposes 1–3 distilled captures at checkpoints, nothing saved without approval
+- `distill-agents` output now ends with a "Memory hygiene" section, so opencode users reading AGENTS.md get the checkpoint habit too
+
+## Also in this release
+
+- 11 memory types (`fact` `preference` `decision` `constraint` `todo` `knowledge` `howto` `gotcha` `lesson` `observation` `reference`)
+- README overhaul, fully bilingual (EN + zh-CN): why open-memex, 11 tools, architecture diagram, stable vs `@alpha` install channels
+- MCP server: 11 tools, re-synced per request; CLI: 26 commands, each with full `--help`
+
+Install: `npm install -g open-memex`
+
+## [0.3.0] - 2026-09-27
+
+- The v2 memory format and protocol ship: `personal` scope (renamed from `user`), RFC 3339 timestamps, type/role split. See `docs/V2-DESIGN.md`; `open-memex migrate --to-v2` converts v1 data. (Published to npm; no GitHub Release was created at the time.)
+
+## [0.1.0] - 2026-09-26
+
+- First public release under the open-memex name (renamed from my-o-memory): local-first memory for AI coding agents — Markdown files as the source of truth, SQLite FTS5 index, opencode plugin + MCP server + CLI.
+
+[Unreleased]: https://github.com/stoneskin/open-memex/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/stoneskin/open-memex/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/stoneskin/open-memex/compare/v0.5.1...v0.6.0
+[0.5.1]: https://github.com/stoneskin/open-memex/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/stoneskin/open-memex/compare/v0.4.0...v0.5.0
+[0.4.1]: https://github.com/stoneskin/open-memex/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/stoneskin/open-memex/releases/tag/v0.4.0
+[0.3.0]: https://github.com/stoneskin/open-memex/releases/tag/v0.3.0
+[0.1.0]: https://github.com/stoneskin/open-memex/releases/tag/v0.1.0
+

package/README.md

@@ -531,6 +531,8 @@ refresh the installed Agent Skill and instruction files with the latest wording.
 If you installed from source or moved the package, `--force` also re-points the
 opencode plugin path.
 
+What changed in each version: see the [CHANGELOG](CHANGELOG.md).
+
 ## Storage layout
 
 ```
@@ -597,7 +599,7 @@ open-memex init [--client vscode|cursor|opencode|visualstudio]
 open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]
 open-memex config                                  # print effective config
 open-memex config set <key> <value>                # change a setting
-open-memex doctor                                  # environment health check
+open-memex doctor                                  # environment health check (incl. plugin entry)
 open-memex audit                                   # memory health check (duplicates, stale, broken chains)
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # preview keyword capture
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio

package/README.zh-CN.md

@@ -365,6 +365,8 @@ npm install -g open-memex@latest   # 或 @alpha
 
 编辑器配置指向已安装的 `open-memex` 命令，所以升级不需要重新接线。大版本升级后跑一次 `open-memex init --force`，把已装的 Agent Skill 和指令文件刷新到最新文案。如果你是从源码安装或挪过包的位置，`--force` 也会把 opencode 插件路径重新指好。
 
+每个版本具体变了什么：见 [CHANGELOG](CHANGELOG.md)（英文）。
+
 ## 存储布局
 
 ```
@@ -419,7 +421,7 @@ open-memex init [--client vscode|cursor|opencode|visualstudio]
 open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]
 open-memex config                                  # 打印生效配置
 open-memex config set <key> <value>                # 改一个设置
-open-memex doctor                                  # 环境健康检查
+open-memex doctor                                  # 环境健康检查（含插件入口巡检）
 open-memex audit                                   # 记忆健康检查（近重复、陈旧、断链）
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # 预览关键词捕获
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio

package/dist/doctor.js

@@ -81,6 +81,135 @@ function lockingCheck() {
         return { name: "locking", ok: false, detail: String(err) };
     }
 }
+/**
+ * D59: patrol the opencode native-plugin entry. The D58 field failure was
+ * silent — the entry was configured, the host never loaded it, and nothing
+ * anywhere said why. Two death modes to catch:
+ *   1. the entry's target file does not exist (package moved, nvm rolled
+ *      to a new version dir, checkout deleted);
+ *   2. the plugin's import closure runtime-imports @opencode-ai/plugin
+ *      (or another host-only module the package does not depend on),
+ *      which is unresolvable from a global install (D58 regression).
+ * Read-only; only inspects the user-level opencode configs.
+ */
+function opencodePluginCheck() {
+    const name = "opencode plugin";
+    try {
+        const jsonPath = opencodeGlobalConfigPath();
+        const candidates = [jsonPath, jsonPath.replace(/\.json$/, ".jsonc")];
+        const entries = [];
+        let sawConfig = false;
+        for (const f of candidates) {
+            if (!fs.existsSync(f))
+                continue;
+            sawConfig = true;
+            const text = fs.readFileSync(f, "utf8");
+            try {
+                const doc = JSON.parse(text);
+                const list = Array.isArray(doc.plugin) ? doc.plugin : [];
+                for (const e of list) {
+                    if (typeof e === "string")
+                        entries.push(e);
+                }
+            }
+            catch {
+                // JSONC (comments/trailing commas): fall back to scanning quoted
+                // strings for plugin entries.
+                for (const m of text.matchAll(/"(file:[^"]+|[^"]+\.(?:ts|js|mts|mjs))"/g)) {
+                    entries.push(m[1]);
+                }
+            }
+        }
+        if (!sawConfig) {
+            return { name, ok: true, detail: "no global opencode config found (skipped)" };
+        }
+        const problems = [];
+        const RUNTIME_SDK_IMPORT = /^\s*import\s+(?!type\b)[^;]*?["']@opencode-ai\/plugin(?:\/[^"']*)?["']/m;
+        const RUNTIME_SDK_REQUIRE = /require\(\s*["']@opencode-ai\/plugin(?:\/[^"']*)?["']\s*\)/;
+        // An entry is ours when its path names the package, or when the target
+        // file carries the plugin's "[open-memex]" log marker (source checkouts
+        // can live at any path).
+        const isOurEntry = (entry) => {
+            if (entry.includes("open-memex"))
+                return true;
+            try {
+                const target = entry.startsWith("file:") ? fileURLToPath(entry) : entry;
+                if (!fs.existsSync(target))
+                    return false;
+                return fs.readFileSync(target, "utf8").slice(0, 65536).includes("[open-memex]");
+            }
+            catch {
+                return false;
+            }
+        };
+        const scanSdkImports = (entryFile) => {
+            // Walk the entry's relative-import closure looking for host-SDK
+            // runtime imports (type-only imports are erased and fine).
+            const offenders = [];
+            const seen = new Set();
+            const queue = [entryFile];
+            while (queue.length > 0 && seen.size < 300) {
+                const file = queue.shift();
+                if (seen.has(file))
+                    continue;
+                seen.add(file);
+                let src;
+                try {
+                    src = fs.readFileSync(file, "utf8");
+                }
+                catch {
+                    continue;
+                }
+                if (RUNTIME_SDK_IMPORT.test(src) || RUNTIME_SDK_REQUIRE.test(src)) {
+                    offenders.push(file);
+                }
+                for (const m of src.matchAll(/(?:from\s+|import\s*\(\s*|import\s+)["'](\.[^"']+)["']/g)) {
+                    const spec = m[1];
+                    const base = path.resolve(path.dirname(file), spec);
+                    for (const cand of [base, `${base}.ts`, `${base}.js`, path.join(base, "index.ts")]) {
+                        if (fs.existsSync(cand) && fs.statSync(cand).isFile()) {
+                            queue.push(cand);
+                            break;
+                        }
+                    }
+                }
+            }
+            return offenders;
+        };
+        const ours = entries.filter(isOurEntry);
+        if (ours.length === 0) {
+            return { name, ok: true, detail: "no global plugin entry (per-project or MCP wiring is not checked)" };
+        }
+        for (const entry of ours) {
+            let target;
+            try {
+                target = entry.startsWith("file:") ? fileURLToPath(entry) : entry;
+            }
+            catch {
+                problems.push(`entry "${entry}" is not a parseable file URL`);
+                continue;
+            }
+            if (!fs.existsSync(target)) {
+                problems.push(`entry points at ${target}, which does not exist — run \`open-memex init --client opencode --global --force\` to re-point it`);
+                continue;
+            }
+            for (const f of scanSdkImports(target)) {
+                problems.push(`${f} runtime-imports @opencode-ai/plugin — opencode silently skips plugins whose imports it cannot resolve from a global install (D58)`);
+            }
+        }
+        if (problems.length > 0) {
+            return { name, ok: false, detail: problems.join("; ") };
+        }
+        return {
+            name,
+            ok: true,
+            detail: `${ours.length} plugin ${ours.length === 1 ? "entry" : "entries"}: target exists, no host-SDK runtime imports`,
+        };
+    }
+    catch (err) {
+        return { name, ok: false, detail: String(err) };
+    }
+}
 /** Spawn the real MCP server, handshake, and verify the five tools list. */
 function mcpCheck() {
     const name = "mcp";
@@ -299,7 +428,7 @@ function vscodeMcpCheck() {
 }
 export async function runDoctor() {
     console.log("open-memex doctor");
-    const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), lockingCheck(), vscodeMcpCheck()];
+    const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), lockingCheck(), opencodePluginCheck(), vscodeMcpCheck()];
     checks.push(await mcpCheck());
     checks.push(legacyCheck());
     let allOk = true;

package/docs/V2-DESIGN.md

@@ -1197,13 +1197,26 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   register. Rule going forward: plugin code imports host SDK types only;
   runtime imports must resolve from the package's own dependencies.
 
+- **D59** — `doctor` patrols the plugin entry it used to take on faith
+  (0.6.2-alpha.1). D58's failure was invisible to every existing check:
+  `doctor` verified the MCP server end-to-end but never looked at the
+  opencode plugin entry, so a configured-but-dead plugin passed all
+  checks. The new `opencode plugin` check reads the user-level opencode
+  configs (`opencode.json` + `opencode.jsonc`), attributes entries to
+  this plugin by package path or the `[open-memex]` marker (source
+  checkouts live anywhere), and fails when (a) the entry's target file
+  does not exist — with the `init --force` re-point command named — or
+  (b) the entry's relative-import closure runtime-imports
+  `@opencode-ai/plugin`, the exact D58 death. It checks only what can be
+  attributed; per-project and MCP wiring are out of scope.
+
 ## Open Questions
 
 _All resolved — see D10 (rename), D11 (type/role split), D12 (explicit pull)._
 
 - **Checkpoint proactivity for capture (open, 2026-10-02):** D53 retired checkpoint *polling* — the server pushes draft counts instead. But agent proactivity at task checkpoints genuinely helps knowledge capture (§3.5 distillation), so the open question is the degree: proactive enough to catch distillable moments, without nagging the user or burning tokens at every checkpoint. Candidate directions (server-pushed hints in tool results, client-side heuristics, or a middle setting) to be evaluated in a later version; default posture TBD.
 
-- **Retrieval robustness: phrasing, synonyms, extra words (open, 2026-10-03):** keyword search matches word forms, not meaning — the asker phrases it differently, adds a word, or uses a synonym and the memory is missed. The current FTS5 setup (porter stemming + pre-tokenized CJK bigrams) already covers morphology and substrings; it cannot bridge semantics. Layered candidate directions, cheapest first: (1) query construction — never feed a raw sentence to FTS; extract content terms, drop stopwords, OR them and let bm25 rank, so extra words hurt ranking instead of killing the match; (2) agent-side query expansion as an explicit protocol in the skill/instructions (decompose the question into concepts, generate 2–3 synonym variants per concept, run several searches before giving up — the LLM is the synonym dictionary, no embedding model needed); (3) capture-time aliasing — when a memory is written, the agent attaches keyword/synonym aliases so future phrasings can hit it. Embeddings are the design's reserved optional capability: real semantic matching, but they require a design decision and a local model to distribute, so they stay deferred unless (1)–(3) prove insufficient. Note (3) pairs naturally with the proactive-capture question below: the same capture pass that proposes a memory can attach its aliases.
+- **Retrieval robustness: phrasing, synonyms, extra words (open, 2026-10-03):** keyword search matches word forms, not meaning — the asker phrases it differently, adds a word, or uses a synonym and the memory is missed. The current FTS5 setup (porter stemming + pre-tokenized CJK bigrams) already covers morphology and substrings; it cannot bridge semantics. Layered candidate directions, cheapest first: (1) query construction — never feed a raw sentence to FTS; extract content terms, drop stopwords, OR them and let bm25 rank, so extra words hurt ranking instead of killing the match; (2) agent-side query expansion as an explicit protocol in the skill/instructions (decompose the question into concepts, generate 2–3 synonym variants per concept, run several searches before giving up — the LLM is the synonym dictionary, no embedding model needed); (3) capture-time aliasing — when a memory is written, the agent attaches keyword/synonym aliases so future phrasings can hit it. Embeddings are the design's reserved optional capability: real semantic matching, but they require a design decision and a local model to distribute, so they stay deferred unless (1)–(3) prove insufficient. Note (3) pairs naturally with the proactive-capture question below: the same capture pass that proposes a memory can attach its aliases. **Status (2026-10-03): layer (1) shipped (D56, 0.6.1)** — query construction now filters EN/CJK function words, dedupes, and caps terms. Layers (2) agent-side expansion and (3) capture-time aliasing remain open; embeddings stay deferred.
 
 - **Proactive capture: agent judgment of what is worth remembering (open, 2026-10-03):** companion to the checkpoint-proactivity question above — that one asks *when* to prompt; this one asks *what qualifies*. Agent hosts with good long-term memory (e.g. Muse) get their results from explicit memorability criteria plus checkpoint consolidation, not from silent background magic; open-memex can adopt both halves. Candidate criteria to teach via the skill/instructions: decisions **and their rationale**, preferences, conventions, gotchas, and abandoned paths ("we tried X, it failed because…") are worth proposing; one-off task details and anything re-derivable from the code are not. Two postures to evaluate: propose-at-checkpoint (agent asks "worth saving?", user vetoes, then `memory_add`) versus auto-draft (agent writes outbox drafts unasked and surfaces them in a batch at the next checkpoint — drafts are git-invisible and deletable, so the cost of a wrong guess is low). Hard boundaries either way: project scope never auto-submits, and no cross-session background consolidation is possible — the plugin lives inside sessions, so consolidation happens at in-session checkpoints and wrap-up passes only. This question also decides how much aliasing (retrieval question above) the capture pass should generate.
 
@@ -1211,11 +1224,11 @@ _All resolved — see D10 (rename), D11 (type/role split), D12 (explicit pull)._
 
 - **Retrospective distillation: mining host transcripts after the fact (open, 2026-10-03):** open-memex captures only in-session (keyword triggers, explicit `memory_add`) and keeps **no transcript** — so anything not captured during the conversation is gone once it ends. Hosts with durable memory (e.g. Muse) avoid this loss with two layers open-memex skipped: full transcript retention plus background distillation. The gap is architectural, not a timing detail: the raw material for a second chance does not exist on our side. But the hosts themselves already retain it — opencode persists sessions and messages in its local store; Claude Code keeps JSONL transcripts under `~/.claude/projects/`; VS Code Copilot's chat state is locked in workspace storage (readable, fragile, not a first target). Candidate direction: a "replay distillation" flow that exports a past session's transcript and has an agent mine it in a dedicated review session, with every extracted candidate landing as an **outbox draft** for human review — never a direct save. Boundaries that keep this inside the existing design: open-memex builds no transcript store of its own (borrow the host's), mining judgment is the agent's LLM work (we provide the export and the queue, not an extractor), fully local, mined drafts carry their provenance (`source` marks them as distilled, from which session). Open sub-questions: host adapters per tool (opencode store format, Claude Code JSONL), how the user picks sessions to mine (by date? by project? "everything since last sync"?), and whether the proactive-capture criteria (open question above) should be the mining rubric verbatim — likely yes.
 
-- **Retrieval explainability and memory health (open, 2026-10-03):** from a heavy-user review. Search is currently a black box: when a memory is missed, there is no way to tell whether the query was bad, the memory is stale, it was ranked down by review state, or it is hiding behind a supersede chain. Candidate additions: a debug/explain view for `search` (matched terms, bm25 score, ranking effects, supersede exclusions), and a memory-side audit next to `doctor` (which today checks the environment, not the memories): near-duplicate candidates, memories untouched for N days still occupying injection slots, broken supersede chains, orphan scopes. Also undocumented and untested territory the same review surfaced: **concurrent sessions** — several agents on one machine writing the same store (simultaneous `memory_add`, reindex races, submit vs pull). File-locking/WAL behavior needs to be established, documented, and ideally guarded by a doctor check before a user finds out via a corrupt index.
+- **Retrieval explainability and memory health (open, 2026-10-03):** from a heavy-user review. Search is currently a black box: when a memory is missed, there is no way to tell whether the query was bad, the memory is stale, it was ranked down by review state, or it is hiding behind a supersede chain. Candidate additions: a debug/explain view for `search` (matched terms, bm25 score, ranking effects, supersede exclusions), and a memory-side audit next to `doctor` (which today checks the environment, not the memories): near-duplicate candidates, memories untouched for N days still occupying injection slots, broken supersede chains, orphan scopes. Also undocumented and untested territory the same review surfaced: **concurrent sessions** — several agents on one machine writing the same store (simultaneous `memory_add`, reindex races, submit vs pull). File-locking/WAL behavior needs to be established, documented, and ideally guarded by a doctor check before a user finds out via a corrupt index. **Status: resolved (D57, 0.6.1)** — `search --explain`, the `audit` command, and the concurrency posture (WAL + unified 5s busy timeout, tmp+rename writes, doctor locking check) all shipped.
 
-- **Host parity: plugin vs MCP tool surface (open, 2026-10-03):** the opencode plugin exposes 5 memory tools; the MCP server exposes 11 (`memory_status`, submit/propose/promote/resolve/pr_status missing on the plugin side). A user switching hosts mid-week hits missing tools with no explanation and reasonably assumes breakage. Options: bring the plugin to parity, or document the asymmetry as intentional (CLI covers the rest) in the tool descriptions themselves so the absence reads as design rather than defect. Needs a decision; silence is the current — worst — option.
+- **Host parity: plugin vs MCP tool surface (open, 2026-10-03):** the opencode plugin exposes 5 memory tools; the MCP server exposes 11 (`memory_status`, submit/propose/promote/resolve/pr_status missing on the plugin side). A user switching hosts mid-week hits missing tools with no explanation and reasonably assumes breakage. Options: bring the plugin to parity, or document the asymmetry as intentional (CLI covers the rest) in the tool descriptions themselves so the absence reads as design rather than defect. Needs a decision; silence is the current — worst — option. **Status: decided (D56, 0.6.1)** — the asymmetry is documented in the MCP-only tool descriptions with CLI equivalents named; full plugin parity remains a possible future feature, no longer an open question.
 
-- **Novice experience: first success and plain language (open, 2026-10-03):** from an AI-novice review. The install ends with instructions, not an experience: candidate fix is a 60-second magic moment — init offers to save one sample memory and immediately has the user's agent answer a question using it, so the user *sees* recall work before being asked to trust it. Same screen should state the privacy model in plain words (personal never leaves this machine, no cloud, detected secrets are masked — all already true, all currently buried in docs), and the first time a suspected secret is masked, the capture path should say so. Underneath: a plain-language layer over the state machine ("saved on this computer" / "shared with the team") with outbox/submit/promote vocabulary becoming the advanced view — this is the same vocabulary wall the PM/BA question above hits from the other side.
+- **Novice experience: first success and plain language (open, 2026-10-03):** from an AI-novice review. The install ends with instructions, not an experience: candidate fix is a 60-second magic moment — init offers to save one sample memory and immediately has the user's agent answer a question using it, so the user *sees* recall work before being asked to trust it. Same screen should state the privacy model in plain words (personal never leaves this machine, no cloud, detected secrets are masked — all already true, all currently buried in docs), and the first time a suspected secret is masked, the capture path should say so. Underneath: a plain-language layer over the state machine ("saved on this computer" / "shared with the team") with outbox/submit/promote vocabulary becoming the advanced view — this is the same vocabulary wall the PM/BA question above hits from the other side. **Status (2026-10-03): partially addressed** — `init` now states the privacy model in plain words (D56); the 60-second magic moment and the plain-language layer remain open.
 
 - **Memory visibility and correctability (open, 2026-10-03):** also from the novice review, and arguably the trust foundation for every other feature. A non-CLI user currently cannot answer "what does my assistant remember about me?" without reading Markdown files. Candidate directions: a human-readable inventory (local HTML export or equivalent) listing memories in plain language with provenance shown the way a person asks for it ("saved 3 days ago while you were discussing deploys in project X") and one-step forget/undo from the same view. Provenance fields already exist in frontmatter; this is presentation, not schema. Without it, proactive capture (above) will read to novices as surveillance rather than help — so this question probably gates the auto-draft posture decision in the capture question.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",

package/src/doctor.ts

@@ -93,6 +93,134 @@ function lockingCheck(): Check {
   }
 }
 
+/**
+ * D59: patrol the opencode native-plugin entry. The D58 field failure was
+ * silent — the entry was configured, the host never loaded it, and nothing
+ * anywhere said why. Two death modes to catch:
+ *   1. the entry's target file does not exist (package moved, nvm rolled
+ *      to a new version dir, checkout deleted);
+ *   2. the plugin's import closure runtime-imports @opencode-ai/plugin
+ *      (or another host-only module the package does not depend on),
+ *      which is unresolvable from a global install (D58 regression).
+ * Read-only; only inspects the user-level opencode configs.
+ */
+function opencodePluginCheck(): Check {
+  const name = "opencode plugin";
+  try {
+    const jsonPath = opencodeGlobalConfigPath();
+    const candidates = [jsonPath, jsonPath.replace(/\.json$/, ".jsonc")];
+    const entries: string[] = [];
+    let sawConfig = false;
+    for (const f of candidates) {
+      if (!fs.existsSync(f)) continue;
+      sawConfig = true;
+      const text = fs.readFileSync(f, "utf8");
+      try {
+        const doc = JSON.parse(text) as { plugin?: unknown };
+        const list = Array.isArray(doc.plugin) ? doc.plugin : [];
+        for (const e of list) {
+          if (typeof e === "string") entries.push(e);
+        }
+      } catch {
+        // JSONC (comments/trailing commas): fall back to scanning quoted
+        // strings for plugin entries.
+        for (const m of text.matchAll(/"(file:[^"]+|[^"]+\.(?:ts|js|mts|mjs))"/g)) {
+          entries.push(m[1]!);
+        }
+      }
+    }
+    if (!sawConfig) {
+      return { name, ok: true, detail: "no global opencode config found (skipped)" };
+    }
+
+    const problems: string[] = [];
+    const RUNTIME_SDK_IMPORT =
+      /^\s*import\s+(?!type\b)[^;]*?["']@opencode-ai\/plugin(?:\/[^"']*)?["']/m;
+    const RUNTIME_SDK_REQUIRE = /require\(\s*["']@opencode-ai\/plugin(?:\/[^"']*)?["']\s*\)/;
+
+    // An entry is ours when its path names the package, or when the target
+    // file carries the plugin's "[open-memex]" log marker (source checkouts
+    // can live at any path).
+    const isOurEntry = (entry: string): boolean => {
+      if (entry.includes("open-memex")) return true;
+      try {
+        const target = entry.startsWith("file:") ? fileURLToPath(entry) : entry;
+        if (!fs.existsSync(target)) return false;
+        return fs.readFileSync(target, "utf8").slice(0, 65536).includes("[open-memex]");
+      } catch {
+        return false;
+      }
+    };
+    const scanSdkImports = (entryFile: string): string[] => {
+      // Walk the entry's relative-import closure looking for host-SDK
+      // runtime imports (type-only imports are erased and fine).
+      const offenders: string[] = [];
+      const seen = new Set<string>();
+      const queue = [entryFile];
+      while (queue.length > 0 && seen.size < 300) {
+        const file = queue.shift()!;
+        if (seen.has(file)) continue;
+        seen.add(file);
+        let src: string;
+        try {
+          src = fs.readFileSync(file, "utf8");
+        } catch {
+          continue;
+        }
+        if (RUNTIME_SDK_IMPORT.test(src) || RUNTIME_SDK_REQUIRE.test(src)) {
+          offenders.push(file);
+        }
+        for (const m of src.matchAll(/(?:from\s+|import\s*\(\s*|import\s+)["'](\.[^"']+)["']/g)) {
+          const spec = m[1]!;
+          const base = path.resolve(path.dirname(file), spec);
+          for (const cand of [base, `${base}.ts`, `${base}.js`, path.join(base, "index.ts")]) {
+            if (fs.existsSync(cand) && fs.statSync(cand).isFile()) {
+              queue.push(cand);
+              break;
+            }
+          }
+        }
+      }
+      return offenders;
+    };
+
+    const ours = entries.filter(isOurEntry);
+    if (ours.length === 0) {
+      return { name, ok: true, detail: "no global plugin entry (per-project or MCP wiring is not checked)" };
+    }
+    for (const entry of ours) {
+      let target: string;
+      try {
+        target = entry.startsWith("file:") ? fileURLToPath(entry) : entry;
+      } catch {
+        problems.push(`entry "${entry}" is not a parseable file URL`);
+        continue;
+      }
+      if (!fs.existsSync(target)) {
+        problems.push(
+          `entry points at ${target}, which does not exist — run \`open-memex init --client opencode --global --force\` to re-point it`,
+        );
+        continue;
+      }
+      for (const f of scanSdkImports(target)) {
+        problems.push(
+          `${f} runtime-imports @opencode-ai/plugin — opencode silently skips plugins whose imports it cannot resolve from a global install (D58)`,
+        );
+      }
+    }
+    if (problems.length > 0) {
+      return { name, ok: false, detail: problems.join("; ") };
+    }
+    return {
+      name,
+      ok: true,
+      detail: `${ours.length} plugin ${ours.length === 1 ? "entry" : "entries"}: target exists, no host-SDK runtime imports`,
+    };
+  } catch (err) {
+    return { name, ok: false, detail: String(err) };
+  }
+}
+
 /** Spawn the real MCP server, handshake, and verify the five tools list. */
 function mcpCheck(): Promise<Check> {
   const name = "mcp";
@@ -320,7 +448,7 @@ function vscodeMcpCheck(): Check {
 
 export async function runDoctor(): Promise<boolean> {
   console.log("open-memex doctor");
-  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), lockingCheck(), vscodeMcpCheck()];
+  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), lockingCheck(), opencodePluginCheck(), vscodeMcpCheck()];
   checks.push(await mcpCheck());
   checks.push(legacyCheck());
   let allOk = true;