open-memex 0.3.0-alpha.3 → 0.4.0-alpha.1

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,12 +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 -- sync-status                                  # last sync time/kind + outbox drafts + repo review states + uncommitted files
+npm run cli -- submit <id...> [--onto <branch>] [--base <branch>]  # drafts → .ai/open-memex/ (local branch+commit)
+npm run cli -- propose <id...> --to project [--local-approve]  # copy personal → project outbox (batch OK)
+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)
 ```
 
-After `npm i -g open-memex@alpha` (or `npm link` from source), the `open-memex` bin is on
+After `npm i -g open-memex` (or `npm link` from source), the `open-memex` bin is on
 PATH: `open-memex mcp` starts the MCP server, `open-memex mcp --print-config <client>`
 prints a client config snippet (client: vscode|cursor|claude|opencode|visualstudio),
 `open-memex init [--client vscode|cursor|opencode|visualstudio] [--instructions personal|project] [--force] [--yes]`
@@ -129,3 +135,7 @@ 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.

package/README.md

@@ -21,16 +21,15 @@ plus a generic MCP server (VS Code Copilot, Cursor, Claude Code, Visual Studio,
 **npm (recommended):**
 
 ```sh
-npm install -g open-memex@alpha
+npm install -g open-memex
 ```
 
-This installs the `0.3.0-alpha` prerelease channel. (`latest` still points at the older
-`0.1.0` stable.)
+This installs the `0.3.0` stable release.
 
 **No install — run via npx:**
 
 ```sh
-npx -y open-memex@alpha <command>   # e.g. npx -y open-memex@alpha init --client vscode
+npx -y open-memex <command>   # e.g. npx -y open-memex init --client vscode
 ```
 
 **From source** (bleeding edge, `V2-dev-p2` branch):
@@ -42,9 +41,6 @@ npm install
 node --experimental-strip-types src/cli.ts <command>
 ```
 
-> The `0.3.0-alpha` npm publish is cut from this branch — if `npx` still resolves an
-> older alpha, install from source until the publish lands.
-
 #### "`open-memex` is not recognized" — PATH setup
 
 A global `npm install -g` puts the `open-memex` launcher in npm's global bin folder.
@@ -65,6 +61,15 @@ If your terminal can't find it, that folder isn't on your `PATH`:
 3. No admin rights / don't want to touch `PATH`? Use the npx form above — npx
    resolves the package itself and needs no `PATH` changes.
 
+#### "`EBUSY` / `EPERM` on `better_sqlite3.node`" — Windows reinstall
+
+On Windows a loaded DLL is locked: if the open-memex MCP server is running
+(VS Code MCP panel, Cursor, etc.), `npm install -g open-memex` cannot
+replace `better_sqlite3.node` and fails with `EBUSY` / `EPERM`. Stop the MCP
+server first (or quit the editor), then re-run the install. If it still fails,
+delete `node_modules/open-memex` and any `node_modules/.open-memex-*` temp
+folders under your global npm root and install again.
+
 ### Step 2 — One-command setup for your editor
 
 Run from your **project root** (so the project scope resolves to this repo):
@@ -74,7 +79,7 @@ Run from your **project root** (so the project scope resolves to this repo):
 ```sh
 open-memex init --client vscode
 # …or without a global install:
-npx -y open-memex@alpha init --client vscode
+npx -y open-memex init --client vscode
 ```
 
 Writes `.vscode/mcp.json` and user-level Copilot instructions, then reload the
@@ -136,8 +141,8 @@ above works too.
 - Existing config files are **merged, never clobbered** — re-running is safe.
   `--force` overwrites.
 - With no durable `open-memex` on `PATH` (e.g. one-shot npx), `init` writes an
-  `npx -y open-memex@alpha mcp` server command into the config so the setup keeps
-  working. `npm i -g open-memex@alpha` + `open-memex init --force` switches to the
+  `npx -y open-memex mcp` server command into the config so the setup keeps
+  working. `npm i -g open-memex` + `open-memex init --force` switches to the
   faster direct command later.
 
 ### Step 3 — Verify it works
@@ -148,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
 
@@ -159,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
 
@@ -217,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:
 
@@ -230,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
 
@@ -258,6 +276,52 @@ 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.
+
+```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...> [--onto <branch>] [--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.
+
+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 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.
+```
+
 Maintenance:
 
 ```sh
@@ -275,12 +339,12 @@ 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
 open-memex mcp               # after a global install
-npx -y open-memex@alpha mcp  # no install needed
+npx -y open-memex mcp  # no install needed
 ```
 
 The project scope is resolved from the process working directory, so configure the
@@ -293,12 +357,14 @@ server with cwd set to your project root (`init` handles this for you).
 
 ## Roadmap
 
-**`0.3.0-alpha` (this release):** generic MCP server, `open-memex` bin/CLI, one-command
+**`0.3.0` (this release):** 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.
 
-**Coming — `0.3.0-beta`:** 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.
 
 **Coming — `0.3.0` (stable):** org layer — org memory repo, curator convention,
 distill-to-AGENTS.md assist.

package/README.zh-CN.md

@@ -21,15 +21,15 @@
 **npm（推荐）：**
 
 ```sh
-npm install -g open-memex@alpha
+npm install -g open-memex
 ```
 
-安装的是 `0.3.0-alpha` 预览通道。（`latest` 仍指向旧的 `0.1.0` 稳定版。）
+安装的是 `0.3.0` 正式版。
 
 **免安装——用 npx 直接跑：**
 
 ```sh
-npx -y open-memex@alpha <命令>   # 例如 npx -y open-memex@alpha init --client vscode
+npx -y open-memex <命令>   # 例如 npx -y open-memex init --client vscode
 ```
 
 **从源码安装**（最新开发版，`V2-dev-p2` 分支）：
@@ -41,9 +41,6 @@ npm install
 node --experimental-strip-types src/cli.ts <命令>
 ```
 
-> `0.3.0-alpha` 的 npm 发布从该分支切出——如果 npx 还解析到旧的 alpha 版，
-> 请先用源码安装，等发布落地。
-
 #### 提示 "'open-memex' 不是内部命令"？——PATH 设置
 
 `npm install -g` 会把 `open-memex` 启动器放到 npm 的全局 bin 目录。
@@ -63,6 +60,14 @@ node --experimental-strip-types src/cli.ts <命令>
 3. 没有管理员权限 / 不想动 `PATH`？用上面的 npx 形式——npx 自己解析包，
    不需要改 `PATH`。
 
+#### Windows 重装报 "`EBUSY` / `EPERM`（`better_sqlite3.node`）"
+
+Windows 下被进程加载的 DLL 是锁死的：如果 open-memex MCP server 正在运行
+（VS Code MCP 面板、Cursor 等），`npm install -g open-memex` 替换不了
+`better_sqlite3.node`，就会报 `EBUSY` / `EPERM`。先停掉 MCP server
+（或退出编辑器），再重跑安装。还不行的话，手动删掉全局 npm 目录下的
+`node_modules/open-memex` 和 `node_modules/.open-memex-*` 临时目录，再装。
+
 ### 第二步——给你的编辑器一键配置
 
 在**项目根目录**下运行（这样 project scope 会解析到这个仓库）：
@@ -72,7 +77,7 @@ node --experimental-strip-types src/cli.ts <命令>
 ```sh
 open-memex init --client vscode
 # ……没装全局包的话：
-npx -y open-memex@alpha init --client vscode
+npx -y open-memex init --client vscode
 ```
 
 自动写 `.vscode/mcp.json` 和用户级 Copilot instructions，然后重新加载窗口，
@@ -132,8 +137,8 @@ Visual Studio 也会自动发现 `.vscode/mcp.json` 和 `.cursor/mcp.json`，
 - 已有配置文件会被**合并，不会被覆盖**——重复运行是安全的。
   `--force` 强制覆盖。
 - 如果 `PATH` 上没有可用的 `open-memex`（比如一次性 npx），`init` 会把
-  `npx -y open-memex@alpha mcp` 写进配置，配置照样能用。
-  以后 `npm i -g open-memex@alpha` + `open-memex init --force` 可切换到更快
+  `npx -y open-memex mcp` 写进配置，配置照样能用。
+  以后 `npm i -g open-memex` + `open-memex init --force` 可切换到更快
   的直接调用。
 
 ### 第三步——验证
@@ -144,7 +149,7 @@ open-memex doctor
 
 检查：Node 版本、配置来源、当前目录的 scope 解析、存储可写性，
 然后启动一个真实的 MCP server 做 `initialize` + `tools/list`——
-五个 tools 都必须出现。
+十一个 tools 都必须出现。
 
 ## Agent 可用的 tools
 
@@ -155,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）
 
@@ -215,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` 打印生效配置（默认值 + 文件）。
 安装后改设置：
 
@@ -228,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 参考
@@ -257,6 +274,45 @@ open-memex status <id> deprecated
 open-memex forget <id>
 ```
 
+团队评审工作流（Phase 2B —— 两个家，各管一段）：
+
+project 草稿先住在 **appdata outbox**（git 看不见、跟分支无关）；只有你
+点名批准的草稿，才会被移入 `<repo>/.ai/open-memex/`，之后随分支和 PR 走。
+没经过你点名，什么都不会动。
+
+```sh
+open-memex sync-status
+# 看索引上次同步的时间和触发方、outbox（待同步）、repo 里的评审状态
+# （draft / proposed / approved / published / rejected），
+# 以及 repo 里还没 commit 的记忆文件。
+
+open-memex submit <id...> [--onto <branch>] [--base <branch>]
+# 把你点名的草稿移入 .ai/open-memex/，状态变为 proposed：
+# 建 mem/sync-<timestamp> 分支（或 --onto 当前分支，跟代码走同一个 PR），
+# 复制、改 review_state、本地 git commit。全有或全无；冲突（同 id 不同内容）
+# 干净回滚。打印 push + gh pr 命令；Agent 拿到你的 Yes 后会自己走完 push/PR。
+# 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 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 合并。
+# 语义冲突只报告、不自动解决。
+```
+
 维护：
 
 ```sh
@@ -275,12 +331,12 @@ 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
 open-memex mcp               # 全局安装后
-npx -y open-memex@alpha mcp  # 免安装
+npx -y open-memex mcp  # 免安装
 ```
 
 project scope 从进程工作目录解析，所以配置 server 时 cwd 要指向项目根目录
@@ -292,12 +348,13 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 
 ## 路线图（Roadmap）
 
-**`0.3.0-alpha`（本版）：** 通用 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 支持。
 
-**Coming —— `0.3.0-beta`：** 团队同步——用 git 做共享记忆
-（`propose` / `promote` / `resolve` 工作流、仓库内记忆目录），
+**进行中 —— `0.4.0`：** 团队同步——用 git 做共享记忆：appdata 草稿箱 →
+`sync-status` → `submit`（本地分支+commit，push/PR 拿你的 Yes 才做）
+→ `promote` / `resolve` 评审工作流、仓库内 `.ai/open-memex/` 目录，
 找 1–2 个同事做 pilot。
 
 **Coming —— `0.3.0`（稳定版）：** 组织层——组织记忆仓库、