open-memex 0.1.0 → 0.3.0-alpha

package/src/doctor.ts

@@ -0,0 +1,161 @@
+// `open-memex doctor` — environment health checks.
+//
+// Read-only except that paths() and the MCP handshake may create the (empty)
+// data directories, exactly like a normal `open-memex mcp` start would.
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.ts";
+import { paths } from "./paths.ts";
+import { resolveCwdScope } from "./scope.ts";
+
+interface Check {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+const EXPECTED_TOOLS = [
+  "memory_add",
+  "memory_search",
+  "memory_list",
+  "memory_supersede",
+  "memory_forget",
+];
+
+function nodeCheck(): Check {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  const ok = major > 22 || (major === 22 && minor >= 6);
+  return {
+    name: "node",
+    ok,
+    detail: `v${process.versions.node} (need >= 22.6 for --experimental-strip-types)`,
+  };
+}
+
+function configCheck(): Check {
+  try {
+    const cfg = loadConfig();
+    const src = configSource();
+    const customized = (Object.keys(DEFAULT_CONFIG) as (keyof typeof DEFAULT_CONFIG)[]).filter(
+      (k) => JSON.stringify(cfg[k]) !== JSON.stringify(DEFAULT_CONFIG[k]),
+    );
+    const detail =
+      (src ?? "built-in defaults") +
+      (customized.length > 0 ? ` — customized: ${customized.join(", ")}` : "");
+    return { name: "config", ok: true, detail };
+  } catch (err) {
+    return { name: "config", ok: false, detail: String(err) };
+  }
+}
+
+function scopeCheck(): Check {
+  try {
+    const s = resolveCwdScope(process.cwd());
+    return { name: "scope", ok: true, detail: `cwd → ${s.kind} scope "${s.key}"` };
+  } catch (err) {
+    return { name: "scope", ok: false, detail: String(err) };
+  }
+}
+
+function storageCheck(): Check {
+  try {
+    const p = paths();
+    fs.accessSync(p.memories, fs.constants.W_OK);
+    return { name: "storage", ok: true, detail: `${p.root} (writable)` };
+  } catch (err) {
+    return { name: "storage", ok: false, detail: String(err) };
+  }
+}
+
+/** Spawn the real MCP server, handshake, and verify the five tools list. */
+function mcpCheck(): Promise<Check> {
+  const name = "mcp";
+  return new Promise((resolve) => {
+    const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+    const server = path.join(root, "src", "mcp.ts");
+    if (!fs.existsSync(server)) {
+      resolve({ name, ok: false, detail: `server entry not found: ${server}` });
+      return;
+    }
+    const child = spawn(process.execPath, ["--experimental-strip-types", server], {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    const done = (c: Check) => {
+      clearTimeout(timer);
+      try {
+        child.kill();
+      } catch {
+        /* already exited */
+      }
+      resolve(c);
+    };
+    const timer = setTimeout(
+      () => done({ name, ok: false, detail: "handshake timed out after 20s" }),
+      20000,
+    );
+
+    let buf = "";
+    const send = (msg: object) => child.stdin.write(JSON.stringify(msg) + "\n");
+
+    child.stdout.on("data", (d: Buffer) => {
+      buf += d.toString();
+      let idx: number;
+      while ((idx = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, idx).trim();
+        buf = buf.slice(idx + 1);
+        if (!line) continue;
+        let msg: { id?: number; result?: { tools?: { name: string }[] } };
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          continue; // ignore non-JSON lines on stdout
+        }
+        if (msg.id === 1 && msg.result) {
+          send({ jsonrpc: "2.0", method: "notifications/initialized" });
+          send({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+        } else if (msg.id === 2) {
+          const names = (msg.result?.tools ?? []).map((t) => t.name);
+          const missing = EXPECTED_TOOLS.filter((t) => !names.includes(t));
+          done({
+            name,
+            ok: missing.length === 0,
+            detail:
+              missing.length === 0
+                ? `handshake OK, 5 tools listed (${names.join(", ")})`
+                : `missing tools: ${missing.join(", ")}`,
+          });
+        }
+      }
+    });
+    child.on("error", (err) =>
+      done({ name, ok: false, detail: `spawn failed: ${(err as Error).message}` }),
+    );
+    // Server stderr is its own log; not a doctor failure signal.
+
+    send({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "open-memex-doctor", version: "0.0.0" },
+      },
+    });
+  });
+}
+
+export async function runDoctor(): Promise<boolean> {
+  console.log("open-memex doctor");
+  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck()];
+  checks.push(await mcpCheck());
+  let allOk = true;
+  for (const c of checks) {
+    console.log(`  ${c.ok ? "ok  " : "FAIL"} ${c.name}: ${c.detail}`);
+    if (!c.ok) allOk = false;
+  }
+  console.log(allOk ? "All checks passed." : "Some checks failed — see above.");
+  return allOk;
+}

package/src/index.ts

@@ -1,6 +1,6 @@
 import type { Plugin } from "@opencode-ai/plugin";
 import { loadConfig } from "./config.ts";
-import { resolveProjectScope, resolveCwdScope, USER_SCOPE, type Scope } from "./scope.ts";
+import { resolveProjectScope, resolveCwdScope, PERSONAL_SCOPE, type Scope } from "./scope.ts";
 import { db } from "./store/db.ts";
 import { syncScope, upsertFromFile } from "./store/sync.ts";
 import { scopeHasFiles } from "./store/migrate.ts";
@@ -8,10 +8,12 @@ import {
   writeMemoryFile,
   readMemoryFile,
   ulid,
+  msToRfc3339,
   type Frontmatter,
 } from "./store/markdown.ts";
 import { buildContextBlock } from "./retrieve/inject.ts";
 import { detectKeywords } from "./capture/keywords.ts";
+import { findDuplicates } from "./store/lifecycle.ts";
 import { redact } from "./redact.ts";
 import { makeTools } from "./tools/memory.ts";
 
@@ -24,7 +26,7 @@ const plugin: Plugin = async ({ worktree, directory }) => {
   try {
     db();
     syncScope(scope.key);
-    syncScope(USER_SCOPE.key);
+    syncScope(PERSONAL_SCOPE.key);
     if (cfg.logLevel === "debug") {
       console.log(`[open-memex] loaded. scope=${scope.key}`);
     }
@@ -61,27 +63,46 @@ const plugin: Plugin = async ({ worktree, directory }) => {
 
       const hits = detectKeywords(text, cfg);
       for (const h of hits) {
-        const { content, hadSecret } = redact(h.content, cfg.redactPatterns);
-        if (hadSecret || content.length === 0) continue;
+        const { content, hadSecret, matchedPattern } = redact(h.content, cfg.redactPatterns);
+        // Secrets are masked (first 4 chars kept) and the capture proceeds;
+        // skip only when nothing usable remains.
+        if (content.length === 0) continue;
+        if (hadSecret && cfg.logLevel === "debug") {
+          console.log(`[open-memex] keyword capture masked secret (${matchedPattern})`);
+        }
+        // Personal patterns ("remember for me" / "记住（个人）") force the personal scope.
+        const target = h.personal ? PERSONAL_SCOPE : scope;
+        // Dedup (§3.4): skip exact duplicates captured before.
+        if (findDuplicates(target.key, content).exact) continue;
         const now = Date.now();
+        const rfc = msToRfc3339(now);
         const fm: Frontmatter = {
           id: ulid(),
-          scope_key: scope.key,
-          scope_kind: scope.kind,
-          project_name: scope.projectName,
-          type: "note",
+          schema_version: 2,
+          scope_key: target.key,
+          scope: target.kind === "project" ? "project" : "personal",
+          visibility: target.kind === "project" ? "internal" : "private",
+          project_name: target.projectName,
+          type: "fact",
+          role: "knowledge",
+          importance: "normal",
+          status: "active",
           tags: ["keyword"],
           source: "keyword",
-          created_at: now,
-          updated_at: now,
+          created_at: rfc,
+          updated_at: rfc,
+          supersedes: null,
+          superseded_by: null,
         };
         try {
           const { filePath } = writeMemoryFile(fm, content);
           const mf = readMemoryFile(filePath);
           if (mf) upsertFromFile(mf);
-          if (cfg.logLevel === "debug") {
-            console.log(`[open-memex] captured keyword memory ${fm.id}`);
-          }
+          // Capture feedback: always visible (not debug-only) — the user said
+          // "记住…", they should see that it landed. The opencode plugin API
+          // offers no toast channel, so the plugin log is the feedback surface.
+          const preview = content.length > 60 ? content.slice(0, 60) + "…" : content;
+          console.log(`[open-memex] remembered → ${target.kind} scope: "${preview}"`);
         } catch (err) {
           console.error("[open-memex] keyword capture failed:", err);
         }

package/src/init.ts

@@ -0,0 +1,304 @@
+// `open-memex init` — one-command project setup (§17 adoption path).
+// Pure file operation: no DB, no network. Safe to run in any directory.
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { DEFAULT_CONFIG, saveConfig } from "./config.ts";
+
+const MARKER = "<!-- open-memex -->";
+
+/** npm dist-tag carrying the 0.3.x preview line. */
+const ALPHA_TAG = "open-memex@alpha";
+
+export interface McpCommand {
+  command: string;
+  args: string[];
+  /** false when no durable bin exists (e.g. one-shot npx) and we fell back to npx. */
+  durable: boolean;
+}
+
+/**
+ * Resolve the MCP server command to write into client configs.
+ *
+ * A one-shot `npx open-memex@alpha init` runs from npm's ephemeral `_npx` cache,
+ * so `open-memex` resolving on PATH *inside that process* does not mean it will be
+ * there tomorrow. Only a bin found on PATH outside `_npx` cache dirs counts as
+ * durable; otherwise fall back to an npx-based command (slower startup, zero install).
+ */
+export function resolveMcpCommand(): McpCommand {
+  const pathEnv = process.env.PATH ?? "";
+  const dirs = pathEnv.split(path.delimiter).filter((d) => d && !d.includes("_npx"));
+  const names = process.platform === "win32" ? ["open-memex.cmd", "open-memex"] : ["open-memex"];
+  const durable = dirs.some((d) =>
+    names.some((n) => {
+      try {
+        return fs.existsSync(path.join(d, n));
+      } catch {
+        return false;
+      }
+    }),
+  );
+  if (durable) return { command: "open-memex", args: ["mcp"], durable: true };
+  return { command: "npx", args: ["-y", ALPHA_TAG, "mcp"], durable: false };
+}
+
+const INSTRUCTIONS = `${MARKER}
+# OpenMemex memory
+
+You have a local memory MCP server (\`open-memex\`) with five tools:
+\`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`, \`memory_forget\`.
+
+- BE PROACTIVE. When the user shares something worth remembering across sessions
+  (a decision, a preference, a project convention, a fix and its cause), call
+  \`memory_add\` without being asked. Keep each memory to one self-contained statement.
+- Before asking the user about past decisions, conventions, or preferences they may
+  have told you before, call \`memory_search\` first — try a few keyword variants
+  (including the user's own language) when the first search comes up empty.
+- Memories default to this project's scope; use the \`personal\` scope for facts about
+  the user that hold across all projects. When a saved fact becomes outdated, call
+  \`memory_supersede\` instead of adding a duplicate.
+`;
+
+/** Project root: git top-level, falling back to cwd. */
+function projectRoot(): string {
+  try {
+    const top = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (top) return top;
+  } catch {
+    /* not a git repo — use cwd */
+  }
+  return process.cwd();
+}
+
+function writeMcpJson(root: string, client: string, force: boolean): string | null {
+  if (client === "opencode") return writeOpencodeMcpJson(root, force);
+  if (client === "visualstudio") return writeVisualStudioMcpJson(root, force);
+  const dir = client === "cursor" ? path.join(root, ".cursor") : path.join(root, ".vscode");
+  const file = path.join(dir, "mcp.json");
+  const sectionKey = client === "cursor" ? "mcpServers" : "servers";
+
+  let doc: Record<string, unknown> = {};
+  if (fs.existsSync(file)) {
+    try {
+      doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+    } catch {
+      console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+      return null;
+    }
+  }
+
+  const section = ((doc[sectionKey] ??= {}) as Record<string, unknown>);
+  if (section["open-memex"] && !force) {
+    console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
+    return file;
+  }
+  // D17: resolve the server command at init time — a one-shot npx leaves no bin behind.
+  const mc = resolveMcpCommand();
+  section["open-memex"] =
+    client === "cursor"
+      ? { command: mc.command, args: mc.args }
+      : {
+          type: "stdio",
+          command: mc.command,
+          args: mc.args,
+          cwd: "${workspaceFolder}",
+        };
+
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+  console.log(`  + ${file}`);
+  if (!mc.durable) {
+    console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
+    console.log(`    For faster startup: \`npm i -g ${ALPHA_TAG}\`, then re-run \`open-memex init --force\`.`);
+  }
+  return file;
+}
+
+/** opencode MCP config: project-level opencode.jsonc, `type: "local"` + command array (v1 format). */
+function writeOpencodeMcpJson(root: string, force: boolean): string | null {
+  const file = path.join(root, "opencode.jsonc");
+  let doc: Record<string, unknown> = {};
+  if (fs.existsSync(file)) {
+    try {
+      doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+    } catch {
+      console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+      return null;
+    }
+  }
+  const section = ((doc["mcp"] ??= {}) as Record<string, unknown>);
+  if (section["open-memex"] && !force) {
+    console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
+    return file;
+  }
+  // D17: resolve the server command at init time — a one-shot npx leaves no bin behind.
+  const mc = resolveMcpCommand();
+  section["open-memex"] = {
+    type: "local",
+    command: [mc.command, ...mc.args],
+    enabled: true,
+  };
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+  console.log(`  + ${file}`);
+  if (!mc.durable) {
+    console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
+    console.log(`    For faster startup: \`npm i -g ${ALPHA_TAG}\`, then re-run \`open-memex init --force\`.`);
+  }
+  return file;
+}
+
+/** Visual Studio (Windows-only, 2022 17.14+ / 2026): solution-level `.mcp.json`
+ * with the `"servers"` section, per Microsoft Learn. Source-controllable.
+ * (VS also auto-discovers `.vscode/mcp.json` and `.cursor/mcp.json`.) */
+function writeVisualStudioMcpJson(root: string, force: boolean): string | null {
+  const file = path.join(root, ".mcp.json");
+  let doc: Record<string, unknown> = {};
+  if (fs.existsSync(file)) {
+    try {
+      doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+    } catch {
+      console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+      return null;
+    }
+  }
+  const section = ((doc["servers"] ??= {}) as Record<string, unknown>);
+  if (section["open-memex"] && !force) {
+    console.log(`  = ${file} already configures open-memex — left as is (use --force to overwrite)`);
+    return file;
+  }
+  // D17: resolve the server command at init time — a one-shot npx leaves no bin behind.
+  const mc = resolveMcpCommand();
+  section["open-memex"] = {
+    type: "stdio",
+    command: mc.command,
+    args: mc.args,
+  };
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+  console.log(`  + ${file}`);
+  if (!mc.durable) {
+    console.log(`  ! no durable \`open-memex\` on PATH (one-shot npx?) — wrote an npx-based command.`);
+    console.log(`    For faster startup: \`npm i -g ${ALPHA_TAG}\`, then re-run \`open-memex init --force\`.`);
+  }
+  return file;
+}
+
+function writeInstructions(root: string): string {
+  const dir = path.join(root, ".github");
+  const file = path.join(dir, "copilot-instructions.md");
+  if (fs.existsSync(file)) {
+    const cur = fs.readFileSync(file, "utf8");
+    if (cur.includes(MARKER)) {
+      console.log(`  = ${file} already has open-memex instructions — left as is`);
+      return file;
+    }
+    fs.writeFileSync(file, cur.replace(/\s+$/, "") + "\n\n" + INSTRUCTIONS);
+  } else {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, INSTRUCTIONS);
+  }
+  console.log(`  + ${file}`);
+  return file;
+}
+
+export const INIT_CLIENTS = ["vscode", "cursor", "opencode", "visualstudio"] as const;
+
+/** Normalize --client values; accepts "visual-studio" as an alias. */
+export function normalizeClient(c: string): string {
+  const lower = c.toLowerCase();
+  return lower === "visual-studio" ? "visualstudio" : lower;
+}
+
+/** Ask a yes/no question. Only called on a TTY when --yes was not passed. */
+async function askBool(q: string, def: boolean): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const hint = def ? "Y/n" : "y/N";
+    const ans = (await rl.question(`${q} [${hint}]: `)).trim().toLowerCase();
+    if (!ans) return def;
+    return ans === "y" || ans === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptClient(): Promise<string | null> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const ans = (
+      await rl.question(
+        "Which editor? (1) VS Code  (2) Cursor  (3) opencode  (4) Visual Studio  (5) skip [1]: ",
+      )
+    ).trim();
+    switch (ans) {
+      case "":
+      case "1":
+        return "vscode";
+      case "2":
+        return "cursor";
+      case "3":
+        return "opencode";
+      case "4":
+        return "visualstudio";
+      case "5":
+        return null;
+      default:
+        console.log(`  ? unknown choice "${ans}" — editor setup skipped`);
+        return null;
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+export async function initProject(opts: {
+  client?: string;
+  force: boolean;
+  yes: boolean;
+}): Promise<void> {
+  const interactive = !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+  let client = normalizeClient(opts.client ?? "");
+  if (client && !(INIT_CLIENTS as readonly string[]).includes(client)) {
+    console.error(`unknown client "${opts.client}" (${INIT_CLIENTS.join("|")})`);
+    process.exit(1);
+  }
+  if (!client && interactive) client = (await promptClient()) ?? "";
+  if (!client && !interactive) client = "vscode"; // historical default for scripts / one-shot npx
+  if (interactive) {
+    // Install-time settings (D19). Non-default answers persist to the JSONC
+    // config file; `open-memex config set` changes them later.
+    const patch: Record<string, unknown> = {};
+    const keywordCaptureEnabled = await askBool(
+      "Auto-capture keywords like 记住… / remember… into memory?",
+      DEFAULT_CONFIG.keywordCaptureEnabled,
+    );
+    if (keywordCaptureEnabled !== DEFAULT_CONFIG.keywordCaptureEnabled)
+      patch.keywordCaptureEnabled = keywordCaptureEnabled;
+    const injectOnFirstTurn = await askBool(
+      "Inject relevant memories when a session starts?",
+      DEFAULT_CONFIG.injectOnFirstTurn,
+    );
+    if (injectOnFirstTurn !== DEFAULT_CONFIG.injectOnFirstTurn)
+      patch.injectOnFirstTurn = injectOnFirstTurn;
+    if (Object.keys(patch).length > 0) {
+      const file = saveConfig(patch);
+      console.log(
+        `  + settings saved to ${file} (change later with \`open-memex config set <key> <value>\`)`,
+      );
+    }
+  }
+  const root = projectRoot();
+  console.log(`open-memex init — project root: ${root}`);
+  if (client) {
+    writeMcpJson(root, client, opts.force);
+    // copilot-instructions.md is VS Code/Cursor-shaped; opencode as a plain MCP
+    // consumer already gets the guidance from the tool descriptions (D16).
+    if (client !== "opencode") writeInstructions(root);
+  } else {
+    console.log("  - editor setup skipped");
+  }
+  console.log(`\nDone. Reload your editor window to start the open-memex MCP server.`);
+}

package/src/mcp.ts

@@ -0,0 +1,133 @@
+/**
+ * open-memex generic MCP server (stdio transport).
+ *
+ * Exposes the same five memory tools as the opencode plugin
+ * (memory_add / memory_search / memory_list / memory_supersede /
+ * memory_forget) over the Model Context Protocol, so any MCP client —
+ * VS Code Copilot Chat, Cursor, Claude Code, etc. — can use open-memex
+ * without a host-specific plugin.
+ *
+ * Run:  node --experimental-strip-types src/mcp.ts
+ *        (or: npm run mcp)
+ *
+ * The project scope is resolved from the process working directory, so
+ * launch the server with cwd set to the project root (VS Code, Cursor and
+ * Claude Code all do this for workspace-configured MCP servers).
+ *
+ * IMPORTANT: stdout is the MCP protocol channel. Never log to stdout here;
+ * diagnostics go to stderr.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "./config.ts";
+import { resolveProjectScope, PERSONAL_SCOPE, type Scope } from "./scope.ts";
+import { db } from "./store/db.ts";
+import { syncScope } from "./store/sync.ts";
+import {
+  addMemory,
+  searchMemories,
+  listMemories,
+  supersedeMemory,
+  forgetMemory,
+  memoryAddArgs,
+  memorySearchArgs,
+  memoryListArgs,
+  memorySupersedeArgs,
+  memoryForgetArgs,
+  TOOL_DESCRIPTIONS,
+  type ToolResult,
+} from "./tools/ops.ts";
+
+const SERVER_VERSION = "0.2.0-alpha";
+
+/** Adapt a framework-agnostic op result to an MCP tool response. */
+function toMcp(p: Promise<ToolResult>) {
+  return p.then(
+    (r) => ({ content: [{ type: "text" as const, text: r.output }] }),
+    (e: unknown) => ({
+      content: [
+        {
+          type: "text" as const,
+          text: `open-memex error: ${(e as Error)?.message ?? String(e)}`,
+        },
+      ],
+      isError: true as const,
+    }),
+  );
+}
+
+export async function runMcpServer() {
+  const cfg = loadConfig();
+  const scope: Scope = resolveProjectScope(process.cwd());
+  const getScope = () => scope;
+
+  // Init DB and one-shot sync of markdown -> index, mirroring the plugin.
+  db();
+  syncScope(scope.key);
+  syncScope(PERSONAL_SCOPE.key);
+  console.error(`[open-memex] MCP server up. scope=${scope.key}`);
+
+  const server = new McpServer({ name: "open-memex", version: SERVER_VERSION });
+
+  server.registerTool(
+    "memory_add",
+    {
+      description: TOOL_DESCRIPTIONS.memory_add,
+      inputSchema: z.object(memoryAddArgs),
+    },
+    (args) => toMcp(addMemory(getScope, cfg, args)),
+  );
+
+  server.registerTool(
+    "memory_search",
+    {
+      description: TOOL_DESCRIPTIONS.memory_search,
+      inputSchema: z.object(memorySearchArgs),
+      annotations: { readOnlyHint: true },
+    },
+    (args) => toMcp(searchMemories(getScope, args)),
+  );
+
+  server.registerTool(
+    "memory_list",
+    {
+      description: TOOL_DESCRIPTIONS.memory_list,
+      inputSchema: z.object(memoryListArgs),
+      annotations: { readOnlyHint: true },
+    },
+    (args) => toMcp(listMemories(getScope, args)),
+  );
+
+  server.registerTool(
+    "memory_supersede",
+    {
+      description: TOOL_DESCRIPTIONS.memory_supersede,
+      inputSchema: z.object(memorySupersedeArgs),
+    },
+    (args) => toMcp(supersedeMemory(cfg, args)),
+  );
+
+  server.registerTool(
+    "memory_forget",
+    {
+      description: TOOL_DESCRIPTIONS.memory_forget,
+      inputSchema: z.object(memoryForgetArgs),
+      annotations: { destructiveHint: true },
+    },
+    (args) => toMcp(forgetMemory(args)),
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// Standalone entry: `node --experimental-strip-types src/mcp.ts`.
+// The CLI (`open-memex mcp`) imports runMcpServer() instead.
+import { pathToFileURL } from "node:url";
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runMcpServer().catch((err) => {
+    console.error("[open-memex] MCP server failed:", err);
+    process.exit(1);
+  });
+}