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

package/AGENTS.md

@@ -29,6 +29,7 @@ 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 -- propose <id...> --to project [--local-approve]  # copy personal → project outbox (batch OK)

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
@@ -352,8 +358,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,6 +281,10 @@ project 草稿先住在 **appdata outbox**（git 看不见、跟分支无关）
 点名批准的草稿，才会被移入 `<repo>/.ai/open-memex/`，之后随分支和 PR 走。
 没经过你点名，什么都不会动。
 
+在接了 MCP 服务器的 AI 对话里，直接说 **"同步记忆"**（或 "sync memory"）——
+agent 会查状态、把 outbox 草稿逐条摘要、问你同步哪几条。agent 也会在新对话
+开始和任务检查点主动提这件事。
+
 ```sh
 open-memex sync-status
 # 看索引上次同步的时间和触发方、outbox（待同步）、repo 里的评审状态
@@ -344,7 +349,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 a git branch for review: creates a branch
+(default mem/sync-*), copies the drafts into the repo memory dir as proposed
+(local-approved copies keep their approval), commits locally, and moves the
+outbox originals out. Prints the push and PR commands — those need your
+explicit approval and are never run automatically.
+
+Usage: open-memex submit <id...> [--onto <branch>] [--base <branch>]
+
+Flags:
+  --onto   submit onto the current branch instead of creating mem/sync-*
+  --base   base branch for the PR suggestion (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
 
@@ -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

package/dist/init.js

@@ -62,6 +62,9 @@ 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
   \`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, 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,

package/dist/mcp.js

@@ -26,6 +26,32 @@ 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, 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.
+- When you finish a meaningful chunk of work, call memory_status again as a checkpoint.
+- 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 +83,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/tools/ops.js

@@ -25,7 +25,7 @@ export const TOOL_DESCRIPTIONS = {
     memory_list: "List memories in a scope, newest first. Useful for browsing what is remembered, or verifying that a save landed.",
     memory_supersede: "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
     memory_forget: "Delete a memory by id. Use when the user asks to forget something.",
-    memory_status: "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start and at task checkpoints, then ask the user which drafts to sync.",
+    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 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_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.",

package/docs/V2-DESIGN.md

@@ -699,6 +699,27 @@ 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.*
+- **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.4",
   "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 a git branch for review: creates a branch
+(default mem/sync-*), copies the drafts into the repo memory dir as proposed
+(local-approved copies keep their approval), commits locally, and moves the
+outbox originals out. Prints the push and PR commands — those need your
+explicit approval and are never run automatically.
+
+Usage: open-memex submit <id...> [--onto <branch>] [--base <branch>]
+
+Flags:
+  --onto   submit onto the current branch instead of creating mem/sync-*
+  --base   base branch for the PR suggestion (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
 
@@ -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());
 

package/src/init.ts

@@ -73,6 +73,9 @@ 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
   \`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, 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,

package/src/mcp.ts

@@ -53,6 +53,33 @@ 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, 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.
+- When you finish a meaningful chunk of work, call memory_status again as a checkpoint.
+- 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 +118,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/tools/ops.ts

@@ -51,7 +51,7 @@ export const TOOL_DESCRIPTIONS = {
     "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
   memory_forget: "Delete a memory by id. Use when the user asks to forget something.",
   memory_status:
-    "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start and at task checkpoints, then ask the user which drafts to sync.",
+    "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.",
   memory_propose: