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

package/AGENTS.md

@@ -31,7 +31,7 @@ npm run typecheck                                    # tsc --noEmit — the only
 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)
@@ -140,3 +140,6 @@ hold `V2` and `V2/…` simultaneously. Full rules: `CONTRIBUTING.md`.
   in-development version. New features on a dev branch bump the minor on the alpha
   line (`0.3.0` → `0.4.0-alpha.1`); fixes bump the patch (`-alpha.1` → `-alpha.2`).
   The bump goes in the same commit as the feature, never as an afterthought.
+  The version number serves the publish: no publish, no mandatory bump. But once a
+  version has been pushed to the remote (shared), later changes must bump — two
+  different code states must never share one version number.

package/README.md

@@ -295,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:
@@ -373,10 +375,13 @@ server with cwd set to your project root (`init` handles this for you).
 **In progress — `0.4.0`:** team sync — shared memory via git: appdata draft
 outbox → `sync-status` → `submit` (local branch+commit, push/PR on your Yes)
 → `promote` / `resolve` review workflow, in-repo `.ai/open-memex/` dir, 1–2
-colleague pilot.
+colleague pilot; capture — §3.5 checkpoint distillation in MCP handshake +
+init instructions (agent proposes 1–3 captures, human decides).
 
 **Coming — `0.3.0` (stable):** org layer — org memory repo, curator convention,
-distill-to-AGENTS.md assist.
+distill-to-AGENTS.md assist, `export`/`import` archive for user portability
+(Markdown + manifest, no walled garden; private excluded by default,
+`-a`/`--all` for full migration).
 
 **Future (signal-gated, no version committed):** native agent plugins (Claude Code /
 Codex hooks as enhancement paths over the same MCP tools); local embeddings as a

package/README.zh-CN.md

@@ -291,11 +291,13 @@ open-memex sync-status
 # （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]
@@ -363,10 +365,13 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 **进行中 —— `0.4.0`：** 团队同步——用 git 做共享记忆：appdata 草稿箱 →
 `sync-status` → `submit`（本地分支+commit，push/PR 拿你的 Yes 才做）
 → `promote` / `resolve` 评审工作流、仓库内 `.ai/open-memex/` 目录，
-找 1–2 个同事做 pilot。
+找 1–2 个同事做 pilot；捕获——§3.5 检查点蒸馏写进 MCP 握手指令和
+init 指令文件（agent 提议 1–3 条，人来定）。
 
 **Coming —— `0.3.0`（稳定版）：** 组织层——组织记忆仓库、
-curator 约定、distill-to-AGENTS.md 辅助。
+curator 约定、distill-to-AGENTS.md 辅助、`export`/`import` 归档
+（Markdown + manifest，不造围墙花园，用户可带走；
+private 默认不导出，`-a`/`--all` 全量迁移）。
 
 **未来（看信号再定，不承诺版本）：** 原生 agent 插件
 （Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；

package/dist/cli.js

@@ -106,17 +106,17 @@ 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.
+    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...> [--onto <branch>] [--base <branch>]
+Usage: open-memex submit <id...> [--branch <name>] [--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)
+  --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`,
@@ -195,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
@@ -811,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/doctor.js

@@ -116,7 +116,7 @@ function mcpCheck() {
                         name,
                         ok: missing.length === 0,
                         detail: missing.length === 0
-                            ? `handshake OK, 5 tools listed (${names.join(", ")})`
+                            ? `handshake OK, ${names.length} tools listed (${names.join(", ")})`
                             : `missing tools: ${missing.join(", ")}`,
                     });
                 }

package/dist/init.js

@@ -47,6 +47,14 @@ You have a local memory MCP server (\`open-memex\`) with eleven tools:
 - 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.
@@ -59,20 +67,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 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,
-  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 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

@@ -1,9 +1,10 @@
 /**
  * open-memex generic MCP server (stdio transport).
  *
- * Exposes the same five memory tools as the opencode plugin
+ * Exposes the memory tools as the opencode plugin
  * (memory_add / memory_search / memory_list / memory_supersede /
- * memory_forget) over the Model Context Protocol, so any MCP client —
+ * memory_forget, plus memory_status / memory_submit / memory_propose /
+ * memory_promote / memory_resolve / memory_pr_status) over the Model Context Protocol, so any MCP client —
  * VS Code Copilot Chat, Cursor, Claude Code, etc. — can use open-memex
  * without a host-specific plugin.
  *
@@ -19,13 +20,28 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { z } from "zod";
 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";
-const SERVER_VERSION = "0.2.0-alpha";
+// 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.
+const SERVER_VERSION = (() => {
+    try {
+        const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0-unknown";
+    }
+    catch {
+        return "0.0.0-unknown";
+    }
+})();
 /**
  * D26: session-start guidance delivered through the MCP handshake itself.
  * The init-written instruction files only exist if the user ran
@@ -37,16 +53,31 @@ const SERVER_INSTRUCTIONS = `You are connected to an open-memex local memory MCP
 (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.
+- 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.
-- When you finish a meaningful chunk of work, call memory_status again as a checkpoint.
+  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.
+- 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.
 - 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

package/dist/store/markdown.js

@@ -3,19 +3,21 @@ import path from "node:path";
 import { randomBytes } from "node:crypto";
 import yaml from "js-yaml";
 import { memoriesDirFor, memoriesDirPath, inRepoMemoriesDirPath, } from "../paths.js";
-/** v2 content-kind taxonomy (V2-DESIGN §3.1). `type` = what the memory IS. */
+/** v2 content-kind taxonomy (V2-DESIGN §3.1). `type` = what the memory IS
+ *  (single-valued, drives behavior). D41: 11 types; `warning`→`gotcha`,
+ *  `workflow`→`howto`, `incident`→`lesson`, `architecture`→`knowledge`. */
 export const MEMORY_TYPE_TAXONOMY = [
-    "preference",
     "fact",
+    "preference",
     "decision",
-    "lesson",
-    "warning",
-    "workflow",
-    "architecture",
     "constraint",
     "todo",
     "knowledge",
+    "howto",
+    "gotcha",
+    "lesson",
     "observation",
+    "reference",
 ];
 const TAXONOMY = new Set(MEMORY_TYPE_TAXONOMY);
 /** Defensive parse: malformed entries are dropped, never fatal. */

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

@@ -26,7 +26,7 @@ export const TOOL_DESCRIPTIONS = {
     memory_supersede: "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
     memory_forget: "Delete a memory by id. Use when the user asks to forget something.",
     memory_status: "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start and at task checkpoints, then ask the user which drafts to sync. The user may also trigger this flow by saying 'sync memory' (or '同步记忆').",
-    memory_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_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.",
@@ -42,9 +42,13 @@ export const memoryAddArgs = {
     type: z
         .enum(MEMORY_TYPE_TAXONOMY)
         .optional()
-        .describe("Category of memory. Default: note."),
+        .describe("Category of memory. Default: fact."),
     scope: scopeArg,
     tags: z.array(z.string()).optional().describe("Optional tags for filtering."),
+    source: z
+        .string()
+        .optional()
+        .describe("Where this memory came from. Default: tool. Pass 'inference' for agent-proposed captures at checkpoints (V2-DESIGN §3.5)."),
 };
 export const memorySearchArgs = {
     query: z
@@ -78,14 +82,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."),
@@ -161,7 +165,7 @@ export async function addMemory(getScope, cfg, args) {
     const fm = buildFrontmatter(s, {
         type: args.type ?? "fact",
         tags: args.tags ?? [],
-        source: "tool",
+        source: args.source ?? "tool",
     });
     const { filePath } = writeMemoryFile(fm, redacted);
     const mf = readMemoryFile(filePath);
@@ -260,16 +264,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

@@ -25,6 +25,12 @@ Decisions log; Prior Art; solo-dev adoption path.
 6. **Adapters translate; they never implement memory logic.** All memory logic lives in Core.
 7. **Memory is the entrance of knowledge, not its final form.** Terminal states are docs / ADRs /
    AGENTS.md instructions — memory is how knowledge gets captured and found.
+8. **Distill conversations; do not archive them.** The default unit of memory is the useful
+   conclusion from a conversation, not the full transcript: what was learned, how it was resolved,
+   and where the authoritative source lives.
+9. **Portable second brain, not a walled garden.** Long-form personal notes are valid memories when
+   the user explicitly saves them; Markdown keeps them readable, exportable, and movable to other
+   tools or machines.
 
 ---
 
@@ -40,6 +46,9 @@ Decisions log; Prior Art; solo-dev adoption path.
 - **MCP is an interface, not the identity.** MCP / CLI / REST / SDK are access layers over the protocol,
   so the project is never locked to one transport or one agent tool (opencode, VS Code Copilot, Cursor,
   Claude Code, Windsurf, …).
+- **Second-brain lens:** for individuals, OpenMemex can also be a local Markdown second brain for
+  AI-assisted work — similar in spirit to users asking AI to save notes into Obsidian or Notion, but
+  with agent recall, scopes, review, and redaction built in from the start.
 - **Company lens:** at organizational scale the same pain is tribal knowledge — senior engineers'
   hard-won experience evaporates when they move on, and every incident gets re-debugged by someone
   new. The current phase therefore prioritizes *capture*: valuable knowledge must land in memory
@@ -132,13 +141,37 @@ canonical_ref: docs/adr-003.md       # memory holds a SUMMARY; the doc is canoni
 
 ### 3.1 Type taxonomy (content kind)
 
-`preference` `fact` `decision` `lesson` `warning` `workflow` `architecture` `constraint`
-`todo` `knowledge` `observation`
+`fact` `preference` `decision` `constraint` `todo` `knowledge` `howto` `gotcha`
+`lesson` `observation` `reference`
 
-`type` describes **what the content is**. `role` describes **how it may be used**.
+`type` describes **what the content is** — single-valued, and it drives behavior
+(lifecycle, review, rendering, retrieval). `role` describes **how it may be used**.
 A `decision` with `role: knowledge` is retrievable history. Only `role: instruction` may enter
 instruction context. (Separation adopted from review: mixing usage semantics into `type` was a design smell.)
 
+One-line definitions:
+
+- `fact` — a verifiable atomic statement (timezone, version number, path, account).
+- `preference` — user likes, dislikes, working style.
+- `decision` — a choice made + why; participates in supersede chains.
+- `constraint` — a hard rule that must not be violated (release process, permission boundaries).
+- `todo` — an actionable item with completion state.
+- `knowledge` — declarative knowledge (how a system works, concept explanations).
+- `howto` — steps to accomplish X.
+- `gotcha` — a pitfall: don't do X because Y.
+- `lesson` — a takeaway from experience, including incident postmortems (the incident id goes in `tags`).
+- `observation` — noticed but not yet distilled.
+- `reference` — a pointer to the authoritative doc via `canonical_ref`; the memory holds the summary.
+
+A type earns its place only if the system treats it differently. If two candidates
+share lifecycle, retrieval, and rendering, the loser becomes a tag. (D41 merged
+`warning`→`gotcha`, `workflow`→`howto`, `incident`→`lesson`, `architecture`→`knowledge`.)
+
+`tags` are retrieval hints, not a second type system: `type` says what the memory is, while tags say
+which topics, tools, subsystems, paths, or incidents it relates to. Write paths should preserve
+human-provided tags and may suggest simple normalized tags (for example `vscode`, `mcp`, `windows`,
+`auth`, `onboarding`) to improve search without changing memory semantics.
+
 ### 3.2 Iron rules
 
 - **Iron rule 1 — the instruction gate:** only memories with `role: instruction`
@@ -170,6 +203,34 @@ Content hash + fuzzy match against existing memories. A superseding write does *
 the old memory becomes `status: superseded` with `superseded_by` pointing forward. History preserved;
 queries rank `active` first.
 
+### 3.5 Conversation distillation
+
+OpenMemex does **not** store raw AI chat transcripts by default. A captured memory should usually be
+a short, human-approved artifact distilled from the conversation: the final conclusion, important
+facts, why the answer matters later, and how the issue was resolved. Good distilled memory candidates
+answer some combination of:
+
+- What did we learn or decide?
+- What solved the problem, including key commands, files, links, or steps?
+- What mistake or gotcha should the next developer avoid?
+- Which scope owns it: `personal`, `project`, or future `org`?
+- If the information already exists in project docs, where is the authoritative doc?
+
+If stable knowledge already lives in a project document, prefer a `type: reference` memory with
+`canonical_ref` pointing at that document over duplicating the full content. Memory should help the
+agent find and apply authoritative docs, not become an outdated second copy of them.
+
+Model-suggested captures use `source: inference` and should default to reviewable draft state. The
+agent may propose 1-3 distilled memories at checkpoints or task end, but humans decide whether to
+save them and which scope they belong to. The product goal is remembering the right conclusion at
+the right scope, not remembering everything.
+
+Long-form notes are still valid when the user explicitly asks to save a long note, write-up, meeting
+summary, research log, or troubleshooting record. In that case OpenMemex behaves like a Markdown
+second-brain target: store the note as user-authored content, preserve the body, tag it for retrieval,
+and keep the same scope/privacy rules. The distinction is intent: implicit/model-suggested capture
+distills; explicit "save this note" may preserve long-form text.
+
 ---
 
 ## 4. Scopes, Visibility & Namespaces
@@ -294,11 +355,21 @@ instructions are never candidates.)
 | Implicit (opt-in) | end-of-session "should I remember X?"; implicit captures default to `confidence: low` and appear in a separate list view for batch cleanup (regret window). |
 | Redaction (hard) | `<private>…</private>` stripped; secret patterns are **masked in place** (first 4 chars kept, rest → `x`) and the write proceeds (D14); pre-commit hook scans shared scopes. |
 
+**Scope routing on capture:** when the user says "save", "remember", or "note this" without an
+explicit scope, the agent should infer ownership from content and current context. Project-specific
+knowledge (repo commands, architecture, code paths, product decisions, team conventions) routes to
+`project`; personal preferences, private working notes, cross-project habits, or content unrelated to
+the current repo routes to `personal`. Ambiguous captures should ask one short clarification instead
+of guessing. `org` capture remains future/curated; a single user's chat never writes org memory
+directly.
+
 ---
 
 ## 9. Sync
 
-- **Git is transport; the local SQLite index is the query layer.** Retrieval never walks git.
+- **Git is a transport, not the product boundary; the local SQLite index is the query layer.**
+  Retrieval never walks git. Git/GitHub is the default sharing provider because it gives teams branch,
+  PR, review, and audit semantics they already trust, but Core must remain provider-agnostic.
 - one-memory-one-file ⇒ concurrent edits almost never conflict.
 - **Pull is explicit** (`open-memex pull`), never automatic on session start — no surprise context changes.
   `pull` = `fetch` + fast-forward only; never auto-commit/push (hard rule for enterprise environments).
@@ -314,6 +385,13 @@ instructions are never candidates.)
 - **Git unavailable:** projects without git (or with unreachable remotes) remain fully usable.
   `personal` scope works everywhere; `project` scope degrades to local-only and `open-memex status`
   annotates it as such. Sync commands fail with a clear message, never with a broken state.
+- **Portability:** because Markdown is the source of truth, memories should be exportable without
+  depending on git. A future `open-memex export` command can archive selected scopes/types/tags into a
+  portable zip/tar bundle (markdown + manifest) for moving to another computer or importing into
+  another application. Export excludes `visibility: private` memories by default; `--all` / `-a`
+  includes everything, for a full personal migration to a new machine. API-backed exporters/providers (Notion, Obsidian-compatible vaults, internal
+  knowledge systems, enterprise stores) are extension paths over the same memory files and admission
+  rules, not separate products.
 
 ---
 
@@ -457,9 +535,10 @@ requirement: personal data never touches third-party services). Benchmarks to tr
 
 (Star counts / funding as of Sep 2026 — re-verify before quoting publicly.)
 - **Phase 3 — Org layer.** Org memory repo · curator convention · `examples/remote-server/` ·
-  distill-to-AGENTS.md assist.
+  distill-to-AGENTS.md assist · export/import archive command for user portability.
 - **Phase 4 — Future, signal-gated.** Cloud `RemoteProvider` customization only on: multi-private-repo
-  sharing needs, fine-grained ACL, audit/compliance mandates.
+  sharing needs, fine-grained ACL, audit/compliance mandates · optional API-backed exporters/providers
+  for enterprise knowledge systems.
 
 ## 19. Migration v1 → v2
 
@@ -714,12 +793,82 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   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.*
+- **D37** — Conversation distillation is the memory unit; transcript storage is
+  not the default. Capture should preserve the useful conclusion from a human/AI
+  session — what was learned, what resolved the issue, what should be avoided,
+  and where the authoritative doc lives — as a short reviewable memory. If the
+  knowledge already exists in docs, store a `reference` memory with
+  `canonical_ref` instead of duplicating the doc. Tags are retrieval hints, not
+  content kinds: `type` classifies the memory, tags describe topics/tools/paths.
+  *Rationale: full chat logs are noisy, harder to review, and riskier for
+  privacy; the value is remembering the right conclusion at the right scope,
+  with enough context for the next human or AI session. Approved 2026-09-28.*
+- **D38** — OpenMemex supports a Markdown second-brain use case while keeping
+  distillation as the default for implicit/model-suggested capture. If the user
+  explicitly asks to save a long note, meeting summary, troubleshooting record,
+  or write-up, preserve it as user-authored Markdown with tags and normal
+  scope/privacy rules. Git/GitHub sync is the default team-sharing provider, not
+  the product boundary: future export/import archives and API-backed providers
+  may move the same markdown memories to other computers, applications, or
+  enterprise systems. For generic "save/remember/note this" requests, the agent
+  routes project-specific knowledge to `project`, personal or repo-unrelated
+  knowledge to `personal`, and asks one clarification if ambiguous; `org` remains
+  curated/future, never a direct single-user chat write. *Rationale: users also
+  want a local AI-assisted second brain, but portability and ownership must stay
+  explicit; sharing mechanisms should be provider choices over the same memory
+  model, not the identity of the product. Approved 2026-09-28.*
+- **D39** — `type` and `tags` are complementary axes, not alternatives. `type` is
+  single-valued: what the memory IS — it drives behavior (lifecycle, review,
+  rendering, retrieval: a `todo` can be completed, a `reference` resolves
+  `canonical_ref`, a `decision` participates in supersede chains). `tags` are
+  multi-valued: what the memory is ABOUT — pure retrieval hints
+  (topics, tools, subsystems, paths, incidents). *Rationale: without type the
+  system cannot tell "a todo I must do" from "a fact I must know" even when both
+  are tagged `auth`; without tags, cross-cutting retrieval ("everything about
+  onboarding") would need a combinatorial type explosion. Type answers "how do I
+  handle this?", tags answer "how do I find this?". Approved 2026-09-28.*
+- **D40** — `open-memex export` excludes `visibility: private` memories by
+  default; `--all` / `-a` includes everything, for a full personal migration to
+  a new machine. *Rationale: the safe default protects privacy; the escape hatch
+  keeps the "no walled garden" promise — the user can always take everything
+  with them. Approved 2026-09-28.*
+- **D42** — §3.5 checkpoint distillation is taught in the MCP handshake
+  instructions (`src/mcp.ts` `SERVER_INSTRUCTIONS`) and the `init`-written
+  instruction files (`src/init.ts` `INSTRUCTIONS`): at checkpoints the agent
+  DISTILLs the session and proposes 1–3 short memories (conclusion, not
+  transcript); nothing is saved without user approval. Approved captures are
+  saved via `memory_add` with the new optional `source` param set to
+  `"inference"` (default `"tool"`). *Rationale: closes the 0.4.0 TODO from D41 —
+  the design's capture loop now reaches the agent. Implemented 2026-09-29.*
+- **D41** — The type taxonomy is reconciled to 11 types with one-line definitions
+  (§3.1): `fact` `preference` `decision` `constraint` `todo` `knowledge` `howto`
+  `gotcha` `lesson` `observation` `reference`. Merged away: `warning`→`gotcha`,
+  `workflow`→`howto`, `incident`→`lesson` (incident id goes in `tags`),
+  `architecture`→`knowledge` (tag `architecture`). *Rationale: a type earns its
+  place only if the system treats it differently (lifecycle, retrieval,
+  rendering); otherwise it is a tag. Fifteen types blur classification and hurt
+  agent accuracy — eleven keeps each type's behavioral slot distinct. `lesson`
+  is deliberately broader than `incident`: a postmortem's shape (timeline, root
+  cause, actions) is a template concern, not a type. Code
+  `MEMORY_TYPE_TAXONOMY` updated to match. Approved 2026-09-28.*
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.4.0-alpha.4",
+  "version": "0.4.0-alpha.7",
   "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

@@ -124,17 +124,17 @@ 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.
+  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...> [--onto <branch>] [--base <branch>]
+Usage: open-memex submit <id...> [--branch <name>] [--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)
+  --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`,
@@ -223,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
@@ -883,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/doctor.ts

@@ -134,7 +134,7 @@ function mcpCheck(): Promise<Check> {
             ok: missing.length === 0,
             detail:
               missing.length === 0
-                ? `handshake OK, 5 tools listed (${names.join(", ")})`
+                ? `handshake OK, ${names.length} tools listed (${names.join(", ")})`
                 : `missing tools: ${missing.join(", ")}`,
           });
         }

package/src/init.ts

@@ -58,6 +58,14 @@ You have a local memory MCP server (\`open-memex\`) with eleven tools:
 - 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.
@@ -70,20 +78,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 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,
-  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 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

@@ -1,9 +1,10 @@
 /**
  * open-memex generic MCP server (stdio transport).
  *
- * Exposes the same five memory tools as the opencode plugin
+ * Exposes the memory tools as the opencode plugin
  * (memory_add / memory_search / memory_list / memory_supersede /
- * memory_forget) over the Model Context Protocol, so any MCP client —
+ * memory_forget, plus memory_status / memory_submit / memory_propose /
+ * memory_promote / memory_resolve / memory_pr_status) over the Model Context Protocol, so any MCP client —
  * VS Code Copilot Chat, Cursor, Claude Code, etc. — can use open-memex
  * without a host-specific plugin.
  *
@@ -19,6 +20,9 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { loadConfig } from "./config.ts";
 import { resolveProjectScope, PERSONAL_SCOPE, type Scope } from "./scope.ts";
@@ -51,7 +55,18 @@ import {
   type ToolResult,
 } from "./tools/ops.ts";
 
-const SERVER_VERSION = "0.2.0-alpha";
+// 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.
+const SERVER_VERSION: string = (() => {
+  try {
+    const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0-unknown";
+  } catch {
+    return "0.0.0-unknown";
+  }
+})();
 
 /**
  * D26: session-start guidance delivered through the MCP handshake itself.
@@ -64,16 +79,31 @@ const SERVER_INSTRUCTIONS = `You are connected to an open-memex local memory MCP
 (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.
+- 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.
-- When you finish a meaningful chunk of work, call memory_status again as a checkpoint.
+  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.
+- 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.
 - 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

package/src/store/markdown.ts

@@ -8,19 +8,21 @@ import {
   inRepoMemoriesDirPath,
 } from "../paths.ts";
 
-/** v2 content-kind taxonomy (V2-DESIGN §3.1). `type` = what the memory IS. */
+/** v2 content-kind taxonomy (V2-DESIGN §3.1). `type` = what the memory IS
+ *  (single-valued, drives behavior). D41: 11 types; `warning`→`gotcha`,
+ *  `workflow`→`howto`, `incident`→`lesson`, `architecture`→`knowledge`. */
 export const MEMORY_TYPE_TAXONOMY = [
-  "preference",
   "fact",
+  "preference",
   "decision",
-  "lesson",
-  "warning",
-  "workflow",
-  "architecture",
   "constraint",
   "todo",
   "knowledge",
+  "howto",
+  "gotcha",
+  "lesson",
   "observation",
+  "reference",
 ] as const;
 
 const TAXONOMY = new Set<string>(MEMORY_TYPE_TAXONOMY);

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

@@ -53,7 +53,7 @@ export const TOOL_DESCRIPTIONS = {
   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.",
+    "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:
@@ -77,9 +77,15 @@ export const memoryAddArgs = {
   type: z
     .enum(MEMORY_TYPE_TAXONOMY)
     .optional()
-    .describe("Category of memory. Default: note."),
+    .describe("Category of memory. Default: fact."),
   scope: scopeArg,
   tags: z.array(z.string()).optional().describe("Optional tags for filtering."),
+  source: z
+    .string()
+    .optional()
+    .describe(
+      "Where this memory came from. Default: tool. Pass 'inference' for agent-proposed captures at checkpoints (V2-DESIGN §3.5).",
+    ),
 };
 export type MemoryAddArgs = z.infer<z.ZodObject<typeof memoryAddArgs>>;
 
@@ -125,14 +131,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>>;
 
@@ -237,7 +245,7 @@ export async function addMemory(
   const fm = buildFrontmatter(s, {
     type: args.type ?? "fact",
     tags: args.tags ?? [],
-    source: "tool",
+    source: args.source ?? "tool",
   });
   const { filePath } = writeMemoryFile(fm, redacted);
   const mf = readMemoryFile(filePath);
@@ -359,14 +367,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") };
 }