open-memex 0.2.0-alpha → 0.3.0-alpha

package/scripts/smoke-pure.ts

@@ -85,7 +85,8 @@ const builtinSamples: Array<[string, string]> = [
   ["npm-token", "t=npm_12345678901234567890123456789012"],
   ["gitlab-pat", "t=glpat-12345678901234567890ab"],
   ["stripe-webhook-secret", "s=whsec_12345678901234567890"],
-  ["private-key-block", "-----BEGIN RSA PRIVATE KEY-----"],
+  ["private-key-block", "-----BEGIN RSA PRIVATE KEY-----\nQUJD\n-----END RSA PRIVATE KEY-----"],
+  ["private-key-truncated", "-----BEGIN RSA PRIVATE KEY-----"],
   ["generic-secret-assignment", 'password = "hunter2hunter2hunter2"'],
 ];
 for (const [id, sample] of builtinSamples) {
@@ -142,6 +143,46 @@ ok("wrapped secret does not trigger", r4.hadSecret === false);
 const r5 = redact("foo CUSTOM123 bar", ["CUSTOM\\d+"]);
 ok("user pattern detected", r5.hadSecret === true && r5.matchedPattern === "CUSTOM\\d+", r5.matchedPattern);
 
+console.log("== redact masking (D14) ==");
+// Secrets are masked in place (first 4 chars kept, rest → x), never refused.
+const m1 = redact("deploy uses key=sk-1234567890abcdefghij1234 in prod", []);
+ok("mask: detected", m1.hadSecret === true && m1.matchedPattern === "openai-key", m1.matchedPattern);
+ok("mask: prefix kept", m1.content.includes("sk-1"), m1.content);
+ok("mask: rest x'd", m1.content.includes("sk-1xxxxxxxxxxxxxxxxxxxxx"), m1.content);
+ok("mask: full secret gone", !m1.content.includes("1234567890abcdefghij"));
+ok("mask: surrounding text kept", m1.content.startsWith("deploy uses key=") && m1.content.includes(" in prod"));
+// User patterns mask too.
+ok("mask: user pattern", redact("foo CUSTOM123 bar", ["CUSTOM\\d+"]).content.includes("CUSTxxxxx"));
+// High-entropy: value masked, name kept.
+const r6 = redact('deploy_key = "aB3dE5fG7hJ9kL2mN4pQ6rS8tU0vW2xY4zA6bC8dE0"', []);
+ok("mask: entropy value masked", r6.content.includes("aB3dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"), r6.content);
+ok("mask: entropy name kept", r6.content.includes("deploy_key ="));
+// URLs are never masked, even when another secret is present in the same text.
+const r7 = redact("see https://api.example.com/v1/users/list and key=sk-1234567890abcdefghij1234", []);
+ok("mask: mixed url+secret detected", r7.hadSecret === true, r7.matchedPattern);
+ok("mask: url intact", r7.content.includes("https://api.example.com/v1/users/list"), r7.content);
+ok("mask: second secret also masked", !r7.content.includes("sk-1234567890"), r7.content);
+// Bare high-entropy URL: the scheme colon must not turn the URL into a secret.
+const r8 = redact("see https://aB3dEfGhIjKlMnOpQrStUvWx0123456789abcdef for details", []);
+ok("mask: bare url untouched", r8.hadSecret === false && r8.content.includes("https://aB3dEfGhIjKlMnOpQrStUvWx0123456789abcdef"), r8.content);
+// Private key: the WHOLE block is masked, body must not survive in readable form.
+const pemBody = "MIIEpAIBAAKCAQEA7bXprGBcW2l5K3R8vN0mQw0F3xY2vBn5T6uI7oP8a9S0dF1gH";
+const r9 = redact(`note: server key\n-----BEGIN RSA PRIVATE KEY-----\n${pemBody}\n-----END RSA PRIVATE KEY-----\nafter`, []);
+ok("mask: pem detected", r9.hadSecret === true && r9.matchedPattern === "private-key-block", r9.matchedPattern);
+ok("mask: pem body gone", !r9.content.includes(pemBody), r9.content);
+ok("mask: pem surrounding kept", r9.content.includes("note: server key") && r9.content.includes("after"));
+// Truncated key (no END marker): masked to end of text.
+const r10 = redact(`note\n-----BEGIN RSA PRIVATE KEY-----\n${pemBody}\ntrailing prose`, []);
+ok("mask: truncated pem detected", r10.hadSecret === true, r10.matchedPattern);
+ok("mask: truncated pem body gone", !r10.content.includes(pemBody) && !r10.content.includes("trailing prose"), r10.content);
+// Name-including patterns mask the value only; the name stays readable (D14).
+const r11 = redact('api_key = "supersecretvalue123456"', []);
+ok("mask: generic name kept", r11.content.includes("api_key ="), r11.content);
+ok("mask: generic value masked", !r11.content.includes("supersecretvalue123456") && r11.content.includes("supexxxxxxxxxxxxxxxx"), r11.content);
+const r12 = redact('aws_secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCY1234567890"', []);
+ok("mask: aws name kept", r12.content.includes("aws_secret_access_key ="), r12.content);
+ok("mask: aws value masked", !r12.content.includes("wJalrXUtnFEMI"), r12.content);
+
 console.log("== keywords ==");
 const hits1 = detectKeywords("remember that this repo uses Bun, not Node", DEFAULT_CONFIG);
 ok("basic remember matched", hits1.length === 1);

package/src/capture/keywords.ts

@@ -3,32 +3,45 @@ import type { MyOMemoryConfig } from "../config.ts";
 export interface KeywordHit {
   content: string;
   pattern: string;
+  /** True when the hit came from a personal-scope pattern: force personal scope. */
+  personal: boolean;
 }
 
 /**
  * Scan user text for memory-capture keyword triggers.
  * Each pattern must have a single capture group whose value becomes the memory body.
+ * Personal patterns (cfg.keywordPersonalPatterns) force the personal scope.
+ *
+ * Personal patterns run first and claim their line: an explicit scope signal
+ * (e.g. "记住我对花粉过敏") must not also fire the generic 记住 into the project scope.
  */
 export function detectKeywords(userText: string, cfg: MyOMemoryConfig): KeywordHit[] {
   if (!cfg.keywordCaptureEnabled) return [];
   const hits: KeywordHit[] = [];
   const lines = userText.split(/\r?\n/);
-  for (const src of cfg.keywordPatterns) {
-    let re: RegExp;
-    try {
-      re = new RegExp(src, "i");
-    } catch {
-      continue;
-    }
-    for (const line of lines) {
-      const m = line.match(re);
-      if (!m || !m[1]) continue;
-      const content = m[1].trim().replace(/[.!?]$/, "").trim();
-      if (content.length >= 3 && content.length <= 2000) {
-        hits.push({ content, pattern: src });
-        break; // one hit per pattern per message
+  const claimed = new Set<number>();
+  const scan = (patterns: string[], personal: boolean, skipClaimed: boolean) => {
+    for (const src of patterns) {
+      let re: RegExp;
+      try {
+        re = new RegExp(src, "i");
+      } catch {
+        continue;
+      }
+      for (let i = 0; i < lines.length; i++) {
+        if (skipClaimed && claimed.has(i)) continue;
+        const m = lines[i].match(re);
+        if (!m || !m[1]) continue;
+        const content = m[1].trim().replace(/[.!?]$/, "").trim();
+        if (content.length >= 3 && content.length <= 2000) {
+          hits.push({ content, pattern: src, personal });
+          if (personal) claimed.add(i);
+          break; // one hit per pattern per message
+        }
       }
     }
-  }
+  };
+  scan(cfg.keywordPersonalPatterns, true, false);
+  scan(cfg.keywordPatterns, false, true);
   return hits;
 }

package/src/cli.ts

@@ -18,6 +18,7 @@ import {
 import { loadConfig } from "./config.ts";
 import { paths } from "./paths.ts";
 import { redact } from "./redact.ts";
+import { resolveMcpCommand } from "./init.ts";
 import fs from "node:fs";
 
 function usage(): never {
@@ -36,6 +37,25 @@ Usage:
   node --experimental-strip-types src/cli.ts migrate [--from <key>] [--to <key>]
                                           [--dry-run] [--on-conflict newer|overwrite|skip]
   node --experimental-strip-types src/cli.ts migrate --to-v2 [--dry-run]
+  node --experimental-strip-types src/cli.ts mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
+  node --experimental-strip-types src/cli.ts init [--client vscode|cursor|opencode|visualstudio] [--force] [--yes]
+  node --experimental-strip-types src/cli.ts config [set <key> <value>]
+  node --experimental-strip-types src/cli.ts capture --dry-run "text"
+  node --experimental-strip-types src/cli.ts doctor
+
+One-command project setup: \`open-memex init\` (or \`npx open-memex@alpha init\`) writes
+the MCP config for your editor (\`.vscode/mcp.json\`, \`.cursor/mcp.json\`,
+\`opencode.jsonc\`, or Visual Studio's solution-level \`.mcp.json\`) plus
+\`.github/copilot-instructions.md\` — no copy-paste needed.
+Existing files are merged, never clobbered; re-running is safe. On a terminal it
+asks which editor to set up and a couple of settings (keyword capture, first-turn
+injection); \`--yes\` accepts all defaults, and non-terminal runs never prompt.
+\`open-memex config set <key> <value>\` changes those settings after install.
+
+Once installed globally (\`npm i -g open-memex@alpha\`) the \`open-memex\` command is
+available directly: \`open-memex mcp\` starts the stdio MCP server (same five
+memory_* tools as the opencode plugin); \`open-memex mcp --print-config <client>\`
+prints a copy-paste MCP client config snippet.
 
 Scope defaults to \`project\` (derived from cwd's git remote or path).
 \`user\` is accepted as a deprecated alias of \`personal\`.
@@ -74,6 +94,89 @@ function resolveCliScope(flags: Record<string, string>, project: Scope): Scope {
     : project;
 }
 
+/** Print a copy-paste MCP client config snippet. Requires a global install
+ * (`npm i -g open-memex@alpha`) so the `open-memex` command is on PATH. */
+function printMcpConfig(client: string): never {
+  const c = client.toLowerCase();
+  // D17: resolve the server command the same way `init` does.
+  const mc = resolveMcpCommand();
+  if (c === "vscode") {
+    console.log(
+      JSON.stringify(
+        {
+          servers: {
+            "open-memex": {
+              type: "stdio",
+              command: mc.command,
+              args: mc.args,
+              cwd: "${workspaceFolder}",
+            },
+          },
+        },
+        null,
+        2,
+      ),
+    );
+  } else if (c === "cursor") {
+    console.log(
+      JSON.stringify(
+        {
+          mcpServers: {
+            "open-memex": { command: mc.command, args: mc.args },
+          },
+        },
+        null,
+        2,
+      ),
+    );
+  } else if (c === "claude") {
+    console.log(`claude mcp add open-memex -- ${mc.command} ${mc.args.join(" ")}`);
+  } else if (c === "opencode") {
+    // D16: opencode as a plain MCP consumer (alternative to the native plugin).
+    console.log(
+      JSON.stringify(
+        {
+          mcp: {
+            "open-memex": {
+              type: "local",
+              command: [mc.command, ...mc.args],
+              enabled: true,
+            },
+          },
+        },
+        null,
+        2,
+      ),
+    );
+  } else if (c === "visualstudio" || c === "visual-studio") {
+    // D20: Visual Studio (Windows-only) reads solution-level `.mcp.json`.
+    console.log(
+      JSON.stringify(
+        {
+          servers: {
+            "open-memex": {
+              type: "stdio",
+              command: mc.command,
+              args: mc.args,
+            },
+          },
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.error(`unknown client "${client}" (vscode|cursor|claude|opencode|visualstudio)`);
+    process.exit(1);
+  }
+  if (!mc.durable) {
+    console.error(
+      `\n# note: no durable \`open-memex\` on PATH — snippet uses npx. \`npm i -g open-memex@alpha\` for faster startup.`,
+    );
+  }
+  process.exit(0);
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   if (!cmd) usage();
@@ -113,6 +216,105 @@ async function main() {
     return;
   }
 
+  // `init` is a pure file operation (§17 adoption path) — no DB needed.
+  // Interactive when on a TTY (asks editor + settings); --yes skips prompts.
+  if (cmd === "init") {
+    const flags = parseFlags(rest);
+    const { initProject } = await import("./init.ts");
+    await initProject({
+      client: flags["client"],
+      force: flags["force"] === "true",
+      yes: flags["yes"] === "true",
+    });
+    return;
+  }
+
+  // `doctor` runs environment health checks — no DB needed (it self-contains).
+  if (cmd === "doctor") {
+    const { runDoctor } = await import("./doctor.ts");
+    const ok = await runDoctor();
+    if (!ok) process.exitCode = 1;
+    return;
+  }
+
+  // `config` prints the effective configuration (defaults + file). No DB needed.
+  // `config set <key> <value>` persists a setting to the config file.
+  if (cmd === "config") {
+    if (rest[0] === "set") {
+      const [, key, ...valueParts] = rest;
+      const { SETTABLE_KEYS, saveConfig, configFilePath } = await import("./config.ts");
+      const validate = key ? SETTABLE_KEYS[key] : undefined;
+      if (!validate) {
+        console.error(
+          `unknown or unsettable key "${key ?? ""}". Settable keys: ${Object.keys(SETTABLE_KEYS).join(", ")}`,
+        );
+        process.exit(1);
+      }
+      const raw = valueParts.join(" ");
+      if (!raw) {
+        console.error(`usage: open-memex config set <key> <value>`);
+        process.exit(1);
+      }
+      let value: unknown = raw;
+      try {
+        value = JSON.parse(raw);
+      } catch {
+        /* keep as string */
+      }
+      try {
+        const saved = validate(value);
+        const file = saveConfig({ [key!]: saved });
+        console.log(`set ${key} = ${JSON.stringify(saved)} (${file})`);
+      } catch (err) {
+        console.error(`invalid value for ${key}: ${(err as Error).message}`);
+        process.exit(1);
+      }
+      return;
+    }
+    const cfg = loadConfig();
+    console.log(JSON.stringify(cfg, null, 2));
+    return;
+  }
+
+  // `capture --dry-run "text"` previews keyword capture without writing. No DB needed.
+  if (cmd === "capture") {
+    if (rest[0] !== "--dry-run") {
+      console.error(`usage: open-memex capture --dry-run "text"`);
+      process.exit(1);
+    }
+    const cfg = loadConfig();
+    const { detectKeywords } = await import("./capture/keywords.ts");
+    const text = rest.slice(1).join(" ");
+    const hits = detectKeywords(text, cfg);
+    if (hits.length === 0) {
+      console.log("no keyword triggers — nothing would be captured.");
+      return;
+    }
+    for (const h of hits) {
+      const r = redact(h.content, cfg.redactPatterns);
+      console.log(`- pattern:      ${h.pattern}`);
+      console.log(`  scope:        ${h.personal ? "personal (forced by pattern)" : "current scope"}`);
+      console.log(`  secret hit:   ${r.hadSecret ? `yes (${r.matchedPattern}) — will be masked` : "no"}`);
+      console.log(
+        `  body:         ${r.content.slice(0, 160)}${r.content.length > 160 ? "…" : ""}`,
+      );
+    }
+    return;
+  }
+
+  // `mcp` starts the stdio MCP server (same tools as the opencode plugin).
+  // Branched before db() — runMcpServer() does its own init, and stdout must
+  // stay clean for the MCP protocol.
+  if (cmd === "mcp") {
+    const flags = parseFlags(rest);
+    if (flags["print-config"]) {
+      printMcpConfig(flags["print-config"] === "true" ? "vscode" : flags["print-config"]);
+    }
+    const { runMcpServer } = await import("./mcp.ts");
+    await runMcpServer();
+    return;
+  }
+
   db();
 
   if (cmd === "where") {
@@ -188,12 +390,9 @@ async function main() {
     const flags = parseFlags(rest.slice(1));
     const s = resolveCliScope(flags, project);
     const { content: red, hadSecret, matchedPattern } = redact(content, cfg.redactPatterns);
-    if (hadSecret) {
-      console.error(`refused: content matched secret pattern (${matchedPattern}).`);
-      process.exit(2);
-    }
     // Dedup on write (§3.4): identical content is idempotent; near-duplicates
     // warn but still save (use `supersede` when this replaces the old one).
+    // Secrets are masked (first 4 chars kept) and the write proceeds.
     const dups = findDuplicates(s.key, red);
     if (dups.exact) {
       console.log(`already exists: id=${dups.exact.id} (identical content — not duplicated)`);
@@ -227,7 +426,12 @@ async function main() {
     const { filePath } = writeMemoryFile(fm, red);
     const mf = readMemoryFile(filePath);
     if (mf) upsertFromFile(mf);
-    console.log(`saved ${fm.id} -> ${filePath}`);
+    console.log(`saved ${fm.id} [${s.kind}] -> ${filePath}`);
+    if (hadSecret) {
+      console.log(
+        `warning: content matched secret pattern (${matchedPattern}); saved with the secret masked (first 4 chars kept).`,
+      );
+    }
     for (const n of dups.near) {
       console.log(
         `warning: similar memory exists (score ${n.score.toFixed(2)}): id=${n.id}\n  ${n.snippet}\n  use \`open-memex supersede ${n.id} "new content"\` if this replaces it.`,
@@ -242,10 +446,6 @@ async function main() {
     if (!id || !content || content.startsWith("--")) usage();
     const flags = parseFlags(rest.slice(2));
     const { content: red, hadSecret, matchedPattern } = redact(content, cfg.redactPatterns);
-    if (hadSecret) {
-      console.error(`refused: content matched secret pattern (${matchedPattern}).`);
-      process.exit(2);
-    }
     try {
       const { oldMf, newMf } = supersede(id, {
         body: red,
@@ -258,6 +458,11 @@ async function main() {
       upsertFromFile(oldMf);
       upsertFromFile(newMf);
       console.log(`superseded ${oldMf.fm.id} → ${newMf.fm.id}`);
+      if (hadSecret) {
+        console.log(
+          `warning: content matched secret pattern (${matchedPattern}); saved with the secret masked (first 4 chars kept).`,
+        );
+      }
     } catch (e) {
       console.error(`supersede failed: ${(e as Error).message}`);
       process.exit(2);

package/src/config.ts

@@ -7,7 +7,10 @@ export interface MyOMemoryConfig {
   maxProfileItems: number;
   injectOnFirstTurn: boolean;
   keywordCaptureEnabled: boolean;
+  /** Patterns whose capture group 1 becomes the memory body; saved to the current scope. */
   keywordPatterns: string[];
+  /** Same shape, but hits are forced into the personal scope (e.g. "remember for me"). */
+  keywordPersonalPatterns: string[];
   redactPatterns: string[];
   logLevel: "debug" | "info" | "warn" | "error";
 }
@@ -18,10 +21,27 @@ export const DEFAULT_CONFIG: MyOMemoryConfig = {
   injectOnFirstTurn: true,
   keywordCaptureEnabled: true,
   keywordPatterns: [
-    "^\\s*remember(?:\\s+that)?[:,]?\\s+(.+)$",
+    "^\\s*remember(?!\\s+for\\s+me)(?:\\s+that)?[:,]?\\s+(.+)$",
     "^\\s*(?:please\\s+)?(?:note|don'?t\\s+forget)(?:\\s+that)?[:,]?\\s+(.+)$",
     "^\\s*TIL[:,]?\\s+(.+)$",
     "^\\s*save\\s+(?:this|to\\s+memory)[:,]?\\s+(.+)$",
+    // Chinese equivalents
+    "^\\s*记住(?!（个人）)[：:,，]?\\s*(.+)$",
+    "^\\s*(?:请)?(?:记一下|记录一下)[：:,，]?\\s*(.+)$",
+    "^\\s*别忘了[：:,，]?\\s*(.+)$",
+    // First-person plural: team/project context, NOT personal
+    "^\\s*我们认为[：:,，]?\\s*(.+)$",
+    "^\\s*我们决定[：:,，]?\\s*(.+)$",
+    "^\\s*帮我们记(?:住|一下)?[：:,，]?\\s*(.+)$",
+  ],
+  keywordPersonalPatterns: [
+    "^\\s*remember\\s+for\\s+me(?:\\s+that)?[:,]?\\s+(.+)$",
+    "^\\s*记住（个人）[：:,，]?\\s*(.+)$",
+    // First-person singular: personal scope ("我" → 个人, "我们" → 项目)
+    "^\\s*记住我(?!们)[：:,，]?\\s*(.+)$",
+    "^\\s*替我记(?:住|一下)?[：:,，]?\\s*(.+)$",
+    "^\\s*我觉得[：:,，]?\\s*(.+)$",
+    "^\\s*我喜欢[：:,，]?\\s*(.+)$",
   ],
   // Built-in provider patterns now live in src/redact.ts (always on).
   // Add only your own extra patterns here.
@@ -39,15 +59,80 @@ function stripJsonComments(raw: string): string {
   return out;
 }
 
-export function loadConfig(): MyOMemoryConfig {
+/** Where `config set` / interactive `init` persist. Respects MY_O_MEMORY_CONFIG. */
+export function configFilePath(): string {
+  return (
+    process.env.MY_O_MEMORY_CONFIG ??
+    path.join(os.homedir(), ".config", "opencode", "open-memex.jsonc")
+  );
+}
+
+function toBool(v: unknown): boolean {
+  if (typeof v === "boolean") return v;
+  if (v === "true" || v === "1") return true;
+  if (v === "false" || v === "0") return false;
+  throw new Error("must be true/false");
+}
+
+function toNonNegInt(v: unknown): number {
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0) throw new Error("must be a non-negative integer");
+  return n;
+}
+
+/** Keys users may change via `open-memex config set <key> <value>`, with validators. */
+export const SETTABLE_KEYS: Record<string, (v: unknown) => unknown> = {
+  maxProjectMemories: toNonNegInt,
+  maxProfileItems: toNonNegInt,
+  injectOnFirstTurn: toBool,
+  keywordCaptureEnabled: toBool,
+  logLevel: (v) => {
+    if (v !== "info" && v !== "debug") throw new Error('must be "info" or "debug"');
+    return v;
+  },
+};
+
+/** Merge a patch into the config file (creates it if missing). Returns the file path. */
+export function saveConfig(patch: Record<string, unknown>): string {
+  const file = configFilePath();
+  let cur: Record<string, unknown> = {};
+  if (fs.existsSync(file)) {
+    try {
+      cur = JSON.parse(stripJsonComments(fs.readFileSync(file, "utf8"))) as Record<
+        string,
+        unknown
+      >;
+    } catch {
+      console.error(`[open-memex] ${file} is not valid JSONC — it will be replaced`);
+    }
+  }
+  const next = { ...cur, ...patch };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(
+    file,
+    "// Managed by `open-memex config set` / `open-memex init` — edit freely (JSONC).\n" +
+      JSON.stringify(next, null, 2) +
+      "\n",
+  );
+  return file;
+}
+
+/** Path of the config file in effect, or null when using built-in defaults. */
+export function configSource(): string | null {
   const candidates = [
     process.env.MY_O_MEMORY_CONFIG,
     path.join(os.homedir(), ".config", "opencode", "open-memex.jsonc"),
     path.join(os.homedir(), ".config", "opencode", "open-memex.json"),
   ].filter(Boolean) as string[];
-
   for (const p of candidates) {
-    if (!fs.existsSync(p)) continue;
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function loadConfig(): MyOMemoryConfig {
+  const p = configSource();
+  if (p) {
     try {
       const raw = fs.readFileSync(p, "utf8");
       const parsed = JSON.parse(stripJsonComments(raw)) as Partial<MyOMemoryConfig>;

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;
+}