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

package/AGENTS.md

@@ -29,8 +29,14 @@ 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 -- 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)
 npm run cli -- pr-status [--apply]                          # map branch PR's GitHub state onto review_state (report; apply = local only)
@@ -139,3 +145,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

@@ -262,6 +262,7 @@ open-memex doctor                                  # environment health check
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # preview keyword capture
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
 open-memex --help      # this reference
+open-memex <command> --help  # help for one command
 open-memex --version   # installed version
 ```
 
@@ -282,6 +283,11 @@ Project drafts live in the **appdata outbox** (git-invisible, branch-independent
 only user-approved drafts move into `<repo>/.ai/open-memex/`, where they follow
 branches and PRs. Nothing moves without you naming it.
 
+In an AI chat with the MCP server connected, just say **"sync memory"**
+(or "同步记忆") — the agent runs the status check, summarizes the outbox drafts,
+and asks which ones to sync. The agent also proposes this on its own at session
+start and at work checkpoints.
+
 ```sh
 open-memex sync-status
 # show when the index was last synced (and what triggered it), the outbox
@@ -289,14 +295,16 @@ open-memex sync-status
 # (draft / proposed / approved / published / rejected),
 # and any uncommitted repo memory files.
 
-open-memex submit <id...> [--onto <branch>] [--base <branch>]
+open-memex submit <id...> [--branch <name>] [--base <branch>]
 # move your named drafts into .ai/open-memex/ as "proposed":
-# creates mem/sync-<timestamp> (or stays on --onto for a code+memory PR),
-# copies, flips review_state, local git commit. All-or-nothing; conflicts
-# (same id, different content) abort cleanly. Prints the push + gh pr
-# commands; an agent holding your Yes carries through push/PR itself.
-# Default PR base is the current branch; --base redirects to main or your
-# integration branch.
+# copies, flips review_state, local git commit ON THE CURRENT BRANCH.
+# Never creates a branch on its own — branch creation is your call
+# (or the agent's, only with your explicit approval for the full chain).
+# All-or-nothing; conflicts (same id, different content) abort cleanly.
+# Prints the push + gh pr commands; an agent holding your Yes carries
+# through push/PR itself. --branch <name> creates the branch first
+# (agent full-chain path). Default PR base is the current branch; --base
+# redirects to main or your integration branch.
 
 open-memex pr-status [--apply]
 # read the branch's GitHub PR and map its state onto each in-repo memory:
@@ -304,6 +312,35 @@ 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.
+
 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
@@ -322,6 +359,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
@@ -352,8 +393,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
 
@@ -364,10 +408,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

@@ -260,6 +260,7 @@ open-memex doctor                                  # 环境健康检查
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # 预览关键词捕获
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
 open-memex --help      # 本帮助
+open-memex <command> --help  # 单个命令的帮助
 open-memex --version   # 已安装版本
 ```
 
@@ -280,17 +281,23 @@ project 草稿先住在 **appdata outbox**（git 看不见、跟分支无关）
 点名批准的草稿，才会被移入 `<repo>/.ai/open-memex/`，之后随分支和 PR 走。
 没经过你点名，什么都不会动。
 
+在接了 MCP 服务器的 AI 对话里，直接说 **"同步记忆"**（或 "sync memory"）——
+agent 会查状态、把 outbox 草稿逐条摘要、问你同步哪几条。agent 也会在新对话
+开始和任务检查点主动提这件事。
+
 ```sh
 open-memex sync-status
 # 看索引上次同步的时间和触发方、outbox（待同步）、repo 里的评审状态
 # （draft / proposed / approved / published / rejected），
 # 以及 repo 里还没 commit 的记忆文件。
 
-open-memex submit <id...> [--onto <branch>] [--base <branch>]
+open-memex submit <id...> [--branch <name>] [--base <branch>]
 # 把你点名的草稿移入 .ai/open-memex/，状态变为 proposed：
-# 建 mem/sync-<timestamp> 分支（或 --onto 当前分支，跟代码走同一个 PR），
-# 复制、改 review_state、本地 git commit。全有或全无；冲突（同 id 不同内容）
-# 干净回滚。打印 push + gh pr 命令；Agent 拿到你的 Yes 后会自己走完 push/PR。
+# 复制、改 review_state、在当前分支本地 git commit。
+# 永不自动建分支——建分支是你说了算（或 Agent 拿到你明确批准走全链时）。
+# 全有或全无；冲突（同 id 不同内容）干净回滚。
+# 打印 push + gh pr 命令；Agent 拿到你的 Yes 后会自己走完 push/PR。
+# --branch <name> 先建分支再提交（Agent 全链路径）。
 # PR 默认 base 是当前分支；--base 可改到 main 或集成支。
 
 open-memex pr-status [--apply]
@@ -298,6 +305,32 @@ 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。
+
 open-memex propose <id...> --to project [--local-approve]
 # 一次 propose 一条或多条（一个分支、一个 PR），每条独立新 id。
 # 全有或全无：id 有错整批回滚，不会留半截。
@@ -313,6 +346,9 @@ open-memex resolve [id-or-path]
 # 语义冲突只报告、不自动解决。
 ```
 
+打理共享记忆的人遵循 curator 公约——`docs/CURATOR.md`：
+批什么、退回什么，以及防止共享记忆腐烂的卫生规则。
+
 维护：
 
 ```sh
@@ -344,7 +380,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）
 
@@ -355,10 +394,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 的增强路径）；