open-memex 0.3.0 → 0.4.0-alpha.10

package/AGENTS.md

@@ -12,7 +12,7 @@ via `prepublishOnly` — Node refuses `--experimental-strip-types` for files und
 
 - **opencode host** loads `src/index.ts` under embedded **Bun**. SQLite here is `bun:sqlite` (built-in).
 - **CLI** (`src/cli.ts`) and smoke tests run under **Node 22+** with `--experimental-strip-types`. SQLite here is `better-sqlite3` (native module).
-- **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same five memory tools to any MCP client (VS Code Copilot, Cursor, Claude Code). **stdout is the protocol channel — never log to stdout in `mcp.ts`; diagnostics go to stderr.**
+- **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same ten memory tools to any MCP client (VS Code Copilot, Cursor, Claude Code). **stdout is the protocol channel — never log to stdout in `mcp.ts`; diagnostics go to stderr.**
 
 `src/store/db.ts` picks the backend at runtime by sniffing `globalThis.Bun`. Both backends share the same surface (`new Database(path)`, `.exec`, `.prepare().run/all/get`, `.close`). Any DB code you write must stay on that common subset — do not import `better-sqlite3` or `bun:sqlite` directly outside `db.ts`.
 
@@ -29,6 +29,18 @@ 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 -- 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)
+npm run cli -- resolve [id-or-path]                          # list / 3-way-merge conflicted memories
 npm run mcp                                          # start the stdio MCP server
 node --experimental-strip-types scripts\smoke-pure.ts   # runs pure-logic checks (no sqlite)
 node --experimental-strip-types scripts\smoke-mcp.ts    # MCP handshake + tool round-trip (temp dirs, no real data)
@@ -129,3 +141,10 @@ hold `V2` and `V2/…` simultaneously. Full rules: `CONTRIBUTING.md`.
   and the frozen `docs/V2-DESIGN.md` (append a `D<n>` decision entry, never rewrite history);
   new commands → README CLI sections + this file's Commands. A change without its docs
   is not done.
+- **Version bumps ship with features.** `package.json` + `package-lock.json` carry the
+  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

@@ -153,7 +153,7 @@ open-memex doctor
 
 Checks: Node version, config source, scope resolution for the current directory,
 storage writability, then boots a real MCP server and runs `initialize` +
-`tools/list` against it — all five tools must show up.
+`tools/list` against it — all eleven tools must show up.
 
 ## Tools the agent gets
 
@@ -164,6 +164,12 @@ storage writability, then boots a real MCP server and runs `initialize` +
 | `memory_list`      | List memories in a scope, newest first |
 | `memory_supersede` | Replace a memory with a newer version (keeps a supersede chain) |
 | `memory_forget`    | Delete a memory by id |
+| `memory_status`    | Show the sync queue: outbox drafts, repo review states, uncommitted files |
+| `memory_submit`    | Move named drafts into the repo memory dir (local branch + commit) |
+| `memory_propose`   | Copy personal memories into the project scope as review candidates |
+| `memory_promote`   | Advance `proposed → approved → published` (or reject / resubmit) |
+| `memory_resolve`   | List conflicted memory files / 3-way-merge one of them |
+| `memory_pr_status` | Map the branch PR's GitHub state onto each memory's review state |
 
 ## Capture
 
@@ -222,10 +228,17 @@ Defaults:
   "maxProfileItems": 5,       // top-N personal items injected on first turn
   "injectOnFirstTurn": true,  // [OPEN-MEMEX] system-prompt block
   "keywordCaptureEnabled": true,
-  "logLevel": "info"          // info | debug
+  "logLevel": "info",          // info | debug
+  "memoryDir": ".ai/open-memex" // in-repo project-memory dir, relative to repo root
 }
 ```
 
+Project-scope memories are stored as one Markdown file each under
+`<repo>/<memoryDir>/` (default `.ai/open-memex/`) so they can be shared via git;
+personal memories stay in local appdata and never leave the machine. Existing
+project files from appdata are moved into the repo dir automatically on first
+write/sync.
+
 `open-memex config` prints the effective config (defaults + file).
 Change a setting after install:
 
@@ -235,7 +248,7 @@ open-memex config set maxProjectMemories 12
 ```
 
 Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
-`keywordCaptureEnabled`, `logLevel`. Full design: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
+`keywordCaptureEnabled`, `logLevel`, `memoryDir`. Full design: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
 
 ## CLI reference
 
@@ -249,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
 ```
 
@@ -263,6 +277,92 @@ open-memex status <id> deprecated
 open-memex forget <id>
 ```
 
+Team review workflow (Phase 2B — two homes, one per stage):
+
+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
+# (pending sync), the repo review states
+# (draft / proposed / approved / published / rejected),
+# and any uncommitted repo memory files.
+
+open-memex submit <id...> [--branch <name>] [--base <branch>]
+# move your named drafts into .ai/open-memex/ as "proposed":
+# 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:
+# merged PR → published, PR approval → approved (approved_by = reviewer),
+# 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
+# whole batch, never a half-proposed one.
+# copy a personal memory into the project scope as a review candidate
+# (never moves — the personal original stays). Result lands in the outbox;
+# run sync-status / submit when you're ready to put it in the repo.
+open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
+# advance one step: proposed → approved → published (or reject with a note).
+# Every transition is appended to the memory's review_history (who/when/why).
+# A rejection never deletes the file — your call: accept it (close the PR,
+# delete the branch), revise + --resubmit for another round, or keep it as
+# a [rejected] record.
+open-memex resolve [id-or-path]
+# list conflicted memory files, or field-level 3-way merge one of them.
+# 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
@@ -280,7 +380,7 @@ simple cases — npm swallows unknown `--flag` args, so prefer direct `node`).
 
 ## MCP server
 
-The same five memory tools over the Model Context Protocol via a stdio server —
+The same eleven memory tools over the Model Context Protocol via a stdio server —
 no host-specific plugin needed. Any MCP client can use open-memex.
 
 ```sh
@@ -293,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
 
@@ -302,11 +405,16 @@ server with cwd set to your project root (`init` handles this for you).
 `init` setup, Chinese keyword capture with personal/project routing, `config` /
 `capture --dry-run` / `doctor` helpers, Visual Studio support.
 
-**Coming — `0.4.0`:** team sync — shared memory via git (`propose` / `promote` /
-`resolve` workflow, in-repo memory dir), 1–2 colleague pilot.
+**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; 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

@@ -149,7 +149,7 @@ open-memex doctor
 
 检查：Node 版本、配置来源、当前目录的 scope 解析、存储可写性，
 然后启动一个真实的 MCP server 做 `initialize` + `tools/list`——
-五个 tools 都必须出现。
+十一个 tools 都必须出现。
 
 ## Agent 可用的 tools
 
@@ -160,6 +160,12 @@ open-memex doctor
 | `memory_list`      | 按 scope 列出记忆，最新的在前 |
 | `memory_supersede` | 用新版本替换一条记忆（保留替换链） |
 | `memory_forget`    | 按 id 删除一条记忆 |
+| `memory_status`    | 显示同步队列：outbox 草稿、repo 评审状态、未提交文件 |
+| `memory_submit`    | 把点名的草稿移入 repo memory 目录（建本地分支 + commit） |
+| `memory_propose`   | 把 personal 记忆复制到 project scope 作为评审候选 |
+| `memory_promote`   | 推进 `proposed → approved → published`（或 reject / resubmit） |
+| `memory_resolve`   | 列出冲突的记忆文件 / 对单个做三路合并 |
+| `memory_pr_status` | 把分支 PR 的 GitHub 状态映射到每条记忆的评审状态 |
 
 ## 捕获（Capture）
 
@@ -220,10 +226,16 @@ Markdown 是 source of truth，SQLite 索引是派生的、可重建的
   "maxProfileItems": 5,       // 首轮注入的个人偏好条数
   "injectOnFirstTurn": true,  // [OPEN-MEMEX] system-prompt 块
   "keywordCaptureEnabled": true,
-  "logLevel": "info"          // info | debug
+  "logLevel": "info",          // info | debug
+  "memoryDir": ".ai/open-memex" // 仓库内项目记忆目录，相对于仓库根目录
 }
 ```
 
+project scope 的记忆以"一个记忆一个 Markdown 文件"的形式存放在
+`<仓库>/<memoryDir>/`（默认 `.ai/open-memex/`）下，可经 git 共享；
+personal 记忆只存本地 appdata，永不离开本机。已有的 appdata 项目文件会在
+首次写入/同步时自动搬进仓库目录。
+
 `open-memex config` 打印生效配置（默认值 + 文件）。
 安装后改设置：
 
@@ -233,7 +245,7 @@ open-memex config set maxProjectMemories 12
 ```
 
 可设置的 key：`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、
-`keywordCaptureEnabled`、`logLevel`。完整设计见
+`keywordCaptureEnabled`、`logLevel`、`memoryDir`。完整设计见
 [docs/V2-DESIGN.md](./docs/V2-DESIGN.md)。
 
 ## CLI 参考
@@ -248,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   # 已安装版本
 ```
 
@@ -262,6 +275,80 @@ open-memex status <id> deprecated
 open-memex forget <id>
 ```
 
+团队评审工作流（Phase 2B —— 两个家，各管一段）：
+
+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...> [--branch <name>] [--base <branch>]
+# 把你点名的草稿移入 .ai/open-memex/，状态变为 proposed：
+# 复制、改 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]
+# 读分支的 GitHub PR，把它的状态映射到每条 in-repo 记忆：
+# 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 有错整批回滚，不会留半截。
+# 把一条 personal 记忆复制到 project scope 进入评审（复制而非移动，
+# personal 原件保留）。结果落在 outbox；准备好进 repo 时再 sync-status / submit。
+open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
+# 晋升一步：proposed → approved → published（或用 --reject 驳回并附注原因）。
+# 每次流转都追加到记忆的 review_history（谁、何时、为什么）。
+# 驳回不删文件，由你决定：接受（关 PR 删分支）、改完 --resubmit 再审、
+# 或留着当 [rejected] 记录。
+open-memex resolve [id-or-path]
+# 列出冲突中的记忆文件，或对其中一个做字段级 3-way 合并。
+# 语义冲突只报告、不自动解决。
+```
+
+打理共享记忆的人遵循 curator 公约——`docs/CURATOR.md`：
+批什么、退回什么，以及防止共享记忆腐烂的卫生规则。
+
 维护：
 
 ```sh
@@ -280,7 +367,7 @@ CLI 跑在 Node 22 下。从源码 checkout 使用时走内置的实验性 TypeS
 
 ## MCP server
 
-同一个五个 memory tools，走 Model Context Protocol 的 stdio server——
+同一个十一个 memory tools，走 Model Context Protocol 的 stdio server——
 不需要宿主专属插件，任何 MCP 客户端都能用 open-memex。
 
 ```sh
@@ -293,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）
 
@@ -301,12 +391,16 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 一键 `init` 配置、中文关键词捕获（含 personal/project 路由）、
 `config` / `capture --dry-run` / `doctor` 助手命令、Visual Studio 支持。
 
-**Coming —— `0.4.0`：** 团队同步——用 git 做共享记忆
-（`propose` / `promote` / `resolve` 工作流、仓库内记忆目录），
-找 1–2 个同事做 pilot。
+**进行中 —— `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 辅助。
+curator 约定、distill-to-AGENTS.md 辅助、`export`/`import` 归档
+（Markdown + manifest，不造围墙花园，用户可带走；
+private 默认不导出，`-a`/`--all` 全量迁移）。
 
 **未来（看信号再定，不承诺版本）：** 原生 agent 插件
 （Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；