open-memex 0.6.1-alpha.1 → 0.6.1

package/AGENTS.md

@@ -18,6 +18,8 @@ via `prepublishOnly` — Node refuses `--experimental-strip-types` for files und
 
 Tool logic is host-agnostic and lives in `src/tools/ops.ts` (plain functions + shared zod arg shapes + `TOOL_DESCRIPTIONS`). `src/tools/memory.ts` (opencode) and `src/mcp.ts` are thin adapters — when adding or changing a tool, change `ops.ts` once and both hosts pick it up.
 
+**Plugin code must not runtime-import `@opencode-ai/plugin`** (D58): it is a devDependency, and opencode does not resolve it for `file://` plugins loaded from a global npm install — the import fails and opencode silently skips the plugin (no error, no tools). Type-only imports are fine. `src/tools/memory.ts` carries a local stand-in for the SDK's `tool()` (a runtime identity) for exactly this reason.
+
 Consequences:
 - Imports **must** use explicit `.ts` extensions (`allowImportingTsExtensions: true`, `moduleResolution: "Bundler"`).
 - No transpile / bundle output. Do not add one; opencode loads the `.ts` file directly.
@@ -31,6 +33,7 @@ npm run typecheck                                    # tsc --noEmit — the only
 npm run cli -- where | list | search "q" | add ... | forget <id> | reindex
 npm run cli -- <command> --help                          # per-command help (AI assistants discover flags this way)
 npm run cli -- sync-status                                  # last sync time/kind + outbox drafts + repo review states + uncommitted files
+npm run cli -- audit [--scope project|personal|both]            # memory health: near-dup pairs, stale actives, broken chains, personal-in-repo (read-only)
 npm run cli -- pull                                          # fetch + fast-forward only (explicit; diverged = clean failure, never force-merge)
 npm run cli -- push                                          # push current branch to remote (explicit only; open-memex never auto-pushes)
 npm run cli -- export [--scope project|personal|both] [--all] [-o <file>]  # portable .tar.gz bundle (markdown + manifest); private excluded unless --all

package/README.md

@@ -598,6 +598,7 @@ open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [
 open-memex config                                  # print effective config
 open-memex config set <key> <value>                # change a setting
 open-memex doctor                                  # environment health check
+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
 open-memex --help      # this reference
@@ -610,6 +611,7 @@ Memory operations:
 ```sh
 open-memex add "This repo uses better-sqlite3" --type fact
 open-memex search "auth flow"
+open-memex search "auth flow" --explain   # show FTS expression, scores, lifecycle-hidden counts
 open-memex list --scope project
 open-memex supersede <id> "Updated content"
 open-memex status <id> deprecated
@@ -711,6 +713,7 @@ Maintenance:
 open-memex where        # show storage + config paths
 open-memex scopes       # list project scopes with memory counts
 open-memex reindex      # rebuild the SQLite index from markdown
+open-memex audit        # memory health: duplicate pairs, stale memories, broken chains
 open-memex migrate --to-v2 [--dry-run]   # v1 data → v2 (renames user scope to personal)
 ```
 

package/README.zh-CN.md

@@ -420,6 +420,7 @@ open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [
 open-memex config                                  # 打印生效配置
 open-memex config set <key> <value>                # 改一个设置
 open-memex doctor                                  # 环境健康检查
+open-memex audit                                   # 记忆健康检查（近重复、陈旧、断链）
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # 预览关键词捕获
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
 open-memex --help      # 这份参考
@@ -432,6 +433,7 @@ open-memex --version   # 已安装版本
 ```sh
 open-memex add "This repo uses better-sqlite3" --type fact
 open-memex search "auth flow"
+open-memex search "auth flow" --explain   # 显示 FTS 表达式、分数、被生命周期藏掉的计数
 open-memex list --scope project
 open-memex supersede <id> "Updated content"
 open-memex status <id> deprecated
@@ -514,6 +516,7 @@ open-memex resolve [id-or-path]
 open-memex where        # 显示存储与配置路径
 open-memex scopes       # 列出各项目作用域及记忆计数
 open-memex reindex      # 从 markdown 重建 SQLite 索引
+open-memex audit        # 记忆健康检查：近重复对、陈旧记忆、断裂的取代链
 open-memex migrate --to-v2 [--dry-run]   # v1 数据 → v2（把 user 作用域改名为 personal）
 ```
 

package/dist/cli.js

@@ -41,12 +41,14 @@ Examples:
   open-memex list --scope personal --limit 20`,
     search: `Search memories by keyword (BM25 full-text), best matches first.
 
-Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N] [--explain]
 
 Flags:
-  --scope   project (default), personal, or both
-  --type    filter by memory type
-  --limit   max results
+  --scope    project (default), personal, or both
+  --type     filter by memory type
+  --limit    max results
+  --explain  show the FTS expression, per-hit score, and how many matches
+             lifecycle hid (superseded / retracted / archived)
 
 Example:
   open-memex search "deploy checklist" --scope both`,
@@ -304,6 +306,18 @@ Usage: open-memex doctor
 
 Example:
   open-memex doctor`,
+    audit: `Memory health audit (read-only, reports never mutates): near-duplicate
+pairs among active memories, stale actives untouched for 90+ days, broken
+supersede chains, personal files found inside the repo memory dir, and
+index/file drift.
+
+Usage: open-memex audit [--scope project|personal|both]
+
+Flags:
+  --scope   project (default), personal, or both
+
+Example:
+  open-memex audit --scope both`,
 };
 function usage(exitCode = 1) {
     console.log(`open-memex CLI
@@ -311,7 +325,7 @@ function usage(exitCode = 1) {
 Usage:
   open-memex where
   open-memex list [--scope project|personal] [--type T] [--limit N]
-  open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+  open-memex search "query" [--scope project|personal|both] [--type T] [--limit N] [--explain]
   open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
   open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
   open-memex status <id> active|deprecated|retracted|archived
@@ -328,6 +342,7 @@ Usage:
   open-memex submit <id...> [--branch <name>] [--base <branch>]
   open-memex pr-status [--apply]
   open-memex reindex
+  open-memex audit [--scope project|personal|both]
   open-memex scopes
   open-memex migrate [--from <key>] [--to <key>]
                                           [--dry-run] [--on-conflict newer|overwrite|skip]
@@ -621,6 +636,36 @@ async function main() {
             process.exitCode = 1;
         return;
     }
+    if (cmd === "audit") {
+        const flags = parseFlags(rest);
+        syncScope(project.key, "cli");
+        syncScope(PERSONAL_SCOPE.key, "cli");
+        const keys = flags.scope === "personal"
+            ? [PERSONAL_SCOPE.key]
+            : flags.scope === "both"
+                ? [project.key, PERSONAL_SCOPE.key]
+                : [project.key];
+        const { runAudit, STALE_DAYS } = await import("./store/audit.js");
+        const r = runAudit(keys);
+        console.log(`audit: ${r.totalMemories} memories (${keys.length === 2 ? "project+personal" : keys[0] === PERSONAL_SCOPE.key ? "personal" : "project"})`);
+        console.log(`  near-duplicate active pairs: ${r.duplicatePairs.length}`);
+        for (const p of r.duplicatePairs.slice(0, 10)) {
+            console.log(`    ${p.a} ~ ${p.b} (similarity ${p.score.toFixed(2)}) — consider supersede`);
+        }
+        console.log(`  stale actives (>= ${STALE_DAYS} days untouched): ${r.stale.length}`);
+        for (const s of r.stale.slice(0, 10)) {
+            console.log(`    ${s.id} — ${s.ageDays} days`);
+        }
+        console.log(`  broken supersede chains: ${r.brokenChains.length}`);
+        for (const b of r.brokenChains) {
+            console.log(`    ${b.id} -> missing ${b.missingTarget}`);
+        }
+        console.log(`  personal files inside repo memory dir: ${r.personalInRepo.length}`);
+        for (const f of r.personalInRepo)
+            console.log(`    ${f}`);
+        console.log(`  index drift: ${r.drift.filesNotIndexed} files not indexed, ${r.drift.rowsMissingFiles} rows missing files`);
+        return;
+    }
     // `config` prints the effective configuration (defaults + file). No DB needed.
     // `config set <key> <value>` persists a setting to the config file.
     if (cmd === "config") {
@@ -743,11 +788,20 @@ async function main() {
             : flags.scope === "project"
                 ? [project.key]
                 : [project.key, PERSONAL_SCOPE.key];
+        const explain = flags.explain === "true";
+        const stats = explain
+            ? { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0 }
+            : undefined;
         const hits = search(query, {
             scopeKeys: keys,
             limit: flags.limit ? Number(flags.limit) : undefined,
             type: flags.type,
+            stats,
         });
+        if (explain && stats) {
+            console.log(`fts: ${stats.ftsQuery || "(empty query)"}`);
+            console.log(`candidates: ${stats.candidates}, hidden by lifecycle: ${stats.hiddenSuperseded} superseded, ${stats.hiddenExcluded} retracted/archived`);
+        }
         if (hits.length === 0) {
             console.log("(no matches)");
             return;
@@ -756,7 +810,8 @@ async function main() {
             const tag = h.scope_key === PERSONAL_SCOPE.key ? "personal" : "project";
             const dep = h.status === "deprecated" ? " [deprecated]" : "";
             const rev = hitStateLabel(h);
-            console.log(`[${tag}/${h.type}]${dep}${rev} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+            const sc = explain ? ` score=${h.score.toFixed(3)}` : "";
+            console.log(`[${tag}/${h.type}]${dep}${rev}${sc} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
         }
         return;
     }
@@ -1261,7 +1316,16 @@ async function main() {
 }
 main()
     .catch((err) => {
-    console.error(err);
+    // D57: lock contention past the busy timeout should read as a transient
+    // condition, not a stack trace. The memory file is written before the
+    // index update, so a locked-out write still lands on the next sync.
+    const code = err?.code;
+    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED") {
+        console.error("open-memex: the memory store is busy (another open-memex process is writing). Wait a moment and retry — nothing was lost.");
+    }
+    else {
+        console.error(err);
+    }
     process.exit(1);
 })
     .finally(() => {

package/dist/doctor.js

@@ -10,6 +10,7 @@ import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.js";
 import { paths } from "./paths.js";
 import { resolveCwdScope } from "./scope.js";
+import { db, backendName } from "./store/db.js";
 import { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.js";
 const EXPECTED_TOOLS = [
     "memory_add",
@@ -59,6 +60,27 @@ function storageCheck() {
         return { name: "storage", ok: false, detail: String(err) };
     }
 }
+/**
+ * D57: several processes share one index (CLI, MCP per editor, opencode
+ * plugin). WAL + a 5s busy timeout is what keeps an overlapping write a
+ * brief wait instead of an instant failure — report the live settings.
+ */
+function lockingCheck() {
+    try {
+        const d = db();
+        const jm = d.prepare("PRAGMA journal_mode").get().journal_mode;
+        const bt = d.prepare("PRAGMA busy_timeout").get().timeout;
+        const ok = jm === "wal" && bt >= 1000;
+        return {
+            name: "locking",
+            ok,
+            detail: `journal=${jm}, busy_timeout=${bt}ms (${backendName()})`,
+        };
+    }
+    catch (err) {
+        return { name: "locking", ok: false, detail: String(err) };
+    }
+}
 /** Spawn the real MCP server, handshake, and verify the five tools list. */
 function mcpCheck() {
     const name = "mcp";
@@ -277,7 +299,7 @@ function vscodeMcpCheck() {
 }
 export async function runDoctor() {
     console.log("open-memex doctor");
-    const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), vscodeMcpCheck()];
+    const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), lockingCheck(), vscodeMcpCheck()];
     checks.push(await mcpCheck());
     checks.push(legacyCheck());
     let allOk = true;

package/dist/retrieve/search.js

@@ -44,7 +44,7 @@ export function hitStateLabel(h) {
  *   drafts/rejected rank after unreviewed content;
  * - deprecated stays visible as a warning but ranks after active.
  */
-function resolveVisible(rows, limit) {
+function resolveVisible(rows, limit, stats) {
     const byId = new Map(rows.map((r) => [r.id, r]));
     const fullRow = (id) => {
         const cached = byId.get(id);
@@ -65,10 +65,15 @@ function resolveVisible(rows, limit) {
     const tiers = [[], [], [], []];
     const deprecated = [];
     for (const r of rows) {
-        if (r.status === "retracted" || r.status === "archived")
+        if (r.status === "retracted" || r.status === "archived") {
+            if (stats)
+                stats.hiddenExcluded++;
             continue;
+        }
         let target = r;
         if (r.status === "superseded") {
+            if (stats)
+                stats.hiddenSuperseded++;
             let cur = r;
             const chain = new Set([r.id]);
             while (cur.status === "superseded" && cur.superseded_by) {
@@ -102,6 +107,12 @@ function resolveVisible(rows, limit) {
  */
 export function search(query, opts = {}) {
     const q = toFtsQuery(query);
+    if (opts.stats) {
+        opts.stats.ftsQuery = q;
+        opts.stats.candidates = 0;
+        opts.stats.hiddenSuperseded = 0;
+        opts.stats.hiddenExcluded = 0;
+    }
     if (!q)
         return [];
     const limit = Math.max(1, Math.min(opts.limit ?? 8, 50));
@@ -134,7 +145,9 @@ export function search(query, opts = {}) {
         .all(...params);
     // FTS5 bm25: lower = better; invert for intuition.
     const raw = rows.map((r) => ({ ...r, score: -r.score }));
-    return resolveVisible(raw, limit);
+    if (opts.stats)
+        opts.stats.candidates = raw.length;
+    return resolveVisible(raw, limit, opts.stats);
 }
 export function list(scopeKey, opts = {}) {
     const limit = Math.max(1, Math.min(opts.limit ?? 20, 100));

package/dist/store/audit.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import { db } from "./db.js";
+import { readMemoryFile, iterInRepoMemoryFiles, iterMemoryFiles, } from "./markdown.js";
+import { similarity, NEAR_DUP_THRESHOLD } from "./lifecycle.js";
+import { projectRoot } from "../paths.js";
+import { loadConfig } from "../config.js";
+// Memory health audit (D57). Read-only: reports, never mutates.
+// Checks, per open question "retrieval explainability & memory health":
+//   - near-duplicate pairs among active memories (same dedup yardstick
+//     as write-time: Jaccard >= 0.8) that were never superseded;
+//   - stale actives: untouched for STALE_DAYS, still in the retrieval /
+//     injection pool;
+//   - broken supersede chains: superseded_by pointing at a missing id;
+//   - personal files inside the in-repo memory dir (iron-rule breach:
+//     personal memory must never land in a shared repo);
+//   - index/file drift after sync (should be zero; reported if not).
+export const STALE_DAYS = 90;
+export function runAudit(scopeKeys) {
+    const d = db();
+    const rows = d
+        .prepare(`SELECT id, scope_key, status, updated_at, superseded_by, content, file_path
+       FROM memories`)
+        .all();
+    const inScope = rows.filter((r) => scopeKeys.includes(r.scope_key));
+    const ids = new Set(rows.map((r) => r.id));
+    // Near-duplicate pairs: active only, same scope. O(n^2) per scope with a
+    // length pre-filter; local stores are small enough for this to be fine.
+    const pairs = [];
+    const byScope = new Map();
+    for (const r of inScope) {
+        if (r.status !== "active")
+            continue;
+        const arr = byScope.get(r.scope_key) ?? [];
+        arr.push(r);
+        byScope.set(r.scope_key, arr);
+    }
+    for (const [scopeKey, arr] of byScope) {
+        for (let i = 0; i < arr.length; i++) {
+            for (let j = i + 1; j < arr.length; j++) {
+                const a = arr[i];
+                const b = arr[j];
+                const la = a.content.length;
+                const lb = b.content.length;
+                if (Math.min(la, lb) / Math.max(la, lb) < 0.5)
+                    continue;
+                const score = similarity(a.content, b.content);
+                if (score >= NEAR_DUP_THRESHOLD) {
+                    pairs.push({ a: a.id, b: b.id, scopeKey, score });
+                }
+            }
+        }
+    }
+    pairs.sort((x, y) => y.score - x.score);
+    const now = Date.now();
+    const stale = inScope
+        .filter((r) => r.status === "active")
+        .map((r) => ({ id: r.id, scopeKey: r.scope_key, ageDays: Math.floor((now - r.updated_at) / 86_400_000) }))
+        .filter((s) => s.ageDays >= STALE_DAYS)
+        .sort((x, y) => y.ageDays - x.ageDays);
+    const brokenChains = inScope
+        .filter((r) => r.superseded_by && !ids.has(r.superseded_by))
+        .map((r) => ({ id: r.id, scopeKey: r.scope_key, missingTarget: r.superseded_by }));
+    // Personal files must never sit in the in-repo dir. Read-only: this only
+    // parses frontmatter of files already in the repo tree.
+    const personalInRepo = [];
+    try {
+        const root = projectRoot();
+        const memoryDir = loadConfig().memoryDir;
+        for (const fp of iterInRepoMemoryFiles(root, memoryDir)) {
+            const mf = readMemoryFile(fp);
+            if (mf && mf.fm.scope === "personal")
+                personalInRepo.push(fp);
+        }
+    }
+    catch {
+        // No project root (e.g. personal-only usage): nothing to scan.
+    }
+    // Drift: index rows whose file vanished, and files on disk the index
+    // never picked up. syncScope normally heals both before audit runs.
+    const indexedPaths = new Set(rows.map((r) => r.file_path));
+    let rowsMissingFiles = 0;
+    for (const r of inScope) {
+        if (!r.file_path || !fs.existsSync(r.file_path))
+            rowsMissingFiles++;
+    }
+    let filesNotIndexed = 0;
+    for (const key of scopeKeys) {
+        for (const fp of iterMemoryFiles(key)) {
+            if (!indexedPaths.has(fp))
+                filesNotIndexed++;
+        }
+    }
+    return {
+        totalMemories: inScope.length,
+        duplicatePairs: pairs,
+        stale,
+        brokenChains,
+        personalInRepo,
+        drift: { filesNotIndexed, rowsMissingFiles },
+    };
+}

package/dist/store/db.js

@@ -111,6 +111,11 @@ export function db() {
     const Database = loadDatabase();
     const d = new Database(indexDb);
     d.exec("PRAGMA journal_mode = WAL;");
+    // Multiple processes share this index (CLI, one MCP server per editor,
+    // the opencode plugin). Without a busy timeout, bun:sqlite defaults to
+    // 0 — any overlapping write fails instantly. 5s matches the tolerance
+    // better-sqlite3 was already giving the CLI/MCP side (D57).
+    d.exec("PRAGMA busy_timeout = 5000;");
     d.exec("PRAGMA synchronous = NORMAL;");
     d.exec("PRAGMA foreign_keys = ON;");
     d.exec(TABLE_SCHEMA);

package/dist/store/markdown.js

@@ -205,7 +205,12 @@ export function writeMemoryFile(fm, body) {
     // Personal stays in appdata and never leaves the machine.
     const dir = memoriesDirFor(fm.scope_key);
     const filePath = path.join(dir, `${fm.id}.md`);
-    fs.writeFileSync(filePath, serialize(fm, body), "utf8");
+    // Atomic publish (D57): write a sibling tmp file and rename over the
+    // target, so a concurrent reader (another process mid-sync) never sees a
+    // torn half-written memory. Same-directory rename is atomic on one fs.
+    const tmpPath = `${filePath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmpPath, serialize(fm, body), "utf8");
+    fs.renameSync(tmpPath, filePath);
     const st = fs.statSync(filePath);
     return { filePath, mtimeMs: st.mtimeMs };
 }

package/dist/tools/memory.js

@@ -1,5 +1,13 @@
-import { tool } from "@opencode-ai/plugin/tool";
 import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./ops.js";
+// Local stand-in for the SDK's tool() helper — same signature, and the SDK
+// function is a runtime identity (`return input`). Do NOT import it from
+// @opencode-ai/plugin at runtime: that package is a devDependency, and when
+// opencode loads this plugin by file:// URL from a global npm install
+// nothing resolves the module — the import fails and opencode silently
+// skips the whole plugin: no error, no tools (D58).
+function tool(input) {
+    return input;
+}
 export function makeTools(getScope, cfg) {
     const memory_add = tool({
         description: TOOL_DESCRIPTIONS.memory_add,

package/docs/V2-DESIGN.md

@@ -1152,6 +1152,51 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   of maximum doubt: memories live only on this machine, personal ones never
   leave it, nothing is uploaded.
 
+- **D57** — explainable search, a memory audit, and the concurrency posture
+  written down (0.6.1-alpha.2; addresses most of the retrieval-explainability
+  / memory-health open question and establishes the concurrent-sessions
+  behavior it asked for). (1) `open-memex search --explain` prints the
+  constructed FTS expression, per-hit bm25 score, and how many matches
+  lifecycle hid (superseded vs retracted/archived), so a miss is diagnosable
+  — bad query, stale memory, or chain-hidden — without reading the index.
+  (2) New `open-memex audit` (read-only; doctor checks the environment, this
+  checks the memories): near-duplicate active pairs (same ≥ 0.8 Jaccard as
+  write-time dedup), actives untouched for 90+ days, broken supersede chains,
+  personal files found inside the in-repo memory dir (iron-rule breach), and
+  index/file drift. Reports only; fixes stay with `supersede` / `forget` by
+  hand. (3) Concurrency, measured: every process opens its own connection to
+  one WAL index; memory files are per-memory ULIDs, so concurrent writes to
+  *different* memories never collide on disk. SQLite was the gap — no
+  `busy_timeout` was set, so better-sqlite3 silently tolerated 5s while
+  bun:sqlite (opencode plugin) timed out at 0 and failed instantly under any
+  overlapping write. Now unified at `PRAGMA busy_timeout = 5000` in `db()`.
+  Past the timeout the CLI prints one plain line ("store is busy … nothing
+  was lost") instead of a stack trace — and nothing *is* lost: the memory
+  file is written before the index update, so the next sync reconciles it
+  (verified end-to-end: a write blocked 8s still lands once the lock frees).
+  Memory file writes are tmp+rename, so a concurrent reader never sees a
+  torn file. Same-memory concurrent edits remain last-writer-wins (accepted:
+  different processes editing the same memory simultaneously is a human
+  conflict, not a storage one). `doctor` reports the live locking settings.
+
+- **D58** — the opencode plugin must never runtime-import the host SDK
+  (0.6.1-alpha.3). Field report: after a global `npm i -g open-memex`, the
+  plugin was configured in `~/.config/opencode/opencode.jsonc` but silently
+  inactive — no memory tools, no error, nothing in opencode's log. Bisected
+  with the real host (opencode 1.18.34) and a minimal plugin: a bare
+  `file://` entry loads fine; adding `import { tool } from
+  "@opencode-ai/plugin/tool"` makes opencode skip the plugin without a
+  trace. That import only ever resolved from a source checkout (where
+  `npm install` provides the devDependency); from a global install's
+  location nothing provides the module and the host does not resolve it
+  for file:// plugins. The helper is a runtime identity (`return input`),
+  so the fix is a local same-signature stand-in in `tools/memory.ts` —
+  types still come from the SDK (type-only imports erase at runtime), and
+  the plugin now depends only on real runtime dependencies. Verified in
+  the real host against a global-install-shaped tree: all five tools
+  register. Rule going forward: plugin code imports host SDK types only;
+  runtime imports must resolve from the package's own dependencies.
+
 ## Open Questions
 
 _All resolved — see D10 (rename), D11 (type/role split), D12 (explicit pull)._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.6.1-alpha.1",
+  "version": "0.6.1",
   "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/cli.ts

@@ -50,12 +50,14 @@ Examples:
 
   search: `Search memories by keyword (BM25 full-text), best matches first.
 
-Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N] [--explain]
 
 Flags:
-  --scope   project (default), personal, or both
-  --type    filter by memory type
-  --limit   max results
+  --scope    project (default), personal, or both
+  --type     filter by memory type
+  --limit    max results
+  --explain  show the FTS expression, per-hit score, and how many matches
+             lifecycle hid (superseded / retracted / archived)
 
 Example:
   open-memex search "deploy checklist" --scope both`,
@@ -337,6 +339,19 @@ Usage: open-memex doctor
 
 Example:
   open-memex doctor`,
+
+  audit: `Memory health audit (read-only, reports never mutates): near-duplicate
+pairs among active memories, stale actives untouched for 90+ days, broken
+supersede chains, personal files found inside the repo memory dir, and
+index/file drift.
+
+Usage: open-memex audit [--scope project|personal|both]
+
+Flags:
+  --scope   project (default), personal, or both
+
+Example:
+  open-memex audit --scope both`,
 };
 
 function usage(exitCode = 1): never {
@@ -345,7 +360,7 @@ function usage(exitCode = 1): never {
 Usage:
   open-memex where
   open-memex list [--scope project|personal] [--type T] [--limit N]
-  open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+  open-memex search "query" [--scope project|personal|both] [--type T] [--limit N] [--explain]
   open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
   open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
   open-memex status <id> active|deprecated|retracted|archived
@@ -362,6 +377,7 @@ Usage:
   open-memex submit <id...> [--branch <name>] [--base <branch>]
   open-memex pr-status [--apply]
   open-memex reindex
+  open-memex audit [--scope project|personal|both]
   open-memex scopes
   open-memex migrate [--from <key>] [--to <key>]
                                           [--dry-run] [--on-conflict newer|overwrite|skip]
@@ -698,6 +714,39 @@ async function main() {
     return;
   }
 
+  if (cmd === "audit") {
+    const flags = parseFlags(rest);
+    syncScope(project.key, "cli");
+    syncScope(PERSONAL_SCOPE.key, "cli");
+    const keys =
+      flags.scope === "personal"
+        ? [PERSONAL_SCOPE.key]
+        : flags.scope === "both"
+          ? [project.key, PERSONAL_SCOPE.key]
+          : [project.key];
+    const { runAudit, STALE_DAYS } = await import("./store/audit.ts");
+    const r = runAudit(keys);
+    console.log(`audit: ${r.totalMemories} memories (${keys.length === 2 ? "project+personal" : keys[0] === PERSONAL_SCOPE.key ? "personal" : "project"})`);
+    console.log(`  near-duplicate active pairs: ${r.duplicatePairs.length}`);
+    for (const p of r.duplicatePairs.slice(0, 10)) {
+      console.log(`    ${p.a} ~ ${p.b} (similarity ${p.score.toFixed(2)}) — consider supersede`);
+    }
+    console.log(`  stale actives (>= ${STALE_DAYS} days untouched): ${r.stale.length}`);
+    for (const s of r.stale.slice(0, 10)) {
+      console.log(`    ${s.id} — ${s.ageDays} days`);
+    }
+    console.log(`  broken supersede chains: ${r.brokenChains.length}`);
+    for (const b of r.brokenChains) {
+      console.log(`    ${b.id} -> missing ${b.missingTarget}`);
+    }
+    console.log(`  personal files inside repo memory dir: ${r.personalInRepo.length}`);
+    for (const f of r.personalInRepo) console.log(`    ${f}`);
+    console.log(
+      `  index drift: ${r.drift.filesNotIndexed} files not indexed, ${r.drift.rowsMissingFiles} rows missing files`,
+    );
+    return;
+  }
+
   // `config` prints the effective configuration (defaults + file). No DB needed.
   // `config set <key> <value>` persists a setting to the config file.
   if (cmd === "config") {
@@ -831,11 +880,22 @@ async function main() {
         : flags.scope === "project"
           ? [project.key]
           : [project.key, PERSONAL_SCOPE.key];
+    const explain = flags.explain === "true";
+    const stats = explain
+      ? { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0 }
+      : undefined;
     const hits = search(query, {
       scopeKeys: keys,
       limit: flags.limit ? Number(flags.limit) : undefined,
       type: flags.type,
+      stats,
     });
+    if (explain && stats) {
+      console.log(`fts: ${stats.ftsQuery || "(empty query)"}`);
+      console.log(
+        `candidates: ${stats.candidates}, hidden by lifecycle: ${stats.hiddenSuperseded} superseded, ${stats.hiddenExcluded} retracted/archived`,
+      );
+    }
     if (hits.length === 0) {
       console.log("(no matches)");
       return;
@@ -844,7 +904,8 @@ async function main() {
       const tag = h.scope_key === PERSONAL_SCOPE.key ? "personal" : "project";
       const dep = h.status === "deprecated" ? " [deprecated]" : "";
       const rev = hitStateLabel(h);
-      console.log(`[${tag}/${h.type}]${dep}${rev} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+      const sc = explain ? ` score=${h.score.toFixed(3)}` : "";
+      console.log(`[${tag}/${h.type}]${dep}${rev}${sc} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
     }
     return;
   }
@@ -1361,7 +1422,17 @@ function positionalArgs(argv: string[]): string[] {
 
 main()
   .catch((err) => {
-    console.error(err);
+    // D57: lock contention past the busy timeout should read as a transient
+    // condition, not a stack trace. The memory file is written before the
+    // index update, so a locked-out write still lands on the next sync.
+    const code = (err as { code?: string })?.code;
+    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED") {
+      console.error(
+        "open-memex: the memory store is busy (another open-memex process is writing). Wait a moment and retry — nothing was lost.",
+      );
+    } else {
+      console.error(err);
+    }
     process.exit(1);
   })
   .finally(() => {

package/src/doctor.ts

@@ -10,6 +10,7 @@ import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.ts";
 import { paths } from "./paths.ts";
 import { resolveCwdScope } from "./scope.ts";
+import { db, backendName } from "./store/db.ts";
 import { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.ts";
 
 interface Check {
@@ -71,6 +72,27 @@ function storageCheck(): Check {
   }
 }
 
+/**
+ * D57: several processes share one index (CLI, MCP per editor, opencode
+ * plugin). WAL + a 5s busy timeout is what keeps an overlapping write a
+ * brief wait instead of an instant failure — report the live settings.
+ */
+function lockingCheck(): Check {
+  try {
+    const d = db();
+    const jm = (d.prepare("PRAGMA journal_mode").get() as { journal_mode: string }).journal_mode;
+    const bt = (d.prepare("PRAGMA busy_timeout").get() as { timeout: number }).timeout;
+    const ok = jm === "wal" && bt >= 1000;
+    return {
+      name: "locking",
+      ok,
+      detail: `journal=${jm}, busy_timeout=${bt}ms (${backendName()})`,
+    };
+  } catch (err) {
+    return { name: "locking", ok: false, detail: String(err) };
+  }
+}
+
 /** Spawn the real MCP server, handshake, and verify the five tools list. */
 function mcpCheck(): Promise<Check> {
   const name = "mcp";
@@ -298,7 +320,7 @@ function vscodeMcpCheck(): Check {
 
 export async function runDoctor(): Promise<boolean> {
   console.log("open-memex doctor");
-  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), vscodeMcpCheck()];
+  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), lockingCheck(), vscodeMcpCheck()];
   checks.push(await mcpCheck());
   checks.push(legacyCheck());
   let allOk = true;

package/src/retrieve/search.ts

@@ -63,6 +63,14 @@ export function hitStateLabel(h: Pick<SearchHit, "scope_key" | "review_state">):
   return ` [${h.review_state || "draft"}]`;
 }
 
+/** Optional diagnostics out-param for `search --explain` (D57). */
+export interface SearchStats {
+  ftsQuery: string;
+  candidates: number;
+  hiddenSuperseded: number;
+  hiddenExcluded: number;
+}
+
 /**
  * Lifecycle-aware post-processing (§3.3):
  * - retracted / archived are excluded from retrieval (kept for audit);
@@ -71,7 +79,7 @@ export function hitStateLabel(h: Pick<SearchHit, "scope_key" | "review_state">):
  *   drafts/rejected rank after unreviewed content;
  * - deprecated stays visible as a warning but ranks after active.
  */
-function resolveVisible(rows: RawRow[], limit: number): SearchHit[] {
+function resolveVisible(rows: RawRow[], limit: number, stats?: SearchStats): SearchHit[] {
   const byId = new Map(rows.map((r) => [r.id, r]));
   const fullRow = (id: string): RawRow | undefined => {
     const cached = byId.get(id);
@@ -96,9 +104,13 @@ function resolveVisible(rows: RawRow[], limit: number): SearchHit[] {
   const deprecated: SearchHit[] = [];
 
   for (const r of rows) {
-    if (r.status === "retracted" || r.status === "archived") continue;
+    if (r.status === "retracted" || r.status === "archived") {
+      if (stats) stats.hiddenExcluded++;
+      continue;
+    }
     let target = r;
     if (r.status === "superseded") {
+      if (stats) stats.hiddenSuperseded++;
       let cur = r;
       const chain = new Set([r.id]);
       while (cur.status === "superseded" && cur.superseded_by) {
@@ -127,9 +139,15 @@ function resolveVisible(rows: RawRow[], limit: number): SearchHit[] {
  */
 export function search(
   query: string,
-  opts: { scopeKeys?: string[]; limit?: number; type?: string } = {},
+  opts: { scopeKeys?: string[]; limit?: number; type?: string; stats?: SearchStats } = {},
 ): SearchHit[] {
   const q = toFtsQuery(query);
+  if (opts.stats) {
+    opts.stats.ftsQuery = q;
+    opts.stats.candidates = 0;
+    opts.stats.hiddenSuperseded = 0;
+    opts.stats.hiddenExcluded = 0;
+  }
   if (!q) return [];
   const limit = Math.max(1, Math.min(opts.limit ?? 8, 50));
   // Over-fetch: lifecycle filtering (chain resolution, exclusions) happens
@@ -176,7 +194,8 @@ export function search(
 
   // FTS5 bm25: lower = better; invert for intuition.
   const raw: RawRow[] = rows.map((r) => ({ ...r, score: -r.score }));
-  return resolveVisible(raw, limit);
+  if (opts.stats) opts.stats.candidates = raw.length;
+  return resolveVisible(raw, limit, opts.stats);
 }
 
 export function list(

package/src/store/audit.ts

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import { db } from "./db.ts";
+import {
+  readMemoryFile,
+  iterInRepoMemoryFiles,
+  iterMemoryFiles,
+} from "./markdown.ts";
+import { similarity, NEAR_DUP_THRESHOLD } from "./lifecycle.ts";
+import { projectRoot } from "../paths.ts";
+import { loadConfig } from "../config.ts";
+
+// Memory health audit (D57). Read-only: reports, never mutates.
+// Checks, per open question "retrieval explainability & memory health":
+//   - near-duplicate pairs among active memories (same dedup yardstick
+//     as write-time: Jaccard >= 0.8) that were never superseded;
+//   - stale actives: untouched for STALE_DAYS, still in the retrieval /
+//     injection pool;
+//   - broken supersede chains: superseded_by pointing at a missing id;
+//   - personal files inside the in-repo memory dir (iron-rule breach:
+//     personal memory must never land in a shared repo);
+//   - index/file drift after sync (should be zero; reported if not).
+
+export const STALE_DAYS = 90;
+
+interface AuditRow {
+  id: string;
+  scope_key: string;
+  status: string;
+  updated_at: number;
+  superseded_by: string | null;
+  content: string;
+  file_path: string;
+}
+
+export interface DuplicatePair {
+  a: string;
+  b: string;
+  scopeKey: string;
+  score: number;
+}
+
+export interface AuditReport {
+  totalMemories: number;
+  duplicatePairs: DuplicatePair[];
+  stale: { id: string; scopeKey: string; ageDays: number }[];
+  brokenChains: { id: string; scopeKey: string; missingTarget: string }[];
+  personalInRepo: string[];
+  drift: { filesNotIndexed: number; rowsMissingFiles: number };
+}
+
+export function runAudit(scopeKeys: string[]): AuditReport {
+  const d = db();
+  const rows = d
+    .prepare(
+      `SELECT id, scope_key, status, updated_at, superseded_by, content, file_path
+       FROM memories`,
+    )
+    .all() as AuditRow[];
+  const inScope = rows.filter((r) => scopeKeys.includes(r.scope_key));
+  const ids = new Set(rows.map((r) => r.id));
+
+  // Near-duplicate pairs: active only, same scope. O(n^2) per scope with a
+  // length pre-filter; local stores are small enough for this to be fine.
+  const pairs: DuplicatePair[] = [];
+  const byScope = new Map<string, AuditRow[]>();
+  for (const r of inScope) {
+    if (r.status !== "active") continue;
+    const arr = byScope.get(r.scope_key) ?? [];
+    arr.push(r);
+    byScope.set(r.scope_key, arr);
+  }
+  for (const [scopeKey, arr] of byScope) {
+    for (let i = 0; i < arr.length; i++) {
+      for (let j = i + 1; j < arr.length; j++) {
+        const a = arr[i]!;
+        const b = arr[j]!;
+        const la = a.content.length;
+        const lb = b.content.length;
+        if (Math.min(la, lb) / Math.max(la, lb) < 0.5) continue;
+        const score = similarity(a.content, b.content);
+        if (score >= NEAR_DUP_THRESHOLD) {
+          pairs.push({ a: a.id, b: b.id, scopeKey, score });
+        }
+      }
+    }
+  }
+  pairs.sort((x, y) => y.score - x.score);
+
+  const now = Date.now();
+  const stale = inScope
+    .filter((r) => r.status === "active")
+    .map((r) => ({ id: r.id, scopeKey: r.scope_key, ageDays: Math.floor((now - r.updated_at) / 86_400_000) }))
+    .filter((s) => s.ageDays >= STALE_DAYS)
+    .sort((x, y) => y.ageDays - x.ageDays);
+
+  const brokenChains = inScope
+    .filter((r) => r.superseded_by && !ids.has(r.superseded_by))
+    .map((r) => ({ id: r.id, scopeKey: r.scope_key, missingTarget: r.superseded_by! }));
+
+  // Personal files must never sit in the in-repo dir. Read-only: this only
+  // parses frontmatter of files already in the repo tree.
+  const personalInRepo: string[] = [];
+  try {
+    const root = projectRoot();
+    const memoryDir = loadConfig().memoryDir;
+    for (const fp of iterInRepoMemoryFiles(root, memoryDir)) {
+      const mf = readMemoryFile(fp);
+      if (mf && mf.fm.scope === "personal") personalInRepo.push(fp);
+    }
+  } catch {
+    // No project root (e.g. personal-only usage): nothing to scan.
+  }
+
+  // Drift: index rows whose file vanished, and files on disk the index
+  // never picked up. syncScope normally heals both before audit runs.
+  const indexedPaths = new Set(rows.map((r) => r.file_path));
+  let rowsMissingFiles = 0;
+  for (const r of inScope) {
+    if (!r.file_path || !fs.existsSync(r.file_path)) rowsMissingFiles++;
+  }
+  let filesNotIndexed = 0;
+  for (const key of scopeKeys) {
+    for (const fp of iterMemoryFiles(key)) {
+      if (!indexedPaths.has(fp)) filesNotIndexed++;
+    }
+  }
+
+  return {
+    totalMemories: inScope.length,
+    duplicatePairs: pairs,
+    stale,
+    brokenChains,
+    personalInRepo,
+    drift: { filesNotIndexed, rowsMissingFiles },
+  };
+}

package/src/store/db.ts

@@ -124,6 +124,11 @@ export function db(): AnyDatabase {
   const Database = loadDatabase();
   const d = new Database(indexDb);
   d.exec("PRAGMA journal_mode = WAL;");
+  // Multiple processes share this index (CLI, one MCP server per editor,
+  // the opencode plugin). Without a busy timeout, bun:sqlite defaults to
+  // 0 — any overlapping write fails instantly. 5s matches the tolerance
+  // better-sqlite3 was already giving the CLI/MCP side (D57).
+  d.exec("PRAGMA busy_timeout = 5000;");
   d.exec("PRAGMA synchronous = NORMAL;");
   d.exec("PRAGMA foreign_keys = ON;");
   d.exec(TABLE_SCHEMA);

package/src/store/markdown.ts

@@ -294,7 +294,12 @@ export function writeMemoryFile(
   // Personal stays in appdata and never leaves the machine.
   const dir = memoriesDirFor(fm.scope_key);
   const filePath = path.join(dir, `${fm.id}.md`);
-  fs.writeFileSync(filePath, serialize(fm, body), "utf8");
+  // Atomic publish (D57): write a sibling tmp file and rename over the
+  // target, so a concurrent reader (another process mid-sync) never sees a
+  // torn half-written memory. Same-directory rename is atomic on one fs.
+  const tmpPath = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(tmpPath, serialize(fm, body), "utf8");
+  fs.renameSync(tmpPath, filePath);
   const st = fs.statSync(filePath);
   return { filePath, mtimeMs: st.mtimeMs };
 }

package/src/tools/memory.ts

@@ -1,4 +1,5 @@
-import { tool } from "@opencode-ai/plugin/tool";
+import type { z } from "zod";
+import type { ToolContext, ToolResult } from "@opencode-ai/plugin";
 import type { Scope } from "../scope.ts";
 import type { MyOMemoryConfig } from "../config.ts";
 import {
@@ -16,6 +17,20 @@ import {
   withOutboxNote,
 } from "./ops.ts";
 
+// Local stand-in for the SDK's tool() helper — same signature, and the SDK
+// function is a runtime identity (`return input`). Do NOT import it from
+// @opencode-ai/plugin at runtime: that package is a devDependency, and when
+// opencode loads this plugin by file:// URL from a global npm install
+// nothing resolves the module — the import fails and opencode silently
+// skips the whole plugin: no error, no tools (D58).
+function tool<Args extends z.ZodRawShape>(input: {
+  description: string;
+  args: Args;
+  execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<ToolResult>;
+}): { description: string; args: Args; execute: typeof input.execute } {
+  return input;
+}
+
 export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
   const memory_add = tool({
     description: TOOL_DESCRIPTIONS.memory_add,