open-memex 0.5.0 → 0.6.0-alpha.4

package/dist/init.js

@@ -7,6 +7,7 @@ import { createInterface } from "node:readline/promises";
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { DEFAULT_CONFIG, saveConfig } from "./config.js";
 import { projectRoot } from "./paths.js";
+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";
@@ -40,54 +41,70 @@ const INSTRUCTIONS = `${MARKER}
 > Applies only when the \`open-memex\` MCP server is available in this session
 > (the \`memory_*\` tools exist). Otherwise ignore this section.
 
-You have a local memory MCP server (\`open-memex\`) with eleven tools:
-\`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`, \`memory_forget\`,
-\`memory_status\`, \`memory_submit\`, \`memory_propose\`, \`memory_promote\`, \`memory_resolve\`,
-\`memory_pr_status\`.
+You have a local memory MCP server (\`open-memex\`). Its tools are
+\`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`,
+\`memory_forget\`, \`memory_status\`, \`memory_submit\`, \`memory_propose\`,
+\`memory_promote\`, \`memory_resolve\`, \`memory_pr_status\` — always call them by
+these full names.
 
-- BE PROACTIVE. When the user shares something worth remembering across sessions
-  (a decision, a preference, a project convention, a fix and its cause), call
-  \`memory_add\` without being asked. Keep each memory to one self-contained statement.
-- At checkpoints (session start, end of a work chunk, after the user commits, after
-  any memory_* action), DISTILL the session: 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 call \`memory_add\` with source "inference" at the
-  confirmed scope. If the knowledge already lives in project docs, save a \`reference\`
-  memory pointing at the doc instead of copying it. Long-form notes are fine ONLY when
-  the user explicitly asks to save one.
-- Before asking the user about past decisions, conventions, or preferences they may
-  have told you before, call \`memory_search\` first — try a few keyword variants
-  (including the user's own language) when the first search comes up empty.
-- Memories default to this project's scope; use the \`personal\` scope for facts about
-  the user that hold across all projects. When a saved fact becomes outdated, call
-  \`memory_supersede\` instead of adding a duplicate.
+- The server tells you when project outbox drafts are waiting for review — in
+  tool results. At session start, call \`memory_status\` once to check. When
+  drafts are waiting, summarize them (one line each) and ask the user which
+  ones to sync into the repo; sync NOTHING the user did not name. If you
+  already asked about these drafts this session, don't ask again. When the
+  server reports none waiting, do nothing.
+- BE PROACTIVE about facts the user states directly: when the user shares a
+  decision, preference, project convention, or fix-and-cause worth remembering
+  across sessions, call \`memory_add\` without being asked. Keep each memory to
+  one self-contained statement, and add a brief "(noted in memory)" so the
+  user sees it worked.
+- For conclusions YOU infer (the user never stated them): when you finish a
+  task the user would describe in one sentence, consider distilling the
+  session — if there is something worth keeping,
+  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), each with its proposed scope. Save
+  NOTHING the user did not approve; on approval call \`memory_add\` with source
+  "inference" at the approved scope. If the knowledge already lives in project
+  docs, save it as type "reference" pointing at the doc instead of copying it.
+  Long-form notes are fine ONLY when the user explicitly asks to save one.
+- Before asking the user about past decisions, conventions, or preferences
+  they may have told you before, call \`memory_search\` first — try a few
+  keyword variants (including the user's own language) when the first search
+  comes up empty.
+- Memories default to this project's scope; use the \`personal\` scope for facts
+  about the user that hold across all projects. When a saved fact becomes
+  outdated, call \`memory_supersede\` (find the old memory's id with
+  \`memory_search\` first) instead of adding a duplicate.
 
 ## Syncing project memories for review (D26)
 
-Project memories you save land in a local outbox first — they are NOT in git yet.
-Syncing them into the repo for review is an explicit, user-approved step:
+Project memories you save land in a local outbox first — they are NOT in git
+yet. Syncing them into the repo for review is an explicit, user-approved step:
 
-- At session start, when you finish a meaningful chunk of work, after the user
-  commits (git commit), and after any memory_* action completes, call
-  \`memory_status\`. If the outbox has drafts, summarize them (one line each) and ask
-  the user which ones to sync. Sync NOTHING the user did not name.
-- When the user says "sync memory" (or "同步记忆"), treat it as a request to run
-  the sync flow above: call \`memory_status\`, summarize the outbox drafts, and ask
-  which ones to sync.
-- When the user approves, call \`memory_submit\` with the approved ids. It copies
-  the drafts into the repo as \`proposed\`, commits locally on the CURRENT branch,
-  and prints the push + PR commands. It NEVER creates a branch on its own.
+- When the server reports drafts waiting for review, call \`memory_status\` to
+  see them. Summarize the drafts (one line each) and ask the user which ones
+  to sync. Sync NOTHING the user did not name.
+- When the user says "sync memory" (or "同步记忆"), run the sync
+  flow above: call \`memory_status\`, summarize the outbox drafts, and ask which
+  ones to sync. ALWAYS use the \`memory_status\` tool for this — never browse
+  the memory data directory directly.
+- When the user approves, call \`memory_submit\` with the approved ids. It
+  copies the drafts into the current project's \`.ai/open-memex/\` directory as
+  \`proposed\` and commits locally on the CURRENT branch. It NEVER creates a
+  branch on its own.
 - After the submit, ask ONE follow-up: "want me to create a branch + push +
-  open the PR, or will you handle it yourself?" A "yes, you do it" answer covers
-  the whole chain — branch creation, push, PR creation — do NOT re-ask at each
-  step. If the user says they will do it themselves, hand them the printed
-  push/PR commands and do nothing. NEVER create branches, push, or open PRs
-  without their explicit approval.
-- Base branch for the memory PR defaults to the branch you are on; the user may
-  redirect it to the integration branch (main) for branch-independent knowledge.
-- If anything conflicts (same id with different content, push rejected), STOP and
-  let the user judge — never overwrite.
+  open the PR, or will you handle it yourself?" A "yes, you do it" answer
+  covers the whole chain — branch creation, push, PR creation — do NOT re-ask
+  at each step. If the user says they will do it themselves, hand them the
+  printed push/PR commands and do nothing. NEVER create branches, push, or open
+  PRs without their explicit approval.
+- If the user wants the memories reviewed on a separate branch, create the
+  branch first (the commit comes along), then push and open the PR. The PR base
+  defaults to the branch submit ran on; \`--base\` overrides it (e.g. \`main\` for
+  branch-independent knowledge).
+- If anything conflicts (same id with different content, push rejected), STOP
+  and let the user judge — never overwrite.
 - After the PR merges, call \`memory_pr_status\` (with \`apply\` when the user
   approves) to map the PR's review state back onto each memory — merged means
   \`published\`, an approval means \`approved\` (credited to the reviewer).
@@ -656,6 +673,11 @@ export async function initProject(opts) {
         writeInstructions(root, scope, clients.find((c) => c !== "opencode"));
     }
     console.log(`\nDone. Reload your editor window to start the open-memex MCP server.`);
+    // D51: close the init→first-use gap — one concrete next step so a new user
+    // sees what "it works" looks like instead of stopping at "it's wired".
+    console.log(`  Next step: \`open-memex add "standup is at 9:30"\` — then ask your agent what it remembers.`);
+    // D50: init completed — the bare-`open-memex` first-run offer won't ask again.
+    markFirstRunDone("initialized");
 }
 // ---------------------------------------------------------------------------
 // uninstall — the reverse of init (D48). Removes the editor wiring init wrote:
@@ -844,4 +866,8 @@ export async function uninstallProject(opts) {
         ? `\nDone. Removed open-memex wiring from ${changed} file(s).`
         : "\nDone. Nothing to remove — no open-memex wiring found.");
     console.log("Your memories are untouched (uninstall never deletes data).");
+    // D50: unwiring is the reverse of init — drop the first-run marker so the
+    // next bare `open-memex` offers to wire again.
+    if (changed > 0)
+        clearFirstRunMarker();
 }

package/dist/mcp.js

@@ -28,7 +28,8 @@ import { loadConfig } from "./config.js";
 import { resolveProjectScope, PERSONAL_SCOPE } from "./scope.js";
 import { db } from "./store/db.js";
 import { syncScope } from "./store/sync.js";
-import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, statusMemories, submitMemoriesOp, proposeMemoriesOp, promoteMemoryOp, resolveMemoryOp, prStatusOp, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, memoryStatusArgs, memorySubmitArgs, memoryProposeArgs, memoryPromoteArgs, memoryResolveArgs, memoryPrStatusArgs, TOOL_DESCRIPTIONS, } from "./tools/ops.js";
+import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, statusMemories, submitMemoriesOp, proposeMemoriesOp, promoteMemoryOp, resolveMemoryOp, prStatusOp, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, memoryStatusArgs, memorySubmitArgs, memoryProposeArgs, memoryPromoteArgs, memoryResolveArgs, memoryPrStatusArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./tools/ops.js";
+import { outboxDraftCount } from "./submit.js";
 // Server version tracks package.json — never hardcode it here again.
 // package.json sits two levels above this file in both layouts
 // (src/mcp.ts and dist/mcp.js), same convention as cli.ts --version.
@@ -49,40 +50,49 @@ const SERVER_VERSION = (() => {
  * client at connect time. Still advisory — no MCP consumer offers a hard
  * session-start hook — but it is the strongest signal available.
  */
-const SERVER_INSTRUCTIONS = `You are connected to an open-memex local memory MCP server
-(eleven memory_* tools: add, search, list, supersede, forget, status, submit,
-propose, promote, resolve, pr_status).
+const SERVER_INSTRUCTIONS = `You are connected to an open-memex local memory MCP server.
+Its tools are memory_add, memory_search, memory_list, memory_supersede,
+memory_forget, memory_status, memory_submit, memory_propose, memory_promote,
+memory_resolve, memory_pr_status — always call them by these full names.
 
-- At the START of this session, when you finish a meaningful chunk of work,
-  after the user commits (git commit), and after any memory_* action completes,
-  call memory_status. If the project outbox has drafts waiting for review,
+- The server tells you when project outbox drafts are waiting for review —
+  in tool results, and in these session-start instructions. When it does,
   summarize them (one line each) and ask the user which ones to sync into the
-  repo. Sync NOTHING the user did not name.
-- When the user says "sync memory" (or "同步记忆"), treat it as a request to run
-  the sync flow: call memory_status, summarize the outbox drafts, and ask which
-  ones to sync. ALWAYS use the memory_status tool for this — never browse the
-  appdata directory directly.
+  repo; sync NOTHING the user did not name. If you already asked about these
+  drafts this session, don't ask again. When the server reports none waiting,
+  do nothing.
+- When the user says "sync memory" (or "同步记忆"), call memory_status,
+  summarize the outbox drafts (one line each), and ask which ones to sync.
+  ALWAYS use the memory_status tool for this — never browse the memory data
+  directory directly.
 - After memory_submit, ask ONE follow-up: "want me to create a branch + push +
   open the PR, or will you handle it yourself?" NEVER create branches, push, or
   open PRs without the user's explicit approval. A "yes, you do it" covers the
   whole chain — do NOT re-ask at each step.
-- BE PROACTIVE: when the user shares something worth remembering across sessions
-  (a decision, a preference, a project convention, a fix and its cause), call
-  memory_add without being asked. Keep each memory to one self-contained statement.
-- At the same checkpoints (session start, end of a work chunk, after the user
-  commits, after any memory_* action), DISTILL the session: 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 call
-  memory_add with source "inference" at the confirmed scope. If the knowledge
-  already lives in project docs, save a \`reference\` memory pointing at the doc
-  instead of copying it. Long-form notes are fine ONLY when the user explicitly
-  asks to save one.
+- BE PROACTIVE about facts the user states directly: when the user shares a
+  decision, preference, project convention, or fix-and-cause worth remembering
+  across sessions, call memory_add without being asked. Keep each memory to one
+  self-contained statement, and add a brief "(noted in memory)" so the user
+  sees it worked.
+- For conclusions YOU infer (the user never stated them): when you finish a
+  task the user would describe in one sentence, consider distilling the
+  session — if there is something worth keeping,
+  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), each with its proposed scope. Save
+  NOTHING the user did not approve; on approval call memory_add with source
+  "inference" at the approved scope. If the knowledge already lives in project
+  docs, save it as type "reference" pointing at the doc instead of copying it.
+  Long-form notes are fine ONLY when the user explicitly asks to save one.
 - Before asking the user about past decisions, conventions, or preferences they
-  may have told you before, call memory_search first.
+  may have told you before, call memory_search first — try a few keyword
+  variants (including the user's own language) when the first search comes up
+  empty.
 - Memories default to this project's scope; use the personal scope for facts
-  about the user that hold across all projects.
-- personal scope memories NEVER leave this machine.`;
+  about the user that hold across all projects. When a saved fact becomes
+  outdated, call memory_supersede (find the old memory's id with memory_search
+  first) instead of adding a duplicate.
+`;
 /** Adapt a framework-agnostic op result to an MCP tool response. */
 function toMcp(p) {
     return p.then((r) => ({ content: [{ type: "text", text: r.output }] }), (e) => ({
@@ -128,11 +138,17 @@ export async function runMcpServer() {
             return fn(args);
         };
     };
-    const server = new McpServer({ name: "open-memex", version: SERVER_VERSION }, { instructions: SERVER_INSTRUCTIONS });
+    // D53: session-start outbox state, pushed. The stdio server starts fresh per
+    // session, so construction-time state ≈ session-start state.
+    const n = outboxDraftCount(scope.key);
+    const instructions = n > 0
+        ? `${SERVER_INSTRUCTIONS}\n\nSession start: the project outbox has ${n} draft${n === 1 ? "" : "s"} waiting for review — call memory_status to see them.`
+        : SERVER_INSTRUCTIONS;
+    const server = new McpServer({ name: "open-memex", version: SERVER_VERSION }, { instructions });
     server.registerTool("memory_add", {
         description: TOOL_DESCRIPTIONS.memory_add,
         inputSchema: z.object(memoryAddArgs),
-    }, withSync((args) => toMcp(addMemory(getScope, cfg, args))));
+    }, withSync((args) => toMcp(withOutboxNote(getScope().key, addMemory(getScope, cfg, args), "call memory_status to review"))));
     server.registerTool("memory_search", {
         description: TOOL_DESCRIPTIONS.memory_search,
         inputSchema: z.object(memorySearchArgs),
@@ -146,12 +162,12 @@ export async function runMcpServer() {
     server.registerTool("memory_supersede", {
         description: TOOL_DESCRIPTIONS.memory_supersede,
         inputSchema: z.object(memorySupersedeArgs),
-    }, withSync((args) => toMcp(supersedeMemory(cfg, args))));
+    }, withSync((args) => toMcp(withOutboxNote(getScope().key, supersedeMemory(cfg, args), "call memory_status to review"))));
     server.registerTool("memory_forget", {
         description: TOOL_DESCRIPTIONS.memory_forget,
         inputSchema: z.object(memoryForgetArgs),
         annotations: { destructiveHint: true },
-    }, withSync((args) => toMcp(forgetMemory(args))));
+    }, withSync((args) => toMcp(withOutboxNote(getScope().key, forgetMemory(args), "call memory_status to review"))));
     server.registerTool("memory_status", {
         description: TOOL_DESCRIPTIONS.memory_status,
         inputSchema: z.object(memoryStatusArgs),
@@ -160,11 +176,11 @@ export async function runMcpServer() {
     server.registerTool("memory_submit", {
         description: TOOL_DESCRIPTIONS.memory_submit,
         inputSchema: z.object(memorySubmitArgs),
-    }, withSync((args) => toMcp(submitMemoriesOp(args))));
+    }, withSync((args) => toMcp(withOutboxNote(getScope().key, submitMemoriesOp(args), "call memory_status to review"))));
     server.registerTool("memory_propose", {
         description: TOOL_DESCRIPTIONS.memory_propose,
         inputSchema: z.object(memoryProposeArgs),
-    }, withSync((args) => toMcp(proposeMemoriesOp(args))));
+    }, withSync((args) => toMcp(withOutboxNote(getScope().key, proposeMemoriesOp(args), "call memory_status to review"))));
     server.registerTool("memory_promote", {
         description: TOOL_DESCRIPTIONS.memory_promote,
         inputSchema: z.object(memoryPromoteArgs),

package/dist/paths.js

@@ -13,6 +13,14 @@ function dataRoot() {
     return path.join(xdg, "open-memex");
 }
 let _cached = null;
+/**
+ * Read-only data-root path — never creates the directory. For existence
+ * checks (D50 first-run detection) that must not pollute storage; contrast
+ * `paths()`, which mkdirs as a side effect.
+ */
+export function dataRootPath() {
+    return dataRoot();
+}
 export function paths() {
     if (_cached)
         return _cached;

package/dist/submit.js

@@ -114,6 +114,19 @@ export function getSyncStatus() {
         uncommitted: uncommittedList,
     };
 }
+/**
+ * D53: cheap outbox draft count — one indexed query, no git I/O — for the
+ * push-not-poll note appended to mutating tool results and to the MCP
+ * session-start instructions. Same outbox definition as getSyncStatus
+ * (file under the scope's outbox dir), without the expensive parts.
+ */
+export function outboxDraftCount(scopeKey) {
+    const outboxDir = memoriesDirPath(scopeKey);
+    const row = db()
+        .prepare(`SELECT COUNT(*) AS n FROM memories WHERE scope_key = ? AND instr(file_path, ?) = 1`)
+        .get(scopeKey, outboxDir + path.sep);
+    return row?.n ?? 0;
+}
 export function formatSyncStatus(st) {
     const lines = [];
     lines.push(`project: ${st.projectName} (${st.scopeKey})`);

package/dist/tools/memory.js

@@ -1,11 +1,11 @@
 import { tool } from "@opencode-ai/plugin/tool";
-import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, TOOL_DESCRIPTIONS, } from "./ops.js";
+import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./ops.js";
 export function makeTools(getScope, cfg) {
     const memory_add = tool({
         description: TOOL_DESCRIPTIONS.memory_add,
         args: memoryAddArgs,
         async execute(args) {
-            return addMemory(getScope, cfg, args);
+            return withOutboxNote(getScope().key, addMemory(getScope, cfg, args));
         },
     });
     const memory_search = tool({
@@ -26,14 +26,14 @@ export function makeTools(getScope, cfg) {
         description: TOOL_DESCRIPTIONS.memory_supersede,
         args: memorySupersedeArgs,
         async execute(args) {
-            return supersedeMemory(cfg, args);
+            return withOutboxNote(getScope().key, supersedeMemory(cfg, args));
         },
     });
     const memory_forget = tool({
         description: TOOL_DESCRIPTIONS.memory_forget,
         args: memoryForgetArgs,
         async execute(args) {
-            return forgetMemory(args);
+            return withOutboxNote(getScope().key, forgetMemory(args));
         },
     });
     return { memory_add, memory_search, memory_list, memory_forget, memory_supersede };

package/dist/tools/ops.js

@@ -15,9 +15,24 @@ import { upsertFromFile, deleteFromIndex } from "../store/sync.js";
 import { findDuplicates, supersede } from "../store/lifecycle.js";
 import { db } from "../store/db.js";
 import { redact } from "../redact.js";
-import { getSyncStatus, formatSyncStatus, submitMemories } from "../submit.js";
+import { getSyncStatus, formatSyncStatus, submitMemories, outboxDraftCount } from "../submit.js";
 import { getPrStatus, formatPrStatus, applyPrStatus } from "../github.js";
 import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory, } from "../review.js";
+/**
+ * D53: push, don't poll. Append the project-outbox pending count to mutating
+ * tool results so agents learn about drafts waiting for review without a
+ * checkpoint poll. Silent when the outbox is empty. `reviewHint` names the
+ * tool to call (MCP); transports without that tool leave it generic.
+ */
+export async function withOutboxNote(scopeKey, p, reviewHint) {
+    const r = await p;
+    const n = outboxDraftCount(scopeKey);
+    if (n > 0) {
+        const tail = reviewHint ? ` — ${reviewHint}` : " for review";
+        r.output += `\n[open-memex: ${n} draft${n === 1 ? "" : "s"} waiting in the project outbox${tail}]`;
+    }
+    return r;
+}
 /** LLM-facing tool descriptions, shared by the opencode plugin and the MCP server. */
 export const TOOL_DESCRIPTIONS = {
     memory_add: "Save a fact, preference, decision, or note to persistent local memory. Call this PROACTIVELY whenever the user shares something worth remembering across sessions — project conventions, tool choices, personal preferences, decisions made, error fixes and their causes. Do not wait to be asked. Keep each memory to one self-contained statement. Default scope is the current project; use the personal scope for facts about the user that apply across all projects.",

package/docs/SCOPES.md

@@ -64,14 +64,15 @@ moves `memories/user/` → `memories/personal/` and rewrites the frontmatter
 tree is kept. Reads remain backward compatible: a v1 file with `scope: user`
 is interpreted as `personal`.
 
-## Visibility (planned, not yet enforced)
+## Visibility
 
 v2 frontmatter carries a separate `visibility` field (`private` | `internal` |
-`shared`). The intended rule: `visibility: private` inside a shared scope is
-**physically isolated** — written to a local-only cache directory, never
-under `.open-memex/` — rather than relying on `.gitignore`. This is not
-implemented yet; today, treat `personal` as the only confidentiality
-boundary and review anything you place under `.open-memex/` before pushing.
+`shared`), defaulting to `private` for the personal scope and `internal` for
+the project scope. `open-memex export` excludes `visibility: private` memories
+by default (`--all` / `-a` includes them, D40). Physical isolation of private
+memories into a local-only cache directory is still planned; today, treat
+`personal` as the only hard confidentiality boundary and review anything you
+place under `.ai/open-memex/` before pushing.
 
 ## Reserved names
 

package/docs/TEST-PLAN.md

@@ -1,4 +1,4 @@
-# OpenMemex 测试计划（v0.4.0-alpha.10）
+# OpenMemex 测试计划（v0.5.1）
 
 > 自动化部分：`node --experimental-strip-types scripts/test-full.ts`
 > 62 项全过（26 个 CLI 命令 + 11 个 MCP tool），隔离环境运行，不碰真实数据。
@@ -6,7 +6,7 @@
 
 ## A. Windows 真机 + VS Code Copilot
 
-- [ ] `npm i -g open-memex@alpha` 全局安装，`open-memex --version` 显示正确版本
+- [ ] `npm i -g open-memex` 全局安装（稳定版），`open-memex --version` 显示正确版本
 - [ ] 在一个真实项目目录跑 `open-memex init`（不加 `--yes`，走一遍交互）
   - 确认 `.vscode/mcp.json` 生成，`~/.copilot/copilot-instructions.md` 合并写入（不覆盖已有内容）
 - [ ] 重启 VS Code，Copilot Chat 里问 "what do you remember about this project?"
@@ -60,10 +60,17 @@
 
 ## G. 同事 pilot（1–2 人，Stone 私下选）
 
-- [ ] 对方 `npx open-memex@alpha init` 走通
+- [ ] 对方 `npx -y open-memex init` 走通
 - [ ] 对方能 propose → 你这边能看到 PR → promote 流程走通
 - [ ] 收集反馈：哪里卡、哪里不符合直觉
 
+## I. init/uninstall 行为（D47–D49）
+
+- [ ] 空的 `mcp.json`：`open-memex init --client vscode` 直接写入，不再报 "not valid JSON"（D49）
+- [ ] 带注释的 `mcp.json`：`init` 不动文件，只打印手贴片段（D47）
+- [ ] `open-memex uninstall --client vscode` 移除接线条目，记忆数据不动；再跑 `init` 可恢复（D48）
+- [ ] 裸 `open-memex uninstall`（交互终端）会先确认再清所有编辑器；`--yes` 跳过确认
+
 ## H. 已知问题观察
 
 - [ ] better-sqlite3 在 Node 24 退出时偶发 crash（exit 134）：注意是否丢数据（预期：不丢，只影响退出码）

package/docs/USER-GUIDE.md

@@ -2,9 +2,8 @@
 
 > This document describes open-memex's **mental model**: where your memories live,
 > how they flow, and who can see them. The in-repo directory (§2, §6 write path)
-> and the propose → promote → resolve workflow (§5) are implemented on the
-> `V2-dev-p2b` branch; features marked **2B** are still to be built;
-> everything else is 0.3.0 behavior.
+> and the propose → promote → resolve workflow (§5) shipped in 0.4.0
+> (Phase 2B); everything described here is current as of 0.5.0.
 
 ## In one sentence
 
@@ -172,7 +171,7 @@ personal idea ──propose──▶ outbox draft ──submit──▶ proposed
 - **Submit** (explicit, your call): `open-memex submit <id...>` → local branch
   + local commit into `.ai/open-memex/`; push/PR are printed for you (or done
   by your agent on your Yes).
-- **Pull** **2B**: `open-memex pull` (always explicit, never automatic) → git fetch +
+- **Pull**: `open-memex pull` (always explicit, never automatic) → git fetch +
   fast-forward → scans `.ai/open-memex/*.md` → merges into the local `index.db` by
   file mtime. Retrieval always goes through SQLite, never walks git.
 - **personal scope**: never syncs (§1 iron rule).
@@ -194,4 +193,4 @@ personal idea ──propose──▶ outbox draft ──submit──▶ proposed
 
 ---
 
-*Companion design record: `docs/V2-DESIGN.md` (decisions D1–D24).*
+*Companion design record: `docs/V2-DESIGN.md` (decisions D1–D49).*

package/docs/USER-GUIDE.zh-CN.md

@@ -2,8 +2,7 @@
 
 > 本文档讲的是 open-memex 的**心智模型**：你的记忆住在哪里、怎么流动、谁能看到。
 > in-repo 目录（§2、§6 的写路径）和 propose → promote → resolve 工作流（§5）
-> 已在 `V2-dev-p2b` 分支实现；标有 **2B** 的功能属于 Phase 2B 待实现部分，
-> 其余为 0.3.0 已有行为。
+> 已随 0.4.0（Phase 2B）发布；本文描述的均为 0.5.0 现行行为。
 
 ## 一句话
 
@@ -143,7 +142,7 @@ server 不能主动推送，调不调 `memory_search` 全看 model 的判断。
   **不碰 repo、不自动 commit、不自动 push**。
 - **交**（显式，你说了算）：`open-memex submit <id...>` → 本地分支 + 本地 commit
   进 `.ai/open-memex/`；push/PR 命令打印给你（或你的 agent 拿着你的 Yes 自己做）。
-- **拉** **2B**：`open-memex pull`（必须显式，没有自动）→ git fetch + fast-forward →
+- **拉**：`open-memex pull`（必须显式，没有自动）→ git fetch + fast-forward →
   扫描 `.ai/open-memex/*.md` → 按文件 mtime 合进本地 `index.db`。检索永远走 SQLite，不 walk git。
 - **personal scope**：永远不同步（§1 铁律）。
 - **没 git 的项目**：照常用，project scope 降级为纯本地并明确提示，不会坏掉。
@@ -158,4 +157,4 @@ server 不能主动推送，调不调 `memory_search` 全看 model 的判断。
 
 ---
 
-*配套设计文档：`docs/V2-DESIGN.md`（D1–D24 决策记录）。*
+*配套设计文档：`docs/V2-DESIGN.md`（D1–D49 决策记录）。*

package/docs/V2-DESIGN.md

@@ -494,7 +494,7 @@ Zero-config is survival for an open-source project. The opencode plugin remains
 - **Phase 1 — Local hardening (1–2 wks).** CJK default (bigram+FTS5) · v1→v2 migration · dedup +
   lifecycle · redaction hardening · scope docs. No external dependencies.
 - **Phase 2A — MCP server (shipped 2026-09-27, D15).** Core/adapters split
-  (`src/tools/ops.ts`) · MCP server (`src/mcp.ts`, stdio) exposing all five memory tools —
+  (`src/tools/ops.ts`) · MCP server (`src/mcp.ts`, stdio) exposing all eleven memory tools —
   read-only-first phasing dropped per D15 · query-aware injection stays host-side.
   Ships in **`0.3.0-alpha`** (with bin/npx user-friendliness polish per §17 adoption path).
 - **Phase 2B — Team sync.** GitProvider · `propose/promote/resolve` · in-repo dir · 1–2 colleague pilot
@@ -538,6 +538,23 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   curator convention ✅ `docs/CURATOR.md` (2026-09-29, pulled forward) ·
   distill-to-AGENTS.md assist ✅ `open-memex distill-agents` (2026-09-29, pulled forward) ·
   export/import archive command ✅ `open-memex export` / `import` (2026-09-29, pulled forward, D40).
+- **0.5.0 (stable, 2026-09-29).** Init UX pass: `init --global` user-level editor
+  wiring (D45) · bare-init auto-detect wires all installed editors (D46) · JSONC
+  configs left untouched with a paste-ready snippet (D47) · `uninstall` reverses
+  `init` without touching memory data (D48) · empty config files treated as
+  blank, not corrupt (D49).
+- **0.5.1 (stable).** `--help` accuracy: `mcp` help states the server exposes 11
+  tools (a superset of the opencode plugin's five memory tools); install hints point
+  at the stable line instead of `@alpha` (F27).
+- **0.6.0 (in development).** Close the install→init gap (D50): postinstall
+  prints the `open-memex init` pointer (never prompts — CI-safe); bare
+  `open-memex` on a fresh machine offers to run init on a TTY. Close the
+  init→first-use gap (D51): init ends with a one-line next-step hint
+  (`open-memex add` + ask the agent to recall it). Agent-prompt clarity pass
+  (D52): rewrite both agent-facing prompts (MCP handshake + init template) so
+  agents execute them correctly. Push-not-poll outbox (D53): the checkpoint
+  mechanism is retired — the server reports the outbox draft count at session
+  start and appends it to mutating tool results when non-zero.
 - **Phase 4 — Future, signal-gated.** Cloud `RemoteProvider` customization only on: multi-private-repo
   sharing needs, fine-grained ACL, audit/compliance mandates · optional API-backed exporters/providers
   for enterprise knowledge systems.
@@ -967,6 +984,78 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   *Rationale: an empty file is the safest write target, not a corrupt file;
   refusing it sent the user down a manual path for no reason. Triggered by
   Stone's report 2026-09-29.*
+- **D50** — close the install→init gap (0.6.0-alpha.1). `npm install -g`
+  only puts the CLI on PATH; the editor wiring is `init`'s job, and a clean
+  reinstall wipes it — Stone hit exactly this on 2026-09-30 (fresh opencode
+  reinstall + `npm i -g open-memex`, then no open-memex in `opencode.jsonc`).
+  Two changes, both CI-safe: (1) a `postinstall` script that **prints**
+  `Run \`open-memex init\`…` — postinstall must never prompt, it runs in CI /
+  Docker / `npm ci` where stdin isn't a terminal; (2) bare `open-memex` on a
+  machine where init never completed **offers** to run it (default yes) when
+  stdin+stdout are TTYs, otherwise prints usage exactly as before. Asked-state
+  is a `.init.json` marker at the data root — init writes it on success, a
+  declined offer writes it too, so the question is asked once; `uninstall`
+  removes it (unwiring is the reverse of init, so the next bare run offers to
+  wire again). The marker is a dotfile and export builds from DB rows, so it
+  can't leak into bundles. The offer re-execs `open-memex init` as a child
+  with inherited stdio rather than calling init in-process — the offer's own
+  readline already consumed stdin's buffer, and a second readline on the same
+  stream would see EOF on burst input (verified with a pty test).
+  *Rationale: install ≠ setup, and the gap only shows up on a fresh machine —
+  exactly when the user has the least context. A printed hint covers the
+  install moment; the interactive offer covers the first-run moment; neither
+  can hang a pipeline. Approved 2026-09-30.*
+- **D51** — close the init→first-use gap (0.6.0-alpha.2). D50 gets the user to
+  a wired editor; a first-time user then stops at "it's wired" with no idea
+  what to do next. `init` now ends with one concrete next step:
+  ``Next step: `open-memex add "standup is at 9:30"` — then ask your agent what
+  it remembers.`` One line, printed unconditionally — the cheapest possible
+  onboarding after wiring. *Rationale: the CLI is editor-independent, so the
+  hint works no matter which client was wired; `add` + recall is the smallest
+  loop that proves the whole system works. Approved 2026-09-30.*
+
+- **D52** — agent-prompt clarity rewrite (0.6.0-alpha.3). Both agent-facing
+  prompts (MCP `initialize` instructions in `src/mcp.ts`, init instruction
+  template in `src/init.ts`) are rewritten to fix ambiguities found on review:
+  (1) the proactive-save vs approval-gate contradiction is resolved by naming
+  the two cases — facts the user *states* are saved proactively, conclusions
+  the agent *infers* are proposed first and saved only on approval;
+  (2) `memory_status`/`memory_search` are excluded from the "after any
+  memory_* action" checkpoint trigger (self-trigger loop);
+  (3) tool names use the full `memory_*` form in both prompts;
+  (4) the four checkpoints are defined once as "Checkpoints" and referenced,
+  with an operational heuristic ("a task the user would describe in one
+  sentence") replacing "meaningful chunk of work";
+  (5) empty outbox → do nothing; "the user commits" → "any git commit in this
+  session"; `type "reference"` named explicitly; PR-base mechanics spelled out
+  per D28. *Rationale: these prompts are the product's UI for agents — a
+  literal-minded agent must execute them correctly without guessing.
+  Approved 2026-10-01.*
+
+- **D53** — push-not-poll outbox: the checkpoint mechanism is retired; code
+  pushes state to the agent instead (0.6.0-alpha.4). `src/submit.ts` gains
+  `outboxDraftCount()` (one indexed SQLite COUNT on the current scope's outbox,
+  no git I/O); `src/tools/ops.ts` gains `withOutboxNote()`, which appends
+  `[open-memex: N draft(s) waiting in the project outbox — call memory_status
+  to review]` to mutating tool results, only when N > 0. It is wired into the
+  five MCP mutating tools (`memory_add`, `memory_supersede`, `memory_forget`,
+  `memory_submit`, `memory_propose`) and the three opencode-plugin mutating
+  tools (`memory_add`, `memory_supersede`, `memory_forget` — there the note
+  stays generic because the plugin has no `memory_status`). The MCP server
+  also appends the live draft count to the `initialize` instructions when N >
+  0 (stdio servers start fresh per session, so construction-time state is
+  session-start state). Both agent-facing prompts drop the Checkpoints section
+  and the post-`memory_submit`/`memory_propose` status checks; the sync rule
+  becomes one line ("when the server reports drafts waiting, call
+  `memory_status`") plus the existing "sync memory" trigger. The static init
+  template keeps one explicit session-start `memory_status` call, since a
+  static file cannot carry live state. An anti-nag clause is added: if the
+  agent already asked about these drafts this session, it does not ask again.
+  *Rationale: the server knows the outbox state; making the agent poll for it
+  on a timer wastes tool calls and teaches a habit that scales badly. The note
+  is silent when the outbox is empty, so the common case costs nothing.
+  `memory_submit` drains the outbox, so its own note is naturally silent.
+  Approved 2026-10-01.*
 
 ## Open Questions