open-memex 0.4.0-alpha.7 → 0.4.0

package/AGENTS.md

@@ -31,6 +31,11 @@ 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 -- pull                                          # fetch + fast-forward only (explicit; diverged = clean failure, never force-merge)
+npm run cli -- push                                          # push current branch to remote (explicit only; open-memex never auto-pushes)
+npm run cli -- export [--scope project|personal|both] [--all] [-o <file>]  # portable .tar.gz bundle (markdown + manifest); private excluded unless --all
+npm run cli -- import <bundle.tar.gz> [--dry-run]               # restore: personal → personal dir, project → outbox re-keyed; conflicts reported, never overwritten
+npm run cli -- distill-agents [--type t1,t2] [-o <file>]         # propose an AGENTS.md snippet from project memories (assist only; you merge by hand)
 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)

package/README.md

@@ -1,15 +1,77 @@
 # open-memex
 
+[![npm version](https://img.shields.io/npm/v/open-memex.svg)](https://www.npmjs.com/package/open-memex)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
+
 [中文文档](./README.zh-CN.md)
 
 Local-first persistent memory for AI coding agents: an [opencode](https://opencode.ai) plugin
 plus a generic MCP server (VS Code Copilot, Cursor, Claude Code, Visual Studio, …).
 
+## Why open-memex?
+
+Engineering knowledge lives in two places: the code, and people's heads.
+Every new AI coding session starts from zero — the same project context gets
+explained again, the same gotchas get rediscovered, the same incident lessons
+fade when the chat ends.
+
+open-memex captures the part worth remembering — the decision, the constraint,
+the lesson — as reviewable Markdown, and injects it back into the next session
+automatically.
+
+> No capture, nothing to inherit.
+
+It also complements agentic development workflows (spec-driven development,
+plan/implement/verify loops): plans produce decisions, verification produces
+rules — open-memex is the memory layer that keeps them across sessions instead
+of re-deriving them on every run.
+
+## How it compares
+
+| | open-memex | Cloud memory services | Wiki / docs portal | Chat history |
+|---|---|---|---|---|
+| Data location | Your machine + your repos | Vendor servers | Central server | Gone when the chat ends |
+| Review before sharing | Yes — outbox + PR | Varies | Yes | No |
+| Agent recall | Session-start injection + search | API calls | Manual lookup | No |
+| Human-readable | Plain Markdown files | Dashboard / API | Yes | No |
+
 - **Markdown files** as the source of truth (human-editable, git-friendly)
 - **SQLite FTS5** as a rebuildable index (BM25 keyword search, via `better-sqlite3`)
 - **Zero cloud**, zero account, zero third-party API
 - Loads directly under opencode's embedded Bun runtime; CLI and MCP server run under Node — no build step in development (the published npm package ships pre-compiled JS), no Bun install
 
+## Architecture
+
+```text
+                        ┌──────────────────┐
+                        │     AI agent     │
+                        │ Copilot / Cursor │
+                        │ Claude / opencode│
+                        └────────┬─────────┘
+                                 │ MCP (stdio) — 11 tools
+                                 │ session-start injection
+                        ┌────────▼─────────┐
+                        │    open-memex    │
+                        │    MCP server    │
+                        └──┬────────────┬──┘
+                           │            │
+              ┌────────────▼───┐  ┌─────▼──────────┐
+              │ Markdown files │  │ SQLite FTS5    │
+              │ source of truth│  │ rebuildable    │
+              │ local-first    │  │ index (BM25)   │
+              └─────────────┬──┘  └────────────────┘
+                            │ submit (explicit,
+                            │  local commit)
+                    ┌───────▼────────┐
+                    │    Git repo    │
+                    │ .ai/open-memex/│
+                    │  PR-reviewed   │
+                    │  team memory   │
+                    └────────────────┘
+
+personal scope: this machine only — never synced, never enters a repo.
+```
+
 ## Installation
 
 ### Requirements
@@ -18,18 +80,36 @@ plus a generic MCP server (VS Code Copilot, Cursor, Claude Code, Visual Studio,
 
 ### Step 1 — Install the CLI
 
-**npm (recommended):**
+#### Stable vs alpha
+
+**Stable** (recommended for most users) — the `latest` tag:
 
 ```sh
 npm install -g open-memex
 ```
 
-This installs the `0.3.0` stable release.
+This installs the `0.4.0` stable release.
+
+**Alpha** (bleeding edge, for testers) — the `alpha` tag:
+
+```sh
+npm install -g open-memex@alpha
+```
+
+See what's published:
+
+```sh
+npm view open-memex version         # latest stable
+npm view open-memex@alpha version   # latest alpha
+```
+
+Alpha builds may have rough edges — bug reports are welcome.
 
 **No install — run via npx:**
 
 ```sh
-npx -y open-memex <command>   # e.g. npx -y open-memex init --client vscode
+npx -y open-memex <command>         # e.g. npx -y open-memex init --client vscode
+npx -y open-memex@alpha <command>  # alpha line, no install
 ```
 
 **From source** (bleeding edge, `V2-dev-p2` branch):
@@ -185,6 +265,62 @@ storage writability, then boots a real MCP server and runs `initialize` +
   4 characters kept, the rest replaced with `x` — and the memory is saved.
   Preview what a message would capture with `open-memex capture --dry-run "…"`.
 
+## Memory types
+
+Eleven types — `type` says what the memory is, `tags` say what it's about:
+
+| Type | Captures |
+|---|---|
+| `fact` | A stable true statement about the project or world |
+| `preference` | How someone likes things done |
+| `decision` | A choice that was made — the why and the trade-off |
+| `constraint` | A rule that must not be violated |
+| `todo` | A commitment to do something later |
+| `knowledge` | Durable domain or architecture knowledge |
+| `howto` | A procedure that worked |
+| `gotcha` | A trap to avoid |
+| `lesson` | What an incident or mistake taught us |
+| `observation` | Something noticed, not yet a conclusion |
+| `reference` | A pointer to the authoritative doc (no copying) |
+
+## Team memory workflow
+
+Personal notes stay private. Project knowledge follows an explicit, reviewable
+pipeline — nothing is shared automatically:
+
+```
+capture → outbox (draft, local) → submit → repo (.ai/open-memex/) → PR review → published → recall
+```
+
+1. **Capture** — save decisions, gotchas, lessons as drafts during normal work.
+2. **Review** — drafts wait in a local outbox; `sync-status` (or saying
+   "sync memory" in chat) shows what's pending.
+3. **Submit** — you name the memories; they move into `<repo>/.ai/open-memex/`
+   with a local commit. open-memex never auto-pushes.
+4. **PR review** — memories are plain Markdown; reviewers approve, request
+   changes, or reject through the normal branch/PR process (`promote`,
+   `pr-status`, `resolve`).
+5. **Recall** — published memories are injected at session start and searchable
+   on demand, for humans and agents alike.
+
+Reviewer convention: [docs/CURATOR.md](./docs/CURATOR.md).
+
+## Security & data
+
+- **Local-first:** everything lives on your machine (`%APPDATA%\open-memex` /
+  `~/.local/share/open-memex`) plus the repos you choose. Zero cloud calls,
+  zero accounts, zero third-party APIs, zero telemetry.
+- **Secrets stay out:** `<private>…</private>` spans are stripped; detected API
+  keys/tokens are masked in place before saving. Preview with
+  `open-memex capture --dry-run "…"`.
+- **Personal never syncs:** the `personal` scope is this machine only — excluded
+  from export by default and can never enter a repo.
+- **Auditable sharing:** team memories move only by explicit `submit`, travel
+  through branch/PR review, and every `promote` transition is appended to the
+  memory's `review_history` (who / when / why).
+- **You own the files:** Markdown is the source of truth — inspect, edit, or
+  delete anything by hand; the SQLite index rebuilds from the files.
+
 ## Scopes
 
 - **project** — scoped to the current repo (keyed off the git origin URL hash, or the cwd if no remote). Default for new memories.
@@ -312,6 +448,37 @@ open-memex pr-status [--apply]
 # changes-requested → suggestion only. Report by default; --apply performs
 # the mapped transitions locally (no push).
 
+open-memex pull
+# pull shared memories from the git remote: fetch + fast-forward ONLY.
+# A diverged branch fails with a clear message — open-memex never
+# force-merges; resolve it by hand, then pull again. On success the
+# local index re-syncs. Pulls are explicit by default; set
+# `open-memex config set sync.autoPull true` for a best-effort pull
+# at MCP session start (a failed pull never blocks the session).
+
+open-memex push
+# push the current branch (with its submitted memories) to the git remote.
+# Explicit only — open-memex never pushes on its own.
+
+open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
+# bundle memories into a portable .tar.gz (markdown + manifest.json) for
+# moving to another machine or another app. Excludes visibility:private
+# memories by default; --all / -a includes everything (full migration).
+
+open-memex import <bundle.tar.gz> [--dry-run]
+# restore a bundle: personal memories go to the personal dir; project
+# memories are re-keyed to the current project and land in the outbox as
+# drafts. Identical ids are skipped; conflicting ids are reported,
+# never overwritten.
+
+open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
+# propose an AGENTS.md snippet distilled from project memories
+# (decisions, constraints, lessons, gotchas, howtos). Prints markdown;
+# -o writes it to a file. You review and merge by hand — open-memex
+# never rewrites your AGENTS.md on its own. The snippet ends with a
+# "memory hygiene" section (§3.5 checkpoint guidance) so agents reading
+# AGENTS.md learn to propose distilled captures at checkpoints.
+
 open-memex propose <id...> --to project [--local-approve]
 # propose one or several personal memories at once (one branch, one PR);
 # each is copied with its own new id. All-or-nothing: a bad id aborts the
@@ -330,6 +497,10 @@ open-memex resolve [id-or-path]
 # Semantic conflicts are reported, never auto-resolved.
 ```
 
+Whoever tends the shared memory follows the curator convention —
+`docs/CURATOR.md`: what to approve, what to send back, and the hygiene
+rules that keep shared memory from rotting.
+
 Maintenance:
 
 ```sh
@@ -368,28 +539,27 @@ server with cwd set to your project root (`init` handles this for you).
 
 ## Roadmap
 
-**`0.3.0` (this release):** generic MCP server, `open-memex` bin/CLI, one-command
+**`0.3.0` (stable):** generic MCP server, `open-memex` bin/CLI, one-command
 `init` setup, Chinese keyword capture with personal/project routing, `config` /
 `capture --dry-run` / `doctor` helpers, Visual Studio support.
 
-**In progress — `0.4.0`:** team sync — shared memory via git: appdata draft
+**`0.4.0` (stable):** 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; 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, `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
-benchmark-gated experiment (no embedding model is ever downloaded without explicit
-opt-in); cloud `RemoteProvider` customization only if multi-repo sharing, ACL, or
-compliance needs demand it.
-
-Design details: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md) (append-only decision log D1–D20).
+→ `promote` / `resolve` review workflow, in-repo `.ai/open-memex/` dir;
+`export` / `import` archive for user portability (Markdown + manifest, no walled
+garden; private excluded by default, `-a` / `--all` for full migration);
+distill-to-AGENTS.md assist (`distill-agents`, propose-only — you merge by hand);
+§3.5 checkpoint distillation in the MCP handshake + init instructions (the agent
+proposes 1–3 captures at checkpoints, the human decides); 1–2 colleague pilot.
+
+**Future (signal-gated, no version committed):** org layer — org memory repo,
+curator convention; native agent plugins (Claude Code / Codex hooks as
+enhancement paths over the same MCP tools); local embeddings as a
+benchmark-gated experiment (no embedding model is ever downloaded without
+explicit opt-in); cloud `RemoteProvider` customization only if multi-repo
+sharing, ACL, or compliance needs demand it.
+
+Design details: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md) (append-only decision log).
 
 ## License
 

package/README.zh-CN.md

@@ -1,15 +1,74 @@
 # open-memex
 
+[![npm version](https://img.shields.io/npm/v/open-memex.svg)](https://www.npmjs.com/package/open-memex)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
+
 [English](./README.md)
 
 给 AI 编程助手的本地优先持久记忆：一个 [opencode](https://opencode.ai) 插件，
 加上一个通用 MCP server（VS Code Copilot、Cursor、Claude Code、Visual Studio 等）。
 
+## 为什么需要 open-memex？
+
+工程知识只存在于两个地方：代码里，和人的脑子里。
+每个新的 AI 编程会话都从零开始——同样的项目背景要反复讲，同样的坑要反复踩，
+同样的事故教训在聊天结束时就消失了。
+
+open-memex 把值得记住的部分——决策、约束、教训——存成可 review 的 Markdown，
+并在下一次会话开始时自动注入回去。
+
+> No capture, nothing to inherit.（不记录，就无从传承。）
+
+它也补齐了 agentic 开发工作流（spec 驱动开发、plan/implement/verify 循环）缺的那一块：
+plan 产出决策，verify 产出规则——open-memex 是让它们跨会话留存的记忆层，
+而不是每次从头重新推导。
+
+## 和其它方案的对比
+
+| | open-memex | 云端记忆服务 | Wiki / 文档平台 | 聊天记录 |
+|---|---|---|---|---|
+| 数据在哪 | 你的机器 + 你的仓库 | 服务商服务器 | 中心服务器 | 聊天结束就没了 |
+| 分享前 review | 有——outbox + PR | 不一定 | 有 | 没有 |
+| Agent 回忆 | 会话开始注入 + 搜索 | 调 API | 人工去查 | 没有 |
+| 人类可读 | 纯 Markdown 文件 | 后台 / API | 有 | 没有 |
+
 - **Markdown 文件**是 source of truth（人类可读、git 友好）
 - **SQLite FTS5** 做可重建索引（BM25 关键词检索，`better-sqlite3`）
 - **零云端**、零账号、零第三方 API
 - 直接跑在 opencode 内嵌的 Bun 运行时里；CLI 和 MCP server 跑在 Node 下——开发时无需构建（发布的 npm 包带预编译好的 JS）、无需安装 Bun
 
+## 架构
+
+```text
+                        ┌──────────────────┐
+                        │     AI agent     │
+                        │ Copilot / Cursor │
+                        │ Claude / opencode│
+                        └────────┬─────────┘
+                                 │ MCP (stdio) — 11 tools
+                                 │ session-start injection
+                        ┌────────▼─────────┐
+                        │    open-memex    │
+                        │    MCP server    │
+                        └──┬────────────┬──┘
+                           │            │
+              ┌────────────▼───┐  ┌─────▼──────────┐
+              │ Markdown files │  │ SQLite FTS5    │
+              │ source of truth│  │ rebuildable    │
+              │ local-first    │  │ index (BM25)   │
+              └─────────────┬──┘  └────────────────┘
+                            │ submit (explicit,
+                            │  local commit)
+                    ┌───────▼────────┐
+                    │    Git repo    │
+                    │ .ai/open-memex/│
+                    │  PR-reviewed   │
+                    │  team memory   │
+                    └────────────────┘
+
+personal scope：只属于这台机器——永不同步，永远进不了仓库。
+```
+
 ## 安装
 
 ### 前置要求
@@ -18,18 +77,36 @@
 
 ### 第一步——安装 CLI
 
-**npm（推荐）：**
+#### 稳定版 vs Alpha 版
+
+**稳定版**（推荐大多数用户）——`latest` 标签：
 
 ```sh
 npm install -g open-memex
 ```
 
-安装的是 `0.3.0` 正式版。
+安装的是 `0.4.0` 正式版。
+
+**Alpha 版**（最新开发版，给测试者）——`alpha` 标签：
+
+```sh
+npm install -g open-memex@alpha
+```
+
+查看已发布版本：
+
+```sh
+npm view open-memex version         # 最新稳定版
+npm view open-memex@alpha version   # 最新 alpha 版
+```
+
+Alpha 版可能有毛边——欢迎报 bug。
 
 **免安装——用 npx 直接跑：**
 
 ```sh
-npx -y open-memex <命令>   # 例如 npx -y open-memex init --client vscode
+npx -y open-memex <命令>          # 例如 npx -y open-memex init --client vscode
+npx -y open-memex@alpha <命令>   # alpha 线，免安装
 ```
 
 **从源码安装**（最新开发版，`V2-dev-p2` 分支）：
@@ -180,6 +257,48 @@ open-memex doctor
   （API key、token、高熵凭据）就地打码——保留前 4 个字符，其余替换为 `x`——
   然后照常保存。用 `open-memex capture --dry-run "…"` 预览一条消息会被如何捕获。
 
+## 记忆类型（Memory types）
+
+11 种类型——`type` 说明这条记忆是什么，`tags` 说明它和什么有关：
+
+| 类型 | 记录什么 |
+|---|---|
+| `fact` | 关于项目或世界的稳定事实 |
+| `preference` | 某人做事的偏好 |
+| `decision` | 做过的选择——为什么、权衡了什么 |
+| `constraint` | 不能违反的规则 |
+| `todo` | 以后要做的承诺 |
+| `knowledge` | 持久的领域或架构知识 |
+| `howto` | 验证过的做法 |
+| `gotcha` | 要避开的坑 |
+| `lesson` | 事故或错误教会我们的东西 |
+| `observation` | 注意到的现象，还不是结论 |
+| `reference` | 指向权威文档的指针（不复制内容） |
+
+## 团队记忆工作流
+
+个人笔记永远私有。项目知识走一条显式、可 review 的流水线——没有任何东西会自动分享：
+
+```
+capture → outbox（本地草稿）→ submit → 仓库（.ai/open-memex/）→ PR review → published → recall
+```
+
+1. **Capture**——正常工作中把决策、坑、教训存成草稿。
+2. **Review**——草稿在本地 outbox 里等着；`sync-status`（或在聊天里说"同步记忆"）查看待处理项。
+3. **Submit**——你点名要分享的记忆才会进 `<repo>/.ai/open-memex/`，并做本地 commit。open-memex 永远不会自动 push。
+4. **PR review**——记忆就是纯 Markdown；reviewer 走正常的分支/PR 流程批准、要求修改或拒绝（`promote`、`pr-status`、`resolve`）。
+5. **Recall**——已发布的记忆在会话开始时自动注入，也可随时搜索，人和 agent 都能用。
+
+Reviewer 守则：[docs/CURATOR.md](./docs/CURATOR.md)。
+
+## 安全与数据
+
+- **本地优先：** 所有东西都在你的机器上（`%APPDATA%\open-memex` / `~/.local/share/open-memex`），加上你选择的仓库。零云端调用、零账号、零第三方 API、零遥测。
+- **密钥进不来：** `<private>…</private>` 包裹的内容会被剥离；检测到的 API key / token 在保存前就地打码。先用 `open-memex capture --dry-run "…"` 预览。
+- **个人 scope 永不同步：** `personal` 只属于这台机器——export 默认排除，也永远进不了仓库。
+- **分享可审计：** 团队记忆只能靠显式的 `submit` 移动，走分支/PR review，每次 `promote` 状态流转都会追加到记忆的 `review_history`（谁/何时/为什么）。
+- **文件是你的：** Markdown 是 source of truth——随手看、随手改、随手删；SQLite 索引可以从文件重建。
+
 ## Scope
 
 - **project** — 绑定当前仓库（用 git origin URL 哈希做 key，无 remote 则用 cwd）。新记忆默认进这里。
@@ -305,6 +424,33 @@ open-memex pr-status [--apply]
 # PR merged → published，PR approved → approved（approved_by = reviewer），
 # changes requested 只给建议。默认只报告；--apply 在本地执行映射的流转（不 push）。
 
+open-memex pull
+# 从 git 远端拉共享记忆：fetch + 只允许 fast-forward。
+# 分支 diverged 时直接报错退出——open-memex 永不强行 merge；
+# 手工解决（rebase 或 merge）后再 pull。成功后本地索引重新同步。
+# pull 默认只显式触发；`open-memex config set sync.autoPull true`
+# 可在 MCP session start 时尝试自动 pull（失败永不阻塞 session）。
+
+open-memex push
+# 把当前分支（含已 submit 的记忆）push 到 git 远端。
+# 只显式触发——open-memex 永不自动 push。
+
+open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
+# 把记忆打包成可携带的 .tar.gz（markdown 原件 + manifest.json），
+# 用于搬到另一台机器或导入别的工具。默认排除 visibility:private 的记忆；
+# --all / -a 全量包含（完整迁移）。
+
+open-memex import <bundle.tar.gz> [--dry-run]
+# 恢复 export 的包：personal 记忆进 personal 目录；project 记忆按当前
+# 项目重新编号 scope_key，进 outbox 当草稿。内容相同的 id 跳过；
+# 内容冲突的 id 只报告，永不覆盖。
+
+open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
+# 把项目记忆（decision/constraint/lesson/gotcha/howto）提炼成
+# AGENTS.md 片段。默认打印到 stdout；-o 写文件。人工审阅后手工合并——
+# open-memex 永不自动改写你的 AGENTS.md。片段末尾带一段"记忆卫生"
+# （§3.5 检查点指引），让读 AGENTS.md 的 agent 学会在检查点提议蒸馏捕获。
+
 open-memex propose <id...> --to project [--local-approve]
 # 一次 propose 一条或多条（一个分支、一个 PR），每条独立新 id。
 # 全有或全无：id 有错整批回滚，不会留半截。
@@ -320,6 +466,9 @@ open-memex resolve [id-or-path]
 # 语义冲突只报告、不自动解决。
 ```
 
+打理共享记忆的人遵循 curator 公约——`docs/CURATOR.md`：
+批什么、退回什么，以及防止共享记忆腐烂的卫生规则。
+
 维护：
 
 ```sh
@@ -358,28 +507,26 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 
 ## 路线图（Roadmap）
 
-**`0.3.0`（本版）：** 通用 MCP server、`open-memex` bin/CLI、
+**`0.3.0`（稳定版）：** 通用 MCP server、`open-memex` bin/CLI、
 一键 `init` 配置、中文关键词捕获（含 personal/project 路由）、
 `config` / `capture --dry-run` / `doctor` 助手命令、Visual Studio 支持。
 
-**进行中 —— `0.4.0`：** 团队同步——用 git 做共享记忆：appdata 草稿箱 →
+**`0.4.0`（稳定版）：** 团队同步——用 git 做共享记忆：appdata 草稿箱 →
 `sync-status` → `submit`（本地分支+commit，push/PR 拿你的 Yes 才做）
-→ `promote` / `resolve` 评审工作流、仓库内 `.ai/open-memex/` 目录，
-找 1–2 个同事做 pilot；捕获——§3.5 检查点蒸馏写进 MCP 握手指令和
-init 指令文件（agent 提议 1–3 条，人来定）。
-
-**Coming —— `0.3.0`（稳定版）：** 组织层——组织记忆仓库、
-curator 约定、distill-to-AGENTS.md 辅助、`export`/`import` 归档
-（Markdown + manifest，不造围墙花园，用户可带走；
-private 默认不导出，`-a`/`--all` 全量迁移）。
-
-**未来（看信号再定，不承诺版本）：** 原生 agent 插件
-（Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；
+→ `promote` / `resolve` 评审工作流、仓库内 `.ai/open-memex/` 目录；
+`export` / `import` 归档做用户可携带（Markdown + manifest，不造围墙花园；
+private 默认不导出，`-a` / `--all` 全量迁移）；
+distill-to-AGENTS.md 辅助（`distill-agents`，只提议不改写——人工合并）；
+§3.5 检查点蒸馏写进 MCP 握手指令和 init 指令文件
+（agent 在检查点提议 1–3 条捕获，人来定）；找 1–2 个同事做 pilot。
+
+**未来（看信号再定，不承诺版本）：** 组织层——组织记忆仓库、curator 约定；
+原生 agent 插件（Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；
 本地 embedding 做基准测试门控的实验（**未经明确 opt-in 绝不下载
 embedding 模型**）；云端 `RemoteProvider` 定制只在多仓库共享、
 ACL 或合规需求出现时才做。
 
-设计细节：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)（append-only 决策日志 D1–D20）。
+设计细节：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)（append-only 决策日志）。
 
 ## 许可证