open-memex 0.4.0-alpha.1 → 0.4.0-alpha.5

package/AGENTS.md

@@ -29,8 +29,9 @@ Consequences:
 npm install                                          # once
 npm run typecheck                                    # tsc --noEmit — the only lint/type gate
 npm run cli -- where | list | search "q" | add ... | forget <id> | reindex
+npm run cli -- <command> --help                          # per-command help (AI assistants discover flags this way)
 npm run cli -- sync-status                                  # last sync time/kind + outbox drafts + repo review states + uncommitted files
-npm run cli -- submit <id...> [--onto <branch>] [--base <branch>]  # drafts → .ai/open-memex/ (local branch+commit)
+npm run cli -- submit <id...> [--branch <name>] [--base <branch>]  # drafts → .ai/open-memex/ (current branch + local commit; never auto-branches)
 npm run cli -- propose <id...> --to project [--local-approve]  # copy personal → project outbox (batch OK)
 npm run cli -- promote <id> [--reject] [--resubmit] [--note "..."]        # proposed → approved → published (audit trail appended)
 npm run cli -- pr-status [--apply]                          # map branch PR's GitHub state onto review_state (report; apply = local only)

package/README.md

@@ -262,6 +262,7 @@ open-memex doctor                                  # environment health check
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # preview keyword capture
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
 open-memex --help      # this reference
+open-memex <command> --help  # help for one command
 open-memex --version   # installed version
 ```
 
@@ -282,6 +283,11 @@ Project drafts live in the **appdata outbox** (git-invisible, branch-independent
 only user-approved drafts move into `<repo>/.ai/open-memex/`, where they follow
 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.
+
 ```sh
 open-memex sync-status
 # show when the index was last synced (and what triggered it), the outbox
@@ -289,14 +295,16 @@ open-memex sync-status
 # (draft / proposed / approved / published / rejected),
 # and any uncommitted repo memory files.
 
-open-memex submit <id...> [--onto <branch>] [--base <branch>]
+open-memex submit <id...> [--branch <name>] [--base <branch>]
 # move your named drafts into .ai/open-memex/ as "proposed":
-# creates mem/sync-<timestamp> (or stays on --onto for a code+memory PR),
-# copies, flips review_state, local git commit. All-or-nothing; conflicts
-# (same id, different content) abort cleanly. Prints the push + gh pr
-# commands; an agent holding your Yes carries through push/PR itself.
-# Default PR base is the current branch; --base redirects to main or your
-# integration branch.
+# copies, flips review_state, local git commit ON THE CURRENT BRANCH.
+# Never creates a branch on its own — branch creation is your call
+# (or the agent's, only with your explicit approval for the full chain).
+# All-or-nothing; conflicts (same id, different content) abort cleanly.
+# Prints the push + gh pr commands; an agent holding your Yes carries
+# through push/PR itself. --branch <name> creates the branch first
+# (agent full-chain path). Default PR base is the current branch; --base
+# redirects to main or your integration branch.
 
 open-memex pr-status [--apply]
 # read the branch's GitHub PR and map its state onto each in-repo memory:
@@ -352,8 +360,11 @@ 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 Copilot instructions
-> that `init` writes).
+> 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
+> editor's instruction files. Both are advisory — no MCP consumer offers a hard
+> session-start hook.
 
 ## Roadmap
 

package/README.zh-CN.md

@@ -260,6 +260,7 @@ open-memex doctor                                  # 环境健康检查
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # 预览关键词捕获
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
 open-memex --help      # 本帮助
+open-memex <command> --help  # 单个命令的帮助
 open-memex --version   # 已安装版本
 ```
 
@@ -280,17 +281,23 @@ project 草稿先住在 **appdata outbox**（git 看不见、跟分支无关）
 点名批准的草稿，才会被移入 `<repo>/.ai/open-memex/`，之后随分支和 PR 走。
 没经过你点名，什么都不会动。
 
+在接了 MCP 服务器的 AI 对话里，直接说 **"同步记忆"**（或 "sync memory"）——
+agent 会查状态、把 outbox 草稿逐条摘要、问你同步哪几条。agent 也会在新对话
+开始和任务检查点主动提这件事。
+
 ```sh
 open-memex sync-status
 # 看索引上次同步的时间和触发方、outbox（待同步）、repo 里的评审状态
 # （draft / proposed / approved / published / rejected），
 # 以及 repo 里还没 commit 的记忆文件。
 
-open-memex submit <id...> [--onto <branch>] [--base <branch>]
+open-memex submit <id...> [--branch <name>] [--base <branch>]
 # 把你点名的草稿移入 .ai/open-memex/，状态变为 proposed：
-# 建 mem/sync-<timestamp> 分支（或 --onto 当前分支，跟代码走同一个 PR），
-# 复制、改 review_state、本地 git commit。全有或全无；冲突（同 id 不同内容）
-# 干净回滚。打印 push + gh pr 命令；Agent 拿到你的 Yes 后会自己走完 push/PR。
+# 复制、改 review_state、在当前分支本地 git commit。
+# 永不自动建分支——建分支是你说了算（或 Agent 拿到你明确批准走全链时）。
+# 全有或全无；冲突（同 id 不同内容）干净回滚。
+# 打印 push + gh pr 命令；Agent 拿到你的 Yes 后会自己走完 push/PR。
+# --branch <name> 先建分支再提交（Agent 全链路径）。
 # PR 默认 base 是当前分支；--base 可改到 main 或集成支。
 
 open-memex pr-status [--apply]
@@ -344,7 +351,10 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 
 > **注意：** MCP 是请求/响应式的——它给 agent 提供 tools，但没有 opencode
 > 插件的关键词自动捕获和首轮上下文注入。想让 agent 主动用记忆，
-> 靠的是 agent 的 instructions（`init` 写的 Copilot instructions）。
+> 靠的是 agent 的 instructions：服务器在 MCP 握手的 `instructions` 里自带
+> session-start 指引（开场调 `memory_status`、检查点再调），`init` 则把更完整
+> 的版本写进编辑器的 instruction 文件。两者都是建议性的——MCP 客户端没有
+> 强制的 session-start hook。
 
 ## 路线图（Roadmap）
 

package/dist/cli.js

@@ -18,6 +18,168 @@ import { resolveMcpCommand } from "./init.js";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+/** Per-command help, printed by `open-memex <command> --help`.
+    AI assistants discover the CLI through --help, so every command needs one. */
+const COMMAND_HELP = {
+    where: `Show which project scope the current directory resolves to, and where its data lives.
+
+Usage: open-memex where`,
+    list: `List memories in a scope, newest first.
+
+Usage: open-memex list [--scope project|personal] [--type T] [--limit N]
+
+Flags:
+  --scope   project (default) or personal
+  --type    filter by memory type
+  --limit   max results
+
+Examples:
+  open-memex list
+  open-memex list --scope personal --limit 20`,
+    search: `Search memories by keyword (BM25 full-text), best matches first.
+
+Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+
+Flags:
+  --scope   project (default), personal, or both
+  --type    filter by memory type
+  --limit   max results
+
+Example:
+  open-memex search "deploy checklist" --scope both`,
+    add: `Save a fact, preference, decision, or note to local memory.
+
+Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+
+Flags:
+  --scope   project (default) or personal (personal never leaves this machine)
+  --type    memory type (default: fact)
+  --tag     comma-separated tags
+
+Example:
+  open-memex add "We deploy on Fridays" --scope project --tag process`,
+    supersede: `Replace a memory with a newer version. The old one is kept as history.
+
+Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]`,
+    status: `Change a memory's lifecycle status.
+
+Usage: open-memex status <id> active|deprecated|retracted|archived`,
+    forget: `Delete a memory by id.
+
+Usage: open-memex forget <id>`,
+    propose: `Copy personal memories into the project outbox as review drafts.
+The personal originals stay put. Nothing enters git at this step.
+
+Usage: open-memex propose <id...> --to project [--local-approve]
+
+Flags:
+  --to             project (required)
+  --local-approve  mark the copies approved right away (solo-dev shortcut)
+
+Example:
+  open-memex propose 01ABC 01DEF --to project`,
+    promote: `Advance a project memory one step up the review ladder
+(proposed → approved → published), or reject it with a note.
+Every transition is appended to the memory's review_history.
+Rejected memories are never deleted — they can be revised and resubmitted.
+
+Usage: open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
+
+Flags:
+  --reject    move back to rejected (requires --note)
+  --resubmit  move a rejected memory back to proposed
+  --note      reason for the transition (recorded in review_history)
+  --by        reviewer name (defaults to the git user)
+
+Examples:
+  open-memex promote 01ABC --note "verified against the runbook"
+  open-memex promote 01ABC --reject --note "outdated after the migration"`,
+    resolve: `List conflicted memories, or 3-way-merge one.
+
+Usage: open-memex resolve [id-or-path]
+
+With no argument, lists conflicts. With an id or file path, shows the
+3-way merge (base / outbox / repo) so you can resolve it by hand.
+Conflicts are never auto-resolved.`,
+    "sync-status": `Show the project memory sync pipeline: when the index last synced
+and what triggered it, drafts waiting in the outbox (appdata), memories in the
+repo awaiting review or published, and repo files not yet committed.
+
+Usage: open-memex sync-status`,
+    submit: `Move outbox drafts into the repo for review: copies the drafts into
+the repo memory dir as proposed (a local-approved copy keeps its approval),
+commits locally on the CURRENT branch, and moves the outbox originals out.
+Never creates a branch on its own — branch creation is your call.
+
+Usage: open-memex submit <id...> [--branch <name>] [--base <branch>]
+
+Flags:
+  --branch  create this branch and submit onto it (only with your explicit
+            approval for the full chain); default: stay on current branch
+  --base    PR base override (default: the branch you're on)
+
+Example:
+  open-memex submit 01ABC 01DEF`,
+    "pr-status": `Map the current branch's GitHub PR state back onto review_state:
+merged → published, approval → approved (approved_by = the reviewer),
+changes-requested → suggestion only (never auto-rejects).
+Each memory in the PR is mapped independently; a human rejection is never
+overwritten. Report-only by default.
+
+Usage: open-memex pr-status [--apply]
+
+Flags:
+  --apply   write the transitions locally (still never pushes)`,
+    reindex: `Rebuild the SQLite index from the markdown files.
+
+Usage: open-memex reindex`,
+    scopes: `List the known scopes (personal + project).
+
+Usage: open-memex scopes`,
+    migrate: `Move memories between scopes, or convert a legacy my-o-memory data dir.
+
+Usage: open-memex migrate [--from <key>] [--to <key>] [--dry-run] [--on-conflict newer|overwrite|skip]
+       open-memex migrate --to-v2 [--dry-run]
+
+Flags:
+  --from / --to   scope keys (default: current project → personal)
+  --dry-run       preview without moving anything
+  --on-conflict   newer (default), overwrite, or skip
+  --to-v2         convert a legacy my-o-memory data dir to the v2 layout
+
+Always preview with --dry-run first; nothing moves without confirmation.`,
+    mcp: `Start the stdio MCP server (the same server editors connect to).
+
+Usage: open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
+
+Flags:
+  --print-config   print the MCP client config instead of starting the server`,
+    init: `One-command project setup: writes the MCP config for your editor and the
+agent memory instructions. Existing files are merged, never clobbered.
+
+Usage: open-memex init [--client vscode|cursor|opencode|visualstudio]
+              [--instructions personal|project] [--force] [--yes]
+
+Flags:
+  --client        editor to configure (default: auto-detect)
+  --instructions  personal (default, ~/.copilot/copilot-instructions.md) or project
+  --force         overwrite existing config
+  --yes           accept all defaults, never prompt`,
+    config: `Show config, or set a key.
+
+Usage: open-memex config [set <key> <value>]
+
+Example:
+  open-memex config set sync.autoPull false`,
+    capture: `Preview what the keyword-capture watcher would extract from text.
+
+Usage: open-memex capture --dry-run "text"`,
+    doctor: `Environment health check: Node version, config source, scope resolution,
+storage writability, then boots a real MCP server and runs initialize +
+tools/list against it — all eleven tools must show up.
+
+Usage: open-memex doctor`,
+};
 function usage(exitCode = 1) {
     console.log(`open-memex CLI
 
@@ -33,7 +195,7 @@ Usage:
   open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
   open-memex resolve [id-or-path]
   open-memex sync-status
-  open-memex submit <id...> [--onto <branch>] [--base <branch>]
+  open-memex submit <id...> [--branch <name>] [--base <branch>]
   open-memex pr-status [--apply]
   open-memex reindex
   open-memex scopes
@@ -72,7 +234,9 @@ the \`--from\` key when migrating.
 git remote after memories were already stored under the cwd-based key.
 \`migrate --to-v2\` converts v1 memory files to the v2 format (§19):
 user→personal scope rename, epoch→RFC 3339 times, priority→importance,
-type: instruction→role split. Always preview with --dry-run first.`);
+type: instruction→role split. Always preview with --dry-run first.
+
+Run \`open-memex <command> --help\` for details on a single command.`);
     process.exit(exitCode);
 }
 function parseFlags(argv) {
@@ -172,6 +336,16 @@ async function main() {
         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")) {
+        const h = COMMAND_HELP[cmd];
+        if (h) {
+            console.log(`open-memex ${cmd}\n\n${h}`);
+            return;
+        }
+        usage(0);
+    }
     const cfg = loadConfig();
     const project = resolveProjectScope(process.cwd());
     // `migrate --to-v2` is a pure file operation (V2-DESIGN §19) — it runs
@@ -637,7 +811,7 @@ async function main() {
             usage();
         syncScope(project.key, "submit");
         try {
-            const r = submitMemories(ids, { onto: flags.onto, base: flags.base });
+            const r = submitMemories(ids, { branch: flags.branch, base: flags.base });
             for (const s of r.submitted) {
                 console.log(`submitted ${s.id} → ${path.relative(process.cwd(), s.filePath)}  [${s.reviewState}]`);
             }

package/dist/init.js

@@ -59,17 +59,22 @@ You have a local memory MCP server (\`open-memex\`) with eleven tools:
 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, and when you finish a meaningful chunk of work, call
+- 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 approves, ask ONE follow-up: a separate memory-only branch/PR
-  (recommended), or fold the memories into the current branch alongside code?
-  A "yes, you do it" answer covers the whole chain — branch, local commit,
-  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.
-  Then call \`memory_submit\` with the approved ids (\`onto\` = current branch name
-  only for the fold-into-code path). It creates the branch, copies the drafts in
-  as \`proposed\`, commits locally, and prints the push + PR commands.
+- 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.
+- 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

package/dist/mcp.js

@@ -26,6 +26,38 @@ 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";
 const SERVER_VERSION = "0.2.0-alpha";
+/**
+ * D26: session-start guidance delivered through the MCP handshake itself.
+ * The init-written instruction files only exist if the user ran
+ * `open-memex init --client`; the initialize `instructions` reach every MCP
+ * 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).
+
+- 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,
+  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.
+- 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.
+- Before asking the user about past decisions, conventions, or preferences they
+  may have told you before, call memory_search first.
+- 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.`;
 /** 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) => ({
@@ -57,7 +89,7 @@ export async function runMcpServer() {
             return fn(args);
         };
     };
-    const server = new McpServer({ name: "open-memex", version: SERVER_VERSION });
+    const server = new McpServer({ name: "open-memex", version: SERVER_VERSION }, { instructions: SERVER_INSTRUCTIONS });
     server.registerTool("memory_add", {
         description: TOOL_DESCRIPTIONS.memory_add,
         inputSchema: z.object(memoryAddArgs),

package/dist/submit.js

@@ -150,7 +150,8 @@ export function submitMemories(ids, opts = {}) {
     if (ids.length === 0)
         fail("submit needs at least one memory id");
     const root = projectRoot();
-    // submit needs a git repo — the whole point is branch + commit.
+    // submit needs a git repo — the memories land in .ai/open-memex/ and are
+    // committed locally. Branch creation is never automatic (D36).
     git(root, ["rev-parse", "--git-dir"]);
     const scope = resolveProjectScope(root);
     const cfg = loadConfig();
@@ -197,26 +198,26 @@ export function submitMemories(ids, opts = {}) {
         fail(`submit aborted — nothing was written:\n  ${problems.join("\n  ")}`);
     }
     // 2. Resolve the target branch.
+    //    D36: submit never creates a branch on its own — it works on the branch
+    //    you're already on. Pass --branch <name> (explicitly) only when the user
+    //    approved the full chain (branch + push + PR).
     const startBranch = git(root, ["branch", "--show-current"]) || git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
-    let branch;
-    if (opts.onto) {
-        if (opts.onto !== startBranch) {
-            fail(`--onto ${opts.onto} is not the current branch (${startBranch || "(detached)"}). submit only targets the branch you're on.`);
-        }
-        branch = opts.onto;
-    }
-    else {
-        const stamp = new Date().toISOString().replace(/[-:]/g, "").slice(0, 15);
-        branch = `mem/sync-${stamp}`;
+    let branch = startBranch;
+    let createdBranch = false;
+    if (opts.branch) {
+        branch = opts.branch;
         let n = 0;
+        let candidate = branch;
         while (true) {
-            const exists = git(root, ["branch", "--list", branch]);
+            const exists = git(root, ["branch", "--list", candidate]);
             if (!exists)
                 break;
             n++;
-            branch = `mem/sync-${stamp}-${n}`;
+            candidate = `${branch}-${n}`;
         }
+        branch = candidate;
         git(root, ["checkout", "-b", branch]);
+        createdBranch = true;
     }
     const base = opts.base ?? startBranch;
     const author = currentAuthor();
@@ -278,7 +279,7 @@ export function submitMemories(ids, opts = {}) {
         }
         // If we created the branch and never committed, remove it too — an
         // aborted submit leaves no trace.
-        if (!opts.onto) {
+        if (createdBranch) {
             try {
                 git(root, ["checkout", "--quiet", startBranch]);
                 git(root, ["branch", "--quiet", "-D", branch]);
@@ -327,13 +328,20 @@ export function submitMemories(ids, opts = {}) {
         removed: 0,
         scanned: validated.length,
     });
+    // D36: no auto-branch — the commit sits on the branch you were already on.
+    // Next steps are printed, not run. For a separate memory PR, create a branch
+    // first (the commit comes along), then push + open the PR.
+    const branchCmd = `git checkout -b mem/sync-YYYYMMDD`;
     return {
         branch,
         base,
         submitted,
         skippedIdentical,
         committed,
+        createdBranch,
         pushCommand: `git push -u origin ${branch}`,
-        prCommand: `gh pr create --base ${base} --title "mem: review ${validated.length} ${validated.length === 1 ? "memory" : "memories"}" --body "Submitted from the open-memex outbox: ${ids8}."`,
+        prCommand: createdBranch
+            ? `gh pr create --base ${base} --title "mem: review ${validated.length} ${validated.length === 1 ? "memory" : "memories"}" --body "Submitted from the open-memex outbox: ${ids8}."`
+            : `${branchCmd}  # if you want a separate memory PR (else push ${branch} directly)\n  git push -u origin <new-branch> && gh pr create --base ${base} --title "mem: review ${validated.length}" --body "Submitted from the open-memex outbox: ${ids8}."`,
     };
 }

package/dist/tools/ops.js

@@ -25,8 +25,8 @@ 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.",
-    memory_submit: "Move outbox drafts into a git branch for review: creates a branch (default mem/sync-*), copies the drafts into the repo memory dir as proposed, commits locally, and moves the outbox originals out. Prints the push and PR commands — those need the user's explicit approval and are never run automatically.",
+    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_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.",
     memory_resolve: "List git-conflicted memory files, or attempt a field-level 3-way merge of one. Semantic conflicts are reported, never auto-resolved.",
@@ -78,14 +78,14 @@ export const memoryForgetArgs = {
 export const memoryStatusArgs = {};
 export const memorySubmitArgs = {
     ids: z.array(z.string().min(1)).min(1).describe("Outbox draft ids to submit."),
-    onto: z
+    branch: z
         .string()
         .optional()
-        .describe("Submit onto this branch instead of creating mem/sync-*. Must be the current branch (for folding memories into a code PR)."),
+        .describe("Create this branch and submit onto it. If omitted, submit stays on the current branch — branches are never auto-created. Only pass this when the user explicitly approved the full chain (branch + push + PR)."),
     base: z
         .string()
         .optional()
-        .describe("PR base branch override. Default: the branch the submit branched from."),
+        .describe("PR base branch override. Default: the branch the submit ran on."),
 };
 export const memoryProposeArgs = {
     ids: z.array(z.string().min(1)).min(1).describe("Personal memory ids to copy into the project outbox."),
@@ -260,16 +260,18 @@ export async function statusMemories() {
     };
 }
 export async function submitMemoriesOp(args) {
-    const r = submitMemories(args.ids, { onto: args.onto, base: args.base });
+    const r = submitMemories(args.ids, { branch: args.branch, base: args.base });
     const lines = [];
     for (const s of r.submitted)
         lines.push(`submitted ${s.id} [${s.reviewState}]`);
     for (const id of r.skippedIdentical)
         lines.push(`already on branch: ${id} (outbox copy removed)`);
-    lines.push(r.committed ? `committed on ${r.branch}.` : `nothing new to commit on ${r.branch}.`);
-    lines.push(`Next (needs the user's explicit approval — never run automatically):`);
+    lines.push(r.committed ? `committed on ${r.branch} (you are still on this branch).` : `nothing new to commit on ${r.branch}.`);
+    lines.push(`Next — ask the user: "want me to create a branch + push + open the PR, or will you handle it yourself?"`);
+    lines.push(`Never create branches, push, or open PRs without their explicit approval. If they handle it themselves, hand them these:`);
     lines.push(`  ${r.pushCommand}`);
-    lines.push(`  ${r.prCommand}`);
+    for (const l of r.prCommand.split("\n"))
+        lines.push(`  ${l}`);
     return { title: `memory: submitted ${r.submitted.length}`, output: lines.join("\n") };
 }
 export async function proposeMemoriesOp(args) {

package/docs/USER-GUIDE.md

@@ -99,13 +99,15 @@ personal idea ──propose──▶ outbox draft ──submit──▶ proposed
   what triggered it — session start, a request, a CLI run, a submit), the
   outbox (pending sync), the repo review states
   (`draft / proposed / approved / published / rejected`), and any uncommitted
-  repo memory files. Your agent calls this at session start and at meaningful
-  checkpoints, then asks which drafts (if any) you want synced.
+  repo memory files. Your agent calls this at session start, at meaningful
+  checkpoints, after you commit, and after memory actions — then asks which
+  drafts (if any) you want synced. You can also just say "sync memory".
 - `open-memex submit <id...>`: moves **your named drafts** into
-  `<repo>/.ai/open-memex/` as `proposed`. It creates `mem/sync-<timestamp>`
-  (or stays on the current branch with `--onto` for a code+memory PR), copies
-  the files, flips `review_state`, and makes a **local** git commit —
-  all-or-nothing, idempotent, crash-safe. It prints the `git push` +
+  `<repo>/.ai/open-memex/` as `proposed`. It copies the files, flips
+  `review_state`, and makes a **local** git commit **on your current branch** —
+  it never creates a branch on its own (branch creation is your call, or your
+  agent's with your explicit approval via `--branch <name>`).
+  All-or-nothing, idempotent, crash-safe. It prints the `git push` +
   `gh pr create` commands; if your agent already has your Yes for this sync,
   it carries through push and PR itself. The PR base defaults to the current
   branch; `--base` redirects to `main` or your integration branch.
@@ -120,8 +122,8 @@ personal idea ──propose──▶ outbox draft ──submit──▶ proposed
     (push, PR, merge).
 - A standalone memory PR contains **only memory files, no code**, reviewed and
   audited separately from code PRs. Reviewers check "is this true? is it safe
-  to share? any secrets?" — things a code PR's CI never checks. You can also
-  ride along in a code PR (`submit --onto <branch>`).
+  to share? any secrets?" — things a code PR's CI never checks. You create the
+  branch yourself when you want one (or your agent does, with your approval).
 - "Request changes" needs no command: while the PR is open, the author edits
   the same file (directly, or by asking their agent in chat), commits, and
   pushes. The state stays `proposed`; the PR is the review mechanism.

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

@@ -87,12 +87,13 @@ server 不能主动推送，调不调 `memory_search` 全看 model 的判断。
 - `open-memex sync-status`：看索引**上次同步的时间和触发方**（会话开始、
   请求、CLI、submit）、草稿箱（待同步）、repo 里的评审状态
   （`draft / proposed / approved / published / rejected`），以及 repo 里还没
-  commit 的记忆文件。你的 agent 会在会话开始和关键节点跑这个，然后问你
-  哪些草稿（如果有）要同步。
+  commit 的记忆文件。你的 agent 会在会话开始、关键节点、你 commit 之后、
+  记忆动作之后跑这个，然后问你哪些草稿（如果有）要同步。你也可以直接说"同步记忆"。
 - `open-memex submit <id...>`：把**你点名的草稿**移入 `<repo>/.ai/open-memex/`，
-  状态变为 `proposed`。它会建 `mem/sync-<timestamp>` 分支（或用 `--onto`
-  留在当前分支，跟代码走同一个 PR），复制文件、改 `review_state`、做一次
-  **本地** git commit——全有或全无、幂等、crash-safe。它打印 `git push` +
+  状态变为 `proposed`。它复制文件、改 `review_state`、在**当前分支**做一次
+  **本地** git commit——永不自动建分支（建分支你说了算，或 agent 拿到你明确
+  批准走全链时用 `--branch <name>`）。
+  全有或全无、幂等、crash-safe。它打印 `git push` +
   `gh pr create` 命令；如果你的 agent 已经拿到你这次的 Yes，它会自己走完
   push 和 PR。PR 默认 base 是当前分支；`--base` 可改到 `main` 或集成支。
   分支上同 id 但内容不同——**直接中止**，等人裁决，绝不覆盖。
@@ -104,7 +105,7 @@ server 不能主动推送，调不调 `memory_search` 全看 model 的判断。
     **git 负责运输**（push、PR、合并）。
 - 独立的记忆 PR **只含记忆文件，不含代码**，跟代码 PR 分开评审、分开审计。
   审的是"这条是真的吗？能给全团队看吗？有没有 secret？"——代码 PR 的 CI 不会查这些。
-  也可以搭代码 PR 的车（`submit --onto <branch>`）。
+  想开分支时你自己建（或 agent 拿到批准后建）。
 - "要求修改"不需要命令：PR 开着的时候，作者直接改同一个文件（自己改，
   或在 chat 里让 agent 改），commit、push。状态一直是 `proposed`，
   PR 本身就是评审机制。

package/docs/V2-DESIGN.md

@@ -699,6 +699,39 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   is never overridden by a PR signal. *Rationale: the PR is where the team
   actually reviews — the mapping closes the loop without inventing new
   review UI. Approved 2026-09-28.*
+- **D34** — The MCP server sends session-start guidance in the handshake
+  `instructions`: call `memory_status` at session start (and at work
+  checkpoints); if the outbox has drafts, summarize and ask the user which to
+  sync; proactive `memory_add`; `memory_search` before asking about the past;
+  personal never leaves the machine. *Rationale: the init-written instruction
+  files only exist if the user ran `init --client` — the handshake reaches
+  every MCP client at connect time. Still advisory: no MCP consumer offers a
+  hard session-start hook, and we do not claim otherwise. Approved 2026-09-28.*
+- **D35** — "sync memory" (or "同步记忆") is a natural-language trigger for the
+  sync flow: the agent calls `memory_status`, summarizes the outbox drafts, and
+  asks the user which ones to sync — same flow as the session-start proposal,
+  but user-initiated. Taught in the MCP handshake instructions, the
+  init-written instruction files, and the `memory_status` tool description.
+  *Rationale: the user should not have to remember command names to sync;
+  saying it in words must work. Approved 2026-09-28.*
+- **D36** — `submit` never creates a branch on its own (revises D26/D27): it
+  copies the named drafts into `.ai/open-memex/`, commits locally on the
+  CURRENT branch, and prints next-step commands. Branch creation is the human's
+  call — or the agent's, only with explicit approval for the full chain, via
+  `submit --branch <name>` / `memory_submit(branch=...)`. *Rationale: an
+  auto-created branch strands the user on it — they forget to switch back.
+  After a submit the agent asks ONE follow-up ("want me to create a branch +
+  push + open the PR, or will you handle it yourself?") instead of branching
+  silently. Checkpoints that trigger `memory_status`: session start, end of a
+  work chunk, after the user commits, and after any memory_* action.
+  The "sync memory" trigger ALWAYS goes through the `memory_status` tool —
+  never by browsing the appdata directory directly. Approved 2026-09-28.*
+- **D33** — Every CLI command answers `open-memex <command> --help` (and `-h`)
+  with its own usage, flags, and examples; checked before config/DB load so
+  help works even in a broken environment. Unknown commands with `--help`
+  fall back to the global usage. *Rationale: AI assistants discover the CLI
+  through --help first — a command that silently swallows --help as a flag
+  teaches the agent nothing. Approved 2026-09-28.*
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.4.0-alpha.1",
+  "version": "0.4.0-alpha.5",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",

package/src/cli.ts

@@ -25,6 +25,189 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** Per-command help, printed by `open-memex <command> --help`.
+    AI assistants discover the CLI through --help, so every command needs one. */
+const COMMAND_HELP: Record<string, string> = {
+  where: `Show which project scope the current directory resolves to, and where its data lives.
+
+Usage: open-memex where`,
+
+  list: `List memories in a scope, newest first.
+
+Usage: open-memex list [--scope project|personal] [--type T] [--limit N]
+
+Flags:
+  --scope   project (default) or personal
+  --type    filter by memory type
+  --limit   max results
+
+Examples:
+  open-memex list
+  open-memex list --scope personal --limit 20`,
+
+  search: `Search memories by keyword (BM25 full-text), best matches first.
+
+Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+
+Flags:
+  --scope   project (default), personal, or both
+  --type    filter by memory type
+  --limit   max results
+
+Example:
+  open-memex search "deploy checklist" --scope both`,
+
+  add: `Save a fact, preference, decision, or note to local memory.
+
+Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+
+Flags:
+  --scope   project (default) or personal (personal never leaves this machine)
+  --type    memory type (default: fact)
+  --tag     comma-separated tags
+
+Example:
+  open-memex add "We deploy on Fridays" --scope project --tag process`,
+
+  supersede: `Replace a memory with a newer version. The old one is kept as history.
+
+Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]`,
+
+  status: `Change a memory's lifecycle status.
+
+Usage: open-memex status <id> active|deprecated|retracted|archived`,
+
+  forget: `Delete a memory by id.
+
+Usage: open-memex forget <id>`,
+
+  propose: `Copy personal memories into the project outbox as review drafts.
+The personal originals stay put. Nothing enters git at this step.
+
+Usage: open-memex propose <id...> --to project [--local-approve]
+
+Flags:
+  --to             project (required)
+  --local-approve  mark the copies approved right away (solo-dev shortcut)
+
+Example:
+  open-memex propose 01ABC 01DEF --to project`,
+
+  promote: `Advance a project memory one step up the review ladder
+(proposed → approved → published), or reject it with a note.
+Every transition is appended to the memory's review_history.
+Rejected memories are never deleted — they can be revised and resubmitted.
+
+Usage: open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
+
+Flags:
+  --reject    move back to rejected (requires --note)
+  --resubmit  move a rejected memory back to proposed
+  --note      reason for the transition (recorded in review_history)
+  --by        reviewer name (defaults to the git user)
+
+Examples:
+  open-memex promote 01ABC --note "verified against the runbook"
+  open-memex promote 01ABC --reject --note "outdated after the migration"`,
+
+  resolve: `List conflicted memories, or 3-way-merge one.
+
+Usage: open-memex resolve [id-or-path]
+
+With no argument, lists conflicts. With an id or file path, shows the
+3-way merge (base / outbox / repo) so you can resolve it by hand.
+Conflicts are never auto-resolved.`,
+
+  "sync-status": `Show the project memory sync pipeline: when the index last synced
+and what triggered it, drafts waiting in the outbox (appdata), memories in the
+repo awaiting review or published, and repo files not yet committed.
+
+Usage: open-memex sync-status`,
+
+  submit: `Move outbox drafts into the repo for review: copies the drafts into
+the repo memory dir as proposed (a local-approved copy keeps its approval),
+commits locally on the CURRENT branch, and moves the outbox originals out.
+Never creates a branch on its own — branch creation is your call.
+
+Usage: open-memex submit <id...> [--branch <name>] [--base <branch>]
+
+Flags:
+  --branch  create this branch and submit onto it (only with your explicit
+            approval for the full chain); default: stay on current branch
+  --base    PR base override (default: the branch you're on)
+
+Example:
+  open-memex submit 01ABC 01DEF`,
+
+  "pr-status": `Map the current branch's GitHub PR state back onto review_state:
+merged → published, approval → approved (approved_by = the reviewer),
+changes-requested → suggestion only (never auto-rejects).
+Each memory in the PR is mapped independently; a human rejection is never
+overwritten. Report-only by default.
+
+Usage: open-memex pr-status [--apply]
+
+Flags:
+  --apply   write the transitions locally (still never pushes)`,
+
+  reindex: `Rebuild the SQLite index from the markdown files.
+
+Usage: open-memex reindex`,
+
+  scopes: `List the known scopes (personal + project).
+
+Usage: open-memex scopes`,
+
+  migrate: `Move memories between scopes, or convert a legacy my-o-memory data dir.
+
+Usage: open-memex migrate [--from <key>] [--to <key>] [--dry-run] [--on-conflict newer|overwrite|skip]
+       open-memex migrate --to-v2 [--dry-run]
+
+Flags:
+  --from / --to   scope keys (default: current project → personal)
+  --dry-run       preview without moving anything
+  --on-conflict   newer (default), overwrite, or skip
+  --to-v2         convert a legacy my-o-memory data dir to the v2 layout
+
+Always preview with --dry-run first; nothing moves without confirmation.`,
+
+  mcp: `Start the stdio MCP server (the same server editors connect to).
+
+Usage: open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
+
+Flags:
+  --print-config   print the MCP client config instead of starting the server`,
+
+  init: `One-command project setup: writes the MCP config for your editor and the
+agent memory instructions. Existing files are merged, never clobbered.
+
+Usage: open-memex init [--client vscode|cursor|opencode|visualstudio]
+              [--instructions personal|project] [--force] [--yes]
+
+Flags:
+  --client        editor to configure (default: auto-detect)
+  --instructions  personal (default, ~/.copilot/copilot-instructions.md) or project
+  --force         overwrite existing config
+  --yes           accept all defaults, never prompt`,
+
+  config: `Show config, or set a key.
+
+Usage: open-memex config [set <key> <value>]
+
+Example:
+  open-memex config set sync.autoPull false`,
+
+  capture: `Preview what the keyword-capture watcher would extract from text.
+
+Usage: open-memex capture --dry-run "text"`,
+
+  doctor: `Environment health check: Node version, config source, scope resolution,
+storage writability, then boots a real MCP server and runs initialize +
+tools/list against it — all eleven tools must show up.
+
+Usage: open-memex doctor`,
+};
+
 function usage(exitCode = 1): never {
   console.log(`open-memex CLI
 
@@ -40,7 +223,7 @@ Usage:
   open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
   open-memex resolve [id-or-path]
   open-memex sync-status
-  open-memex submit <id...> [--onto <branch>] [--base <branch>]
+  open-memex submit <id...> [--branch <name>] [--base <branch>]
   open-memex pr-status [--apply]
   open-memex reindex
   open-memex scopes
@@ -79,7 +262,9 @@ the \`--from\` key when migrating.
 git remote after memories were already stored under the cwd-based key.
 \`migrate --to-v2\` converts v1 memory files to the v2 format (§19):
 user→personal scope rename, epoch→RFC 3339 times, priority→importance,
-type: instruction→role split. Always preview with --dry-run first.`);
+type: instruction→role split. Always preview with --dry-run first.
+
+Run \`open-memex <command> --help\` for details on a single command.`);
   process.exit(exitCode);
 }
 
@@ -204,6 +389,17 @@ async function main() {
     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")) {
+    const h = COMMAND_HELP[cmd];
+    if (h) {
+      console.log(`open-memex ${cmd}\n\n${h}`);
+      return;
+    }
+    usage(0);
+  }
+
   const cfg = loadConfig();
   const project = resolveProjectScope(process.cwd());
 
@@ -687,7 +883,7 @@ function positionalArgs(argv: string[]): string[] {
     if (ids.length === 0) usage();
     syncScope(project.key, "submit");
     try {
-      const r = submitMemories(ids, { onto: flags.onto, base: flags.base });
+      const r = submitMemories(ids, { branch: flags.branch, base: flags.base });
       for (const s of r.submitted) {
         console.log(`submitted ${s.id} → ${path.relative(process.cwd(), s.filePath)}  [${s.reviewState}]`);
       }

package/src/init.ts

@@ -70,17 +70,22 @@ You have a local memory MCP server (\`open-memex\`) with eleven tools:
 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, and when you finish a meaningful chunk of work, call
+- 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 approves, ask ONE follow-up: a separate memory-only branch/PR
-  (recommended), or fold the memories into the current branch alongside code?
-  A "yes, you do it" answer covers the whole chain — branch, local commit,
-  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.
-  Then call \`memory_submit\` with the approved ids (\`onto\` = current branch name
-  only for the fold-into-code path). It creates the branch, copies the drafts in
-  as \`proposed\`, commits locally, and prints the push + PR commands.
+- 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.
+- 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

package/src/mcp.ts

@@ -53,6 +53,39 @@ import {
 
 const SERVER_VERSION = "0.2.0-alpha";
 
+/**
+ * D26: session-start guidance delivered through the MCP handshake itself.
+ * The init-written instruction files only exist if the user ran
+ * `open-memex init --client`; the initialize `instructions` reach every MCP
+ * 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).
+
+- 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,
+  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.
+- 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.
+- Before asking the user about past decisions, conventions, or preferences they
+  may have told you before, call memory_search first.
+- 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.`;
+
 /** Adapt a framework-agnostic op result to an MCP tool response. */
 function toMcp(p: Promise<ToolResult>) {
   return p.then(
@@ -91,7 +124,10 @@ export async function runMcpServer() {
     };
   };
 
-  const server = new McpServer({ name: "open-memex", version: SERVER_VERSION });
+  const server = new McpServer(
+    { name: "open-memex", version: SERVER_VERSION },
+    { instructions: SERVER_INSTRUCTIONS },
+  );
 
   server.registerTool(
     "memory_add",

package/src/submit.ts

@@ -191,15 +191,19 @@ export function formatSyncStatus(st: SyncStatus): string {
 // ---------------------------------------------------------------------------
 
 export interface SubmitOptions {
-  /** Submit onto this branch instead of creating mem/sync-*. Must be the current branch. */
-  onto?: string;
-  /** PR base override (default: the branch we branched from). */
+  /** Create this branch and submit onto it. If omitted, submit stays on the
+      current branch — D36: no auto-created branches; branch creation is the
+      human's call (or the agent's, only with explicit approval). */
+  branch?: string;
+  /** PR base override (default: the branch the submit ran on). */
   base?: string;
 }
 
 export interface SubmitResult {
   branch: string;
   base: string;
+  /** true when --branch created a new branch for this submit */
+  createdBranch: boolean;
   submitted: Array<{ id: string; filePath: string; reviewState: ReviewState }>;
   /** already on the branch with identical content — outbox move completed */
   skippedIdentical: string[];
@@ -219,7 +223,8 @@ interface Validated {
 export function submitMemories(ids: string[], opts: SubmitOptions = {}): SubmitResult {
   if (ids.length === 0) fail("submit needs at least one memory id");
   const root = projectRoot();
-  // submit needs a git repo — the whole point is branch + commit.
+  // submit needs a git repo — the memories land in .ai/open-memex/ and are
+  // committed locally. Branch creation is never automatic (D36).
   git(root, ["rev-parse", "--git-dir"]);
 
   const scope = resolveProjectScope(root);
@@ -269,24 +274,25 @@ export function submitMemories(ids: string[], opts: SubmitOptions = {}): SubmitR
   }
 
   // 2. Resolve the target branch.
+  //    D36: submit never creates a branch on its own — it works on the branch
+  //    you're already on. Pass --branch <name> (explicitly) only when the user
+  //    approved the full chain (branch + push + PR).
   const startBranch = git(root, ["branch", "--show-current"]) || git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
-  let branch: string;
-  if (opts.onto) {
-    if (opts.onto !== startBranch) {
-      fail(`--onto ${opts.onto} is not the current branch (${startBranch || "(detached)"}). submit only targets the branch you're on.`);
-    }
-    branch = opts.onto;
-  } else {
-    const stamp = new Date().toISOString().replace(/[-:]/g, "").slice(0, 15);
-    branch = `mem/sync-${stamp}`;
+  let branch: string = startBranch;
+  let createdBranch = false;
+  if (opts.branch) {
+    branch = opts.branch;
     let n = 0;
+    let candidate = branch;
     while (true) {
-      const exists = git(root, ["branch", "--list", branch]);
+      const exists = git(root, ["branch", "--list", candidate]);
       if (!exists) break;
       n++;
-      branch = `mem/sync-${stamp}-${n}`;
+      candidate = `${branch}-${n}`;
     }
+    branch = candidate;
     git(root, ["checkout", "-b", branch]);
+    createdBranch = true;
   }
   const base = opts.base ?? startBranch;
   const author = currentAuthor();
@@ -348,7 +354,7 @@ export function submitMemories(ids: string[], opts: SubmitOptions = {}): SubmitR
     }
     // If we created the branch and never committed, remove it too — an
     // aborted submit leaves no trace.
-    if (!opts.onto) {
+    if (createdBranch) {
       try {
         git(root, ["checkout", "--quiet", startBranch]);
         git(root, ["branch", "--quiet", "-D", branch]);
@@ -399,13 +405,20 @@ export function submitMemories(ids: string[], opts: SubmitOptions = {}): SubmitR
     removed: 0,
     scanned: validated.length,
   });
+  // D36: no auto-branch — the commit sits on the branch you were already on.
+  // Next steps are printed, not run. For a separate memory PR, create a branch
+  // first (the commit comes along), then push + open the PR.
+  const branchCmd = `git checkout -b mem/sync-YYYYMMDD`;
   return {
     branch,
     base,
     submitted,
     skippedIdentical,
     committed,
+    createdBranch,
     pushCommand: `git push -u origin ${branch}`,
-    prCommand: `gh pr create --base ${base} --title "mem: review ${validated.length} ${validated.length === 1 ? "memory" : "memories"}" --body "Submitted from the open-memex outbox: ${ids8}."`,
+    prCommand: createdBranch
+      ? `gh pr create --base ${base} --title "mem: review ${validated.length} ${validated.length === 1 ? "memory" : "memories"}" --body "Submitted from the open-memex outbox: ${ids8}."`
+      : `${branchCmd}  # if you want a separate memory PR (else push ${branch} directly)\n  git push -u origin <new-branch> && gh pr create --base ${base} --title "mem: review ${validated.length}" --body "Submitted from the open-memex outbox: ${ids8}."`,
   };
 }

package/src/tools/ops.ts

@@ -51,9 +51,9 @@ 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.",
+    "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_submit:
-    "Move outbox drafts into a git branch for review: creates a branch (default mem/sync-*), copies the drafts into the repo memory dir as proposed, commits locally, and moves the outbox originals out. Prints the push and PR commands — those need the user's explicit approval and are never run automatically.",
+    "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:
@@ -125,14 +125,16 @@ export type MemoryStatusArgs = z.infer<z.ZodObject<typeof memoryStatusArgs>>;
 
 export const memorySubmitArgs = {
   ids: z.array(z.string().min(1)).min(1).describe("Outbox draft ids to submit."),
-  onto: z
+  branch: z
     .string()
     .optional()
-    .describe("Submit onto this branch instead of creating mem/sync-*. Must be the current branch (for folding memories into a code PR)."),
+    .describe(
+      "Create this branch and submit onto it. If omitted, submit stays on the current branch — branches are never auto-created. Only pass this when the user explicitly approved the full chain (branch + push + PR).",
+    ),
   base: z
     .string()
     .optional()
-    .describe("PR base branch override. Default: the branch the submit branched from."),
+    .describe("PR base branch override. Default: the branch the submit ran on."),
 };
 export type MemorySubmitArgs = z.infer<z.ZodObject<typeof memorySubmitArgs>>;
 
@@ -359,14 +361,15 @@ export async function statusMemories(): Promise<ToolResult> {
 }
 
 export async function submitMemoriesOp(args: MemorySubmitArgs): Promise<ToolResult> {
-  const r = submitMemories(args.ids, { onto: args.onto, base: args.base });
+  const r = submitMemories(args.ids, { branch: args.branch, base: args.base });
   const lines: string[] = [];
   for (const s of r.submitted) lines.push(`submitted ${s.id} [${s.reviewState}]`);
   for (const id of r.skippedIdentical) lines.push(`already on branch: ${id} (outbox copy removed)`);
-  lines.push(r.committed ? `committed on ${r.branch}.` : `nothing new to commit on ${r.branch}.`);
-  lines.push(`Next (needs the user's explicit approval — never run automatically):`);
+  lines.push(r.committed ? `committed on ${r.branch} (you are still on this branch).` : `nothing new to commit on ${r.branch}.`);
+  lines.push(`Next — ask the user: "want me to create a branch + push + open the PR, or will you handle it yourself?"`);
+  lines.push(`Never create branches, push, or open PRs without their explicit approval. If they handle it themselves, hand them these:`);
   lines.push(`  ${r.pushCommand}`);
-  lines.push(`  ${r.prCommand}`);
+  for (const l of r.prCommand.split("\n")) lines.push(`  ${l}`);
   return { title: `memory: submitted ${r.submitted.length}`, output: lines.join("\n") };
 }