open-memex 0.5.1 → 0.6.0-alpha.4

package/AGENTS.md

@@ -64,6 +64,13 @@ previews keyword capture without writing, `open-memex doctor` runs health checks
 (node version, config, scope resolution, storage writability, VS Code MCP enablement, MCP handshake).
 `open-memex init` with no --client auto-detects and wires every installed editor
 (`--yes` skips, scripts never prompt); `open-memex config set <key> <value>` edits settings after install.
+`npm install -g` prints a pointer to `open-memex init` via a postinstall script
+(print-only — postinstall must never prompt, it runs in CI/Docker; D50).
+Bare `open-memex` on a machine where init never completed offers to run it on a
+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).
 `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

package/README.md

@@ -189,6 +189,14 @@ project has a solution file. Prefer to pick a single editor? Pass `--client`:
 >   project: init once, the wiring works in every project. It works the same
 >   whether the package was installed globally or run via npx.
 
+Installing the package also prints a reminder to run `open-memex init` — the
+wiring is a separate step. And if you run bare `open-memex` on a machine where
+init never completed, it offers to run it for you (only on an interactive
+terminal; scripts and CI just see the usual usage text). When init finishes,
+it prints one concrete next step — save a memory with `open-memex add`, then
+ask your agent to recall it — so a first-time user sees what "it works" looks
+like.
+
 **VS Code** (Copilot):
 
 ```sh
@@ -508,8 +516,9 @@ branches and PRs. Nothing moves without you naming it.
 
 In an AI chat with the MCP server connected, just say **"sync memory"**
 (or "同步记忆") — the agent runs the status check, summarizes the outbox drafts,
-and asks which ones to sync. The agent also proposes this on its own at session
-start and at work checkpoints.
+and asks which ones to sync. The server also tells the agent on its own: at
+session start the handshake reports how many drafts are waiting, and every
+memory-changing tool result carries the current count when it is non-zero.
 
 ```sh
 open-memex sync-status
@@ -563,8 +572,8 @@ open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N]
 # (decisions, constraints, lessons, gotchas, howtos). Prints markdown;
 # -o writes it to a file. You review and merge by hand — open-memex
 # never rewrites your AGENTS.md on its own. The snippet ends with a
-# "memory hygiene" section (§3.5 checkpoint guidance) so agents reading
-# AGENTS.md learn to propose distilled captures at checkpoints.
+# "memory hygiene" section (§3.5 distillation guidance) so agents reading
+# AGENTS.md learn to propose distilled captures when a task ends.
 
 open-memex propose <id...> --to project [--local-approve]
 # propose one or several personal memories at once (one branch, one PR);
@@ -619,8 +628,9 @@ server with cwd set to your project root (`init` handles this for you).
 > **Note:** MCP is request/response — it gives the agent tools, not the opencode
 > plugin's automatic keyword capture or first-turn context injection. Proactive
 > memory use depends on the agent's instructions: the server sends session-start
-> guidance (call `memory_status` at session start and at checkpoints) in the MCP
-> handshake `instructions`, and `init` writes the fuller version into the
+> guidance in the MCP handshake `instructions` (including the live outbox draft
+> count at session start, plus the pending count appended to memory-changing
+> tool results when non-zero), and `init` writes the fuller version into the
 > editor's instruction files. Both are advisory — no MCP consumer offers a hard
 > session-start hook.
 
@@ -636,8 +646,8 @@ outbox → `sync-status` → `submit` (local branch+commit, push/PR on your Yes)
 `export` / `import` archive for user portability (Markdown + manifest, no walled
 garden; private excluded by default, `-a` / `--all` for full migration);
 distill-to-AGENTS.md assist (`distill-agents`, propose-only — you merge by hand);
-§3.5 checkpoint distillation in the MCP handshake + init instructions (the agent
-proposes 1–3 captures at checkpoints, the human decides); 1–2 colleague pilot.
+§3.5 distillation in the MCP handshake + init instructions (the agent proposes
+1–3 captures when a task ends, the human decides); 1–2 colleague pilot.
 
 **`0.5.0` (stable):** init UX pass — `init --global` writes the editor wiring
 once at user level (D45); bare `init` auto-detects installed editors and wires

package/README.zh-CN.md

@@ -181,6 +181,12 @@ npx -y open-memex init --yes
 > - `init --global` 是把*编辑器配置*写到用户级而不是项目里：init 一次，
 >   每个项目都生效。不管包是全局安装的还是用 npx 临时跑的，效果一样。
 
+装完包还会打印一句提醒，让你跑 `open-memex init`——接线是独立的一步。
+如果你在从没跑过 init 的机器上直接敲 `open-memex`，它会问你要不要现在
+init（只在交互终端里问；脚本和 CI 里看到的还是原来的 usage）。
+init 跑完会打印一个具体的下一步——用 `open-memex add` 存一条记忆，再让
+agent 回忆它——让第一次用的用户一眼看到"跑起来了"是什么样子。
+
 **VS Code**（Copilot）：
 
 ```sh
@@ -482,8 +488,8 @@ project 草稿先住在 **appdata outbox**（git 看不见、跟分支无关）
 没经过你点名，什么都不会动。
 
 在接了 MCP 服务器的 AI 对话里，直接说 **"同步记忆"**（或 "sync memory"）——
-agent 会查状态、把 outbox 草稿逐条摘要、问你同步哪几条。agent 也会在新对话
-开始和任务检查点主动提这件事。
+agent 会查状态、把 outbox 草稿逐条摘要、问你同步哪几条。服务器也会主动告诉
+agent：新对话开始时握手里带待审草稿数，每次改记忆的 tool 返回里也带当前数（为零时不带）。
 
 ```sh
 open-memex sync-status
@@ -530,7 +536,7 @@ open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N]
 # 把项目记忆（decision/constraint/lesson/gotcha/howto）提炼成
 # AGENTS.md 片段。默认打印到 stdout；-o 写文件。人工审阅后手工合并——
 # open-memex 永不自动改写你的 AGENTS.md。片段末尾带一段"记忆卫生"
-# （§3.5 检查点指引），让读 AGENTS.md 的 agent 学会在检查点提议蒸馏捕获。
+# （§3.5 蒸馏指引），让读 AGENTS.md 的 agent 学会在任务结束时提议蒸馏捕获。
 
 open-memex propose <id...> --to project [--local-approve]
 # 一次 propose 一条或多条（一个分支、一个 PR），每条独立新 id。
@@ -582,9 +588,9 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 > **注意：** MCP 是请求/响应式的——它给 agent 提供 tools，但没有 opencode
 > 插件的关键词自动捕获和首轮上下文注入。想让 agent 主动用记忆，
 > 靠的是 agent 的 instructions：服务器在 MCP 握手的 `instructions` 里自带
-> session-start 指引（开场调 `memory_status`、检查点再调），`init` 则把更完整
-> 的版本写进编辑器的 instruction 文件。两者都是建议性的——MCP 客户端没有
-> 强制的 session-start hook。
+> session-start 指引（含开场时的 outbox 待审草稿数；改记忆的 tool 返回里也会
+> 带当前数，为零时不带），`init` 则把更完整的版本写进编辑器的 instruction
+> 文件。两者都是建议性的——MCP 客户端没有强制的 session-start hook。
 
 ## 路线图（Roadmap）
 
@@ -598,8 +604,8 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 `export` / `import` 归档做用户可携带（Markdown + manifest，不造围墙花园；
 private 默认不导出，`-a` / `--all` 全量迁移）；
 distill-to-AGENTS.md 辅助（`distill-agents`，只提议不改写——人工合并）；
-§3.5 检查点蒸馏写进 MCP 握手指令和 init 指令文件
-（agent 在检查点提议 1–3 条捕获，人来定）；找 1–2 个同事做 pilot。
+§3.5 蒸馏写进 MCP 握手指令和 init 指令文件
+（agent 在任务结束时提议 1–3 条捕获，人来定）；找 1–2 个同事做 pilot。
 
 **`0.5.0`（稳定版）：** init 体验整修——`init --global` 一次写好用户级编辑器接线（D45）；裸 `init` 自动检测已装编辑器并一次全接上（D46）；非标准 JSON 配置不再报错，而是原样保留并打印手贴片段（D47）；`uninstall` 逆转 `init` 且永不碰记忆数据（D48）；空配置文件按空白处理、不再误判为损坏（D49）。"一份记忆，所有 Agent 通用"：同一台机器上的每个编辑器，经由同一个 MCP 接口读写同一份记忆。
 

package/dist/cli.js

@@ -496,7 +496,27 @@ function printMcpConfig(client) {
 }
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
-    if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help")
+    if (!cmd) {
+        // D50: fresh machine + interactive terminal → offer init instead of bare usage.
+        // Non-interactive (CI/scripts/pipes) prints usage exactly as before.
+        const { offerFirstRunInit } = await import("./first-run.js");
+        const outcome = await offerFirstRunInit(async () => {
+            // Re-exec `open-memex init` as a child with inherited stdio instead of
+            // calling initProject() in-process: the offer's readline already
+            // consumed stdin's buffer, and a second readline on the same stream
+            // would see EOF on burst input instead of the user's next answers.
+            const { spawnSync } = await import("node:child_process");
+            const r = spawnSync(process.execPath, [...process.execArgv, fileURLToPath(import.meta.url), "init"], { stdio: "inherit" });
+            if (r.error)
+                throw r.error;
+            if ((r.status ?? 1) !== 0)
+                process.exit(r.status ?? 1);
+        });
+        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

package/dist/distill-agents.js

@@ -53,10 +53,11 @@ export function distillAgentsMarkdown(opts) {
     }
     // D43 — §3.5 memory-hygiene footer (double insurance for opencode users,
     // who never see the MCP handshake / init instructions): teach the agent
-    // reading this AGENTS.md to propose distilled captures at checkpoints.
+    // reading this AGENTS.md to propose distilled captures when a task ends
+    // (D53: the checkpoint mechanism is gone).
     lines.push(`### Memory hygiene (open-memex)`);
     lines.push(``);
-    lines.push(`- At checkpoints (session start, end of a work chunk, after the user commits),`, `  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 without user approval.`, `- If the knowledge already lives in project docs, save a \`reference\` memory`, `  pointing at the doc instead of copying it.`);
+    lines.push(`- When you finish a task the user would describe in one sentence, 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 without user approval.`, `- If the knowledge already lives in project docs, save a \`reference\` memory`, `  pointing at the doc instead of copying it.`);
     lines.push(``);
     return lines.join("\n");
 }

package/dist/first-run.js

@@ -0,0 +1,75 @@
+/**
+ * D50: first-run init offer. `npm install -g open-memex` only puts the CLI on
+ * PATH — the editor wiring is `init`'s job, and a clean reinstall wipes it.
+ * When bare `open-memex` runs on a machine where init never completed, offer
+ * to run it instead of just printing usage.
+ *
+ * The "asked" state is a marker file at the data root (`init` writes it on
+ * success, a declined offer writes it too), so the question is asked exactly
+ * once. `uninstall` removes it — unwiring is the reverse of init, so the next
+ * bare run offers to wire again. The marker is a dotfile: export builds from
+ * DB rows, never by walking the data root, so it can't leak into bundles.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { dataRootPath } from "./paths.js";
+const MARKER = ".init.json";
+export function firstRunMarkerPath(root = dataRootPath()) {
+    return path.join(root, MARKER);
+}
+/** True when init has neither run nor been declined on this machine. */
+export function isFirstRun(root) {
+    return !fs.existsSync(firstRunMarkerPath(root ?? dataRootPath()));
+}
+/** Record the outcome — best effort; a missing marker just asks again next time. */
+export function markFirstRunDone(state) {
+    const file = firstRunMarkerPath();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ v: 1, state, at: new Date().toISOString() }) + "\n");
+    }
+    catch {
+        /* ignore */
+    }
+}
+export function clearFirstRunMarker() {
+    try {
+        fs.rmSync(firstRunMarkerPath(), { force: true });
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Pure decision, kept separate for tests: prompt only on an interactive
+ *  terminal — scripts, CI and piped runs never get the question. */
+export function shouldOfferFirstRun(tty = { stdinTTY: process.stdin.isTTY, stdoutTTY: process.stdout.isTTY }, firstRun = isFirstRun()) {
+    return firstRun && !!tty.stdinTTY && !!tty.stdoutTTY;
+}
+function askYesNo(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (ans) => {
+            rl.close();
+            resolve(!/^\s*(n|no)\s*$/i.test(ans));
+        });
+    });
+}
+/**
+ * Bare-`open-memex` first-run flow. `runInit` is injected so tests don't need
+ * the real init. Returns "skipped" when there's nothing to ask (already set
+ * up, or non-interactive) — the caller then prints usage as before.
+ */
+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");
+    if (await askYesNo("Run it now? [Y/n] ")) {
+        await runInit();
+        return "initialized";
+    }
+    markFirstRunDone("declined");
+    console.log("No problem — run `open-memex init` any time.");
+    return "declined";
+}

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 };