open-memex 0.3.0 → 0.4.0-alpha.4

package/docs/USER-GUIDE.md

@@ -0,0 +1,195 @@
+# OpenMemex User Guide
+
+> This document describes open-memex's **mental model**: where your memories live,
+> how they flow, and who can see them. The in-repo directory (§2, §6 write path)
+> and the propose → promote → resolve workflow (§5) are implemented on the
+> `V2-dev-p2b` branch; features marked **2B** are still to be built;
+> everything else is 0.3.0 behavior.
+
+## In one sentence
+
+open-memex is a local-first memory layer: **Markdown is the source of truth;
+SQLite is just a rebuildable index.** Lose the index and you rebuild it.
+Lose the Markdown and it's really gone.
+
+## 1. Two scopes: personal vs project
+
+Every memory belongs to a scope, which decides **how far it may travel**:
+
+| | personal | project |
+|---|---|---|
+| Holds | Facts about you: preferences, habits, cross-project info | Facts about the project: stack, conventions, decisions, gotchas |
+| Lives | Only on your machine (see §2) | Local + eligible for team sharing (see §2, §6) |
+| Rule | **Never leaves this machine** | Can be promoted to team knowledge |
+
+Keywords route automatically (D18): "remember… / I think… / I like…" (I) → personal;
+"we decided… / we think… / remember for us…" (we) → project.
+
+## 2. Two homes: appdata vs the repo directory
+
+| | appdata (the desk) | repo `.ai/open-memex/` (the shelf) |
+|---|---|---|
+| Location | Windows `%APPDATA%/open-memex`, Linux `~/.local/share/open-memex` | Project root, default `.ai/open-memex/` (D23, configurable via `memoryDir`) |
+| Holds | `memories/personal/` personal memories; project-scope **draft outbox**; `index.db` local index | Submitted project memories (`proposed` and up) |
+| In git? | No | Yes — git is its courier |
+| The index? | `index.db` is rebuildable, **never committed** | No index stored; rebuilt from Markdown on demand |
+
+The private notebook (personal) never goes on the shelf. That's an iron rule, not a setting.
+
+Project memories start life as **drafts in the appdata outbox** — git-invisible,
+branch-independent. Only drafts you explicitly name move to the shelf, via
+`open-memex submit` (§5). One stage, one home: after a successful submit the
+outbox original is gone; before it, the repo knows nothing.
+
+## 3. First-turn injection: how the 8 and 5 are chosen
+
+Before the agent's first turn, open-memex injects an `[OPEN-MEMEX]` context block so it
+doesn't need a search call just to get oriented. Defaults: **8 project + 5 personal**
+memories (`maxProjectMemories` / `maxProfileItems`, tunable).
+
+Selection has exactly one criterion: **most recently updated first**
+(`ORDER BY updated_at DESC`), minus retracted/archived items, with superseded
+versions resolved away. Not "the N most important" — "the N most recently touched".
+What you just updated is most likely relevant to what you're doing now.
+
+Token budget: each item is squeezed to one line (≤240 chars, ~60 tokens), so 8 items
+cost ≈ 500 tokens worst case. Beyond that, diminishing returns — the long tail is what
+`memory_search` is for; stuffing everything into the first turn buries the signal.
+
+Raise it: `open-memex config set maxProjectMemories 12`
+
+## 4. Later turns: when memory gets searched again
+
+First-turn injection happens once. After that there is **no automatic re-search** —
+MCP is request/response; the server cannot push. Whether `memory_search` gets called
+is entirely the model's judgment, guided by two things:
+
+- The injected block's footer: "Use the `memory_search` tool to look up more."
+- The Copilot instructions written by `init`: "before asking the user about something
+  they may have told you before, call `memory_search` first — try a few keyword
+  variants before giving up."
+
+So: when the conversation touches past decisions, preferences, or conventions, the
+model *should* search first — but nothing enforces it. This is a known gap in the
+current version; Phase 2C's native plugin hooks (e.g. Claude Code's
+`UserPromptSubmit`) are meant to close it.
+
+## 5. Promotion workflow: how a memory becomes team knowledge
+
+A personal observation becomes team knowledge by exactly one road —
+**explicit promotion, never automatic sync**:
+
+```
+personal idea ──propose──▶ outbox draft ──submit──▶ proposed ──┬──promote──▶ approved ──promote──▶ published/shared
+                                                              │                        │
+                                                           --reject                 --reject
+                                                              │                        │  (approval withdrawn
+                                                              ▼                        │   before merge)
+                                                           rejected ──resubmit──▶ proposed
+```
+
+- `open-memex propose <id...> --to project`: **copies** one or more personal
+  memories into the **appdata outbox** as review candidates (`review_state:
+  draft`, each with its own new id, `derived_from` pointing back at the
+  personal original). **Copy, not move — the personal original stays.**
+  All-or-nothing: a bad id aborts the whole batch. Nothing touches the repo
+  yet — the outbox is git-invisible and branch-independent.
+  Solo devs can use `--local-approve` to self-approve.
+- `open-memex sync-status`: shows **when the index was last synced** (and
+  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.
+- `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` +
+  `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.
+  Same id with different content on the branch **aborts** — a human decides,
+  never auto-overwrite.
+  - Keep the four jobs straight: **propose crosses the boundary**
+    (personal → project outbox, the only step that copies across);
+    **submit moves drafts into the repo** (outbox → `.ai/open-memex/`,
+    `draft → proposed`); **promote only flips the status label** on a file
+    already in `.ai/open-memex/` (`proposed → approved → published`) — it
+    never moves files between directories; **git does the transport**
+    (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>`).
+- "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.
+- `open-memex promote <id>`: advances the memory one step up the ladder
+  (`proposed → approved → published`). `--reject --note "..."` rejects with a
+  reason (also allowed from `approved`, before merge — withdrawing approval).
+  Every transition is appended to the memory's `review_history` — who moved it,
+  when, from what to what, and why — so the review trail survives long after
+  the PR is closed.
+  After the PR merges, run `promote <id>` once more to mark it `published`
+  — or let `pr-status --apply` do it for you (below).
+  (Lifting project memories to org level is Phase 4.)
+- **A rejection never deletes anything.** The file stays on your branch; what
+  happens next is the human's call:
+  1. **Accept**: close the PR and delete the branch — the file goes with it
+     (the local index cleans itself up on the next sync);
+  2. **Revise and resubmit**: edit the file, run
+     `open-memex promote <id> --resubmit`, commit, push — review continues on
+     the same PR;
+  3. **Keep as a record**: leave it; it stays visible with a `[rejected]` tag
+     and your note, so the team can see what was considered and why not.
+- `open-memex pr-status [--apply]`: reads the current branch's GitHub PR
+  and maps its state onto each in-repo memory's review state — merged PR →
+  `published`, PR approval → `approved` (`approved_by` = the reviewer), review
+  "request changes" → a suggestion for you to act on (never auto-rejects).
+  Each memory keeps its own state: a human `rejected` is never overridden by
+  a PR signal. Report by default; `--apply` performs the mapped transitions
+  locally (no push). This is how a team review on GitHub closes the loop back
+  into the memory index without new review UI.
+- `open-memex resolve [id]`: with no argument, lists conflicted memory files;
+  with an id, attempts a **field-level 3-way merge** of the YAML frontmatter
+  (`tags` union, `updated_at` takes latest, body merged when only one side
+  changed). Semantic conflicts — both sides changed the same field or the
+  body differently — are **reported, never auto-resolved**: the file is left
+  untouched for a human to decide.
+- `list` / `search` show a `[draft]` / `[proposed]` / `[approved]` /
+  `[published]` / `[rejected]` tag next to project memories in review, and
+  retrieval ranks reviewed knowledge (`approved` / `published`) above
+  unreviewed outbox drafts — drafts stay findable but never pose as vetted.
+
+## 6. Sync: git is the courier, not the brain
+
+- **Write**: `memory_add` (project scope) → writes the **appdata outbox** and
+  updates the local index. **Never touches the repo, never auto-commits,
+  never auto-pushes.**
+- **Submit** (explicit, your call): `open-memex submit <id...>` → local branch
+  + local commit into `.ai/open-memex/`; push/PR are printed for you (or done
+  by your agent on your Yes).
+- **Pull** **2B**: `open-memex pull` (always explicit, never automatic) → git fetch +
+  fast-forward → scans `.ai/open-memex/*.md` → merges into the local `index.db` by
+  file mtime. Retrieval always goes through SQLite, never walks git.
+- **personal scope**: never syncs (§1 iron rule).
+- **Projects without git**: keep working; project scope degrades to local-only with
+  a clear notice. Nothing breaks.
+
+## 7. Security baseline
+
+- Memory is **data** by default, never instructions — external content (pulled from
+  sync, promoted by others) passes an admission check before it lands; the
+  prompt-injection screen on shared files is heuristic, the real boundary is the
+  data/instruction separation.
+- Every memory carries provenance: `source` + `confidence` + `via` + author.
+  Shared-scope writes go into an audit log.
+- A pre-commit hook scans shared scopes for secrets and guards against history
+  rewrites.
+- `<private>…</private>` sections are stripped at write time; detected secret
+  patterns are masked in place and the write proceeds.
+
+---
+
+*Companion design record: `docs/V2-DESIGN.md` (decisions D1–D24).*

package/docs/USER-GUIDE.zh-CN.md

@@ -0,0 +1,160 @@
+# OpenMemex 用户守则
+
+> 本文档讲的是 open-memex 的**心智模型**：你的记忆住在哪里、怎么流动、谁能看到。
+> in-repo 目录（§2、§6 的写路径）和 propose → promote → resolve 工作流（§5）
+> 已在 `V2-dev-p2b` 分支实现；标有 **2B** 的功能属于 Phase 2B 待实现部分，
+> 其余为 0.3.0 已有行为。
+
+## 一句话
+
+open-memex 是本地优先的记忆层：**Markdown 是真相，SQLite 只是可重建的索引**。索引丢了可以重建，
+Markdown 丢了才是真的丢了。
+
+## 1. 两种 Scope：personal 与 project
+
+每条记忆都属于一个 scope，决定它**能走多远**：
+
+| | personal | project |
+|---|---|---|
+| 存什么 | 关于你的事实：偏好、习惯、跨项目的信息 | 关于项目的事：技术栈、约定、决策、踩过的坑 |
+| 存哪里 | 只在你本机（见 §2） | 本机 + 可进团队共享（见 §2、§6） |
+| 一句话 | **永不离开这台机器** | 可以晋升为团队知识 |
+
+关键词会自动路由（D18）：「记住…/我觉得…/我喜欢…」（我）→ personal；
+「我们认为…/我们决定…/帮我们记住…」（我们）→ project。
+
+## 2. 两个家：appdata 与 repo 目录
+
+| | appdata（书桌） | repo `.ai/open-memex/`（书架） |
+|---|---|---|
+| 位置 | Windows `%APPDATA%/open-memex`，Linux `~/.local/share/open-memex` | 项目根目录下，默认 `.ai/open-memex/`（D23，可配置 `memoryDir`） |
+| 放什么 | `memories/personal/` 个人记忆；project scope **草稿箱（outbox）**；`index.db` 本地索引 | 已提交的 project 记忆（`proposed` 及以上） |
+| 进 git 吗 | 不进 | 进，git 就是它的搬运工 |
+| 索引呢 | `index.db` 可重建，**永远不入库** | 不存索引，用时从 Markdown 重建 |
+
+个人笔记本（personal）永远不上书架。这是铁律，不是配置项。
+
+project 记忆先以**草稿**身份住在 appdata outbox——git 看不见、跟分支无关。
+只有你亲手点名的草稿，才会被 `open-memex submit` 移上书架（§5）。
+一个阶段只住一个地方：submit 成功后 outbox 原件消失；submit 之前，
+repo 里什么都不知道。
+
+## 3. 首轮注入：8 条和 5 条是怎么选出来的
+
+Agent 第一轮发言前，open-memex 会塞一个 `[OPEN-MEMEX]` 上下文块进去，省得每次先调一次搜索。
+默认注入 **project 8 条、personal 5 条**（`maxProjectMemories` / `maxProfileItems`，可调）。
+
+入选标准只有一个：**最近更新优先**（`ORDER BY updated_at DESC`），并过滤掉已撤回/归档、
+解析掉被替代的旧版本。不是"最重要的 N 条"，而是"最近在折腾的 N 条"——
+你刚更新过的东西，最可能跟当前工作相关。
+
+Token 账：每条压成一行（≤240 字符，约 60 token），8 条 ≈ 500 token 上限。
+超过这个数收益递减——长尾靠 `memory_search` 按需查，全塞进首轮反而淹没信号。
+
+调大：`open-memex config set maxProjectMemories 12`
+
+## 4. 后续轮次：什么时候会再搜记忆
+
+首轮注入只发生一次。之后**没有自动重搜机制**——MCP 是 request/response 模式，
+server 不能主动推送，调不调 `memory_search` 全看 model 的判断。引导它的有两处：
+
+- 注入块页脚："Use the `memory_search` tool to look up more."
+- Copilot instructions（`init` 写入的）："问用户以前说过的事之前，先 `memory_search`；
+  先试几个关键词变体，搜不到再问。"
+
+也就是说：当对话触及历史决策、偏好、约定时，model **应该**先搜，但没有任何机制强制。
+这是当前版本的已知缺口——Phase 2C 的原生插件 hooks（如 Claude Code 的
+`UserPromptSubmit`）就是来补这块的。
+
+## 5. 晋升工作流：记忆如何变成团队知识
+
+个人观察变成团队知识只有一条路——**显式晋升，绝不自动同步**：
+
+```
+个人想法 ──propose──▶ 草稿箱 ──submit──▶ proposed ──┬──promote──▶ approved ──promote──▶ 已发布/共享
+                                                    │                         │
+                                                 --reject                  --reject
+                                                    │                         │  （合并前可撤回批准）
+                                                    ▼                         ▼
+                                                 rejected ──resubmit──▶ proposed
+```
+
+- `open-memex propose <id...> --to project`：把一条或多条 personal 记忆**复制**到
+  **appdata 草稿箱**进入评审（`review_state: draft`，每条独立新 id，
+  `derived_from` 指回 personal 原件）。**复制而非移动——personal 原件保留。**
+  全有或全无：id 有错整批回滚。这一步还不碰 repo——草稿箱 git 看不见、跟分支无关。
+  单人开发可用 `--local-approve` 自批。
+- `open-memex sync-status`：看索引**上次同步的时间和触发方**（会话开始、
+  请求、CLI、submit）、草稿箱（待同步）、repo 里的评审状态
+  （`draft / proposed / approved / published / rejected`），以及 repo 里还没
+  commit 的记忆文件。你的 agent 会在会话开始和关键节点跑这个，然后问你
+  哪些草稿（如果有）要同步。
+- `open-memex submit <id...>`：把**你点名的草稿**移入 `<repo>/.ai/open-memex/`，
+  状态变为 `proposed`。它会建 `mem/sync-<timestamp>` 分支（或用 `--onto`
+  留在当前分支，跟代码走同一个 PR），复制文件、改 `review_state`、做一次
+  **本地** git commit——全有或全无、幂等、crash-safe。它打印 `git push` +
+  `gh pr create` 命令；如果你的 agent 已经拿到你这次的 Yes，它会自己走完
+  push 和 PR。PR 默认 base 是当前分支；`--base` 可改到 `main` 或集成支。
+  分支上同 id 但内容不同——**直接中止**，等人裁决，绝不覆盖。
+  - 四个动作分工要分清：**propose 是跨界**（personal → project 草稿箱，
+    唯一跨越"私有/共享"边界的动作）；**submit 把草稿搬进 repo**
+    （outbox → `.ai/open-memex/`，`draft → proposed`）；**promote 只改状态标签**
+    （文件一直在 `.ai/open-memex/` 里没动过，只是 `review_state`
+    从 proposed → approved → published）——它不在目录之间搬文件；
+    **git 负责运输**（push、PR、合并）。
+- 独立的记忆 PR **只含记忆文件，不含代码**，跟代码 PR 分开评审、分开审计。
+  审的是"这条是真的吗？能给全团队看吗？有没有 secret？"——代码 PR 的 CI 不会查这些。
+  也可以搭代码 PR 的车（`submit --onto <branch>`）。
+- "要求修改"不需要命令：PR 开着的时候，作者直接改同一个文件（自己改，
+  或在 chat 里让 agent 改），commit、push。状态一直是 `proposed`，
+  PR 本身就是评审机制。
+- `open-memex promote <id>`：把记忆往阶梯上推一步
+  （`proposed → approved → published`）。`--reject --note "..."` 驳回并附注原因
+  （合并前也可从 `approved` 驳回，即撤回批准）。每次流转都追加到记忆的
+  `review_history`——谁动的、何时、从什么到什么、为什么——PR 关了很久以后
+  还能查到这条评审链。
+  PR 合并后，再跑一次 `promote <id>` 标记为 `published`——或者让下面的
+  `pr-status --apply` 代劳。（project 记忆提升到 org 级是 Phase 4 的事。）
+- **驳回不删任何东西。**文件留在你的分支上，之后怎么处理由人决定：
+  1. **接受**：关 PR、删分支——文件跟着走（本地索引下次 sync 自己清掉）；
+  2. **改完重提**：改文件，跑 `open-memex promote <id> --resubmit`，
+     commit、push——同一个 PR 里继续评审；
+  3. **留作记录**：不动它；它带着 `[rejected]` 标签和你的注记一直可见，
+     团队以后能看到"这个考虑过，为啥没要"。
+- `open-memex pr-status [--apply]`：读当前分支的 GitHub PR，把它的状态映射
+  到每条 in-repo 记忆的评审状态——PR merged → `published`，PR approved →
+  `approved`（`approved_by` = reviewer），"request changes" 只给建议、从不自动
+  驳回。每条记忆保持自己的独立状态：人做出的 `rejected` 不会被 PR 信号覆盖。
+  默认只报告；`--apply` 在本地执行映射的流转（不 push）。团队在 GitHub 上做完
+  评审，这个命令把结论闭环回记忆索引，不用另造评审 UI。
+- `open-memex resolve [id]`：不带参数列出冲突中的记忆文件；带 id 则尝试
+  **字段级 3-way 合并** YAML frontmatter（`tags` 取并集、`updated_at` 取最新、
+  只有一边改了 body 才合）。语义冲突——两边改了同一字段或 body 各改各的——
+  **只报告、不自动解决**：文件原样不动，等人来裁决。
+- `list` / `search` 会在 project 记忆旁显示 `[draft]` / `[proposed]` /
+  `[approved]` / `[published]` / `[rejected]` 标签；检索会把已评审的知识
+  （`approved` / `published`）排在未评审的 outbox 草稿前面——草稿照样能搜到，
+  但不会冒充已审核的结论。
+
+## 6. 同步：git 是搬运工，不是大脑
+
+- **写**：`memory_add`（project scope）→ 写 **appdata 草稿箱**，同时更新本地索引。
+  **不碰 repo、不自动 commit、不自动 push**。
+- **交**（显式，你说了算）：`open-memex submit <id...>` → 本地分支 + 本地 commit
+  进 `.ai/open-memex/`；push/PR 命令打印给你（或你的 agent 拿着你的 Yes 自己做）。
+- **拉** **2B**：`open-memex pull`（必须显式，没有自动）→ git fetch + fast-forward →
+  扫描 `.ai/open-memex/*.md` → 按文件 mtime 合进本地 `index.db`。检索永远走 SQLite，不 walk git。
+- **personal scope**：永远不同步（§1 铁律）。
+- **没 git 的项目**：照常用，project scope 降级为纯本地并明确提示，不会坏掉。
+
+## 7. 安全底线
+
+- 记忆默认是**数据**，不是指令——外来内容（同步拉回的、别人晋升的）入库前要过
+  admission 检查；共享文件的 prompt-injection 筛查只是启发式的，真正的边界是数据/指令分离。
+- 每条记忆带出身证明：`source` + `confidence` + `via` + 作者。共享写操作进 audit log。
+- pre-commit hook 扫描共享 scope 的 secret，防止 history rewrite。
+- `<private>…</private>` 包裹的内容在写入时直接剥离；命中的 secret 模式做掩码后写入继续。
+
+---
+
+*配套设计文档：`docs/V2-DESIGN.md`（D1–D24 决策记录）。*

package/docs/V2-DESIGN.md

@@ -235,7 +235,7 @@ instructions are never candidates.)
 
 ```
 <project-repo>/
-├── .open-memex/            # default; configurable (alt: .ai/memory/)
+├── .ai/open-memex/            # default (D23); configurable (alt: .ai/memory/)
 │   ├── 01K6AB….md           # one memory = one file ("reduces unrelated merge conflicts…")
 │   └── …
 ├── AGENTS.md                # constitution + ONE pointer line to the memory system
@@ -243,9 +243,9 @@ instructions are never candidates.)
 └── docs/                    # human-authored formal docs (ADRs, guides)
 ```
 
-- The in-repo directory name is **configurable** (`memoryDir` in config): default `.open-memex/`
-  (brand clarity, no collisions), alternative `.ai/memory/` for teams that prefer the emerging `.ai/`
-  namespace convention.
+- The in-repo directory name is **configurable** (`memoryDir` in config): default
+  `.ai/open-memex/` (D23 — `.ai/` namespace + brand clarity, no collisions),
+  alternatives `.open-memex/` and `.ai/memory/`.
 - `index.db` is **never committed** — rebuildable from markdown.
 - Org repo layout (Phase 4): `company-memory/{engineering,architecture,decisions,lessons,policies}/…`
 - AGENTS.md pointer: `> Project memory lives in .open-memex/ — query it with memory_search before answering.`
@@ -421,7 +421,7 @@ Zero-config is survival for an open-source project. The opencode plugin remains
   Ships in **`0.3.0-alpha`** (with bin/npx user-friendliness polish per §17 adoption path).
 - **Phase 2B — Team sync.** GitProvider · `propose/promote/resolve` · in-repo dir · 1–2 colleague pilot
   (pilot project selection is maintainer-private, not tracked in this doc).
-  Ships in **`0.3.0-beta`**.
+  Ships in **`0.4.0`** (was labeled `0.3.0-beta` before 0.3.0 shipped as stable).
   Embeddings/rerank run as a **parallel benchmark-gated experiment**, not on the critical path.
 - **Phase 2C — Native agent plugins (candidates, not committed).** Claude Code plugin and/or
   Codex plugin as hook-enhanced paths over the same MCP tool surface (`SessionStart` →
@@ -488,7 +488,7 @@ requirement: personal data never touches third-party services). Benchmarks to tr
 - **D7** — Embeddings are an optional capability, BM25+CJK is the default. *Rationale: zero-setup
   default; no mandatory 100MB download or native dependency.*
 - **D8** — Contested choices become **configurable with a popular default**, not hard-coded.
-  Applies to: in-repo dir name (default `.open-memex/`), CJK tokenizer (default bigram),
+  Applies to: in-repo dir name (default `.ai/open-memex/` per D23), CJK tokenizer (default bigram),
   embeddings model (default `multilingual-e5-small`). *Rationale: the five-AI review split on all
   three; maintainers shouldn't burn decision capital where config suffices.*
 - **D9** — The LAN reference server lives at `examples/remote-server/`. *Rationale: maintainer decision
@@ -597,6 +597,129 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   keeps the old repo-level behavior for teams where everyone uses open-memex.
   The instructions carry a guard clause ("ignore this section when the
   `open-memex` MCP server is not available") as cheap insurance. 2026-09-27.*
+- **D23** — Default in-repo memory dir is `.ai/open-memex/` (configurable via
+  `memoryDir`; rejects absolute paths and `..`). *Rationale: `.ai/` is the
+  emerging convention for AI-local project state; the `open-memex/` leaf keeps
+  brand clarity and avoids collisions with other tools' `.ai/` content.
+  2026-09-27.*
+- **D24** — Project-scope markdown lives in the repo: writes with
+  `scope: project` go to `<projectRoot>/<memoryDir>/` (D23 default
+  `.ai/open-memex/`); `personal` never leaves appdata. Legacy appdata project
+  files are lazily migrated on first write/`syncScope` — the move is guarded by
+  the appdata dir name (which *is* the scope key), so it can only ever migrate
+  the current scope's files. The index's `file_path` is the single locator for
+  reads/deletes (`findMemoryFile`, `forget`); on the near-impossible id
+  collision between locations, the in-repo copy wins. *Rationale: one home per
+  scope, no silent data loss, no repo pollution before first use.* 2026-09-27.*
+- **D25** — Review workflow semantics (`propose` / `promote` / `resolve`,
+  `src/review.ts`): (1) `review_state` frontmatter field
+  (`draft → proposed → approved/rejected → published`, default `draft`) plus
+  `proposed_by` / `approved_by` / `derived_from` / `review_note` provenance;
+  the SQLite index carries `review_state` (schema v6, rebuilt from markdown —
+  D1). (2) `propose` **copies** personal → project (new id, never moves — the
+  personal original stays private); one call takes several ids (one branch,
+  one PR; all-or-nothing — a bad id aborts the whole batch);
+  `--local-approve` skips the PR for solo
+  devs. (3) `promote` advances exactly one step up the ladder
+  (`proposed → approved → published`), `--reject`s with a note (also from
+  `approved`, withdrawing approval before merge), or `--resubmit`s a rejected
+  memory back to `proposed` for another round; `draft` and terminal states
+  refuse. (4) `resolve` lists conflicted memory files, or
+  attempts a field-level 3-way merge from git stages 1/2/3 (`tags` union,
+  `updated_at` takes latest, body merged only when one side changed); semantic
+  conflicts (same field / body changed differently on both sides) are reported
+  and the file is left untouched — **never auto-resolved**. (5) A rejection
+  never deletes anything: the file stays on the author's branch; the human
+  accepts (close PR, delete branch), revises + `--resubmit`s, or keeps it as
+  a `[rejected]` record. (6) No git
+  automation anywhere in the workflow: no branch creation, no commits, no PRs —
+  the commands print the exact next steps for the human. Org-level promotion is
+  Phase 4. *Rationale: the review ladder must be explicit and auditable; the
+  tool assists merging but a human always decides meaning.* 2026-09-27.*
+- **D26** — **Supersedes D24.** Project-scope markdown has two homes, one per
+  lifecycle stage — never silently moved between them. (1) `memory_add` /
+  `memory_propose` with `scope: project` write to the **appdata outbox**
+  (`memories/<project_key>/<id>.md`, `review_state: draft`); the outbox is
+  git-invisible and branch-independent. The D24 lazy migration is deleted —
+  appdata project files are legitimate drafts, not legacy. (2) `open-memex
+  submit <id...>` / `memory_submit` moves user-named drafts into the repo's
+  `<memoryDir>/` (D23), flipping `review_state` to `proposed`: the file now
+  follows branches and PRs. `sync-status` / `memory_status` shows both sides
+  (outbox drafts, repo review states, uncommitted repo files). (3) The move is
+  one-stage-one-place: copy → verify hash → local commit → verify → delete
+  outbox original; re-running is idempotent (identical content skips, different
+  content aborts). `search` prefers the repo copy when both exist; conflicts
+  (same id, different content; push rejected) stop and ask the human — never
+  overwrite. *Rationale: an AI agent drafts constantly; the repo should only
+  ever see what the human explicitly approved for review. The outbox is the
+  agent's desk, the repo dir is the shared table. Approved 2026-09-28.*
+- **D27** — **Revises D25 §6 (no git automation).** `submit` automates the
+  *local* half of the git workflow: create `mem/sync-<timestamp>` (or
+  `--onto` the current branch for code+memory PRs), copy, `git add` only the
+  memory files, local commit, verify. It prints the push + `gh pr create`
+  commands for the human — but an agent that already holds the user's Yes for
+  this sync carries through push and PR creation without re-asking (each step
+  is not a separate approval). Batch submit is all-or-nothing; an empty-branch
+  abort rolls the branch back. *Rationale: the old "no git automation" rule
+  assumed a human at the keyboard; the agent-driven flow needs local mechanics
+  automated while push/PR stay under the user's explicit per-sync Yes/No.
+  Approved 2026-09-28.*
+- **D28** — Memory PR base defaults to the **current branch**; the user may
+  redirect to `main` or the project's integration branch (`--base`). A
+  standalone memory PR and a code+memory PR are both supported — the agent asks
+  which one each time; on "with code" it uses `--onto` and never commits
+  unrelated staged changes. *Rationale: memory usually reviews against the work
+  it describes (current branch); the integration branch is the exception, not
+  the default. Approved 2026-09-28.*
+- **D29** — Every review transition is written to a per-memory audit trail
+  (`review_history`: at/by/from/to/note) — reject / resubmit / approve /
+  publish all append, never overwrite; `propose` and `submit` seed it; merge
+  conflict resolution unions both sides' histories. *Rationale: review is a
+  decision log, not a flag — "who rejected this and why" must be answerable
+  months later. Approved 2026-09-28.*
+- **D30** — Retrieval ranks by review state: approved/published project
+  memories outrank unreviewed content; project drafts/rejected sink to the
+  bottom and are visibly tagged `[draft]` in search/list/inject output, while
+  personal memories (always draft by design) are never demoted or tagged.
+  Explicit search still finds drafts — they are deprioritized, not hidden.
+  *Rationale: reviewed knowledge should win the context window; drafts stay
+  discoverable but never masquerade as vetted. Approved 2026-09-28.*
+- **D31** — Every index sync records when it ran, what triggered it
+  (`session` / `request` / `cli` / `submit`) and its stats, in
+  `<appdata>/sync-state.json`; `sync-status` shows the last sync first.
+  *Rationale: "is my index fresh?" must be answerable without guessing —
+  especially across branch switches where the in-repo dir changes underneath.
+  Approved 2026-09-28.*
+- **D32** — The branch PR's GitHub state maps back onto each in-repo
+  memory's review_state via `pr-status` / `memory_pr_status`: merged PR →
+  published, PR approval → approved with `approved_by` = reviewer login,
+  changes-requested → suggestion only (never auto-rejects). Report by
+  default; `--apply` performs the mapped transitions locally (no push —
+  inside the D27 line). Each memory keeps its own state: a human `rejected`
+  is never overridden by a PR signal. *Rationale: the PR is where the team
+  actually reviews — the mapping closes the loop without inventing new
+  review UI. Approved 2026-09-28.*
+- **D34** — The MCP server sends session-start guidance in the handshake
+  `instructions`: call `memory_status` at session start (and at work
+  checkpoints); if the outbox has drafts, summarize and ask the user which to
+  sync; proactive `memory_add`; `memory_search` before asking about the past;
+  personal never leaves the machine. *Rationale: the init-written instruction
+  files only exist if the user ran `init --client` — the handshake reaches
+  every MCP client at connect time. Still advisory: no MCP consumer offers a
+  hard session-start hook, and we do not claim otherwise. Approved 2026-09-28.*
+- **D35** — "sync memory" (or "同步记忆") is a natural-language trigger for the
+  sync flow: the agent calls `memory_status`, summarizes the outbox drafts, and
+  asks the user which ones to sync — same flow as the session-start proposal,
+  but user-initiated. Taught in the MCP handshake instructions, the
+  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.*
+- **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.*
 
 ## Open Questions
 

package/package.json

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

@@ -80,9 +80,9 @@ try {
   const tools = await req("tools/list", {});
   const names = (tools.result?.tools ?? []).map((t: any) => t.name).sort();
   check(
-    "tools/list has 5 memory tools",
+    "tools/list has 11 memory tools",
     JSON.stringify(names) ===
-      JSON.stringify(["memory_add", "memory_forget", "memory_list", "memory_search", "memory_supersede"]),
+      JSON.stringify(["memory_add", "memory_forget", "memory_list", "memory_pr_status", "memory_promote", "memory_propose", "memory_resolve", "memory_search", "memory_status", "memory_submit", "memory_supersede"]),
     names.join(","),
   );
   const addSchema = tools.result.tools.find((t: any) => t.name === "memory_add").inputSchema;