open-memex 0.2.0-alpha → 0.3.0-alpha

package/README.zh-CN.md

@@ -0,0 +1,307 @@
+# open-memex
+
+[English](./README.md)
+
+给 AI 编程助手的本地优先持久记忆：一个 [opencode](https://opencode.ai) 插件，
+加上一个通用 MCP server（VS Code Copilot、Cursor、Claude Code、Visual Studio 等）。
+
+- **Markdown 文件**是 source of truth（人类可读、git 友好）
+- **SQLite FTS5** 做可重建索引（BM25 关键词检索，`better-sqlite3`）
+- **零云端**、零账号、零第三方 API
+- 直接跑在 opencode 内嵌的 Bun 运行时里；CLI 和 MCP server 跑在 Node 下——无需构建、无需安装 Bun
+
+## 安装
+
+### 前置要求
+
+- **Node.js ≥ 22.6**（`open-memex doctor` 会帮你检查）
+
+### 第一步——安装 CLI
+
+**npm（推荐）：**
+
+```sh
+npm install -g open-memex@alpha
+```
+
+安装的是 `0.3.0-alpha` 预览通道。（`latest` 仍指向旧的 `0.1.0` 稳定版。）
+
+**免安装——用 npx 直接跑：**
+
+```sh
+npx -y open-memex@alpha <命令>   # 例如 npx -y open-memex@alpha init --client vscode
+```
+
+**从源码安装**（最新开发版，`V2-dev-p2` 分支）：
+
+```sh
+git clone -b V2-dev-p2 https://github.com/stoneskin/open-memex.git
+cd open-memex
+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 目录。
+如果终端找不到它，说明该目录不在你的 `PATH` 里：
+
+1. 先找到这个目录：`npm config get prefix`
+   - **Windows：** 启动器（`open-memex.cmd`）就在该目录下，例如
+     `C:\Users\<你>\AppData\Roaming\npm`
+   - **macOS / Linux：** 在 `<prefix>/bin` 下，例如 `/usr/local/bin`
+     或 `~/.nvm/versions/node/v22.x.x/bin`
+2. 把它加进 `PATH`：
+   - **Windows：** 设置 → 系统 → 关于 → 高级系统设置 → 环境变量 →
+     把该目录加到*用户*的 `Path` 里 → **重启终端**。用 `where open-memex` 验证。
+   - **macOS / Linux：** 在 `~/.zshrc`（或 `~/.bashrc`）里加一行
+     `export PATH="$(npm prefix -g)/bin:$PATH"`，重启 shell，
+     用 `command -v open-memex` 验证。
+3. 没有管理员权限 / 不想动 `PATH`？用上面的 npx 形式——npx 自己解析包，
+   不需要改 `PATH`。
+
+### 第二步——给你的编辑器一键配置
+
+在**项目根目录**下运行（这样 project scope 会解析到这个仓库）：
+
+**VS Code**（Copilot）：
+
+```sh
+open-memex init --client vscode
+# ……没装全局包的话：
+npx -y open-memex@alpha init --client vscode
+```
+
+自动写 `.vscode/mcp.json` 和 `.github/copilot-instructions.md`，然后重新加载窗口，
+在 Copilot Chat 的 MCP 面板里确认 `open-memex` server 已启动。
+
+**Cursor：**
+
+```sh
+open-memex init --client cursor
+```
+
+自动写 `.cursor/mcp.json` 和 `.github/copilot-instructions.md`。
+
+**opencode**（作为普通 MCP 客户端）：
+
+```sh
+open-memex init --client opencode
+```
+
+写项目级 `opencode.jsonc`（`type: "local"`）。想用原生插件？
+在 `~/.config/opencode/opencode.jsonc` 里加
+`"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]`——
+在 tools 之外还能获得关键词自动捕获和首轮上下文注入。
+
+**Claude Code**（在项目根目录运行）：
+
+```sh
+claude mcp add open-memex -- open-memex mcp
+# ……或打印配置片段：open-memex mcp --print-config claude
+```
+
+**Visual Studio**（在 solution 目录运行）：
+
+```sh
+open-memex init --client visualstudio
+```
+
+写 solution 级 `.mcp.json` 和 `.github/copilot-instructions.md`。需要
+Visual Studio 2022 17.14+ 或 Visual Studio 2026（**仅 Windows**）。
+Visual Studio 也会自动发现 `.vscode/mcp.json` 和 `.cursor/mcp.json`，
+所以上面的 VS Code 配置同样可用。
+
+**Codex：** 暂无 `init` 客户端——以 `open-memex mcp --print-config` 为起点手动添加
+（`config.toml` 的 `[mcp_servers]`，或 `codex mcp add`）。
+
+`init` 说明：
+
+- 在终端里会交互式询问：配哪个编辑器、是否开启关键词自动捕获、
+  是否在首轮注入记忆。`--yes` 全用默认值；脚本 / 非 TTY 环境不提问
+  （编辑器默认 VS Code）。
+- 已有配置文件会被**合并，不会被覆盖**——重复运行是安全的。
+  `--force` 强制覆盖。
+- 如果 `PATH` 上没有可用的 `open-memex`（比如一次性 npx），`init` 会把
+  `npx -y open-memex@alpha mcp` 写进配置，配置照样能用。
+  以后 `npm i -g open-memex@alpha` + `open-memex init --force` 可切换到更快
+  的直接调用。
+
+### 第三步——验证
+
+```sh
+open-memex doctor
+```
+
+检查：Node 版本、配置来源、当前目录的 scope 解析、存储可写性，
+然后启动一个真实的 MCP server 做 `initialize` + `tools/list`——
+五个 tools 都必须出现。
+
+## Agent 可用的 tools
+
+| Tool | 作用 |
+|---|---|
+| `memory_add`       | 保存事实、偏好、决定、笔记 |
+| `memory_search`    | BM25 关键词检索，跨 project + personal 记忆 |
+| `memory_list`      | 按 scope 列出记忆，最新的在前 |
+| `memory_supersede` | 用新版本替换一条记忆（保留替换链） |
+| `memory_forget`    | 按 id 删除一条记忆 |
+
+## 捕获（Capture）
+
+- **关键词触发**（opencode 原生插件，扫描用户消息）：中文 `记住…` /
+  `记一下` / `记录一下` / `别忘了…`，英文 `remember …` / `note that …` /
+  `don't forget …` / `TIL …` / `save this …`。
+  Scope 路由：第一人称单数进 **personal**（`记住我…`、`替我记…`、
+  `我觉得…`、`我喜欢…`、`remember for me`）；第一人称复数进当前
+  **project** scope（`我们认为…`、`我们决定…`、`帮我们记住…`）。
+- **Agent 主动调用** `memory_add`
+- **脱敏**：`<private>…</private>` 标签内的内容会被剥离；检测到的密钥
+  （API key、token、高熵凭据）就地打码——保留前 4 个字符，其余替换为 `x`——
+  然后照常保存。用 `open-memex capture --dry-run "…"` 预览一条消息会被如何捕获。
+
+## Scope
+
+- **project** — 绑定当前仓库（用 git origin URL 哈希做 key，无 remote 则用 cwd）。新记忆默认进这里。
+- **personal** — 跨所有项目全局，**仅本机，永不上传/同步**。放个人偏好。（v1 叫 `user`，`migrate --to-v2` 会自动改名。）
+
+完整 scope 模型（key 推导、迁移、visibility、保留名）见
+[docs/SCOPES.md](./docs/SCOPES.md)。
+
+## 检索（Retrieval）
+
+每个会话的首轮，`open-memex` 会往 system prompt 里注入一个 `[OPEN-MEMEX]` 块，
+包含 top-N 最新 project 记忆 + top-N 个人偏好。Agent 也可以随时调用
+`memory_search` 按需检索。
+
+## 存储布局
+
+```
+%APPDATA%\open-memex\               (Windows)
+$XDG_DATA_HOME/open-memex/          (Linux/macOS)
+├── index.db                         # SQLite FTS5 索引（可重建）
+└── memories/
+    ├── personal/
+    │   └── <id>.md
+    └── project__<name>__<hash12>/
+        └── <id>.md
+```
+
+每个 `.md` 文件是 v2 YAML frontmatter（`id, scope, scope_key, visibility, role,
+type, importance, status, tags, created_at, updated_at, schema_version` 等）+
+记忆正文。可以手工编辑——插件启动时按文件 mtime 重新同步。
+Markdown 是 source of truth，SQLite 索引是派生的、可重建的
+（`open-memex reindex`）。
+
+## 配置（Config）
+
+可选文件 `~/.config/opencode/open-memex.jsonc`（可用 `MY_O_MEMORY_CONFIG`
+改路径；`MY_O_MEMORY_HOME` 改存储根目录）。
+
+默认值：
+
+```jsonc
+{
+  "maxProjectMemories": 8,    // 首轮注入的 project 记忆条数
+  "maxProfileItems": 5,       // 首轮注入的个人偏好条数
+  "injectOnFirstTurn": true,  // [OPEN-MEMEX] system-prompt 块
+  "keywordCaptureEnabled": true,
+  "logLevel": "info"          // info | debug
+}
+```
+
+`open-memex config` 打印生效配置（默认值 + 文件）。
+安装后改设置：
+
+```sh
+open-memex config set keywordCaptureEnabled false
+open-memex config set maxProjectMemories 12
+```
+
+可设置的 key：`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、
+`keywordCaptureEnabled`、`logLevel`。完整设计见
+[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)。
+
+## CLI 参考
+
+安装与健康检查：
+
+```sh
+open-memex init [--client vscode|cursor|opencode|visualstudio] [--force] [--yes]
+open-memex config                                  # 打印生效配置
+open-memex config set <key> <value>                # 改设置
+open-memex doctor                                  # 环境健康检查
+open-memex capture --dry-run "记住我喜欢简洁的回答"  # 预览关键词捕获
+open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
+```
+
+记忆操作：
+
+```sh
+open-memex add "This repo uses better-sqlite3" --type project-config
+open-memex search "auth flow"
+open-memex list --scope project
+open-memex supersede <id> "Updated content"
+open-memex status <id> deprecated
+open-memex forget <id>
+```
+
+维护：
+
+```sh
+open-memex where        # 显示存储与配置文件路径
+open-memex scopes       # 列出 project scope 及记忆条数
+open-memex reindex      # 从 markdown 重建 SQLite 索引
+open-memex migrate --to-v2 [--dry-run]   # v1 数据 → v2
+```
+
+CLI 跑在 Node 22 内置的实验性 TypeScript loader 下（无需构建）。
+从源码 checkout 使用时，每条命令前加
+`node --experimental-strip-types src/cli.ts`（简单场景也可用
+`npm run cli -- <命令>`——但 npm 会吞掉未知的 `--flag` 参数，
+所以推荐直接用 `node`）。
+
+## MCP server
+
+同一个五个 memory tools，走 Model Context Protocol 的 stdio server——
+不需要宿主专属插件，任何 MCP 客户端都能用 open-memex。
+
+```sh
+open-memex mcp               # 全局安装后
+npx -y open-memex@alpha mcp  # 免安装
+```
+
+project scope 从进程工作目录解析，所以配置 server 时 cwd 要指向项目根目录
+（`init` 会帮你处理好）。
+
+> **注意：** MCP 是请求/响应式的——它给 agent 提供 tools，但没有 opencode
+> 插件的关键词自动捕获和首轮上下文注入。想让 agent 主动用记忆，
+> 靠的是 agent 的 instructions（`init` 写的 `.github/copilot-instructions.md`）。
+
+## 路线图（Roadmap）
+
+**`0.3.0-alpha`（本版）：** 通用 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` 工作流、仓库内记忆目录），
+找 1–2 个同事做 pilot。
+
+**Coming —— `0.3.0`（稳定版）：** 组织层——组织记忆仓库、
+curator 约定、distill-to-AGENTS.md 辅助。
+
+**未来（看信号再定，不承诺版本）：** 原生 agent 插件
+（Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；
+本地 embedding 做基准测试门控的实验（**未经明确 opt-in 绝不下载
+embedding 模型**）；云端 `RemoteProvider` 定制只在多仓库共享、
+ACL 或合规需求出现时才做。
+
+设计细节：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)（append-only 决策日志 D1–D20）。
+
+## 许可证
+
+[Apache-2.0](./LICENSE)

package/bin/open-memex.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// `open-memex` bin launcher: re-execs src/cli.ts with TypeScript type-stripping
+// enabled, so the command works on Node 22.6+ without the user passing
+// --experimental-strip-types themselves. (Plain JS — no build step.)
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const entry = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "src",
+  "cli.ts",
+);
+
+const child = spawn(
+  process.execPath,
+  ["--experimental-strip-types", entry, ...process.argv.slice(2)],
+  { stdio: "inherit" },
+);
+child.on("error", (err) => {
+  console.error(`open-memex: failed to start: ${err.message}`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/docs/V2-DESIGN.md

@@ -40,6 +40,11 @@ Decisions log; Prior Art; solo-dev adoption path.
 - **MCP is an interface, not the identity.** MCP / CLI / REST / SDK are access layers over the protocol,
   so the project is never locked to one transport or one agent tool (opencode, VS Code Copilot, Cursor,
   Claude Code, Windsurf, …).
+- **Company lens:** at organizational scale the same pain is tribal knowledge — senior engineers'
+  hard-won experience evaporates when they move on, and every incident gets re-debugged by someone
+  new. The current phase therefore prioritizes *capture*: valuable knowledge must land in memory
+  first, because team/org sharing, onboarding, and incident learning all build on that foundation.
+  (No capture, nothing to inherit.)
 
 ### Non-goals
 
@@ -287,7 +292,7 @@ instructions are never candidates.)
 | Explicit tools | `memory_add/update/forget` (soft delete) · `search/get/list/status` · `propose/promote` · `resolve`. Write tools confirm with the user; read tools are open. |
 | Keyword triggers | `remember …`, `note that …`, `TIL …`, `save this: …` + Chinese `记住` `记得` `保存一下` … |
 | Implicit (opt-in) | end-of-session "should I remember X?"; implicit captures default to `confidence: low` and appear in a separate list view for batch cleanup (regret window). |
-| Redaction (hard) | `<private>…</private>` stripped; secret patterns refuse the write; pre-commit hook scans shared scopes. |
+| Redaction (hard) | `<private>…</private>` stripped; secret patterns are **masked in place** (first 4 chars kept, rest → `x`) and the write proceeds (D14); pre-commit hook scans shared scopes. |
 
 ---
 
@@ -410,11 +415,47 @@ Zero-config is survival for an open-source project. The opencode plugin remains
   VS Code MCP-server support; corporate Copilot local-tool support. **Hard gate before Phase 2.**
 - **Phase 1 — Local hardening (1–2 wks).** CJK default (bigram+FTS5) · v1→v2 migration · dedup +
   lifecycle · redaction hardening · scope docs. No external dependencies.
-- **Phase 2A — Read-only MCP.** Core/adapters split · MCP server (search/get/list/status) ·
-  query-aware injection.
+- **Phase 2A — MCP server (shipped 2026-09-27, D15).** Core/adapters split
+  (`src/tools/ops.ts`) · MCP server (`src/mcp.ts`, stdio) exposing all five memory tools —
+  read-only-first phasing dropped per D15 · query-aware injection stays host-side.
+  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`**.
   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` →
+  context injection, `UserPromptSubmit` → keyword-triggered search, `Stop`/`PostToolUse` →
+  capture); per D16, no host-specific extraction intelligence — opencode is likewise
+  supported as a plain MCP consumer. Gated on real-world signal from 0.3.0-alpha MCP
+  dogfooding.
+
+### Agent integration matrix
+
+| Agent | Integration path | Native hooks? | Status |
+|---|---|---|---|
+| opencode | native plugin (`src/index.ts`) | ✅ keyword capture + first-turn injection | shipped (Phase 1) |
+| VS Code Copilot | MCP server + `.github/copilot-instructions.md` | ❌ — VS Code extension API cannot intercept Copilot Chat (researched 2026-09-27); an extension would add no hook capability, so not worth building | ships `0.3.0-alpha` |
+| Cursor | MCP server + rules | ❌ no chat plugin API | ships `0.3.0-alpha` |
+| Claude Code | MCP server today; plugin + hooks candidate | ✅ `SessionStart` / `UserPromptSubmit` / `PostToolUse` | Phase 2C candidate |
+| Codex (CLI/IDE) | MCP server (`[mcp_servers]` in config.toml / `codex mcp add`) today; plugin + hooks + marketplace candidate | ✅ hooks mirror Claude Code's | Phase 2C candidate |
+
+### Competitive landscape (for future positioning)
+
+Coding-agent memory is crowded; open-memex's wedge is **zero-cloud, zero-account,
+zero-embedding-download**, with repo-native markdown as source of truth (maintainer
+requirement: personal data never touches third-party services). Benchmarks to track:
+
+| Product | Scale / backing (Sep 2026) | Shape | Gap vs open-memex |
+|---|---|---|---|
+| Mem0 | ~50k+★, $24M Series A (YC) | universal memory SDK/API, vector+graph, cloud-first | cloud dependency; not repo-native for coding agents |
+| Letta (ex-MemGPT) | ~24k★, $10M seed | stateful agent platform, memory blocks | agent runtime, not a drop-in coding-agent memory |
+| Zep / Graphiti | ~20–30k★, $12M seed | temporal knowledge graph, enterprise | heavy infra; overkill as a coding vault |
+| Cognee | ~15–30k★, $7.5M seed | graph ECL pipelines | ingest-oriented, no coding-agent hooks |
+| Supermemory | ~15k★, $2.6M seed | consumer second-brain + SaaS API | cloud SaaS |
+| atlaso-labs/codex | Codex marketplace | long-term memory plugin for Codex (hooks + MCP + cloud-sync upsell) | **direct comparable** for a future Codex plugin; their cloud upsell vs our local-first |
+
+(Star counts / funding as of Sep 2026 — re-verify before quoting publicly.)
 - **Phase 3 — Org layer.** Org memory repo · curator convention · `examples/remote-server/` ·
   distill-to-AGENTS.md assist.
 - **Phase 4 — Future, signal-gated.** Cloud `RemoteProvider` customization only on: multi-private-repo
@@ -474,6 +515,69 @@ Zero-config is survival for an open-source project. The opencode plugin remains
   `autoPull: true`, a failed pull never blocks the session and every pull emits a receipt.
   *Rationale: a memory pull can change agent behavior, so it must be a deliberate, visible act —
   predictable offline-first beats silent freshness. Unanimous 5/5 in round-4 AI review, 2026-09-26.*
+- **D14** — Secret detection masks instead of refusing. A write-path secret hit is **masked in
+  place** (first 4 characters kept, the rest replaced with `x`, length-preserving) and the write
+  proceeds with a notice; `<private>…</private>` spans are still stripped to `[REDACTED]`.
+  Amends the v0.2 rule "secret patterns refuse the write" (§8, §11). *Rationale: a refused write
+  loses the surrounding context the user asked to remember; a prefix-masked secret stays
+  recognizable (which key it was) while the credential itself is not recoverable from the file.
+  Supersedes the refusal behavior; applies to every write path (tools, keyword capture, CLI).
+  2026-09-27.*
+- **D15** — Phase 2A MCP server ships with all five tools, not read-only first. The MCP server
+  (`src/mcp.ts`, stdio) exposes `memory_add` / `memory_search` / `memory_list` /
+  `memory_supersede` / `memory_forget` — amends the §18 roadmap's "Read-only MCP" phasing.
+  *Rationale: the write path is the same Core (redact/D14, dedup, lifecycle) already shipped and
+  dogfooded in the opencode plugin, so a separate read-only stage adds process cost without
+  reducing risk. Core/adapters split implemented as `src/tools/ops.ts` (host-agnostic logic +
+  shared zod schemas); the opencode plugin and the MCP server are thin adapters over it.
+  Query-aware injection stays host-side: MCP is request/response and offers no hooks, so
+  proactive memory use depends on the host's agent instructions. 2026-09-27.*
+- **D16** — No separate LLM extraction pass; memory intelligence lives in model-driven tool
+  calls. A dedicated post-session extraction (opencode `session.idle` hook → hidden session
+  → host model) was evaluated and rejected: the model's own decision to call `memory_add`
+  *is* the LLM judgment of "worth remembering", so a second pass is redundant and
+  host-specific. Investment goes into the shared layer instead — `TOOL_DESCRIPTIONS` in
+  `src/tools/ops.ts` and each host's agent instructions — so every host benefits at once.
+  Native plugins (opencode now; Claude Code / Codex as Phase 2C candidates) remain as
+  hook-enhanced paths, but opencode is also supported as a plain MCP consumer of
+  `open-memex mcp`, keeping one unified tool surface. 2026-09-27.
+- **D17** — `open-memex init` resolves the MCP server command at init time. A durable
+  `open-memex` on PATH (outside npm's ephemeral `_npx` cache) → `command: "open-memex"`;
+  otherwise (one-shot `npx open-memex@alpha init`) → `command: "npx", args: ["-y",
+  "open-memex@alpha", "mcp"]` plus a hint to `npm i -g` + re-run `init --force`.
+  `mcp --print-config` uses the same resolution. *Rationale: a one-shot npx run leaves
+  no bin behind, so writing `command: "open-memex"` would produce a dead MCP server on
+  the next editor launch; the npx fallback keeps the one-command setup actually
+  one-command. 2026-09-27.*
+
+- **D18** — Keyword scope routing: 我 → personal, 我们 → project. Chinese capture
+  keywords are split into two pattern lists: personal patterns (`记住我`/`替我记`/
+  `我觉得`/`我喜欢`, plus legacy `remember for me`/`记住（个人）`) route to the personal
+  scope, while project patterns (`我们认为`/`我们决定`/`帮我们记住`, and the generic
+  `记住…` for `记住我们的…`) route to the current project scope. Personal patterns are
+  scanned first and *claim* the line so the generic `记住…` pattern cannot double-fire;
+  `记住我` uses a `(?!们)` guard so it never swallows `记住我们…`. *Rationale: the
+  user's own rule — "我" is personal, "我们" is the current project — stated 2026-09-27;
+  scanning user messages (never assistant output) with personal-first claim keeps one
+  utterance to one memory. README + repo AGENTS.md keyword sections updated in the same
+  commit. 2026-09-27.*
+- **D19** — `open-memex init` asks setup questions; `open-memex config set` edits settings
+  after install. `init` prompts on a TTY (editor: vscode/cursor/opencode; keyword
+  auto-capture on/off; first-turn injection on/off), `--yes` accepts all defaults, and
+  non-terminal runs never prompt (scripts keep the historical vscode default).
+  Non-default answers persist to the JSONC config file; `open-memex config set <key>
+  <value>` changes them later (validated keys: `maxProjectMemories`, `maxProfileItems`,
+  `injectOnFirstTurn`, `keywordCaptureEnabled`, `logLevel`). `init --client opencode`
+  merges a `type: "local"` MCP entry into project-level `opencode.jsonc` (v1 format).
+  *Rationale: install time is the only moment the user's attention is guaranteed, and a
+  print-only `config` left no path to change settings afterwards. 2026-09-27.*
+- **D20** — `init` / `mcp --print-config` support Visual Studio. Writes solution-level
+  `.mcp.json` with the `"servers"` section (`{ "type": "stdio", "command", "args" }`),
+  per Microsoft Learn (VS 2022 17.14+ / VS 2026, Windows-only). `.github/copilot-
+  instructions.md` is still written — VS's Copilot reads it too. Note VS also
+  auto-discovers `.vscode/mcp.json` and `.cursor/mcp.json`, so repos already set up for
+  VS Code get VS support for free; the explicit `.mcp.json` is the source-controllable
+  option. 2026-09-27.*
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.2.0-alpha",
+  "version": "0.3.0-alpha",
   "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",
@@ -15,11 +15,14 @@
   "main": "src/index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "cli": "node --experimental-strip-types src/cli.ts"
+    "cli": "node --experimental-strip-types src/cli.ts",
+    "mcp": "node --experimental-strip-types src/mcp.ts"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
     "better-sqlite3": "^11.7.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "zod": "^4.1.8"
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.18.30",
@@ -27,5 +30,11 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0"
+  },
+  "bin": {
+    "open-memex": "bin/open-memex.js"
+  },
+  "engines": {
+    "node": ">=22.6"
   }
 }

package/scripts/smoke-mcp.ts

@@ -0,0 +1,135 @@
+// MCP server smoke test: handshake + tools/list + add/search/forget over stdio.
+// Usage:  node --experimental-strip-types scripts/smoke-mcp.ts
+// Uses temp dirs for MY_O_MEMORY_HOME and the project cwd — no real data touched.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOME = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-home-"));
+const PROJ = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-proj-"));
+
+const MCP_TS = fileURLToPath(new URL("../src/mcp.ts", import.meta.url));
+
+const child = spawn(
+  "node",
+  ["--experimental-strip-types", MCP_TS],
+  {
+    cwd: PROJ,
+    env: { ...process.env, MY_O_MEMORY_HOME: HOME },
+    stdio: ["pipe", "pipe", "pipe"],
+  },
+);
+
+let buf = "";
+let id = 0;
+const pending = new Map<number, (v: any) => void>();
+const stdoutLines: string[] = [];
+
+child.stdout.on("data", (d) => {
+  buf += d.toString();
+  let idx;
+  while ((idx = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, idx).trim();
+    buf = buf.slice(idx + 1);
+    if (!line) continue;
+    stdoutLines.push(line);
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      console.error("NON-JSON on stdout:", line);
+      process.exitCode = 1;
+      continue;
+    }
+    if (msg.id !== undefined && pending.has(msg.id)) {
+      pending.get(msg.id)!(msg);
+      pending.delete(msg.id);
+    }
+  }
+});
+child.stderr.on("data", (d) => process.stderr.write("[srv:err] " + d.toString()));
+
+function req(method: string, params?: any): Promise<any> {
+  const myId = ++id;
+  return new Promise((resolve) => {
+    pending.set(myId, resolve);
+    child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id: myId, method, params }) + "\n");
+  });
+}
+function notify(method: string, params?: any) {
+  child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+}
+
+const results: string[] = [];
+function check(name: string, ok: boolean, detail = "") {
+  results.push(`${ok ? "PASS" : "FAIL"} ${name}${detail ? " — " + detail : ""}`);
+  if (!ok) process.exitCode = 1;
+}
+
+try {
+  const init = await req("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "mcp-e2e", version: "0.0.1" },
+  });
+  check("initialize", !!init.result?.serverInfo, JSON.stringify(init.result?.serverInfo));
+  notify("notifications/initialized");
+
+  const tools = await req("tools/list", {});
+  const names = (tools.result?.tools ?? []).map((t: any) => t.name).sort();
+  check(
+    "tools/list has 5 memory tools",
+    JSON.stringify(names) ===
+      JSON.stringify(["memory_add", "memory_forget", "memory_list", "memory_search", "memory_supersede"]),
+    names.join(","),
+  );
+  const addSchema = tools.result.tools.find((t: any) => t.name === "memory_add").inputSchema;
+  check("memory_add schema has content+type+scope+tags", !!addSchema.properties?.content && !!addSchema.properties?.type, Object.keys(addSchema.properties ?? {}).join(","));
+
+  // D14 through MCP: a fake secret must be masked, not refused.
+  const add = await req("tools/call", {
+    name: "memory_add",
+    arguments: { content: "mcp e2e probe: deploy key sk-test-FAKESECRET1234567890abcdef", type: "fact" },
+  });
+  const addText: string = add.result?.content?.[0]?.text ?? "";
+  const savedId = (addText.match(/id=([A-Za-z0-9_]+)/) ?? [])[1];
+  check("memory_add saves (not refuses)", !add.result?.isError && !!savedId, addText.slice(0, 80));
+  check("memory_add notes masking (D14)", addText.includes("masked"), addText.slice(0, 120));
+
+  // The raw secret must not be on disk.
+  const mdFiles: string[] = [];
+  const walk = (d: string) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith(".md")) mdFiles.push(p);
+    }
+  };
+  walk(HOME);
+  const leaked = mdFiles.filter((f) => fs.readFileSync(f, "utf8").includes("sk-test-FAKESECRET1234567890abcdef"));
+  check("secret not leaked to disk", leaked.length === 0, leaked.join(","));
+
+  const search = await req("tools/call", {
+    name: "memory_search",
+    arguments: { query: "mcp e2e probe" },
+  });
+  const searchText: string = search.result?.content?.[0]?.text ?? "";
+  check("memory_search finds it", searchText.includes(savedId), searchText.slice(0, 80));
+  check("memory_search output masked", !searchText.includes("sk-test-FAKESECRET1234567890abcdef"));
+
+  const list = await req("tools/call", { name: "memory_list", arguments: {} });
+  check("memory_list works", (list.result?.content?.[0]?.text ?? "").includes(savedId));
+
+  const forget = await req("tools/call", { name: "memory_forget", arguments: { id: savedId } });
+  check("memory_forget works", (forget.result?.content?.[0]?.text ?? "").includes("Deleted"));
+
+  const search2 = await req("tools/call", { name: "memory_search", arguments: { query: "mcp e2e probe" } });
+  check("memory gone after forget", !(search2.result?.content?.[0]?.text ?? "").includes(savedId));
+} finally {
+  child.kill();
+}
+
+console.log(results.join("\n"));
+console.log(process.exitCode ? "MCP E2E: FAILURES" : "MCP E2E: ALL PASS");