open-memex 0.6.0-alpha.5 → 0.6.0

package/AGENTS.md

@@ -75,13 +75,23 @@ TTY (usage as before when non-interactive); init/uninstall maintain a
 `.init.json` first-run marker at the data root so the offer is asked once (D50);
 init ends with a one-line next-step hint (`open-memex add` + ask the agent to
 recall it) so a first-time user sees what "it works" looks like (D51).
+init also installs the bundled `open-memex` Agent Skill (skills/open-memex/SKILL.md,
+teaches skill-aware agents the CLI: save/search/scope rules/outbox flow) into each
+wired editor's user-level skills dir — ~/.copilot/skills/ (VS Code),
+~/.cursor/skills/ (Cursor), ~/.config/opencode/skills/ (opencode, per-project MCP
+mode only — with the native plugin the skill is skipped and any previously installed
+one is removed, D55); Visual Studio
+has no skills concept and is skipped. Copy, not symlink (Windows needs no
+Developer Mode); existing skill kept unless --force (D54).
 `open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]`
 reverses init — removes the MCP server entry / opencode plugin line / Copilot
-instructions section; memory data never touched (D48); no --client → auto-detect
+instructions section / Agent Skill directory; memory data never touched (D48); no --client → auto-detect
 with an interactive confirm, explicit --client never prompts; `--yes` only skips
 that confirm; `--global` limits cleanup to user-level. Empty/whitespace-only
 config files parse as `{}` and are safely populated (D49); non-JSON (JSONC)
-files are left untouched with a printed manual snippet (D47).
+files are left untouched with a printed manual snippet (D47). init/uninstall also sweep
+pre-rename `my-o-memory` plugin entries and MCP server keys wherever they touch a
+config, and `open-memex doctor` reports any remaining pre-rename leftovers (F30).
 The published `open-memex` bin points at `dist/cli.js` (compiled at publish time).
 From a source checkout, `npm run cli` / `npm run mcp` still run `src/` directly
 with type-stripping — no build step needed for development.

package/README.md

@@ -113,6 +113,12 @@ This installs the `0.5.1` stable release.
 npm install -g open-memex@alpha
 ```
 
+```sh
+open-memex init
+```
+
+The install isn't complete until you run `open-memex init` — it wires up your editors (VS Code, Cursor, opencode, and Visual Studio for solution projects).
+
 See what's published:
 
 ```sh
@@ -180,7 +186,10 @@ npx -y open-memex init --yes
 With no `--client`, `init` **detects your installed editors and wires them all**
 — user-level where the editor supports it (VS Code / Cursor MCP config, opencode
 native plugin), so one init covers every project. Visual Studio joins in when the
-project has a solution file. Prefer to pick a single editor? Pass `--client`:
+project has a solution file. It also installs an **Agent Skill** (`open-memex`)
+into each editor's skills folder (not opencode when the native plugin is wired —
+the plugin already provides memory tools), so skill-aware agents can use your memory via
+the CLI with no MCP configuration. Prefer to pick a single editor? Pass `--client`:
 
 > **Two different "globals" — don't mix them up.**
 > - `npm install -g open-memex` installs the *package* globally: it puts the

package/README.zh-CN.md

@@ -108,6 +108,12 @@ npm install -g open-memex
 npm install -g open-memex@alpha
 ```
 
+```sh
+open-memex init
+```
+
+不跑 `open-memex init` 把编辑器接上，安装就不算完成（支持 VS Code、Cursor、opencode，有 .sln 的项目还支持 Visual Studio）。
+
 查看已发布版本：
 
 ```sh
@@ -173,6 +179,9 @@ npx -y open-memex init --yes
 不带 `--client` 时，`init` 会**自动检测本机装了哪些编辑器，一次全接上**——
 支持用户级的编辑器走用户级（VS Code / Cursor 的 MCP 配置、opencode 原生插件），
 一次 init，所有项目通用；项目里有 solution 文件时 Visual Studio 也会一起配。
+同时会给每个编辑器装一个 **Agent Skill**（`open-memex`，opencode 用原生插件时除外——
+插件已经提供了记忆工具），懂 skill 的 agent
+不用配 MCP 也能通过 CLI 用你的记忆。
 想只配某一个编辑器？加 `--client`：
 
 > **两个"全局"不是一回事，别搞混。**

package/dist/cli.js

@@ -516,30 +516,31 @@ async function main() {
             usage(0);
         return;
     }
-    if (cmd === "--help" || cmd === "-h" || cmd === "help")
-        usage(0);
-    if (cmd === "--version" || cmd === "-v") {
-        // package.json sits two levels above this file in both layouts
-        // (src/cli.ts and dist/cli.js).
-        const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-        const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
-        console.log(`open-memex ${pkg.version}`);
-        return;
-    }
     // F28: npm runs lifecycle scripts in the background and swallows their
     // stdout (unless --foreground-scripts), so the D50 postinstall pointer
     // never reaches the user. Every CLI entry point therefore carries a
     // one-line nudge on stderr until init has run or been declined — stderr
     // keeps the MCP stdio protocol (stdout) intact, and the .init.json marker
     // makes it once-ever. `init`/`uninstall` are excluded (already there /
-    // nothing to wire).
+    // nothing to wire). Placed before the --help/--version early returns:
+    // `-v` is the first thing people run after installing.
     if (cmd !== "init" && cmd !== "uninstall") {
         const { isFirstRun } = await import("./first-run.js");
         if (isFirstRun()) {
             console.error("open-memex: first run? `open-memex init` wires it into your editors " +
-                "(auto-detects VS Code, Cursor, opencode).");
+                "(auto-detects VS Code, Cursor, opencode — and Visual Studio for solution projects).");
         }
     }
+    if (cmd === "--help" || cmd === "-h" || cmd === "help")
+        usage(0);
+    if (cmd === "--version" || cmd === "-v") {
+        // package.json sits two levels above this file in both layouts
+        // (src/cli.ts and dist/cli.js).
+        const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+        console.log(`open-memex ${pkg.version}`);
+        return;
+    }
     // Per-command help: `open-memex <command> --help`. Checked before loadConfig()
     // so it works even when the environment is broken.
     if (rest.includes("--help") || rest.includes("-h")) {

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 { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.js";
 const EXPECTED_TOOLS = [
     "memory_add",
     "memory_search",
@@ -278,6 +279,7 @@ export async function runDoctor() {
     console.log("open-memex doctor");
     const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), vscodeMcpCheck()];
     checks.push(await mcpCheck());
+    checks.push(legacyCheck());
     let allOk = true;
     for (const c of checks) {
         console.log(`  ${c.ok ? "ok  " : "FAIL"} ${c.name}: ${c.detail}`);
@@ -287,3 +289,31 @@ export async function runDoctor() {
     console.log(allOk ? "All checks passed." : "Some checks failed — see above.");
     return allOk;
 }
+/**
+ * F30: the my-o-memory → open-memex rename left configs and data behind that
+ * silently split memories across two data dirs (the exact trap: the old
+ * opencode plugin kept loading and writing to the OLD dir). Read-only.
+ */
+function legacyCheck() {
+    const name = "legacy my-o-memory";
+    const found = [];
+    const envHome = process.env.MY_O_MEMORY_HOME;
+    if (envHome && envHome.includes(LEGACY_PACKAGE_NAME))
+        found.push(`MY_O_MEMORY_HOME points at a pre-rename dir (${envHome}) — unset it, then merge old data with \`open-memex migrate --to-v2\``);
+    const root = paths().root;
+    const legacyDir = path.join(path.dirname(root), LEGACY_PACKAGE_NAME);
+    if (fs.existsSync(legacyDir) && fs.statSync(legacyDir).isDirectory())
+        found.push(`legacy data dir ${legacyDir} — merge it with \`open-memex migrate --to-v2\``);
+    for (const f of [opencodeGlobalConfigPath(), userMcpConfigPath("vscode"), userMcpConfigPath("cursor")]) {
+        try {
+            if (fs.existsSync(f) && fs.readFileSync(f, "utf8").includes(LEGACY_PACKAGE_NAME))
+                found.push(`stale "${LEGACY_PACKAGE_NAME}" reference in ${f} — re-run \`open-memex init --force --yes\``);
+        }
+        catch {
+            /* unreadable — not this check's problem */
+        }
+    }
+    return found.length === 0
+        ? { name, ok: true, detail: "no pre-rename leftovers found" }
+        : { name, ok: false, detail: found.join("; ") };
+}

package/dist/first-run.js

@@ -64,7 +64,7 @@ export async function offerFirstRunInit(runInit) {
     if (!shouldOfferFirstRun())
         return "skipped";
     console.log(`It looks like open-memex hasn't been set up on this machine yet.\n` +
-        "`open-memex init` wires it into your editors (auto-detects VS Code, Cursor and opencode).\n");
+        "`open-memex init` wires it into your editors (auto-detects VS Code, Cursor and opencode — and Visual Studio for solution projects).\n");
     if (await askYesNo("Run it now? [Y/n] ")) {
         await runInit();
         return "initialized";

package/dist/init.js

@@ -11,6 +11,14 @@ import { markFirstRunDone, clearFirstRunMarker } from "./first-run.js";
 const MARKER = "<!-- open-memex -->";
 /** npm dist-tag carrying the 0.3.x preview line. */
 const ALPHA_TAG = "open-memex@alpha";
+/**
+ * F30: pre-rename package name. The my-o-memory → open-memex rename left
+ * editor configs behind that still load the OLD plugin/server — which writes
+ * to the OLD data dir, silently splitting the user's memories in two.
+ * init, uninstall and doctor treat these leftovers as stale and remove (or
+ * report) them wherever they touch a config.
+ */
+export const LEGACY_PACKAGE_NAME = "my-o-memory";
 /**
  * Resolve the MCP server command to write into client configs.
  *
@@ -228,13 +236,18 @@ function writeServerEntryFile(file, sectionKey, entry, force, mkdir) {
         doc = parsed;
     }
     const merged = mergeServerEntry(doc, sectionKey, entry, force);
-    if (merged === "kept") {
+    // F30: drop a stale my-o-memory server entry — the rename left configs
+    // loading the OLD server, which writes to the OLD data dir.
+    const staleRemoved = removeServerEntry(doc, sectionKey, LEGACY_PACKAGE_NAME) === "removed";
+    if (merged === "kept" && !staleRemoved) {
         console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
         return file;
     }
     if (mkdir)
         fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+    if (staleRemoved)
+        console.log(`  - ${file} (stale my-o-memory server entry removed — package renamed to open-memex)`);
     console.log(`  + ${file}`);
     return file;
 }
@@ -304,16 +317,25 @@ function writeOpencodeGlobalPlugin(force) {
         catch {
             console.log(`  ! ${file} has comments or invalid JSON — left untouched, fix it manually.`);
             console.log(`    To enable open-memex everywhere, add "plugin": ["${url}"] to it.`);
+            console.log(`    Also remove any "${LEGACY_PACKAGE_NAME}" entries from "plugin" (stale — package renamed).`);
             return null;
         }
     }
-    if (mergePluginEntry(doc, url, force) === "kept") {
+    // F30: the my-o-memory → open-memex rename left the OLD plugin loading
+    // alongside the new one — it writes to the OLD data dir, silently splitting
+    // memories in two. Drop it wherever init touches the plugin list.
+    const staleRemoved = removePluginEntry(doc, LEGACY_PACKAGE_NAME) === "removed";
+    const merged = mergePluginEntry(doc, url, force);
+    if (merged === "kept" && !staleRemoved) {
         console.log(`  = ${file} already loads the open-memex plugin — left as is (use --force to overwrite)`);
         return file;
     }
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
-    console.log(`  + ${file} (native plugin — works in every project, no per-project init needed)`);
+    if (staleRemoved)
+        console.log(`  - ${file} (stale my-o-memory plugin entry removed — package renamed to open-memex)`);
+    if (merged === "added")
+        console.log(`  + ${file} (native plugin — works in every project, no per-project init needed)`);
     return file;
 }
 /** opencode MCP config: project-level opencode.jsonc, `type: "local"` + command array (v1 format). */
@@ -335,7 +357,9 @@ function writeOpencodeMcpJson(root, force) {
         doc = parsed;
     }
     const section = (doc["mcp"] ??= {});
-    if (section["open-memex"] && !force) {
+    // F30: drop the pre-rename server entry — it points at the OLD data dir.
+    const staleRemoved = removeServerEntry(doc, "mcp", LEGACY_PACKAGE_NAME) === "removed";
+    if (section["open-memex"] && !force && !staleRemoved) {
         console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
         return file;
     }
@@ -347,6 +371,8 @@ function writeOpencodeMcpJson(root, force) {
         enabled: true,
     };
     fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+    if (staleRemoved)
+        console.log(`  - ${file} (stale my-o-memory MCP entry removed — package renamed to open-memex)`);
     console.log(`  + ${file}`);
     if (!mc.durable) {
         console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
@@ -374,7 +400,9 @@ function writeVisualStudioMcpJson(root, force) {
         }
     }
     const section = (doc["servers"] ??= {});
-    if (section["open-memex"] && !force) {
+    // F30: drop the pre-rename server entry — it points at the OLD data dir.
+    const staleRemoved = removeServerEntry(doc, "servers", LEGACY_PACKAGE_NAME) === "removed";
+    if (section["open-memex"] && !force && !staleRemoved) {
         console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
         return file;
     }
@@ -386,6 +414,8 @@ function writeVisualStudioMcpJson(root, force) {
         args: mc.args,
     };
     fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+    if (staleRemoved)
+        console.log(`  - ${file} (stale my-o-memory MCP entry removed — package renamed to open-memex)`);
     console.log(`  + ${file}`);
     if (!mc.durable) {
         console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
@@ -497,6 +527,78 @@ async function promptConfigLevel() {
         rl.close();
     }
 }
+// ---------------------------------------------------------------------------
+// D54: Agent Skills. The bundled open-memex skill (skills/open-memex/SKILL.md)
+// teaches skill-aware agents to use open-memex via the CLI. init copies it
+// (not symlinks — Windows needs no Developer Mode) into each wired editor's
+// user-level skills dir; uninstall removes only our directory.
+// D55 exception: opencode with the native plugin (global mode) never gets the
+// skill — the plugin already provides memory tools, and the duplicated CLI
+// guidance only makes the agent chatty. See shouldInstallSkill.
+// ---------------------------------------------------------------------------
+/** Package root, two levels above this module (src/init.ts or dist/init.js). */
+export function packageRoot() {
+    return path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+}
+/** Where the bundled skill lives inside the installed package. */
+export function skillSourceDir(pkgRoot = packageRoot()) {
+    return path.join(pkgRoot, "skills", "open-memex");
+}
+/**
+ * D54: user-level Agent Skills directory for the open-memex skill, per client.
+ * null = the client has no skills concept (Visual Studio).
+ */
+export function skillTargetDir(client, env = {}) {
+    const home = env.home ?? os.homedir();
+    switch (client) {
+        case "vscode":
+            return path.join(home, ".copilot", "skills", "open-memex");
+        case "cursor":
+            return path.join(home, ".cursor", "skills", "open-memex");
+        case "opencode":
+            return path.join(opencodeConfigDir(home, env.xdgConfigHome ?? process.env.XDG_CONFIG_HOME), "skills", "open-memex");
+        case "visualstudio":
+            return null;
+    }
+}
+/**
+ * Install the bundled skill for one client. Skips when already present unless
+ * force (a customized skill is never clobbered silently).
+ */
+export function writeSkill(client, opts = {}) {
+    const target = skillTargetDir(client, opts);
+    if (!target)
+        return "unsupported";
+    const source = skillSourceDir(opts.pkgRoot ?? packageRoot());
+    if (!exists(path.join(source, "SKILL.md")))
+        return "missing-source";
+    if (exists(target) && !opts.force)
+        return "skipped";
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.cpSync(source, target, { recursive: true });
+    return "installed";
+}
+/** Remove the open-memex skill installed by init for one client. */
+export function removeSkill(client, env = {}) {
+    const target = skillTargetDir(client, env);
+    if (!target || !exists(target))
+        return "absent";
+    fs.rmSync(target, { recursive: true, force: true });
+    return "removed";
+}
+/**
+ * D55: whether init installs the Agent Skill for a client. opencode with the
+ * native plugin (global mode) already gives the agent memory tools plus
+ * keyword capture and context injection — the skill's CLI guidance is pure
+ * duplication there and makes the agent chatty (two overlapping instruction
+ * sets + a "MCP or CLI?" choice on every memory action). Everywhere else the
+ * skill stays as the no-tools fallback.
+ */
+export function shouldInstallSkill(client, global) {
+    if (client === "opencode" && global)
+        return false;
+    return true;
+}
 function exists(p) {
     try {
         return fs.existsSync(p);
@@ -639,6 +741,12 @@ export async function initProject(opts) {
     const root = projectRoot();
     console.log(`open-memex init — project root: ${root}`);
     for (const client of clients) {
+        // D55: opencode's native plugin supersedes the skill — don't install it
+        // there, and remove one a previous init left behind.
+        const installSkill = shouldInstallSkill(client, global);
+        if (client === "opencode" && !installSkill && removeSkill(client) === "removed") {
+            console.log(`  - Agent Skill removed for opencode (superseded by the native plugin)`);
+        }
         if (client === "vscode" || client === "cursor") {
             if (global)
                 writeGlobalMcpJson(client, opts.force);
@@ -661,6 +769,14 @@ export async function initProject(opts) {
                 writeMcpJson(root, client, opts.force);
             }
         }
+        if (!installSkill)
+            continue;
+        // D54: Agent Skills — user-level by design (init once), alongside the MCP wiring.
+        const skill = writeSkill(client, { force: opts.force });
+        if (skill === "installed")
+            console.log(`  + Agent Skill installed (${skillTargetDir(client)})`);
+        else if (skill === "skipped")
+            console.log(`  - Agent Skill already present for ${client} (use --force to refresh)`);
     }
     if (clients.length === 0) {
         console.log("  - editor setup skipped");
@@ -685,14 +801,16 @@ export async function initProject(opts) {
 // instructions section. Memory data is never touched.
 // ---------------------------------------------------------------------------
 /**
- * Pure removal of the open-memex server entry from a parsed config doc.
+ * Pure removal of a server entry from a parsed config doc.
  * Prunes the section when it becomes empty. Mutates `doc`.
+ * `key` defaults to "open-memex"; F30 passes LEGACY_PACKAGE_NAME to sweep
+ * the pre-rename leftovers.
  */
-export function removeServerEntry(doc, sectionKey) {
+export function removeServerEntry(doc, sectionKey, key = "open-memex") {
     const section = doc[sectionKey];
-    if (!section || typeof section !== "object" || !("open-memex" in section))
+    if (!section || typeof section !== "object" || !(key in section))
         return "absent";
-    delete section["open-memex"];
+    delete section[key];
     if (Object.keys(section).length === 0)
         delete doc[sectionKey];
     return "removed";
@@ -744,11 +862,15 @@ function removeServerEntryFile(file, sectionKey) {
         return null;
     }
     const res = removeServerEntry(doc, sectionKey);
-    if (res === "removed") {
+    // F30: also sweep the pre-rename leftovers — uninstalling open-memex while
+    // the OLD my-o-memory entry still loads leaves a zombie server on the old data dir.
+    const stale = removeServerEntry(doc, sectionKey, LEGACY_PACKAGE_NAME);
+    if (res === "removed" || stale === "removed") {
         fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
-        console.log(`  - ${file} (open-memex entry removed)`);
+        console.log(`  - ${file} (memory-plugin server entries removed)`);
+        return "removed";
     }
-    return res;
+    return "absent";
 }
 /** Remove the open-memex plugin URL from one opencode user-level config file. */
 function removeOpencodePluginFile(file) {
@@ -761,11 +883,14 @@ function removeOpencodePluginFile(file) {
         return null;
     }
     const res = removePluginEntry(doc, "open-memex");
-    if (res === "removed") {
+    // F30: also sweep the pre-rename leftover — see removeServerEntryFile.
+    const stale = removePluginEntry(doc, LEGACY_PACKAGE_NAME);
+    if (res === "removed" || stale === "removed") {
         fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
-        console.log(`  - ${file} (open-memex plugin removed)`);
+        console.log(`  - ${file} (memory-plugin entries removed)`);
+        return "removed";
     }
-    return res;
+    return "absent";
 }
 /** Remove the open-memex section from one copilot-instructions.md file. */
 function removeInstructionsFile(file) {
@@ -855,6 +980,8 @@ export async function uninstallProject(opts) {
             // Solution-level only — --global is meaningless, same as init.
             bump(removeServerEntryFile(path.join(root, ".mcp.json"), "servers"));
         }
+        // D54: remove the Agent Skill installed by init.
+        bump(removeSkill(client));
     }
     // Copilot instructions: init may have written personal (default) or project.
     if (clients.some((c) => c !== "opencode")) {

package/dist/tools/ops.js

@@ -40,7 +40,7 @@ export const TOOL_DESCRIPTIONS = {
     memory_list: "List memories in a scope, newest first. Useful for browsing what is remembered, or verifying that a save landed.",
     memory_supersede: "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
     memory_forget: "Delete a memory by id. Use when the user asks to forget something.",
-    memory_status: "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start and at task checkpoints, then ask the user which drafts to sync. The user may also trigger this flow by saying 'sync memory' (or '同步记忆').",
+    memory_status: "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start, when the server reports drafts waiting for review, or when the user says 'sync memory' (or '同步记忆'); then ask the user which drafts to sync.",
     memory_submit: "Move outbox drafts into the repo memory dir for review: copies the drafts in as proposed (or keeps a local approval), commits locally on the current branch, and moves the outbox originals out. Never creates a branch on its own — pass branch= only with the user's explicit approval for the full chain. Prints the push and PR commands — those need the user's explicit approval and are never run automatically.",
     memory_propose: "Copy personal memories into the project outbox as review drafts. The personal originals stay put.",
     memory_promote: "Advance a project memory one step up the review ladder (proposed → approved → published), or reject it with a note. Rejected memories are never deleted — they can be revised and resubmitted.",
@@ -63,7 +63,7 @@ export const memoryAddArgs = {
     source: z
         .string()
         .optional()
-        .describe("Where this memory came from. Default: tool. Pass 'inference' for agent-proposed captures at checkpoints (V2-DESIGN §3.5)."),
+        .describe("Where this memory came from. Default: tool. Pass 'inference' for agent-proposed captures (V2-DESIGN §3.5)."),
 };
 export const memorySearchArgs = {
     query: z

package/docs/V2-DESIGN.md

@@ -1073,6 +1073,68 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   channel the project controls — the CLI — not in npm script output.
   Reported 2026-10-01.*
 
+- **F29** — Copilot review fixes on PR #11 (0.6.0-alpha.7). (a) The lockfile
+  carried a stray `"version": "0.6.0-alpha.1"` key as a direct child of
+  `packages` (left by the D50 version bump; hand-edited bumps preserved it) —
+  `npm ls --package-lock-only` failed on it. Removed; version bumps now go
+  through `npm pkg set` so npm owns the lockfile format. (b) D53 missed the
+  shared `TOOL_DESCRIPTIONS.memory_status`: it still told agents to call the
+  tool "at session start and at task checkpoints" — the polling this change
+  retires. Now: session start, server-reported drafts, or explicit "sync
+  memory". Same staleness removed from the `source` field hint. (c) Onboarding
+  strings (postinstall note, first-run nudge, bare-CLI offer) now mention
+  Visual Studio auto-detection for solution projects instead of listing only
+  three editors. *Lesson: never hand-edit version fields in package-lock.json.
+  Reported 2026-10-01.*
+
+- **D54** — Agent Skills support (0.6.0-alpha.8). Ship a bundled
+  `open-memex` skill (`skills/open-memex/SKILL.md`: frontmatter + CLI guide —
+  proactive save, search, scope routing, outbox→submit flow) inside the npm
+  package. `init` copies it (not symlinks — Windows needs no Developer Mode)
+  into each wired editor's user-level skills dir: VS Code →
+  `~/.copilot/skills/open-memex/`, Cursor → `~/.cursor/skills/open-memex/`,
+  opencode → `~/.config/opencode/skills/open-memex/`; Visual Studio has no
+  skills concept and is skipped. User-level by design (D46: init once). An
+  existing skill is never clobbered silently — kept unless `--force`.
+  `uninstall` removes only the `open-memex` skill directory. The skill tells
+  agents to prefer MCP tools (`memory_add` etc.) when available and fall back
+  to the CLI otherwise (with the `npx -y open-memex@latest` prefix when the
+  CLI isn't on PATH). *Rationale: skill-aware agents get memory with zero MCP
+  configuration; the skill is the CLI-shaped complement to the MCP server.
+  Requested by Stone 2026-10-01 after the Agent Skills ecosystem suggestion.*
+
+- **F30** — Sweep pre-rename `my-o-memory` leftovers (0.6.0-alpha.9). The
+  my-o-memory → open-memex rename left editor configs behind that still load
+  the OLD plugin/server, which writes to the OLD data dir — silently splitting
+  the user's memories in two (found live on Stone's work machine 2026-10-01:
+  the old opencode plugin sat above the new one in `opencode.json`, so
+  opencode and the CLI wrote to different data roots). `init` now drops stale
+  `my-o-memory` plugin entries and `my-o-memory` MCP server keys wherever it
+  touches a config (opencode global plugin list, per-project `opencode.jsonc`,
+  `.mcp.json`, VS Code/Cursor `mcp.json` incl. `--global`), even on the
+  "kept" path; JSONC files it can't parse get a manual-removal hint.
+  `uninstall` sweeps the same leftovers. `doctor` gains a read-only
+  `legacy my-o-memory` check: fails when a legacy data dir exists next to the
+  data root, when a user-level config still references `my-o-memory`, or when
+  `MY_O_MEMORY_HOME` points at a pre-rename dir. *Lesson: a package rename
+  must clean up its own old wiring — the old entry and the new entry are never
+  both valid. Reported 2026-10-01.*
+
+- **D55** — opencode's native plugin supersedes the Agent Skill
+  (0.6.0-alpha.10). Real-world feedback (Stone 2026-10-01): with both the
+  native plugin's `memory_*` tools and the D54 skill installed, opencode's
+  agent turned chatty — two overlapping instruction sets plus a "use MCP or
+  CLI?" choice on every memory action. No data corruption (identical saves
+  dedupe), but the UX regressed from "one tool call and done" to narration.
+  `init` no longer installs the skill for opencode when the native plugin is
+  wired (`--global`), and removes a previously installed one; the per-project
+  plain-MCP mode keeps the skill as the no-tools fallback. VS Code/Cursor
+  keep the skill — their MCP wiring is more fragile (server-start failures,
+  policy blocks), so the fallback still earns its keep, and the skill already
+  tells agents to prefer MCP tools when available. *Lesson: don't ship two
+  overlapping integrations for the same editor — the agent pays the
+  duplication cost in chatter. Reported 2026-10-01.*
+
 ## 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.0-alpha.5",
+  "version": "0.6.0",
   "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/postinstall.js

@@ -5,5 +5,5 @@
 // prints the pointer. Plain JS, no dependencies.
 console.log(
   "\nopen-memex installed. Run `open-memex init` to wire it into your editors — " +
-    "it auto-detects VS Code, Cursor and opencode.\n",
+    "it auto-detects VS Code, Cursor and opencode (and Visual Studio for solution projects).\n",
 );

package/scripts/smoke-pure.ts

@@ -8,7 +8,7 @@ import { DEFAULT_CONFIG } from "../src/config.ts";
 import { resolveProjectScope, resolveCwdScope, PERSONAL_SCOPE } from "../src/scope.ts";
 import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
 import { contentHash, similarity, NEAR_DUP_THRESHOLD } from "../src/store/lifecycle.ts";
-import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, opencodeGlobalConfigPath, printManualEntryHint, parseJsonConfig, removeServerEntry, removePluginEntry, removeInstructionsSection } from "../src/init.ts";
+import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, opencodeGlobalConfigPath, printManualEntryHint, parseJsonConfig, removeServerEntry, removePluginEntry, removeInstructionsSection, LEGACY_PACKAGE_NAME, shouldInstallSkill } from "../src/init.ts";
 
 let fails = 0;
 function ok(name: string, cond: boolean, info?: unknown) {
@@ -451,6 +451,12 @@ const rdoc2: Record<string, unknown> = { servers: { "open-memex": { command: "x"
 ok("remove prunes empty section", removeServerEntry(rdoc2, "servers") === "removed" && !("servers" in rdoc2));
 ok("remove absent when no entry", removeServerEntry({ servers: {} }, "servers") === "absent");
 ok("remove absent when no section", removeServerEntry({}, "servers") === "absent");
+// F30: pre-rename leftovers are swept by key.
+const ldoc: Record<string, unknown> = { servers: { "my-o-memory": { command: "x" }, "open-memex": { command: "y" } } };
+ok("remove drops legacy my-o-memory key, keeps open-memex", removeServerEntry(ldoc, "servers", LEGACY_PACKAGE_NAME) === "removed"
+  && !("my-o-memory" in (ldoc["servers"] as Record<string, unknown>))
+  && "open-memex" in (ldoc["servers"] as Record<string, unknown>));
+ok("legacy package name is my-o-memory", LEGACY_PACKAGE_NAME === "my-o-memory");
 // removePluginEntry: removes any open-memex URL, prunes empty array.
 const rpdoc: Record<string, unknown> = { plugin: ["file:///x/open-memex/src/index.ts", "other-plugin"], theme: "dark" };
 ok("plugin remove by substring", removePluginEntry(rpdoc, "open-memex") === "removed"
@@ -458,6 +464,10 @@ ok("plugin remove by substring", removePluginEntry(rpdoc, "open-memex") === "rem
 const rpdoc3: Record<string, unknown> = { plugin: ["file:///open-memex/y"] };
 ok("plugin remove prunes empty array", removePluginEntry(rpdoc3, "open-memex") === "removed" && !("plugin" in rpdoc3));
 ok("plugin remove absent", removePluginEntry({ plugin: ["other"] }, "open-memex") === "absent");
+// F30: the rename left the OLD plugin loading next to the new one — init must drop it.
+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"]));
 // 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");
@@ -488,6 +498,11 @@ fs.writeFileSync(path.join(winBin, "code.cmd"), "@echo off\n");
 ok("win32 detects vscode via code.cmd",
   detectInstalledClients({ pathEnv: winBin, home: emptyHome, platform: "win32", root: emptyHome, xdgConfigHome: path.join(emptyHome, ".config") }).includes("vscode"));
 for (const d of [fakeHome, binDir, detHome, detRoot, emptyHome, winBin]) fs.rmSync(d, { recursive: true, force: true });
+// D55: opencode's native plugin supersedes the skill — init must not install it there.
+ok("opencode+global skips skill", shouldInstallSkill("opencode", true) === false);
+ok("opencode per-project keeps skill fallback", shouldInstallSkill("opencode", false) === true);
+ok("vscode keeps skill", shouldInstallSkill("vscode", true) === true);
+ok("cursor keeps skill", shouldInstallSkill("cursor", false) === true);
 
 console.log(fails === 0 ? "\nALL PASS" : `\n${fails} FAILURES`);
 process.exit(fails === 0 ? 0 : 1);

package/skills/open-memex/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: open-memex
+description: Persistent local-first memory for the user and their projects. Use when the user shares facts, preferences, or decisions worth remembering across sessions, or when you need to recall past context before answering.
+---
+
+# open-memex — local memory
+
+open-memex gives you persistent memory across sessions. Memories live in local
+markdown files (SQLite FTS index); the `personal` scope never leaves this machine.
+
+If `open-memex` MCP tools (`memory_add`, `memory_search`, …) are available in
+this session, prefer them. Otherwise use the CLI below. If `open-memex` is not
+on PATH, prefix commands with `npx -y open-memex@latest`.
+
+## Save — be proactive
+
+When the user shares something worth remembering — a fact, preference,
+decision, convention, or error fix — save it without being asked:
+
+```sh
+open-memex add "standup is at 9:30"                        # current project scope
+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.
+
+## Recall
+
+```sh
+open-memex search "deployment steps"   # keyword search across scopes
+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.
+
+## Project outbox → repo (the sync flow)
+
+New project memories land in a local outbox (not in git). Review and publish:
+
+```sh
+open-memex sync-status     # drafts waiting, repo review state, uncommitted files
+open-memex submit <id>     # publish drafts to .ai/open-memex/ + local commit
+```
+
+If any command output reports drafts waiting in the project outbox, run
+`open-memex sync-status` and ask the user which drafts to sync. The user may
+also trigger this flow by saying "sync memory".
+
+Run `open-memex <command> --help` for full usage of any command.

package/src/cli.ts

@@ -577,16 +577,6 @@ async function main() {
     if (outcome !== "initialized") usage(0);
     return;
   }
-  if (cmd === "--help" || cmd === "-h" || cmd === "help") usage(0);
-
-  if (cmd === "--version" || cmd === "-v") {
-    // package.json sits two levels above this file in both layouts
-    // (src/cli.ts and dist/cli.js).
-    const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
-    console.log(`open-memex ${pkg.version}`);
-    return;
-  }
 
   // F28: npm runs lifecycle scripts in the background and swallows their
   // stdout (unless --foreground-scripts), so the D50 postinstall pointer
@@ -594,17 +584,29 @@ async function main() {
   // one-line nudge on stderr until init has run or been declined — stderr
   // keeps the MCP stdio protocol (stdout) intact, and the .init.json marker
   // makes it once-ever. `init`/`uninstall` are excluded (already there /
-  // nothing to wire).
+  // nothing to wire). Placed before the --help/--version early returns:
+  // `-v` is the first thing people run after installing.
   if (cmd !== "init" && cmd !== "uninstall") {
     const { isFirstRun } = await import("./first-run.ts");
     if (isFirstRun()) {
       console.error(
         "open-memex: first run? `open-memex init` wires it into your editors " +
-          "(auto-detects VS Code, Cursor, opencode).",
+          "(auto-detects VS Code, Cursor, opencode — and Visual Studio for solution projects).",
       );
     }
   }
 
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") usage(0);
+
+  if (cmd === "--version" || cmd === "-v") {
+    // package.json sits two levels above this file in both layouts
+    // (src/cli.ts and dist/cli.js).
+    const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    console.log(`open-memex ${pkg.version}`);
+    return;
+  }
+
   // Per-command help: `open-memex <command> --help`. Checked before loadConfig()
   // so it works even when the environment is broken.
   if (rest.includes("--help") || rest.includes("-h")) {

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 { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.ts";
 
 interface Check {
   name: string;
@@ -299,6 +300,7 @@ export async function runDoctor(): Promise<boolean> {
   console.log("open-memex doctor");
   const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), vscodeMcpCheck()];
   checks.push(await mcpCheck());
+  checks.push(legacyCheck());
   let allOk = true;
   for (const c of checks) {
     console.log(`  ${c.ok ? "ok  " : "FAIL"} ${c.name}: ${c.detail}`);
@@ -307,3 +309,33 @@ export async function runDoctor(): Promise<boolean> {
   console.log(allOk ? "All checks passed." : "Some checks failed — see above.");
   return allOk;
 }
+
+/**
+ * F30: the my-o-memory → open-memex rename left configs and data behind that
+ * silently split memories across two data dirs (the exact trap: the old
+ * opencode plugin kept loading and writing to the OLD dir). Read-only.
+ */
+function legacyCheck(): Check {
+  const name = "legacy my-o-memory";
+  const found: string[] = [];
+  const envHome = process.env.MY_O_MEMORY_HOME;
+  if (envHome && envHome.includes(LEGACY_PACKAGE_NAME))
+    found.push(
+      `MY_O_MEMORY_HOME points at a pre-rename dir (${envHome}) — unset it, then merge old data with \`open-memex migrate --to-v2\``,
+    );
+  const root = paths().root;
+  const legacyDir = path.join(path.dirname(root), LEGACY_PACKAGE_NAME);
+  if (fs.existsSync(legacyDir) && fs.statSync(legacyDir).isDirectory())
+    found.push(`legacy data dir ${legacyDir} — merge it with \`open-memex migrate --to-v2\``);
+  for (const f of [opencodeGlobalConfigPath(), userMcpConfigPath("vscode"), userMcpConfigPath("cursor")]) {
+    try {
+      if (fs.existsSync(f) && fs.readFileSync(f, "utf8").includes(LEGACY_PACKAGE_NAME))
+        found.push(`stale "${LEGACY_PACKAGE_NAME}" reference in ${f} — re-run \`open-memex init --force --yes\``);
+    } catch {
+      /* unreadable — not this check's problem */
+    }
+  }
+  return found.length === 0
+    ? { name, ok: true, detail: "no pre-rename leftovers found" }
+    : { name, ok: false, detail: found.join("; ") };
+}

package/src/first-run.ts

@@ -84,7 +84,7 @@ export async function offerFirstRunInit(
   if (!shouldOfferFirstRun()) return "skipped";
   console.log(
     `It looks like open-memex hasn't been set up on this machine yet.\n` +
-      "`open-memex init` wires it into your editors (auto-detects VS Code, Cursor and opencode).\n",
+      "`open-memex init` wires it into your editors (auto-detects VS Code, Cursor and opencode — and Visual Studio for solution projects).\n",
   );
   if (await askYesNo("Run it now? [Y/n] ")) {
     await runInit();

package/src/init.ts

@@ -14,6 +14,15 @@ const MARKER = "<!-- open-memex -->";
 /** npm dist-tag carrying the 0.3.x preview line. */
 const ALPHA_TAG = "open-memex@alpha";
 
+/**
+ * F30: pre-rename package name. The my-o-memory → open-memex rename left
+ * editor configs behind that still load the OLD plugin/server — which writes
+ * to the OLD data dir, silently splitting the user's memories in two.
+ * init, uninstall and doctor treat these leftovers as stale and remove (or
+ * report) them wherever they touch a config.
+ */
+export const LEGACY_PACKAGE_NAME = "my-o-memory";
+
 export interface McpCommand {
   command: string;
   args: string[];
@@ -254,12 +263,17 @@ function writeServerEntryFile(
     doc = parsed;
   }
   const merged = mergeServerEntry(doc, sectionKey, entry, force);
-  if (merged === "kept") {
+  // F30: drop a stale my-o-memory server entry — the rename left configs
+  // loading the OLD server, which writes to the OLD data dir.
+  const staleRemoved = removeServerEntry(doc, sectionKey, LEGACY_PACKAGE_NAME) === "removed";
+  if (merged === "kept" && !staleRemoved) {
     console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
     return file;
   }
   if (mkdir) fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+  if (staleRemoved)
+    console.log(`  - ${file} (stale my-o-memory server entry removed — package renamed to open-memex)`);
   console.log(`  + ${file}`);
   return file;
 }
@@ -336,16 +350,25 @@ function writeOpencodeGlobalPlugin(force: boolean): string | null {
     } catch {
       console.log(`  ! ${file} has comments or invalid JSON — left untouched, fix it manually.`);
       console.log(`    To enable open-memex everywhere, add "plugin": ["${url}"] to it.`);
+      console.log(`    Also remove any "${LEGACY_PACKAGE_NAME}" entries from "plugin" (stale — package renamed).`);
       return null;
     }
   }
-  if (mergePluginEntry(doc, url, force) === "kept") {
+  // F30: the my-o-memory → open-memex rename left the OLD plugin loading
+  // alongside the new one — it writes to the OLD data dir, silently splitting
+  // memories in two. Drop it wherever init touches the plugin list.
+  const staleRemoved = removePluginEntry(doc, LEGACY_PACKAGE_NAME) === "removed";
+  const merged = mergePluginEntry(doc, url, force);
+  if (merged === "kept" && !staleRemoved) {
     console.log(`  = ${file} already loads the open-memex plugin — left as is (use --force to overwrite)`);
     return file;
   }
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
-  console.log(`  + ${file} (native plugin — works in every project, no per-project init needed)`);
+  if (staleRemoved)
+    console.log(`  - ${file} (stale my-o-memory plugin entry removed — package renamed to open-memex)`);
+  if (merged === "added")
+    console.log(`  + ${file} (native plugin — works in every project, no per-project init needed)`);
   return file;
 }
 
@@ -368,7 +391,9 @@ function writeOpencodeMcpJson(root: string, force: boolean): string | null {
     doc = parsed;
   }
   const section = ((doc["mcp"] ??= {}) as Record<string, unknown>);
-  if (section["open-memex"] && !force) {
+  // F30: drop the pre-rename server entry — it points at the OLD data dir.
+  const staleRemoved = removeServerEntry(doc, "mcp", LEGACY_PACKAGE_NAME) === "removed";
+  if (section["open-memex"] && !force && !staleRemoved) {
     console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
     return file;
   }
@@ -380,6 +405,8 @@ function writeOpencodeMcpJson(root: string, force: boolean): string | null {
     enabled: true,
   };
   fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+  if (staleRemoved)
+    console.log(`  - ${file} (stale my-o-memory MCP entry removed — package renamed to open-memex)`);
   console.log(`  + ${file}`);
   if (!mc.durable) {
     console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
@@ -408,7 +435,9 @@ function writeVisualStudioMcpJson(root: string, force: boolean): string | null {
     }
   }
   const section = ((doc["servers"] ??= {}) as Record<string, unknown>);
-  if (section["open-memex"] && !force) {
+  // F30: drop the pre-rename server entry — it points at the OLD data dir.
+  const staleRemoved = removeServerEntry(doc, "servers", LEGACY_PACKAGE_NAME) === "removed";
+  if (section["open-memex"] && !force && !staleRemoved) {
     console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
     return file;
   }
@@ -420,6 +449,8 @@ function writeVisualStudioMcpJson(root: string, force: boolean): string | null {
     args: mc.args,
   };
   fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+  if (staleRemoved)
+    console.log(`  - ${file} (stale my-o-memory MCP entry removed — package renamed to open-memex)`);
   console.log(`  + ${file}`);
   if (!mc.durable) {
     console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
@@ -553,6 +584,93 @@ export interface DetectEnv {
   xdgConfigHome?: string;
 }
 
+// ---------------------------------------------------------------------------
+// D54: Agent Skills. The bundled open-memex skill (skills/open-memex/SKILL.md)
+// teaches skill-aware agents to use open-memex via the CLI. init copies it
+// (not symlinks — Windows needs no Developer Mode) into each wired editor's
+// user-level skills dir; uninstall removes only our directory.
+// D55 exception: opencode with the native plugin (global mode) never gets the
+// skill — the plugin already provides memory tools, and the duplicated CLI
+// guidance only makes the agent chatty. See shouldInstallSkill.
+// ---------------------------------------------------------------------------
+
+/** Package root, two levels above this module (src/init.ts or dist/init.js). */
+export function packageRoot(): string {
+  return path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+}
+
+/** Where the bundled skill lives inside the installed package. */
+export function skillSourceDir(pkgRoot: string = packageRoot()): string {
+  return path.join(pkgRoot, "skills", "open-memex");
+}
+
+/**
+ * D54: user-level Agent Skills directory for the open-memex skill, per client.
+ * null = the client has no skills concept (Visual Studio).
+ */
+export function skillTargetDir(
+  client: InitClient,
+  env: DetectEnv = {},
+): string | null {
+  const home = env.home ?? os.homedir();
+  switch (client) {
+    case "vscode":
+      return path.join(home, ".copilot", "skills", "open-memex");
+    case "cursor":
+      return path.join(home, ".cursor", "skills", "open-memex");
+    case "opencode":
+      return path.join(
+        opencodeConfigDir(home, env.xdgConfigHome ?? process.env.XDG_CONFIG_HOME),
+        "skills",
+        "open-memex",
+      );
+    case "visualstudio":
+      return null;
+  }
+}
+
+/**
+ * Install the bundled skill for one client. Skips when already present unless
+ * force (a customized skill is never clobbered silently).
+ */
+export function writeSkill(
+  client: InitClient,
+  opts: { force?: boolean; pkgRoot?: string } & DetectEnv = {},
+): "installed" | "skipped" | "unsupported" | "missing-source" {
+  const target = skillTargetDir(client, opts);
+  if (!target) return "unsupported";
+  const source = skillSourceDir(opts.pkgRoot ?? packageRoot());
+  if (!exists(path.join(source, "SKILL.md"))) return "missing-source";
+  if (exists(target) && !opts.force) return "skipped";
+  fs.rmSync(target, { recursive: true, force: true });
+  fs.cpSync(source, target, { recursive: true });
+  return "installed";
+}
+
+/** Remove the open-memex skill installed by init for one client. */
+export function removeSkill(
+  client: InitClient,
+  env: DetectEnv = {},
+): "removed" | "absent" {
+  const target = skillTargetDir(client, env);
+  if (!target || !exists(target)) return "absent";
+  fs.rmSync(target, { recursive: true, force: true });
+  return "removed";
+}
+
+/**
+ * D55: whether init installs the Agent Skill for a client. opencode with the
+ * native plugin (global mode) already gives the agent memory tools plus
+ * keyword capture and context injection — the skill's CLI guidance is pure
+ * duplication there and makes the agent chatty (two overlapping instruction
+ * sets + a "MCP or CLI?" choice on every memory action). Everywhere else the
+ * skill stays as the no-tools fallback.
+ */
+export function shouldInstallSkill(client: InitClient, global: boolean): boolean {
+  if (client === "opencode" && global) return false;
+  return true;
+}
+
 function exists(p: string): boolean {
   try {
     return fs.existsSync(p);
@@ -711,6 +829,12 @@ export async function initProject(opts: {
   const root = projectRoot();
   console.log(`open-memex init — project root: ${root}`);
   for (const client of clients) {
+    // D55: opencode's native plugin supersedes the skill — don't install it
+    // there, and remove one a previous init left behind.
+    const installSkill = shouldInstallSkill(client, global);
+    if (client === "opencode" && !installSkill && removeSkill(client) === "removed") {
+      console.log(`  - Agent Skill removed for opencode (superseded by the native plugin)`);
+    }
     if (client === "vscode" || client === "cursor") {
       if (global) writeGlobalMcpJson(client, opts.force);
       else writeMcpJson(root, client, opts.force);
@@ -726,6 +850,12 @@ export async function initProject(opts: {
         writeMcpJson(root, client, opts.force);
       }
     }
+    if (!installSkill) continue;
+    // D54: Agent Skills — user-level by design (init once), alongside the MCP wiring.
+    const skill = writeSkill(client, { force: opts.force });
+    if (skill === "installed") console.log(`  + Agent Skill installed (${skillTargetDir(client)})`);
+    else if (skill === "skipped")
+      console.log(`  - Agent Skill already present for ${client} (use --force to refresh)`);
   }
   if (clients.length === 0) {
     console.log("  - editor setup skipped");
@@ -751,16 +881,19 @@ export async function initProject(opts: {
 // ---------------------------------------------------------------------------
 
 /**
- * Pure removal of the open-memex server entry from a parsed config doc.
+ * Pure removal of a server entry from a parsed config doc.
  * Prunes the section when it becomes empty. Mutates `doc`.
+ * `key` defaults to "open-memex"; F30 passes LEGACY_PACKAGE_NAME to sweep
+ * the pre-rename leftovers.
  */
 export function removeServerEntry(
   doc: Record<string, unknown>,
   sectionKey: string,
+  key = "open-memex",
 ): "removed" | "absent" {
   const section = doc[sectionKey];
-  if (!section || typeof section !== "object" || !("open-memex" in section)) return "absent";
-  delete (section as Record<string, unknown>)["open-memex"];
+  if (!section || typeof section !== "object" || !(key in section)) return "absent";
+  delete (section as Record<string, unknown>)[key];
   if (Object.keys(section as Record<string, unknown>).length === 0) delete doc[sectionKey];
   return "removed";
 }
@@ -810,11 +943,15 @@ function removeServerEntryFile(file: string, sectionKey: string): "removed" | "a
     return null;
   }
   const res = removeServerEntry(doc, sectionKey);
-  if (res === "removed") {
+  // F30: also sweep the pre-rename leftovers — uninstalling open-memex while
+  // the OLD my-o-memory entry still loads leaves a zombie server on the old data dir.
+  const stale = removeServerEntry(doc, sectionKey, LEGACY_PACKAGE_NAME);
+  if (res === "removed" || stale === "removed") {
     fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
-    console.log(`  - ${file} (open-memex entry removed)`);
+    console.log(`  - ${file} (memory-plugin server entries removed)`);
+    return "removed";
   }
-  return res;
+  return "absent";
 }
 
 /** Remove the open-memex plugin URL from one opencode user-level config file. */
@@ -827,11 +964,14 @@ function removeOpencodePluginFile(file: string): "removed" | "absent" | null {
     return null;
   }
   const res = removePluginEntry(doc, "open-memex");
-  if (res === "removed") {
+  // F30: also sweep the pre-rename leftover — see removeServerEntryFile.
+  const stale = removePluginEntry(doc, LEGACY_PACKAGE_NAME);
+  if (res === "removed" || stale === "removed") {
     fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
-    console.log(`  - ${file} (open-memex plugin removed)`);
+    console.log(`  - ${file} (memory-plugin entries removed)`);
+    return "removed";
   }
-  return res;
+  return "absent";
 }
 
 /** Remove the open-memex section from one copilot-instructions.md file. */
@@ -918,6 +1058,8 @@ export async function uninstallProject(opts: {
       // Solution-level only — --global is meaningless, same as init.
       bump(removeServerEntryFile(path.join(root, ".mcp.json"), "servers"));
     }
+    // D54: remove the Agent Skill installed by init.
+    bump(removeSkill(client));
   }
   // Copilot instructions: init may have written personal (default) or project.
   if (clients.some((c) => c !== "opencode")) {

package/src/tools/ops.ts

@@ -71,7 +71,7 @@ export const TOOL_DESCRIPTIONS = {
     "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
   memory_forget: "Delete a memory by id. Use when the user asks to forget something.",
   memory_status:
-    "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start and at task checkpoints, then ask the user which drafts to sync. The user may also trigger this flow by saying 'sync memory' (or '同步记忆').",
+    "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start, when the server reports drafts waiting for review, or when the user says 'sync memory' (or '同步记忆'); then ask the user which drafts to sync.",
   memory_submit:
     "Move outbox drafts into the repo memory dir for review: copies the drafts in as proposed (or keeps a local approval), commits locally on the current branch, and moves the outbox originals out. Never creates a branch on its own — pass branch= only with the user's explicit approval for the full chain. Prints the push and PR commands — those need the user's explicit approval and are never run automatically.",
   memory_propose:
@@ -104,7 +104,7 @@ export const memoryAddArgs = {
     .string()
     .optional()
     .describe(
-      "Where this memory came from. Default: tool. Pass 'inference' for agent-proposed captures at checkpoints (V2-DESIGN §3.5).",
+      "Where this memory came from. Default: tool. Pass 'inference' for agent-proposed captures (V2-DESIGN §3.5).",
     ),
 };
 export type MemoryAddArgs = z.infer<z.ZodObject<typeof memoryAddArgs>>;