open-memex 0.6.0 → 0.6.1-alpha.3

package/README.md

@@ -1,141 +1,195 @@
 # open-memex
 
-> A shared organizational memory layer that helps people and AI capture, retain, and reuse institutional knowledge.
+> Persistent memory for your AI coding agents — on your machine, in plain Markdown, shared by every tool you code with.
 
 [![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, …).
+Every AI coding session starts from zero: you re-explain the project, the agent
+rediscovers the same gotchas, and yesterday's decisions vanish when the chat
+ends. open-memex gives your agents a memory that survives the session. Say
+"remember: we deploy on Fridays" once, and next week Copilot, Cursor, opencode,
+or Claude Code already knows — because they all read and write the same local
+memory on your machine.
+
+- **Free and open source** (Apache-2.0). No account, no cloud, no telemetry —
+  everything lives on your machine, in files you can open and edit.
+- **Local-first**: memories are plain Markdown files (the source of truth) with
+  a rebuildable SQLite keyword index. Nothing leaves your machine unless you
+  explicitly share it.
+- **One memory, every agent**: wire up several editors with one command; they
+  share the same memory instead of keeping separate silos.
+
+New here? This README takes you from install to a working memory in about a
+minute. The [concept guide](./docs/CONCEPTS.md) explains the mental model in
+depth once you're up and running.
+
+## Contents
+
+- [Quick start](#quick-start)
+- [Core concepts](#core-concepts)
+- [Which editors, which features](#which-editors-which-features)
+- [Installation](#installation)
+- [Setting up your editor](#setting-up-your-editor)
+- [What `init` changes on your machine](#what-init-changes-on-your-machine)
+- [Capture: how memories get saved](#capture-how-memories-get-saved)
+- [Tools the agent gets](#tools-the-agent-gets)
+- [Memory types](#memory-types)
+- [Team workflow: sharing memories through Git](#team-workflow-sharing-memories-through-git)
+- [Retrieval: how memories come back](#retrieval-how-memories-come-back)
+- [Security & data](#security--data)
+- [Limitations](#limitations)
+- [Upgrading](#upgrading)
+- [Storage layout](#storage-layout)
+- [Config](#config)
+- [CLI reference](#cli-reference)
+- [MCP server](#mcp-server)
+- [Scopes, in detail](#scopes-in-detail)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+- [Project status](#project-status)
+
+## Quick start
+
+You need **Node.js ≥ 22.6** (check with `node -v`). Then:
 
-## Why open-memex?
+```sh
+npm install -g open-memex
+open-memex init
+```
 
-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.
+`init` detects the editors you have installed (VS Code, Cursor, opencode, and
+Visual Studio when your project has a solution file) and connects each one to
+open-memex. Restart your editor afterwards.
 
-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.
+**See it work** (30 seconds):
 
-> No capture, nothing to inherit.
+```sh
+open-memex add "This project deploys on Fridays"
+```
 
-### One memory, every agent
+Now open a new chat in your editor and ask your agent: *"When does this project
+deploy?"* It already knows — no re-explaining. That round trip, capture once and
+recall forever, is the whole product. Everything below is detail.
 
-Most developers don't use one AI tool — they use several on the same machine:
-Copilot in VS Code, Cursor, opencode, Claude Code. Each tool keeps
-its own silo: a decision made in one is invisible to the others.
+Optional but recommended — check everything is wired up:
 
-open-memex is tool-agnostic by design. Memory lives as Markdown + SQLite next
-to your project, and every editor talks to it through the same MCP interface.
-Wire up two, three, five clients with `open-memex init` — they all read and
-write the same memory on that machine. A constraint captured in VS Code is respected in
-opencode; a lesson learned in Cursor shows up in Claude Code.
+```sh
+open-memex doctor
+```
 
-> Your memory belongs to you — not to your tools.
+## Core concepts
 
-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.
+Three ideas explain almost everything open-memex does.
 
-## How it compares
+**1. Two scopes: `project` and `personal`.**
+Every memory belongs to one of two places:
 
-| | 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 |
-| Works across AI tools | Yes — any MCP client (same machine) | Per-integration | No | No |
+- **project** — knowledge about one codebase (decisions, constraints, lessons).
+  Scoped to the current repo automatically; you never set this up by hand.
+- **personal** — knowledge about *you* (preferences, habits) that applies in
+  every project. It lives only on this machine and can never be shared into a
+  repo.
 
-- **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
+Facts about you ("I prefer concise diffs") go to `personal`; everything else
+defaults to the current project.
 
-## Architecture
+**2. Capture → recall.**
+Memories are saved as small Markdown files, one fact each. On the first turn of
+every new session, open-memex hands your agent the most relevant ones
+automatically, so it starts the session already knowing them. The agent can also
+search the full memory on demand. You never have to "load" anything yourself.
 
-```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.
-```
+**3. Your files, your rules.**
+The Markdown files are the source of truth — open them, edit them, delete them,
+grep them. The SQLite index next to them is just a search accelerator and
+rebuilds from the files at any time (`open-memex reindex`). Team sharing, when
+you want it, goes through the same review flow as code: nothing is shared
+automatically (see [Team workflow](#team-workflow-sharing-memories-through-git)).
 
-## Installation
+## Which editors, which features
 
-### Requirements
+open-memex talks to editors two ways: a native **opencode plugin**, and a
+standard **MCP server** that any MCP-capable editor can use. (MCP — Model
+Context Protocol — is the open standard editors use to give agents extra tools;
+open-memex appears in your editor as a set of `memory_*` tools.) What you get
+depends on which path an editor uses:
 
-- **Node.js ≥ 22.6** (`open-memex doctor` verifies this for you)
+| Editor | Setup | Tools | Session-start recall | Keyword auto-capture |
+|---|---|---|---|---|
+| opencode (native plugin, recommended) | `open-memex init --client opencode --global` | 5 core tools | Built in — first turn of every session | Yes — `remember …`, `记住…` |
+| VS Code (Copilot) | `open-memex init --client vscode` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
+| Cursor | `open-memex init --client cursor` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
+| Claude Code | `claude mcp add open-memex -- open-memex mcp` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
+| Visual Studio 2022 17.14+ / 2026 | `open-memex init --client visualstudio` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
+| Codex and other MCP clients | `open-memex mcp --print-config` | All 11 via MCP | Via MCP guidance* | No — the agent saves when you ask |
+
+\* MCP has no hard session-start hook, so open-memex sends the agent guidance in
+the MCP handshake (including how many drafts are waiting) and `init` writes the
+fuller version into the editor's instruction files. In practice agents follow
+it; the opencode plugin is the only path with true built-in first-turn
+injection. The [Tools](#tools-the-agent-gets) section lists the 5 core tools
+and the 6 extra workflow tools, so the "5 vs 11" split is explicit.
+
+All editors on the same machine read and write the **same** memory — a
+constraint captured in VS Code is respected in opencode; a lesson learned in
+Cursor shows up in Claude Code. (Different machines do not sync automatically;
+see the [FAQ](#faq).)
+
+`init` also installs an **Agent Skill** (a short instruction file that teaches
+skill-aware agents to use the CLI) for VS Code and Cursor, and for opencode in
+per-project MCP mode. With the opencode native plugin wired, no skill is
+installed there — the plugin already provides the memory tools, and a second
+instruction set only made agents chatty.
 
-### Step 1 — Install the CLI
+## How it compares
 
-#### Stable vs alpha
+| | open-memex | Instruction files (`CLAUDE.md`, `AGENTS.md`, …) | Cloud memory services | Chat history |
+|---|---|---|---|---|
+| Where it lives | Your machine + your repos | In the repo | Vendor servers | Gone when the chat ends |
+| Who maintains it | Captured as you work; you review | You write and update by hand | The service | — |
+| Works across AI tools | Yes — any MCP client (same machine) | One file per tool convention | Per-integration | No |
+| Review before sharing | Yes — outbox + pull request | Yes — it's just files | Varies | No |
+| Human-readable | Plain Markdown files | Yes | Dashboard / API | No |
 
-**Stable** (recommended for most users) — the `latest` tag:
+Instruction files are great for a handful of standing rules — keep using them
+(open-memex can even draft one from your memories; see `distill-agents` below).
+open-memex covers the growing pile of decisions, lessons, and preferences that
+no one remembers to write down.
 
-```sh
-npm install -g open-memex
-```
+## Installation
 
-This installs the `0.5.1` stable release.
+### Requirements
 
-**Alpha** (bleeding edge, for testers) — the `alpha` tag:
+- **Node.js ≥ 22.6** (`open-memex doctor` verifies this for you)
 
-```sh
-npm install -g open-memex@alpha
-```
+### Install the CLI
 
 ```sh
-open-memex init
+npm install -g open-memex
 ```
 
-The install isn't complete until you run `open-memex init` — it wires up your editors (VS Code, Cursor, opencode, and Visual Studio for solution projects).
-
-See what's published:
-
-```sh
-npm view open-memex version         # latest stable
-npm view open-memex@alpha version   # latest alpha
-```
+That's the stable release. Installing the package may print a reminder to run
+`open-memex init` — the editor wiring is a separate step (see
+[Setting up your editor](#setting-up-your-editor)), so don't worry if you
+don't see the reminder; just run `init` next.
 
-Alpha builds may have rough edges — bug reports are welcome.
+Two alternatives:
 
-**No install — run via npx:**
+- **No install — run via npx:** `npx -y open-memex <command>` runs any command
+  without installing (e.g. `npx -y open-memex init --client vscode`). Slower to
+  start, nothing to uninstall.
+- **Alpha builds** (newest features, rougher edges, for testers):
+  `npm install -g open-memex@alpha`. Check what's published with
+  `npm view open-memex version` (stable) and `npm view open-memex@alpha version`
+  (alpha).
 
-```sh
-npx -y open-memex <command>         # e.g. npx -y open-memex init --client vscode
-npx -y open-memex@alpha <command>  # alpha line, no install
-```
+If `open-memex` isn't found after installing, your PATH needs attention — see
+[Troubleshooting](#troubleshooting).
 
-**From source** (bleeding edge, `main` branch):
+### From source (for contributors)
 
 ```sh
 git clone -b main https://github.com/stoneskin/open-memex.git
@@ -144,38 +198,10 @@ npm install
 node --experimental-strip-types src/cli.ts <command>
 ```
 
-#### "`open-memex` is not recognized" — PATH setup
+## Setting up your editor
 
-A global `npm install -g` puts the `open-memex` launcher in npm's global bin folder.
-If your terminal can't find it, that folder isn't on your `PATH`:
-
-1. Find the folder: `npm config get prefix`
-   - **Windows:** the launcher (`open-memex.cmd`) sits directly in that folder, e.g.
-     `C:\Users\<you>\AppData\Roaming\npm`
-   - **macOS / Linux:** it's in `<prefix>/bin`, e.g. `/usr/local/bin` or
-     `~/.nvm/versions/node/v22.x.x/bin`
-2. Add it to `PATH`:
-   - **Windows:** Settings → System → About → Advanced system settings →
-     Environment Variables → add the folder to the *User* `Path` → **restart the
-     terminal**. Verify with `where open-memex`.
-   - **macOS / Linux:** add `export PATH="$(npm prefix -g)/bin:$PATH"` to
-     `~/.zshrc` (or `~/.bashrc`), restart the shell, verify with
-     `command -v open-memex`.
-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):
+Run `init` from your **project root** (the top folder of the repo you're working
+in) so the project scope resolves to that repo:
 
 ```sh
 open-memex init --yes
@@ -183,41 +209,22 @@ open-memex init --yes
 npx -y open-memex init --yes
 ```
 
-With no `--client`, `init` **detects your installed editors and wires them all**
-— user-level where the editor supports it (VS Code / Cursor MCP config, opencode
-native plugin), so one init covers every project. Visual Studio joins in when the
-project has a solution file. It also installs an **Agent Skill** (`open-memex`)
-into each editor's skills folder (not opencode when the native plugin is wired —
-the plugin already provides memory tools), so skill-aware agents can use your memory via
-the CLI with no MCP configuration. Prefer to pick a single editor? Pass `--client`:
-
-> **Two different "globals" — don't mix them up.**
-> - `npm install -g open-memex` installs the *package* globally: it puts the
->   `open-memex` command on your PATH.
-> - `init --global` writes the *editor config* at user level instead of the
->   project: init once, the wiring works in every project. It works the same
->   whether the package was installed globally or run via npx.
-
-Installing the package also prints a reminder to run `open-memex init` — the
-wiring is a separate step. And if you run bare `open-memex` on a machine where
-init never completed, it offers to run it for you (only on an interactive
-terminal; scripts and CI just see the usual usage text). When init finishes,
-it prints one concrete next step — save a memory with `open-memex add`, then
-ask your agent to recall it — so a first-time user sees what "it works" looks
-like.
+`--yes` accepts the recommended defaults for everything `init` asks about
+(editors to wire, auto-capture, first-turn recall). Leave it off if you want to
+answer each question. With no `--client`, `init` detects your installed editors
+and wires them all — one init covers every project. Prefer a single editor?
+Pass `--client`:
 
 **VS Code** (Copilot):
 
 ```sh
 open-memex init --client vscode
-# …or without installing the package first:
-npx -y open-memex init --client vscode
 ```
 
-Wires the project-level `.vscode/mcp.json` and user-level Copilot instructions,
-then reload the window and confirm the `open-memex` server is started in Copilot
-Chat's MCP panel. On a TTY, `init` asks whether the MCP config should be
-per-project or user-level instead of guessing; `--global` forces user-level.
+Writes the MCP server entry; reload the window afterwards and confirm the
+`open-memex` server is started in Copilot Chat's MCP panel. By default the
+server entry goes to VS Code's *user-level* config (works in every project);
+`init` can also write a project-level `.vscode/mcp.json` if you prefer.
 
 **Cursor:**
 
@@ -225,24 +232,8 @@ per-project or user-level instead of guessing; `--global` forces user-level.
 open-memex init --client cursor
 ```
 
-Same shape as VS Code: project-level `.cursor/mcp.json` by default, user-level
-with `--global` (or when `init` asks on a TTY), plus user-level Copilot
-instructions.
-
-**One-time setup for all projects (VS Code / Cursor):**
-
-```sh
-open-memex init --client vscode --global --yes
-```
-
-Writes the server entry to the editor's *user-level* MCP config
-(`%APPDATA%\Code\User\mcp.json` on Windows,
-`~/Library/Application Support/Code/User/mcp.json` on macOS,
-`~/.config/Code/User/mcp.json` on Linux; `~/.cursor/mcp.json` for Cursor)
-instead of the project — init once, the server starts in every project.
-A per-project `.vscode/mcp.json` still wins if a project defines its own.
-If the user-level file has comments in it (VS Code accepts JSONC), `init` leaves
-the file untouched and prints the exact snippet to paste in by hand.
+Same shape as VS Code: user-level MCP config by default, project-level
+`.cursor/mcp.json` on request, plus Copilot-style instructions.
 
 **opencode** (native plugin — recommended):
 
@@ -250,12 +241,11 @@ the file untouched and prints the exact snippet to paste in by hand.
 open-memex init --client opencode --global --yes
 ```
 
-Merges `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` into your
-user-level `~/.config/opencode/opencode.json` (or `opencode.jsonc` if that is
-the file you already have) — one-time, every project picks it
-up, no per-project init. You get keyword auto-capture and first-turn context
-injection on top of the tools. (A config file with comments is left untouched —
-add the `plugin` line by hand in that case.)
+Merges the native plugin into your user-level `~/.config/opencode/opencode.json`
+(or `opencode.jsonc` if that's the file you already have) — one-time, every
+project picks it up, no per-project init. You get the 5 core tools, keyword
+auto-capture, and first-turn context injection. (A config file with comments is
+left untouched — `init` prints the line to add by hand.)
 
 **opencode** (as a plain MCP consumer):
 
@@ -263,8 +253,9 @@ add the `plugin` line by hand in that case.)
 open-memex init --client opencode
 ```
 
-Writes project-level `opencode.jsonc` (`type: "local"`). Needed only if you
-prefer plain MCP over the native plugin.
+Writes a project-level `opencode.jsonc` with the MCP server. Only needed if you
+prefer plain MCP over the native plugin — you give up keyword capture and
+built-in injection.
 
 **Claude Code** (from your project root):
 
@@ -279,97 +270,144 @@ claude mcp add open-memex -- open-memex mcp
 open-memex init --client visualstudio
 ```
 
-Writes solution-level `.mcp.json` and user-level Copilot instructions. Requires
-Visual Studio 2022 17.14+ or Visual Studio 2026 (**Windows-only**). Visual Studio
-also auto-discovers `.vscode/mcp.json` and `.cursor/mcp.json`, so the VS Code setup
-above works too.
+Writes solution-level `.mcp.json`. Requires Visual Studio 2022 17.14+ or Visual
+Studio 2026 (Windows-only). Visual Studio also auto-discovers `.vscode/mcp.json`
+and `.cursor/mcp.json`, so the VS Code setup above works too.
 
 **Codex:** no `init` client yet — add the server manually via
 `open-memex mcp --print-config` as a starting point (`[mcp_servers]` in
 `config.toml`, or `codex mcp add`).
 
-**Remove the wiring:**
+### One-time setup for all projects (VS Code / Cursor)
 
 ```sh
-open-memex uninstall --yes
+open-memex init --client vscode --global --yes
 ```
 
-Reverses `init` — removes the MCP server entry, the opencode plugin line, and
-the open-memex section of the Copilot instructions. With no `--client` it cleans
-up every detected editor (project-level and user-level wiring); `--global`
-limits the cleanup to user-level. Your memories are never touched.
-
-`init` notes:
-
-- With no `--client`, `init` auto-detects installed editors (VS Code via `code`
-  on `PATH` / install location / existing user config; Cursor via `cursor` on
-  `PATH` or `~/.cursor`; opencode via `opencode` on `PATH` or its config dir;
-  Visual Studio when the project has a `.sln`) and wires them all — user-level
-  where supported, so one init covers every project.
-- `--global` writes the MCP server entry to the editor's user-level config
-  (VS Code / Cursor) — one init for all projects. For opencode, `--global`
-  wires the native plugin at user level (no per-project init needed);
-  Visual Studio stays solution-level by design.
-- The Copilot memory instructions default to **user-level**
-  (`~/.copilot/copilot-instructions.md`; `%USERPROFILE%\copilot-instructions.md`
-  for Visual Studio) — they apply to all your projects and are never checked
-  into a repo, so teammates without open-memex see nothing and nothing breaks
-  for them. `--instructions project` writes `.github/copilot-instructions.md`
-  instead, for teams where everyone uses open-memex.
-- On a terminal it shows the detected editors, asks you to confirm wiring them
-  all (or pick one), and asks whether to enable keyword auto-capture and
-  first-turn memory injection. `--yes` accepts the defaults; scripts /
-  non-TTY never prompt and wire every detected editor.
-- Existing config files are **merged, never clobbered** — re-running is safe.
-  `--force` overwrites.
+> **Two different "globals" — don't mix them up.**
+> - `npm install -g open-memex` installs the *package* globally: it puts the
+>   `open-memex` command on your PATH.
+> - `init --global` writes the *editor config* at user level instead of the
+>   project: init once, the wiring works in every project. It works the same
+>   whether the package was installed globally or run via npx.
+
+The `--global` form writes the server entry to the editor's *user-level* MCP
+config (`%APPDATA%\Code\User\mcp.json` on Windows,
+`~/Library/Application Support/Code/User/mcp.json` on macOS,
+`~/.config/Code/User/mcp.json` on Linux; `~/.cursor/mcp.json` for Cursor)
+instead of the project — init once, the server starts in every project.
+A per-project `.vscode/mcp.json` still wins if a project defines its own.
+If the user-level file has comments in it (editors accept JSONC), `init` leaves
+the file untouched and prints the exact snippet to paste in by hand.
+
+### `init` behavior notes
+
+- Existing config files are **merged, never overwritten** — re-running `init`
+  is safe. `--force` rewrites our entries.
 - With no durable `open-memex` on `PATH` (e.g. one-shot npx), `init` writes an
   `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.
+- On an interactive terminal, `init` shows the detected editors and asks you to
+  confirm; scripts and CI never prompt and wire every detected editor.
+- If you run bare `open-memex` on a machine where init never completed, it
+  offers to run it for you (interactive terminals only).
 
-### Step 3 — Verify it works
+### Remove the wiring
 
 ```sh
-open-memex doctor
+open-memex uninstall --yes
+```
+
+Reverses `init` — removes the MCP server entry, the opencode plugin line, the
+Agent Skill, and the open-memex section of the editor instructions. With no
+`--client` it cleans up every detected editor; `--global` limits the cleanup to
+user-level wiring. Your memories are never touched.
+
+## What `init` changes on your machine
+
+Everything `init` writes, in one place:
+
+- **Memory data** (created on first use, not by `init` itself):
+  `%APPDATA%\open-memex\` on Windows, `~/.local/share/open-memex/` on
+  macOS/Linux — your memory files and the search index. Nothing here is ever
+  modified by `uninstall`.
+- **Editor wiring** (removed by `open-memex uninstall`):
+  - opencode: a `"plugin"` entry merged into
+    `~/.config/opencode/opencode.json` (or `.jsonc`). Stale `my-o-memory`
+    entries from before the rename are removed at the same time.
+  - VS Code / Cursor: an `open-memex` server entry in the user-level or
+    project-level MCP config, plus an open-memex section in the Copilot
+    instructions (user-level `~/.copilot/copilot-instructions.md` by default;
+    `--instructions project` writes `.github/copilot-instructions.md` in the
+    repo instead, for teams where everyone uses open-memex).
+  - Visual Studio: `.mcp.json` next to your solution.
+  - Agent Skill: a `skills/open-memex/` folder for VS Code
+    (`~/.copilot/skills/`), Cursor (`~/.cursor/skills/`), or opencode in
+    per-project MCP mode (`~/.config/opencode/skills/`).
+- **Your repo**: nothing. Files only appear in a repo when you explicitly run
+  `submit` (see Team workflow) — a local commit, never an automatic push.
+
+Files with comments (JSONC) are never rewritten: `init` prints the exact
+snippet to paste instead.
+
+## Capture: how memories get saved
+
+Three ways memories get in:
+
+- **Keyword triggers** (opencode native plugin only): say `remember …`,
+  `note that …`, `don't forget …`, `TIL …`, `save this …` — or in Chinese
+  `记住…` / `记一下` / `记录一下` / `别忘了…` — and the sentence is captured
+  without any tool call. Captures land in the current **project** by default;
+  phrases that signal "this is about me" — `remember for me …`, `记住我…`,
+  `替我记…`, `我觉得…`, `我喜欢…` — go to **personal** instead, and
+  team-context phrases (`我们决定…`, `帮我们记住…`) stay in project.
+- **The agent saves it**: in any editor, ask your agent to remember something
+  (or it saves on its own when you state a fact worth keeping) — it calls
+  `memory_add`. The routing above is a heuristic; you can always say "save this
+  to my personal memory" or use the CLI with `--scope` to be explicit.
+- **The CLI**: `open-memex add "…"` with optional `--scope` / `--tags` / `--type`.
+
+**Redaction.** Wrap anything sensitive in `<private>…</private>` and it is
+stripped before saving. Recognized secrets (API keys, tokens, high-entropy
+credentials) are masked in place — the first 4 characters are kept so you can
+tell *which* key it was, the rest is replaced — and the memory is still saved.
+Preview exactly what a message would capture, safely, any time:
+
+```sh
+open-memex capture --dry-run "…"
 ```
 
-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 eleven tools must show up.
+If a secret slips through anyway, `open-memex forget <id>` deletes the memory.
 
 ## Tools the agent gets
 
+The MCP server exposes eleven tools; the opencode native plugin exposes the
+five core ones (marked ●). The other six are the team-review workflow tools —
+they only matter once you share memories through Git.
+
 | Tool | What it does |
 |---|---|
-| `memory_add`       | Save a fact, preference, decision, note |
-| `memory_search`    | Keyword search (BM25) across project + personal memories |
-| `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
-
-- **Keyword triggers** in user messages (opencode native plugin): `remember …`,
-  `note that …`, `don't forget …`, `TIL …`, `save this …`, plus Chinese
-  `记住…` / `记一下` / `记录一下` / `别忘了…`.
-  Scope routing: first-person singular goes **personal** (`remember for me`,
-  `记住我…`, `替我记…`, `我觉得…`, `我喜欢…`); first-person plural goes to the
-  current **project** scope (`我们认为…`, `我们决定…`, `帮我们记住…`).
-- **Explicit tool calls** by the agent (via `memory_add`)
-- **Redaction**: content inside `<private>…</private>` tags is stripped; detected
-  secrets (API keys, tokens, high-entropy credentials) are masked in place — first
-  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_add`       | Save a fact, preference, decision, note |
+| ● `memory_search`    | Keyword search (BM25) across project + personal memories |
+| ● `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 |
+
+So an MCP-connected editor always has the full set; opencode's plugin covers
+capture and recall, and anything workflow-shaped goes through the CLI or an
+MCP-connected editor.
 
 ## Memory types
 
-Eleven types — `type` says what the memory is, `tags` say what it's about:
+Every memory has a `type` (what it is) and `tags` (what it's about). Eleven
+types are built in:
 
 | Type | Captures |
 |---|---|
@@ -385,60 +423,119 @@ Eleven types — `type` says what the memory is, `tags` say what it's about:
 | `observation` | Something noticed, not yet a conclusion |
 | `reference` | A pointer to the authoritative doc (no copying) |
 
-## Team memory workflow
+`--type` accepts any string, but sticking to the built-in set keeps session-start
+labels, search, and `distill-agents` output predictable.
+
+## Team workflow: sharing memories through Git
 
-Personal notes stay private. Project knowledge follows an explicit, reviewable
-pipeline — nothing is shared automatically:
+**Working solo? You can skip this section** — everything above is the whole
+product for one person. Nothing below ever happens automatically.
+
+Personal notes stay private. Project knowledge, when you choose to share it,
+follows an explicit, reviewable pipeline shaped like code review:
 
 ```
 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.
+2. **Review** — drafts wait in a local outbox (on your machine, invisible to
+   git); `open-memex sync-status` — or just 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.
+   with a local commit on your current branch. open-memex never pushes on its
+   own; it prints the push + PR commands, and an agent holding your explicit
+   yes can carry them out.
 4. **PR review** — memories are plain Markdown; reviewers approve, request
-   changes, or reject through the normal branch/PR process (`promote`,
-   `pr-status`, `resolve`).
+   changes, or reject through the normal branch/PR process.
 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).
+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.
+
+## Retrieval: how memories come back
+
+On the first turn of every session, open-memex injects an `[OPEN-MEMEX]` block
+into the agent's context with the most recent project memories (default: top 8)
+and your personal preferences (default: top 5). It looks like this:
+
+```text
+[OPEN-MEMEX]
+
+User profile / preferences:
+- I prefer concise diffs
+
+Project knowledge (my-repo):
+- [decision] We deploy on Fridays; the release train leaves at 10:00
+
+Use the `memory_search` tool to look up more. Use `memory_add` to save new facts.
+Do not mention this block to the user unless asked.
+```
+
+It's a snapshot, not the whole memory — the agent can call `memory_search` any
+time for the rest. Both top-N counts are configurable (see [Config](#config)).
+For MCP clients this block is delivered as handshake guidance the agent follows;
+the opencode plugin injects it directly on the first turn.
 
 ## 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.
+- **Local-first:** everything lives on your machine (`%APPDATA%\open-memex` on
+  Windows, `~/.local/share/open-memex` on macOS/Linux) 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.
+- **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
+## Limitations
+
+Honest edges, so nothing surprises you:
+
+- **Keyword search, not semantic.** Retrieval is BM25 keyword matching: search
+  finds the words you saved, not paraphrases. (Plain questions are fine —
+  "how do we…" / "请问…" wording is filtered out before matching, so asking
+  naturally doesn't dilute the results.) No embedding model is ever
+  downloaded without your explicit opt-in.
+- **One machine.** Editors on the same machine share memory; there is no
+  cross-machine sync. `export` / `import` bundles (below) move memory between
+  machines manually.
+- **A snapshot, not everything.** Session-start recall is a top-N snapshot (8
+  project + 5 personal by default); older memories are one `memory_search`
+  away, but they are not all in context at once.
+- **MCP guidance is advisory.** Outside opencode, proactive capture and recall
+  depend on the agent following the handshake instructions — there is no hard
+  session-start hook in MCP. The tools themselves always work when called.
+- **Capture routing is a heuristic.** Personal-signal phrases (`remember for
+  me …`, `我喜欢…`) go to personal; everything else defaults to the current
+  project. When it guesses wrong, say the scope out loud or use `--scope` in
+  the CLI.
+
+## Upgrading
 
-- **project** — scoped to the current repo (keyed off the git origin URL hash, or the cwd if no remote). Default for new memories.
-- **personal** — global across all your projects, this machine only, never synced. Use for personal preferences. (v1 called this `user`; `migrate --to-v2` renames it.)
-
-See [docs/SCOPES.md](./docs/SCOPES.md) for the full scope model: key derivation, migration, visibility, reserved names.
-
-## Retrieval
+```sh
+npm install -g open-memex@latest   # or @alpha
+```
 
-On the first turn of every session, `open-memex` injects a `[OPEN-MEMEX]` block into the system prompt containing top-N recent project memories + top-N personal preferences. The agent can also call `memory_search` on demand.
+Your editor configs point at the installed `open-memex` command, so upgrades
+need no re-wiring. After a major upgrade, run `open-memex init --force` once to
+refresh the installed Agent Skill and instruction files with the latest wording.
+If you installed from source or moved the package, `--force` also re-points the
+opencode plugin path.
 
 ## Storage layout
 
 ```
 %APPDATA%\open-memex\               (Windows)
-$XDG_DATA_HOME/open-memex/          (Linux/macOS)
+~/.local/share/open-memex/          (macOS/Linux; $XDG_DATA_HOME if set)
 ├── index.db                         # SQLite FTS5 index (rebuildable)
 └── memories/
     ├── personal/
@@ -447,16 +544,21 @@ $XDG_DATA_HOME/open-memex/          (Linux/macOS)
         └── <id>.md
 ```
 
-Each `.md` file has v2 YAML frontmatter (`id, scope, scope_key, visibility, role, type,
-importance, status, tags, created_at, updated_at, schema_version`, …) followed by the
-memory content. You can edit them by hand — the plugin re-syncs on startup by comparing
-file mtimes. Markdown is the source of truth; the SQLite index is derived and rebuildable
-(`open-memex reindex`).
+Each `.md` file is one memory: YAML frontmatter (`id, scope, type, tags,
+created_at, schema_version`, …) followed by the content. You can edit them by
+hand — the index re-syncs from the files, and Markdown is always the source of
+truth (`open-memex reindex` rebuilds the index from scratch).
+
+Once you `submit`, project memories also live as Markdown files under
+`<repo>/.ai/open-memex/` (configurable via `memoryDir`), where they travel with
+branches and PRs like any other file.
 
 ## Config
 
-Optional file at `~/.config/opencode/open-memex.jsonc` (override path with
-`MY_O_MEMORY_CONFIG`; override storage root with `MY_O_MEMORY_HOME`).
+Settings live in `~/.config/opencode/open-memex.jsonc` — the `opencode` in the
+path is historical; this one file is shared by every client. Override the config
+path with `MY_O_MEMORY_CONFIG` and the storage root with `MY_O_MEMORY_HOME`
+(legacy environment names from before the rename, still honored).
 
 Defaults:
 
@@ -471,22 +573,19 @@ Defaults:
 }
 ```
 
-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:
+`open-memex config` prints the effective config (defaults + file). Change a
+setting after install:
 
 ```sh
 open-memex config set keywordCaptureEnabled false
 open-memex config set maxProjectMemories 12
+open-memex config set sync.autoPull true   # best-effort pull at MCP session start
 ```
 
 Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
-`keywordCaptureEnabled`, `logLevel`, `memoryDir`. Full design: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
+`keywordCaptureEnabled`, `logLevel`, `memoryDir`, and `sync.autoPull` (a dotted
+key that writes into the nested `sync` object). Full design:
+[docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
 
 ## CLI reference
 
@@ -499,6 +598,7 @@ open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [
 open-memex config                                  # print effective config
 open-memex config set <key> <value>                # change a setting
 open-memex doctor                                  # environment health check
+open-memex audit                                   # memory health check (duplicates, stale, broken chains)
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # preview keyword capture
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
 open-memex --help      # this reference
@@ -509,25 +609,25 @@ open-memex --version   # installed version
 Memory operations:
 
 ```sh
-open-memex add "This repo uses better-sqlite3" --type project-config
+open-memex add "This repo uses better-sqlite3" --type fact
 open-memex search "auth flow"
+open-memex search "auth flow" --explain   # show FTS expression, scores, lifecycle-hidden counts
 open-memex list --scope project
 open-memex supersede <id> "Updated content"
 open-memex status <id> deprecated
 open-memex forget <id>
 ```
 
-Team review workflow (Phase 2B — two homes, one per stage):
+Team review workflow (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 server also tells the agent on its own: at
-session start the handshake reports how many drafts are waiting, and every
-memory-changing tool result carries the current count when it is non-zero.
+only drafts you approve 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 server also tells the agent on its own: at session start the
+handshake reports how many drafts are waiting, and every memory-changing tool
+result carries the current count when it is non-zero.
 
 ```sh
 open-memex sync-status
@@ -544,8 +644,9 @@ open-memex submit <id...> [--branch <name>] [--base <branch>]
 # 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.
+# (agent full-chain path). Default PR base is the current branch (memory
+# PRs stack onto your working branch); --base redirects it to main or
+# wherever you review.
 
 open-memex pr-status [--apply]
 # read the branch's GitHub PR and map its state onto each in-repo memory:
@@ -581,8 +682,8 @@ open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N]
 # (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 distillation guidance) so agents reading
-# AGENTS.md learn to propose distilled captures when a task ends.
+# "memory hygiene" section so agents reading AGENTS.md learn to propose
+# distilled captures when a task ends.
 
 open-memex propose <id...> --to project [--local-approve]
 # propose one or several personal memories at once (one branch, one PR);
@@ -612,119 +713,177 @@ Maintenance:
 open-memex where        # show storage + config paths
 open-memex scopes       # list project scopes with memory counts
 open-memex reindex      # rebuild the SQLite index from markdown
-open-memex migrate --to-v2 [--dry-run]   # v1 data → v2
+open-memex audit        # memory health: duplicate pairs, stale memories, broken chains
+open-memex migrate --to-v2 [--dry-run]   # v1 data → v2 (renames user scope to personal)
 ```
 
-The CLI runs under Node 22. From a source checkout it uses the built-in experimental
-TypeScript loader (no build step); the published npm package ships pre-compiled JS
-(`npm run build` at publish time). From a source checkout, prefix every command with
-`node --experimental-strip-types src/cli.ts` (or `npm run cli -- <command>` for
-simple cases — npm swallows unknown `--flag` args, so prefer direct `node`).
+The CLI runs under Node 22. From a source checkout it uses the built-in
+experimental TypeScript loader (no build step); the published npm package ships
+pre-compiled JS (`npm run build` at publish time). From a source checkout,
+prefix every command with `node --experimental-strip-types src/cli.ts` (or
+`npm run cli -- <command>` for simple cases — npm swallows unknown `--flag`
+args, so prefer direct `node`).
 
 ## MCP server
 
-The same eleven memory tools over the Model Context Protocol via a stdio server —
+The same 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 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
-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 server sends session-start
-> guidance in the MCP handshake `instructions` (including the live outbox draft
-> count at session start, plus the pending count appended to memory-changing
-> tool results when non-zero), 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
-
-**`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.
-
-**`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;
-`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 distillation in the MCP handshake + init instructions (the agent proposes
-1–3 captures when a task ends, the human decides); 1–2 colleague pilot.
-
-**`0.5.0` (stable):** init UX pass — `init --global` writes the editor wiring
-once at user level (D45); bare `init` auto-detects installed editors and wires
-them all (D46); non-JSON configs are left untouched with a paste-ready snippet
-instead of an error (D47); `uninstall` reverses `init` without touching memory
-data (D48); empty config files are treated as blank, not corrupt (D49).
-"One memory, every agent": every editor on the same machine reads and writes
-the same memory through one MCP interface.
-
-**`0.5.1` (stable):** `--help` accuracy fixes — the `mcp` help text now states the
-server exposes 11 tools (a superset of the opencode plugin's five memory tools),
-and install hints point at the stable line instead of `@alpha` (F27).
-
-**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).
+The project scope is resolved from the process working directory, so configure
+the 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 injection.
+> Proactive memory use depends on the agent's instructions: the server sends
+> session-start guidance in the MCP handshake `instructions` (including the
+> live outbox draft count at session start, plus the pending count appended to
+> memory-changing tool results when non-zero), and `init` writes the fuller
+> version into the editor's instruction files. Both are advisory — no MCP
+> consumer offers a hard session-start hook.
+
+## Scopes, in detail
+
+- **project** — scoped to the current repo, keyed off the git origin URL hash
+  (so clones of the same repo share a scope), or off the cwd path if there is
+  no remote. Default for new memories.
+- **personal** — global across all your projects, this machine only, never
+  synced. Use for personal preferences. (v1 called this `user`;
+  `migrate --to-v2` renames it.)
+
+See [docs/SCOPES.md](./docs/SCOPES.md) for the full scope model: key derivation,
+migration, visibility, reserved names. The [concept guide](./docs/CONCEPTS.md)
+walks through the mental model end to end.
+
+## Troubleshooting
+
+**`open-memex` is not recognized / command not found.**
+A global `npm install -g` puts the `open-memex` launcher in npm's global bin
+folder. If your terminal can't find it, that folder isn't on your `PATH`:
+
+1. Find the folder: `npm config get prefix`
+   - **Windows:** the launcher (`open-memex.cmd`) sits directly in that folder,
+     e.g. `C:\Users\<you>\AppData\Roaming\npm`
+   - **macOS / Linux:** it's in `<prefix>/bin`, e.g. `/usr/local/bin` or
+     `~/.nvm/versions/node/v22.x.x/bin`
+2. Add it to `PATH`:
+   - **Windows:** Settings → System → About → Advanced system settings →
+     Environment Variables → add the folder to the *User* `Path` → **restart
+     the terminal**. Verify with `where open-memex`.
+   - **macOS / Linux:** add `export PATH="$(npm prefix -g)/bin:$PATH"` to
+     `~/.zshrc` (or `~/.bashrc`), restart the shell, verify with
+     `command -v open-memex`.
+3. No admin rights / don't want to touch `PATH`? Use the npx form —
+   `npx -y open-memex <command>` resolves the package itself and needs no
+   `PATH` changes.
+
+**`EBUSY` / `EPERM` on `better_sqlite3.node` (Windows).**
+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.
+
+**`init` says it left a config file untouched.**
+Your editor config has comments (JSONC) or invalid JSON, and open-memex never
+rewrites files it can't parse safely. `init` printed the exact snippet to add
+by hand — paste it in, and you're done. The same applies to the opencode
+config: if it has comments, add the `"plugin"` line manually.
+
+**Something's off — run `open-memex doctor`.**
+Checks the Node version, config source, scope resolution for the current
+directory, and storage writability; verifies VS Code hasn't disabled MCP;
+then boots a real MCP server and runs `initialize` + `tools/list` against
+it — all eleven tools must show up. It also reports pre-rename `my-o-memory`
+leftovers if any editor config still references the old package name.
 
 ## FAQ
 
-**Do I need to initialize open-memex for each project after installing?**
-Two layers. The data layer needs nothing — there is no per-project init:
-the data dir is created on demand and the project scope is derived
-automatically from your cwd's git remote or path, so memories are
-namespaced per project with zero setup. The editor wiring takes one step:
-run `open-memex init` with no arguments and it auto-detects every editor
-you have installed (VS Code, Cursor, opencode — plus Visual Studio when the
-project has a `.sln`) and wires them all, user-level wherever the editor
-supports it, so one init covers every project. Prefer a single editor?
-`open-memex init --client <vscode|cursor|opencode|visualstudio>`. Prefer to
-force user-level for VS Code / Cursor? Add `--global`. The Copilot memory
-instructions default to user-level (`~/.copilot/`), which is global.
+**Do I need git?**
+No. Capture and recall work in any folder — without a git repo the project
+scope simply keys off the folder path. Git is only needed for the team
+workflow (`submit` / PR review), which is optional.
+
+**I use several editors. Do they really share one memory?**
+Yes — on the same machine. Every wired editor reads and writes the same local
+memory; see the [capability matrix](#which-editors-which-features) for what
+each editor gets. A decision captured in VS Code is respected in opencode.
+
+**I work on two computers (office + home). Does memory sync?**
+Not automatically — memory is per-machine by design, and your personal scope
+never leaves the machine it was created on. To move memory manually, use
+`open-memex export` on one machine and `open-memex import` on the other.
+Project memories shared through Git (Team workflow) travel with the repo, so
+cloning the repo on the second machine brings the *published project* memories
+along — your personal ones stay behind, on purpose.
+
+**Is it really free? Do I need an account?**
+Free and open source (Apache-2.0). No account, no sign-up, no telemetry, no
+cloud calls. If it can't phone home, there's nothing to phone home to: the
+only network open-memex ever touches is your own git remote, when you
+explicitly push.
+
+**I accidentally pasted a secret into a memory. What now?**
+`open-memex search "<part of it>"` to find the memory, then
+`open-memex forget <id>` to delete it. To prevent it next time, wrap sensitive
+text in `<private>…</private>` (stripped before saving) — recognized API keys
+and tokens are also masked automatically. Preview any message safely with
+`open-memex capture --dry-run "…"`.
+
+**Do I need to run `init` for every project?**
+No. The data layer needs nothing — the project scope is derived automatically
+from your cwd's git remote or path, so memories are namespaced per project
+with zero setup. The editor wiring is one `open-memex init` per machine
+(user-level wherever the editor supports it). Run it again only after
+upgrading (`--force`) or if you switch editors.
 
 **Does opencode need `init`?**
-Two paths. Recommended: `open-memex init --client opencode --global` —
-it merges the native open-memex plugin into
-`~/.config/opencode/opencode.json` for you. One-time setup, applies to all
-projects, and additionally enables keyword auto-capture and first-turn
-memory injection. Prefer to do it by hand? Add
-`"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]`
-(the installed package's path) to that file instead. As a plain MCP
-consumer: `open-memex init --client opencode` writes a project-level
-`opencode.jsonc` (no hooks). If your user-level config has comments, `init`
-leaves it untouched and prints the manual step.
+Two paths. Recommended: `open-memex init --client opencode --global` — it
+merges the native open-memex plugin into `~/.config/opencode/opencode.json`
+for you. One-time setup, applies to all projects, and additionally enables
+keyword auto-capture and first-turn memory injection. Prefer to do it by hand?
+Add `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` (the
+installed package's path) to that file instead. As a plain MCP consumer:
+`open-memex init --client opencode` writes a project-level `opencode.jsonc`
+(no hooks). If your user-level config has comments, `init` leaves it
+untouched and prints the manual step.
 
 **VS Code — run `init` once, or per project?**
 Once. Plain `open-memex init` auto-detects VS Code and writes the MCP server
-entry to VS Code's user-level `mcp.json`
-(`%APPDATA%/Code/User/mcp.json` on Windows,
-`~/Library/Application Support/Code/User/mcp.json` on macOS,
+entry to VS Code's user-level `mcp.json` (`%APPDATA%/Code/User/mcp.json` on
+Windows, `~/Library/Application Support/Code/User/mcp.json` on macOS,
 `~/.config/Code/User/mcp.json` on Linux), so the server starts in every
 project. A per-project `.vscode/mcp.json` still wins when present, and the
 entry keeps `cwd=${workspaceFolder}` so project-scope resolution keeps
 working per window. If your user-level `mcp.json` has comments (VS Code
-accepts JSONC), `init` leaves it alone and prints the exact snippet to add
-by hand. An empty file is treated as blank and written to directly.
+accepts JSONC), `init` leaves it alone and prints the exact snippet to add by
+hand. An empty file is treated as blank and written to directly.
 
 **How do I remove the editor wiring?**
-`open-memex uninstall` reverses `init`: it removes the MCP server entry,
-the opencode plugin line, and the open-memex section of the Copilot
-instructions. With no `--client` it cleans up every detected editor;
-`--global` limits the cleanup to user-level wiring. Your memories are
+`open-memex uninstall` reverses `init`: it removes the MCP server entry, the
+opencode plugin line, the Agent Skill directory, and the open-memex section of
+the Copilot instructions. With no `--client` it cleans up every detected
+editor; `--global` limits the cleanup to user-level wiring. Your memories are
 never touched.
 
+## Project status
+
+open-memex is stable and in daily use; the current stable line is published on
+npm as `latest`, with `alpha` builds for testers. Release history lives in
+[GitHub Releases](https://github.com/stoneskin/open-memex/releases); design
+decisions are recorded in the append-only log at
+[docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
+
+On the horizon (no version promises): native agent plugins for more editors as
+enhancements over the same MCP tools; local embeddings as an opt-in experiment
+(no model is ever downloaded without asking); an org layer only if real
+multi-repo sharing, ACL, or compliance needs demand it.
+
 ## License
 
 [Apache-2.0](./LICENSE)