open-memex 0.6.2 → 0.7.0-alpha.2

package/docs/V2-DESIGN.md

@@ -1210,6 +1210,100 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   `@opencode-ai/plugin`, the exact D58 death. It checks only what can be
   attributed; per-project and MCP wiring are out of scope.
 
+- **D60** — one plugin serves both opencode generations (0.7.0-alpha.1).
+  Opencode 2 changes the plugin contract end to end: config reads
+  `plugins` (directories or `{package}` objects) instead of v1's
+  `plugin` file entries, a v1-style file entry only earns a log warning
+  ("configured plugin path must be a directory") and is silently skipped
+  — the D58 death in a new shape; and the plugin value itself is a
+  structurally decoded `{ id, setup(ctx) }` rather than the v1 server
+  factory. A single `open-memex init --client opencode --global` now
+  writes both keys (`plugin` file URL and `plugins` directory): each
+  host loads from its own key — verified: opencode 1.18.34 ignores the
+  `plugins` array with a config-normalization warning, and opencode 2
+  warns per `plugin` file entry but loads the directory entry — so users on either generation get a
+  working plugin from the same install. `src/index.ts` default-exports
+  `{ id, setup, server }`: v2 calls `setup`, v1 calls `server`, the
+  shared logic (bootstrap, keyword capture, one-time injection) lives in
+  `src/plugin-core.ts`. Cost of the bridge on the v1 side: v1 hosts
+  older than 1.18.29 only invoke function default exports and would
+  skip this object; 1.18.29+ accepts it — the README states the new
+  minimum. The v2 adapter (src/opencode-v2.ts) obeys D58's rule — no
+  runtime `@opencode/plugin` import (a devDependency again); the
+  context is duck-typed from the 2.0 surface, tool arg shapes compile
+  from the same zod shapes via `z.toJSONSchema`, and hooks map
+  one-to-one (session `prompt` → keyword capture, session `context` →
+  first-turn injection). One registration subtlety cost real debugging
+  time and is worth recording: on 2.0.1 a plugin tool added without
+  options is exposed to the model only in code mode — callable through
+  an `execute` meta-tool that runs model-written JS
+  (`tools.memory_search(...)`) — and a model that instead calls the
+  tool by name gets a host-side "Unknown tool" error, so whether the
+  memory tools work at all depends on the model's calling style. Each
+  tool therefore registers with `options: { codemode: false }`, which
+  restores plain function calling (verified: direct calls execute
+  first try). The D59 doctor check extends to both keys:
+  v2 entries are checked for an existing, resolvable entry file and the
+  closure scan now covers `@opencode/plugin` too, plus a generation
+  advisory — when the installed host and the config point at different
+  generations, doctor fails and names the fix (`init --force`; package-
+  name entries installed via `opencode plugin add` are recorded but not
+  path-checked). Field-verified on real hosts 1.18.34 and 2.0.1.
+
+- **D61 — proactive capture cluster: propose posture, a shared
+  memorability rubric, and capture-time aliasing (retrieval layer 3).**
+  Builds on the "proactive capture" open question below and the
+  CHECKPOINT_PROACTIVITY / MEMORY_VISIBILITY notes. Three pieces,
+  shipped together because they are one user-visible behavior — the
+  agent capturing well without being asked each time:
+  (1) **Posture: propose, not auto-draft.** When the agent finishes a
+  task the user would describe in one sentence, it proposes 1–3 short
+  candidate memories in the conversation and saves only what the user
+  approves (approved inferences are saved with `source: "inference"`,
+  the §3.5 convention). The guidance is text, not mechanism — the same
+  rubric written into the bundled skill, the AGENTS.md memory-hygiene
+  footer, the MCP handshake instructions, the `memory_add` tool
+  description, and a one-line summary in the injected context block —
+  with throttling rules (task end / decision / gotcha moments only, no
+  mid-task interruptions, never re-propose a declined candidate). The
+  auto-draft posture (write first, surface later in bulk) is deferred
+  until memory visibility ships: without an inventory the user can
+  read, silent drafting reads as surveillance, so D61 deliberately
+  does not build it.
+  (2) **Rubric.** One memorability standard, shared by this live
+  capture path and the future retrospective-distillation group:
+  worth saving — decisions and their reasons, preferences,
+  conventions, gotchas, approaches tried and abandoned, and
+  `reference` memories pointing at authoritative docs; not worth
+  saving — one-off task details and anything re-derivable from the
+  code. Retrieval robustness layer 2 (agent-side query expansion:
+  decompose into concepts, 2–3 phrasings each, cross-language, check
+  the other scope) ships as guidance in the same texts, on top of the
+  D56 server-side layer 1.
+  (3) **Capture-time aliases (layer 3).** When a memory is saved, the
+  agent attaches up to 4 aliases — alternate phrasings, synonyms,
+  equivalents in the user's other language — stored in a new optional
+  frontmatter field `aliases` (additive; files without it parse
+  unchanged, `schema_version` stays 2) and indexed in their own FTS
+  column (index schema 6→7, rebuilt from markdown automatically).
+  Gated by a new `captureAliases` config flag (init asks once, default
+  on, `config set captureAliases off` opts out): when off, aliases
+  passed by agents are dropped and the alias guidance disappears from
+  the MCP handshake. Turning it off never rewrites existing memory
+  files — aliases already stored stay stored and searchable, and
+  supersede keeps carrying them forward; the flag gates new captures
+  only (no silent data destruction). Aliases pass through the same
+  secret redaction as memory content before they are stored, and a
+  malformed alias list (blanks, more than 4) is normalized silently —
+  never a tool-call error.
+  Keyword capture (no agent in the loop) leaves
+  aliases empty rather than inventing them; `supersede` carries
+  aliases forward unless the caller replaces them. Aliases are
+  normalized (trim, case-insensitive dedupe, cap 4) and bad ones cost
+  nothing — they rank as bm25 noise, never an error. Retrospective
+  distillation over host transcripts stays its own group; it will
+  reuse this rubric.
+
 ## 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.2",
+  "version": "0.7.0-alpha.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/scripts/smoke-pure.ts

@@ -1,6 +1,6 @@
 // Quick smoke test — runs the pure-logic modules (no bun:sqlite dependency).
 // Usage:  node --experimental-strip-types scripts\smoke-pure.ts
-import { parse, serialize, ulid, normalizeFrontmatter, msToRfc3339, timeToMs, parseRawFrontmatter, type Frontmatter } from "../src/store/markdown.ts";
+import { parse, serialize, ulid, normalizeFrontmatter, msToRfc3339, timeToMs, parseRawFrontmatter, normalizeAliases, type Frontmatter } from "../src/store/markdown.ts";
 import { planConversion, isV2File, migrateV2 } from "../src/store/v2migrate.ts";
 import { redact, findSecret } from "../src/redact.ts";
 import { detectKeywords } from "../src/capture/keywords.ts";
@@ -9,7 +9,9 @@ import { resolveProjectScope, resolveCwdScope, PERSONAL_SCOPE } from "../src/sco
 import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
 import { toFtsQuery } from "../src/retrieve/query.ts";
 import { contentHash, similarity, NEAR_DUP_THRESHOLD } from "../src/store/lifecycle.ts";
-import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, opencodeGlobalConfigPath, printManualEntryHint, parseJsonConfig, removeServerEntry, removePluginEntry, removeInstructionsSection, LEGACY_PACKAGE_NAME, shouldInstallSkill } from "../src/init.ts";
+import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, mergeV2PluginEntry, removeV2PluginEntry, opencodeGlobalConfigPath, printManualEntryHint, parseJsonConfig, removeServerEntry, removePluginEntry, removeInstructionsSection, LEGACY_PACKAGE_NAME, shouldInstallSkill } from "../src/init.ts";
+import { z } from "zod";
+import { memoryAddArgs } from "../src/tools/ops.ts";
 
 let fails = 0;
 function ok(name: string, cond: boolean, info?: unknown) {
@@ -57,6 +59,28 @@ ok("id survives", parsed?.fm.id === a);
 ok("tags survive", JSON.stringify(parsed?.fm.tags) === '["hello","world"]');
 ok("body survives", parsed?.body.trim() === body);
 
+console.log("== capture aliases (D61) ==");
+ok("normalize trims/dedupes/caps at 4",
+  JSON.stringify(normalizeAliases(["  Time Off ", "time off", "", "节假日", "vacation", "PTO", "leave"])) === '["Time Off","节假日","vacation","PTO"]');
+ok("normalize of undefined is empty", JSON.stringify(normalizeAliases(undefined)) === "[]");
+const fmA: Frontmatter = { ...fm, id: ulid(), aliases: ["time off", "节假日", "vacation days"] };
+const parsedA = parse(serialize(fmA, "body text"));
+ok("aliases survive round-trip",
+  JSON.stringify(parsedA?.fm.aliases) === '["time off","节假日","vacation days"]');
+ok("no aliases -> field omitted from file",
+  !/^aliases:/m.test(serialize(fm, "x")));
+ok("empty aliases array -> field omitted",
+  !/^aliases:/m.test(serialize({ ...fm, aliases: [] }, "x")));
+ok("parse caps hand-edited aliases at 4",
+  (normalizeFrontmatter({ id: "x", aliases: ["1", "2", "3", "4", "5"] } as never).aliases ?? []).length === 4);
+{
+  // D61 review: the tool schema must never reject a sloppy alias list —
+  // normalization decides, not validation (bad aliases are noise).
+  const shape = z.object(memoryAddArgs);
+  const sloppy = shape.safeParse({ content: "x", aliases: ["a", "", "b", "c", "d", "e"] });
+  ok("tool schema accepts >4 / blank aliases (normalize drops them)", sloppy.success);
+}
+
 console.log("== redact ==");
 const r1 = redact("api key is <private>sk-supersecretkey</private> ok", DEFAULT_CONFIG.redactPatterns);
 ok("private stripped", !r1.content.includes("sk-supersecretkey"));
@@ -504,6 +528,27 @@ ok("plugin remove absent", removePluginEntry({ plugin: ["other"] }, "open-memex"
 const lpdoc: Record<string, unknown> = { plugin: ["file:///g/my-o-memory/src/index.ts", "file:///g/open-memex/src/index.ts"] };
 ok("plugin remove drops legacy my-o-memory entry", removePluginEntry(lpdoc, LEGACY_PACKAGE_NAME) === "removed"
   && JSON.stringify(lpdoc["plugin"]) === JSON.stringify(["file:///g/open-memex/src/index.ts"]));
+// D60: the OpenCode 2 `plugins` array (directory strings and {package} objects).
+const vdoc: Record<string, unknown> = {};
+ok("v2 merge creates array", mergeV2PluginEntry(vdoc, "/x/open-memex/src", false) === "added"
+  && JSON.stringify(vdoc["plugins"]) === JSON.stringify(["/x/open-memex/src"]));
+ok("v2 merge dup kept", mergeV2PluginEntry(vdoc, "/x/open-memex/src", false) === "kept");
+const vdoc2: Record<string, unknown> = { plugins: [{ package: "other-plugin", options: {} }, "/old/open-memex/src"] };
+ok("v2 merge kept with existing open-memex entry (no force)", mergeV2PluginEntry(vdoc2, "/new/open-memex/src", false) === "kept"
+  && (vdoc2["plugins"] as unknown[]).length === 2);
+ok("v2 merge force replaces stale open-memex dir, keeps others", mergeV2PluginEntry(vdoc2, "/new/open-memex/src", true) === "added"
+  && (vdoc2["plugins"] as unknown[]).length === 2
+  && JSON.stringify(vdoc2["plugins"]) === JSON.stringify([{ package: "other-plugin", options: {} }, "/new/open-memex/src"]));
+ok("v2 remove drops string + object entries", removeV2PluginEntry(vdoc2, "open-memex") === "removed"
+  && JSON.stringify(vdoc2["plugins"]) === JSON.stringify([{ package: "other-plugin", options: {} }]));
+ok("v2 remove absent", removeV2PluginEntry(vdoc2, "open-memex") === "absent");
+const vdoc3: Record<string, unknown> = { plugins: ["/x/open-memex/src"] };
+ok("v2 remove prunes empty array", removeV2PluginEntry(vdoc3, "open-memex") === "removed" && !("plugins" in vdoc3));
+// D60: the plugin entrypoint default-exports both host generations.
+const entryModule = (await import("../src/index.ts")) as { default: { id?: unknown; setup?: unknown; server?: unknown } };
+ok("entry default export has id/setup/server", entryModule.default.id === "open-memex"
+  && typeof entryModule.default.setup === "function"
+  && typeof entryModule.default.server === "function");
 // removeInstructionsSection: cuts MARKER..end, "" when nothing remains.
 ok("instructions remove keeps prior content",
   removeInstructionsSection("# mine\n\n<!-- open-memex -->\n# OpenMemex memory\n") === "# mine\n");

package/scripts/test-full.ts

@@ -133,6 +133,34 @@ ok("list --type filter", r.out.includes(idDecision) && !r.out.includes(idFact));
 r = cli(["search", "ff merges"], PROJ);
 ok("search finds decision", r.out.includes(idDecision), r.out.slice(0, 150));
 
+// D61: capture-time aliases — a differently-worded query still hits.
+const idAlias = addMem(["fulltest holiday policy lives in the handbook", "--aliases", "time off;vacation days"], PROJ);
+r = cli(["search", "vacation"], PROJ);
+ok("search hits via alias-only term", r.out.includes(idAlias), r.out.slice(0, 150));
+ok("alias-only hit explains itself (aka)", /aka:/i.test(r.out), r.out.slice(0, 150));
+
+// D61 review: aliases go through the same redaction as content. (The
+// secret is assembled at runtime so no credential-shaped literal sits
+// in this file.)
+const fakePat = "ghp_" + "Ab3".repeat(12);
+const idSecretAlias = addMem(["fulltest alias redaction target", "--aliases", `${fakePat}; benign alias`], PROJ);
+r = cli(["search", "benign"], PROJ);
+ok("benign alias still searchable", r.out.includes(idSecretAlias), r.out.slice(0, 150));
+{
+  const dir = path.join(TESTENV.MY_O_MEMORY_HOME, "memories");
+  const stack = [dir];
+  let hit = "";
+  while (stack.length && !hit) {
+    const d = stack.pop()!;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) stack.push(p);
+      else if (p.endsWith(`${idSecretAlias}.md`)) hit = fs.readFileSync(p, "utf8");
+    }
+  }
+  ok("secret-looking alias is masked in the stored file", !!hit && !hit.includes(fakePat), hit.slice(0, 200));
+}
+
 // ---------- 3. supersede / status / forget ----------
 console.log("== supersede / status / forget ==");
 r = cli(["supersede", idFact, "fulltest fact about deploys v2"], PROJ);

package/skills/open-memex/SKILL.md

@@ -25,6 +25,32 @@ open-memex add "I prefer concise diffs" --scope personal   # applies everywhere
 Keep each memory one self-contained statement. Scope routing: facts about the
 user ("I"/"me") → `personal`; everything else → the current project.
 
+Worth saving: decisions and their reasons, preferences, conventions, gotchas,
+approaches tried and abandoned. Not worth saving: one-off task details or
+anything re-derivable from the code.
+
+Attach alternate phrasings when saving — synonyms, another way the question
+might be worded, equivalents in the user's other language — so reworded
+questions still find the memory:
+
+```sh
+open-memex add "Public holidays are listed in the HR portal" --aliases "holidays;time off;节假日"
+```
+
+(Aliases are stored only when the install has capture aliases enabled — the
+init default.)
+
+## At task checkpoints — propose, don't just save
+
+For conclusions you infer yourself (the user never stated them): when you
+finish a task the user would describe in one sentence, propose 1–3 short
+memories capturing the useful conclusion (what was learned or decided, how an
+issue was resolved, what to avoid, where the authoritative doc lives — not the
+raw transcript). Save nothing the user did not approve; on approval, save it —
+with the `memory_add` tool pass `source: "inference"` so the capture is marked
+as agent-proposed. Don't interrupt mid-task, and don't re-propose something
+the user already declined.
+
 ## Recall
 
 ```sh
@@ -33,7 +59,10 @@ open-memex list                       # recent memories in the current project
 ```
 
 Search before asking the user about past decisions or preferences they may
-have told you before.
+have told you before. Search well: break the question into its concepts and
+try 2–3 phrasings per concept — synonyms, the user's other language, shorter
+keyword forms — and check the other scope too, before concluding nothing is
+stored.
 
 ## Project outbox → repo (the sync flow)
 

package/src/cli.ts

@@ -15,6 +15,7 @@ import {
   readMemoryFile,
   ulid,
   msToRfc3339,
+  normalizeAliases,
   type Frontmatter,
 } from "./store/markdown.ts";
 import { loadConfig } from "./config.ts";
@@ -64,19 +65,26 @@ Example:
 
   add: `Save a fact, preference, decision, or note to local memory.
 
-Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2] [--aliases "a;b"]
 
 Flags:
-  --scope   project (default) or personal (personal never leaves this machine)
-  --type    memory type (default: fact)
-  --tag     comma-separated tags
+  --scope    project (default) or personal (personal never leaves this machine)
+  --type     memory type (default: fact)
+  --tag      comma-separated tags
+  --aliases  alternate phrasings of this fact (up to 4), indexed with the
+             memory so differently-worded searches still match; separate
+             with ; (commas also accepted — use ; when an alias itself
+             contains one). Stored only when capture aliases are enabled
+             (init default)
 
 Example:
   open-memex add "We deploy on Fridays" --scope project --tag process`,
 
   supersede: `Replace a memory with a newer version. The old one is kept as history.
 
-Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
+Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2] [--aliases "a;b"]
+
+Without --aliases, the old memory's aliases carry over.
 
 Example:
   open-memex supersede 01ABC "We deploy on Thursdays now"`,
@@ -943,6 +951,20 @@ async function main() {
             .map((t) => t.trim())
             .filter(Boolean)
         : [],
+      // D61: --aliases "phrase one; phrase two" (comma also accepted; use
+      // ; when an alias itself contains a comma). A bare --aliases with no
+      // value makes parseFlags yield "true" — treat that as absent. Stored
+      // only when the install enables capture aliases, redacted like content.
+      ...(typeof flags.aliases === "string" && flags.aliases !== "true" && cfg.captureAliases
+        ? {
+            aliases: normalizeAliases(
+              flags.aliases
+                .split(/[;,]/)
+                .map((a) => redact(a.trim(), cfg.redactPatterns).content)
+                .filter(Boolean),
+            ),
+          }
+        : {}),
       source: "cli",
       created_at: rfc,
       updated_at: rfc,
@@ -985,6 +1007,15 @@ async function main() {
         tags: flags.tag
           ? flags.tag.split(",").map((t) => t.trim()).filter(Boolean)
           : undefined,
+        aliases:
+          typeof flags.aliases === "string" && flags.aliases !== "true" && cfg.captureAliases
+            ? normalizeAliases(
+                flags.aliases
+                  .split(/[;,]/)
+                  .map((a) => redact(a.trim(), cfg.redactPatterns).content)
+                  .filter(Boolean),
+              )
+            : undefined,
         source: "cli",
       });
       upsertFromFile(oldMf);

package/src/config.ts

@@ -7,6 +7,14 @@ export interface MyOMemoryConfig {
   maxProfileItems: number;
   injectOnFirstTurn: boolean;
   keywordCaptureEnabled: boolean;
+  /**
+   * D61: capture-time aliasing (retrieval layer 3). When on, agents are
+   * asked to attach 2–4 aliases (alternate phrasings, other-language
+   * equivalents) to each memory they save; ops stores them and the index
+   * searches them, so differently-worded questions still hit. Asked once
+   * at init, default on; off = aliases passed by agents are dropped.
+   */
+  captureAliases: boolean;
   /** Patterns whose capture group 1 becomes the memory body; saved to the current scope. */
   keywordPatterns: string[];
   /** Same shape, but hits are forced into the personal scope (e.g. "remember for me"). */
@@ -34,6 +42,7 @@ export const DEFAULT_CONFIG: MyOMemoryConfig = {
   maxProfileItems: 5,
   injectOnFirstTurn: true,
   keywordCaptureEnabled: true,
+  captureAliases: true,
   keywordPatterns: [
     "^\\s*remember(?!\\s+for\\s+me)(?:\\s+that)?[:,]?\\s+(.+)$",
     "^\\s*(?:please\\s+)?(?:note|don'?t\\s+forget)(?:\\s+that)?[:,]?\\s+(.+)$",
@@ -110,6 +119,7 @@ export const SETTABLE_KEYS: Record<string, (v: unknown) => unknown> = {
   maxProfileItems: toNonNegInt,
   injectOnFirstTurn: toBool,
   keywordCaptureEnabled: toBool,
+  captureAliases: toBool,
   memoryDir: toRelativeDir,
   "sync.autoPull": toBool,
   logLevel: (v) => {

package/src/distill-agents.ts

@@ -78,8 +78,14 @@ export function distillAgentsMarkdown(opts: DistillAgentsOptions): string {
     `  conclusion — what was learned or decided, how an issue was resolved, what`,
     `  to avoid, where the authoritative doc lives — not the raw transcript.`,
     `  Save nothing without user approval.`,
+    `  Worth keeping: decisions and their reasons, preferences, conventions,`,
+    `  gotchas, approaches tried and abandoned. Not worth keeping: one-off task`,
+    `  details or anything re-derivable from the code.`,
     `- If the knowledge already lives in project docs, save a \`reference\` memory`,
     `  pointing at the doc instead of copying it.`,
+    `- When saving via \`memory_add\`, attach 2–4 aliases (alternate phrasings,`,
+    `  synonyms, equivalents in the user's other language) when the install has`,
+    `  capture aliases enabled — they make reworded questions find the memory.`,
   );
   lines.push(``);
   return lines.join("\n");

package/src/doctor.ts

@@ -94,14 +94,17 @@ 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).
+ * D59/D60: patrol the opencode native-plugin entries. The D58 field failure
+ * was silent — the entry was configured, the host never loaded it, and
+ * nothing anywhere said why. Death modes to catch:
+ *   1. the entry's target does not exist (package moved, nvm rolled to a
+ *      new version dir, checkout deleted);
+ *   2. the plugin's import closure runtime-imports a host SDK package
+ *      (@opencode-ai/plugin on v1, @opencode/plugin on v2) — unresolvable
+ *      from a global install, the host silently skips the plugin (D58);
+ *   3. (D60) the config wires only the other host generation: an
+ *      opencode 2 host never reads the v1 `plugin` file entry (it demands
+ *      a directory under `plugins`), and opencode 1 cannot read `plugins`.
  * Read-only; only inspects the user-level opencode configs.
  */
 function opencodePluginCheck(): Check {
@@ -109,23 +112,37 @@ function opencodePluginCheck(): Check {
   try {
     const jsonPath = opencodeGlobalConfigPath();
     const candidates = [jsonPath, jsonPath.replace(/\.json$/, ".jsonc")];
-    const entries: string[] = [];
+    const v1Entries: string[] = [];
+    const v2Entries: string[] = [];
     let sawConfig = false;
+    const v2EntryPackage = (entry: unknown): string | null => {
+      if (typeof entry === "string") return entry;
+      if (entry !== null && typeof entry === "object" && "package" in entry) {
+        const p = (entry as { package?: unknown }).package;
+        return typeof p === "string" ? p : null;
+      }
+      return null;
+    };
     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);
+        const doc = JSON.parse(text) as { plugin?: unknown; plugins?: unknown };
+        if (Array.isArray(doc.plugin)) {
+          for (const e of doc.plugin) if (typeof e === "string") v1Entries.push(e);
+        }
+        if (Array.isArray(doc.plugins)) {
+          for (const e of doc.plugins) {
+            const p = v2EntryPackage(e);
+            if (p !== null) v2Entries.push(p);
+          }
         }
       } 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]!);
+          v1Entries.push(m[1]!);
         }
       }
     }
@@ -134,23 +151,63 @@ function opencodePluginCheck(): Check {
     }
 
     const problems: string[] = [];
+    // Host SDK packages per generation; a runtime import of either from a
+    // globally installed plugin cannot resolve (D58).
     const RUNTIME_SDK_IMPORT =
-      /^\s*import\s+(?!type\b)[^;]*?["']@opencode-ai\/plugin(?:\/[^"']*)?["']/m;
-    const RUNTIME_SDK_REQUIRE = /require\(\s*["']@opencode-ai\/plugin(?:\/[^"']*)?["']\s*\)/;
+      /^\s*import\s+(?!type\b)[^;]*?["']@opencode(?:-ai)?\/plugin(?:\/[^"']*)?["']/m;
+    const RUNTIME_SDK_REQUIRE = /require\(\s*["']@opencode(?:-ai)?\/plugin(?:\/[^"']*)?["']\s*\)/;
 
+    const toPath = (entry: string): string | null => {
+      try {
+        return entry.startsWith("file:") ? fileURLToPath(entry) : entry;
+      } catch {
+        return null;
+      }
+    };
     // 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;
+    const fileHasMarker = (target: string): boolean => {
       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;
       }
     };
+    /** Resolve an OpenCode 2 directory entry to its entry file, if any. */
+    const resolveV2EntryFile = (target: string): string | null => {
+      try {
+        if (!fs.existsSync(target)) return null;
+        if (fs.statSync(target).isFile()) return target;
+        for (const idx of ["index.ts", "index.js", "index.mts", "index.mjs"]) {
+          const p = path.join(target, idx);
+          if (fs.existsSync(p)) return p;
+        }
+        const pkgJson = path.join(target, "package.json");
+        if (fs.existsSync(pkgJson)) {
+          const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf8")) as { main?: unknown };
+          if (typeof pkg.main === "string") {
+            const main = path.join(target, pkg.main);
+            if (fs.existsSync(main)) return main;
+          }
+        }
+      } catch {
+        return null;
+      }
+      return null;
+    };
+    const isOursV1 = (entry: string): boolean => {
+      if (entry.includes("open-memex")) return true;
+      const target = toPath(entry);
+      return target !== null && fs.existsSync(target) && fileHasMarker(target);
+    };
+    const isOursV2 = (entry: string): boolean => {
+      if (entry.includes("open-memex")) return true;
+      const target = toPath(entry);
+      if (target === null) return false;
+      const file = resolveV2EntryFile(target);
+      return file !== null && fileHasMarker(file);
+    };
     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).
@@ -184,15 +241,14 @@ function opencodePluginCheck(): Check {
       return offenders;
     };
 
-    const ours = entries.filter(isOurEntry);
-    if (ours.length === 0) {
+    const oursV1 = v1Entries.filter(isOursV1);
+    const oursV2 = v2Entries.filter(isOursV2);
+    if (oursV1.length === 0 && oursV2.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 {
+    for (const entry of oursV1) {
+      const target = toPath(entry);
+      if (target === null) {
         problems.push(`entry "${entry}" is not a parseable file URL`);
         continue;
       }
@@ -204,17 +260,72 @@ function opencodePluginCheck(): Check {
       }
       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)`,
+          `${f} runtime-imports a host SDK package — opencode silently skips plugins whose imports it cannot resolve from a global install (D58)`,
+        );
+      }
+    }
+    for (const entry of oursV2) {
+      // A bare package name ("open-memex" via `opencode plugin add`) is
+      // resolved by the host's plugin manager; there is no local path to
+      // verify.
+      const isPackageName =
+        !entry.startsWith("file:") &&
+        !entry.startsWith(".") &&
+        !path.isAbsolute(entry) &&
+        !/^[a-zA-Z]:[\\/]/.test(entry);
+      if (isPackageName) continue;
+      const target = toPath(entry);
+      if (target === null || !fs.existsSync(target)) {
+        problems.push(
+          `opencode 2 entry "${entry}" does not resolve to an existing path — run \`open-memex init --client opencode --global --force\` to re-point it`,
+        );
+        continue;
+      }
+      const entryFile = resolveV2EntryFile(target);
+      if (entryFile === null) {
+        problems.push(
+          `opencode 2 entry "${entry}" has no loadable plugin file (looked for index.ts/index.js and package.json main)`,
         );
+        continue;
       }
+      for (const f of scanSdkImports(entryFile)) {
+        problems.push(
+          `${f} runtime-imports a host SDK package — opencode silently skips plugins whose imports it cannot resolve from a global install (D58)`,
+        );
+      }
+    }
+
+    // D60: generation mismatch — the config wires only the generation the
+    // installed host cannot read. Best-effort: no binary, no opinion.
+    let hostMajor: number | null = null;
+    try {
+      const out = execFileSync("opencode", ["--version"], {
+        timeout: 3000,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      const m = out.match(/(\d+)\.(\d+)\.(\d+)/);
+      if (m) hostMajor = Number(m[1]);
+    } catch {
+      hostMajor = null;
     }
+    if (hostMajor !== null && hostMajor >= 2 && oursV1.length > 0 && oursV2.length === 0) {
+      problems.push(
+        `the installed opencode is v${hostMajor} but the config only has the opencode 1 "plugin" entry — v2 loads directories from "plugins" and will silently skip this plugin; run \`open-memex init --client opencode --global --force\` to add the v2 entry`,
+      );
+    } else if (hostMajor === 1 && oursV2.length > 0 && oursV1.length === 0) {
+      problems.push(
+        `the installed opencode is v1 but the config only has the opencode 2 "plugins" entry — v1 reads the "plugin" key and will not load this plugin; run \`open-memex init --client opencode --global --force\` to add the v1 entry`,
+      );
+    }
+
     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`,
+      detail: `${oursV1.length + oursV2.length} plugin ${oursV1.length + oursV2.length === 1 ? "entry" : "entries"}: target exists, no host-SDK runtime imports`,
     };
   } catch (err) {
     return { name, ok: false, detail: String(err) };