open-memex 0.2.0-alpha → 0.3.0-alpha.1

package/dist/store/v2migrate.js

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+import { paths } from "../paths.js";
+import { parseRawFrontmatter, normalizeFrontmatter, isTaxonomyType, serialize, } from "./markdown.js";
+/**
+ * v1 → v2 file migration (V2-DESIGN §19). Explicit only — run via
+ * `open-memex migrate --to-v2`. Converts frontmatter in place:
+ *
+ *   - scope rename: v1 `user` → v2 `personal` (scope, scope_key, and the
+ *     storage dir `memories/user/` → `memories/personal/`)
+ *   - times: epoch ms → RFC 3339
+ *   - `priority: N` → `importance: low|normal|high`
+ *   - `type: instruction` → `type: knowledge` + `role: instruction`
+ *   - unknown v1 types → `knowledge` (v2 taxonomy, §3.1)
+ *   - adds `schema_version: 2`, `visibility`, `role`, `status`
+ *
+ * Legacy `my-o-memory` data roots (§19/D13: `.my-o-memory/` →
+ * `.open-memex/`, `~/.my-o-memory/` → `~/.open-memex/`) are merged into the
+ * current root; the old dir is kept as a dated backup.
+ */
+const V2_MARKER = /^schema_version:\s*2(\s|$)/m;
+export function isV2File(raw) {
+    return V2_MARKER.test(raw);
+}
+/**
+ * Plan the v1 → v2 conversion of one file. Returns null when the file is
+ * already v2 (nothing to do). Pure — no disk writes.
+ */
+export function planConversion(filePath, memoriesRoot) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    if (isV2File(raw))
+        return null;
+    const parsed = parseRawFrontmatter(raw);
+    if (!parsed)
+        return null;
+    const { rawFm, body } = parsed;
+    const fm = normalizeFrontmatter(rawFm);
+    const changes = [];
+    // scope rename
+    if (rawFm.scope_kind === "user" || rawFm.scope_key === "user") {
+        changes.push("scope user → personal");
+    }
+    else if (!rawFm.scope) {
+        changes.push(`scope → ${fm.scope} (default)`);
+    }
+    // storage dir move follows scope_key
+    const toPath = path.join(memoriesRoot, fm.scope_key, path.basename(filePath));
+    if (toPath !== filePath) {
+        changes.push(`file moved: ${path.basename(path.dirname(filePath))}/ → ${fm.scope_key}/`);
+    }
+    // visibility default
+    if (!rawFm.visibility) {
+        changes.push(`visibility → ${fm.visibility} (default)`);
+    }
+    // type taxonomy
+    const rawType = rawFm.type;
+    if (rawType === "instruction") {
+        changes.push("type instruction → knowledge, role → instruction (D11)");
+    }
+    else if (typeof rawType === "string" && rawType && !isTaxonomyType(rawType)) {
+        changes.push(`type "${rawType}" → knowledge (not in v2 taxonomy)`);
+        fm.type = "knowledge";
+    }
+    else if (!rawType) {
+        changes.push(`type → ${fm.type} (default)`);
+    }
+    // priority → importance
+    if (typeof rawFm.priority === "number") {
+        changes.push(`priority ${rawFm.priority} → importance ${fm.importance}`);
+    }
+    else if (!rawFm.importance) {
+        changes.push(`importance → ${fm.importance} (default)`);
+    }
+    // times
+    if (typeof rawFm.created_at === "number") {
+        changes.push("created_at/updated_at: epoch ms → RFC 3339");
+    }
+    // status default
+    if (!rawFm.status) {
+        changes.push(`status → ${fm.status} (default)`);
+    }
+    changes.push("schema_version → 2");
+    return { fm, body, fromPath: filePath, toPath, changes };
+}
+/**
+ * Merge a legacy `my-o-memory` data root into the current `open-memex` root.
+ * The old dir is renamed to a dated backup — never deleted. Returns the
+ * backup path, or null when no legacy dir exists.
+ */
+function migrateLegacyDataRoot(dryRun) {
+    const { root } = paths();
+    const legacy = path.join(path.dirname(root), "my-o-memory");
+    if (!fs.existsSync(legacy) || !fs.statSync(legacy).isDirectory())
+        return null;
+    const stamp = new Date().toISOString().slice(0, 10);
+    const backup = `${legacy}.backup-${stamp}`;
+    if (!dryRun) {
+        const legacyMem = path.join(legacy, "memories");
+        if (fs.existsSync(legacyMem)) {
+            for (const entry of fs.readdirSync(legacyMem)) {
+                const src = path.join(legacyMem, entry);
+                const dst = path.join(root, "memories", entry);
+                if (!fs.existsSync(dst)) {
+                    fs.renameSync(src, dst);
+                }
+                else {
+                    // merge file-by-file, never overwrite
+                    for (const name of fs.readdirSync(src)) {
+                        const s = path.join(src, name);
+                        const d = path.join(dst, name);
+                        if (!fs.existsSync(d))
+                            fs.renameSync(s, d);
+                    }
+                }
+            }
+        }
+        fs.renameSync(legacy, backup);
+    }
+    return backup;
+}
+export function migrateV2(opts) {
+    const { memories: memoriesRoot } = paths();
+    const result = {
+        scanned: 0,
+        converted: 0,
+        skippedV2: 0,
+        plans: [],
+        legacyBackup: null,
+    };
+    result.legacyBackup = migrateLegacyDataRoot(opts.dryRun);
+    if (!fs.existsSync(memoriesRoot))
+        return result;
+    for (const entry of fs.readdirSync(memoriesRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(memoriesRoot, entry.name);
+        for (const name of fs.readdirSync(dir)) {
+            if (!name.endsWith(".md"))
+                continue;
+            const filePath = path.join(dir, name);
+            result.scanned++;
+            const plan = planConversion(filePath, memoriesRoot);
+            if (!plan) {
+                result.skippedV2++;
+                continue;
+            }
+            if (!opts.dryRun) {
+                fs.mkdirSync(path.dirname(plan.toPath), { recursive: true });
+                fs.writeFileSync(plan.toPath, serialize(plan.fm, plan.body), "utf8");
+                if (plan.toPath !== plan.fromPath)
+                    fs.unlinkSync(plan.fromPath);
+            }
+            result.converted++;
+            result.plans.push(plan);
+        }
+    }
+    return result;
+}

package/dist/tools/memory.js

@@ -0,0 +1,40 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, TOOL_DESCRIPTIONS, } from "./ops.js";
+export function makeTools(getScope, cfg) {
+    const memory_add = tool({
+        description: TOOL_DESCRIPTIONS.memory_add,
+        args: memoryAddArgs,
+        async execute(args) {
+            return addMemory(getScope, cfg, args);
+        },
+    });
+    const memory_search = tool({
+        description: TOOL_DESCRIPTIONS.memory_search,
+        args: memorySearchArgs,
+        async execute(args) {
+            return searchMemories(getScope, args);
+        },
+    });
+    const memory_list = tool({
+        description: TOOL_DESCRIPTIONS.memory_list,
+        args: memoryListArgs,
+        async execute(args) {
+            return listMemories(getScope, args);
+        },
+    });
+    const memory_supersede = tool({
+        description: TOOL_DESCRIPTIONS.memory_supersede,
+        args: memorySupersedeArgs,
+        async execute(args) {
+            return supersedeMemory(cfg, args);
+        },
+    });
+    const memory_forget = tool({
+        description: TOOL_DESCRIPTIONS.memory_forget,
+        args: memoryForgetArgs,
+        async execute(args) {
+            return forgetMemory(args);
+        },
+    });
+    return { memory_add, memory_search, memory_list, memory_forget, memory_supersede };
+}

package/dist/tools/ops.js

@@ -0,0 +1,186 @@
+/**
+ * Framework-agnostic memory operations.
+ *
+ * The same functions back both the opencode plugin tools
+ * (`src/tools/memory.ts`) and the generic MCP server (`src/mcp.ts`).
+ * They take plain validated args and return a plain { title, output }
+ * result; each host adapts that to its own tool-result shape.
+ */
+import { z } from "zod";
+import { PERSONAL_SCOPE } from "../scope.js";
+import { search, list } from "../retrieve/search.js";
+import { writeMemoryFile, deleteMemoryFile, readMemoryFile, ulid, msToRfc3339, MEMORY_TYPE_TAXONOMY, } from "../store/markdown.js";
+import { upsertFromFile, deleteFromIndex } from "../store/sync.js";
+import { findDuplicates, supersede } from "../store/lifecycle.js";
+import { db } from "../store/db.js";
+import { redact } from "../redact.js";
+/** LLM-facing tool descriptions, shared by the opencode plugin and the MCP server. */
+export const TOOL_DESCRIPTIONS = {
+    memory_add: "Save a fact, preference, decision, or note to persistent local memory. Call this PROACTIVELY whenever the user shares something worth remembering across sessions — project conventions, tool choices, personal preferences, decisions made, error fixes and their causes. Do not wait to be asked. Keep each memory to one self-contained statement. Default scope is the current project; use the personal scope for facts about the user that apply across all projects.",
+    memory_search: "Search persistent memory by keyword (BM25 full-text). Returns matching memories from the current project and/or personal scope. Call before asking the user about past decisions, conventions, or preferences they may have told you before — try a few keyword variants, including the user's own language, when the first search comes up empty.",
+    memory_list: "List memories in a scope, newest first. Useful for browsing what is remembered, or verifying that a save landed.",
+    memory_supersede: "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
+    memory_forget: "Delete a memory by id. Use when the user asks to forget something.",
+};
+/** Shared zod input shapes (raw shape, not z.object — hosts wrap as needed). */
+export const scopeArg = z
+    .enum(["project", "personal", "user"])
+    .optional()
+    .describe("Memory scope. `project` = tied to this repo. `personal` = global across all your projects. `user` is a deprecated alias of `personal`. Default: project.");
+export const memoryAddArgs = {
+    content: z.string().min(1).describe("The fact to remember. One idea per memory."),
+    type: z
+        .enum(MEMORY_TYPE_TAXONOMY)
+        .optional()
+        .describe("Category of memory. Default: note."),
+    scope: scopeArg,
+    tags: z.array(z.string()).optional().describe("Optional tags for filtering."),
+};
+export const memorySearchArgs = {
+    query: z
+        .string()
+        .min(1)
+        .describe("Free-text query. File paths, error strings, identifiers work well."),
+    scope: z
+        .enum(["project", "personal", "user", "both"])
+        .optional()
+        .describe("Which scope(s) to search. Default: both."),
+    type: z.string().optional().describe("Restrict to memories of this type."),
+    limit: z.number().int().min(1).max(50).optional(),
+};
+export const memoryListArgs = {
+    scope: scopeArg,
+    type: z.string().optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+};
+export const memorySupersedeArgs = {
+    id: z.string().min(1).describe("ID of the memory being replaced."),
+    content: z.string().min(1).describe("The new, corrected content."),
+    type: z
+        .enum(MEMORY_TYPE_TAXONOMY)
+        .optional()
+        .describe("Category of the new memory. Defaults to the old memory's type."),
+    tags: z.array(z.string()).optional().describe("Optional tags for the new memory."),
+};
+export const memoryForgetArgs = {
+    id: z.string().min(1),
+};
+function resolveScope(getScope, kind) {
+    return kind === "personal" || kind === "user" ? PERSONAL_SCOPE : getScope();
+}
+function buildFrontmatter(s, body) {
+    const rfc = msToRfc3339(Date.now());
+    return {
+        id: ulid(),
+        schema_version: 2,
+        scope_key: s.key,
+        scope: s.kind === "project" ? "project" : "personal",
+        visibility: s.kind === "project" ? "internal" : "private",
+        project_name: s.projectName,
+        type: body.type,
+        role: "knowledge",
+        importance: "normal",
+        status: "active",
+        tags: body.tags,
+        source: body.source,
+        created_at: rfc,
+        updated_at: rfc,
+        supersedes: null,
+        superseded_by: null,
+    };
+}
+export async function addMemory(getScope, cfg, args) {
+    const { content: redacted, hadSecret, matchedPattern } = redact(args.content, cfg.redactPatterns);
+    const secretNote = hadSecret
+        ? `\nNote: content matched a secret pattern (${matchedPattern}); it was saved with the secret masked (first 4 chars kept, rest replaced with x).`
+        : "";
+    const s = resolveScope(getScope, args.scope);
+    // Dedup on write (§3.4): identical content is idempotent; near-duplicates
+    // are reported so the caller can supersede instead of duplicating.
+    const dups = findDuplicates(s.key, redacted);
+    if (dups.exact) {
+        return {
+            title: "memory: already exists",
+            output: `Identical memory already exists: id=${dups.exact.id}. Not duplicated.`,
+        };
+    }
+    const fm = buildFrontmatter(s, {
+        type: args.type ?? "fact",
+        tags: args.tags ?? [],
+        source: "tool",
+    });
+    const { filePath } = writeMemoryFile(fm, redacted);
+    const mf = readMemoryFile(filePath);
+    if (mf)
+        upsertFromFile(mf);
+    let output = `Saved to ${s.kind} scope (${s.key}) as ${fm.type}. id=${fm.id}${secretNote}`;
+    for (const n of dups.near) {
+        output += `\nNote: similar memory exists (score ${n.score.toFixed(2)}): id=${n.id} — ${n.snippet}. Use memory_supersede if this replaces it.`;
+    }
+    return { title: `memory: saved ${fm.id}`, output };
+}
+export async function searchMemories(getScope, args) {
+    const project = getScope();
+    const scopeKeys = args.scope === "personal" || args.scope === "user"
+        ? [PERSONAL_SCOPE.key]
+        : args.scope === "project"
+            ? [project.key]
+            : [project.key, PERSONAL_SCOPE.key];
+    const hits = search(args.query, {
+        scopeKeys,
+        limit: args.limit,
+        type: args.type,
+    });
+    if (hits.length === 0) {
+        return {
+            title: "memory: 0 results",
+            output: `No memories matched "${args.query}".`,
+        };
+    }
+    const lines = hits.map((h) => `- [${h.scope_key === PERSONAL_SCOPE.key ? "personal" : "project"}/${h.type}] id=${h.id}\n  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+    return { title: `memory: ${hits.length} result(s)`, output: lines.join("\n") };
+}
+export async function listMemories(getScope, args) {
+    const s = resolveScope(getScope, args.scope);
+    const hits = list(s.key, { type: args.type, limit: args.limit });
+    if (hits.length === 0) {
+        return { title: "memory: empty", output: `No memories in scope ${s.key}.` };
+    }
+    const lines = hits.map((h) => `- [${h.type}] id=${h.id} — ${h.snippet.replace(/\s+/g, " ").trim()}`);
+    return { title: `memory: ${hits.length} in ${s.key}`, output: lines.join("\n") };
+}
+export async function supersedeMemory(cfg, args) {
+    const { content: redacted, hadSecret, matchedPattern } = redact(args.content, cfg.redactPatterns);
+    const secretNote = hadSecret ? ` (secret masked: ${matchedPattern})` : "";
+    try {
+        const { oldMf, newMf } = supersede(args.id, {
+            body: redacted,
+            type: args.type,
+            tags: args.tags,
+            source: "tool",
+        });
+        upsertFromFile(oldMf);
+        upsertFromFile(newMf);
+        return {
+            title: `memory: superseded ${oldMf.fm.id}`,
+            output: `Replaced ${oldMf.fm.id} with ${newMf.fm.id} (old kept as history).${secretNote}`,
+        };
+    }
+    catch (e) {
+        return {
+            title: "memory: supersede failed",
+            output: e.message,
+        };
+    }
+}
+export async function forgetMemory(args) {
+    const row = db()
+        .prepare(`SELECT scope_key FROM memories WHERE id = ?`)
+        .get(args.id);
+    if (!row) {
+        return { title: "memory: not found", output: `No memory with id ${args.id}.` };
+    }
+    deleteMemoryFile(row.scope_key, args.id);
+    deleteFromIndex(args.id);
+    return { title: "memory: forgotten", output: `Deleted ${args.id}.` };
+}

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,78 @@ 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.*
+- **D21** — The published npm package ships pre-compiled JS (`tsc -p tsconfig.build.json`
+  → `dist/`, via `prepublishOnly`; bin points at `dist/cli.js`). *Rationale: Node's
+  `--experimental-strip-types` refuses files under `node_modules`
+  (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so the old launcher
+  (`bin/open-memex.js` re-execing `src/cli.ts`) crashed on every global install —
+  reported 2026-09-27 on Node v22.12.0. Development stays build-free (`npm run cli`
+  / `npm run mcp` run `src/` directly); `doctor`'s MCP self-check resolves its server
+  entry the same way it is running (`dist/mcp.js` vs `src/mcp.ts`). The opencode
+  native plugin still loads `src/index.ts` (Bun strips types anywhere). 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.1",
   "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,16 @@
   "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",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
   },
   "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 +32,11 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0"
+  },
+  "bin": {
+    "open-memex": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=22.6"
   }
 }