open-memex 0.3.0-alpha → 0.3.0-alpha.3

package/dist/doctor.js

@@ -0,0 +1,151 @@
+// `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.js";
+import { paths } from "./paths.js";
+import { resolveCwdScope } from "./scope.js";
+const EXPECTED_TOOLS = [
+    "memory_add",
+    "memory_search",
+    "memory_list",
+    "memory_supersede",
+    "memory_forget",
+];
+function nodeCheck() {
+    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() {
+    try {
+        const cfg = loadConfig();
+        const src = configSource();
+        const customized = Object.keys(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() {
+    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() {
+    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() {
+    const name = "mcp";
+    return new Promise((resolve) => {
+        // D21: the installed package runs compiled JS from dist/ (Node refuses
+        // --experimental-strip-types for files under node_modules), while a source
+        // checkout runs src/ directly. Resolve the server entry the same way this
+        // file itself is running.
+        const here = fileURLToPath(import.meta.url);
+        const fromDist = here.endsWith(`dist${path.sep}doctor.js`);
+        const server = fromDist
+            ? path.join(path.dirname(here), "mcp.js")
+            : path.join(path.dirname(path.dirname(here)), "src", "mcp.ts");
+        if (!fs.existsSync(server)) {
+            resolve({ name, ok: false, detail: `server entry not found: ${server}` });
+            return;
+        }
+        const child = spawn(process.execPath, fromDist ? [server] : ["--experimental-strip-types", server], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const done = (c) => {
+            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) => child.stdin.write(JSON.stringify(msg) + "\n");
+        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;
+                let msg;
+                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.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() {
+    console.log("open-memex doctor");
+    const checks = [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/dist/index.js

@@ -0,0 +1,121 @@
+import { loadConfig } from "./config.js";
+import { resolveProjectScope, resolveCwdScope, PERSONAL_SCOPE } from "./scope.js";
+import { db } from "./store/db.js";
+import { syncScope, upsertFromFile } from "./store/sync.js";
+import { scopeHasFiles } from "./store/migrate.js";
+import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
+import { buildContextBlock } from "./retrieve/inject.js";
+import { detectKeywords } from "./capture/keywords.js";
+import { findDuplicates } from "./store/lifecycle.js";
+import { redact } from "./redact.js";
+import { makeTools } from "./tools/memory.js";
+const plugin = async ({ worktree, directory }) => {
+    const cfg = loadConfig();
+    const roots = worktree || directory || process.cwd();
+    const scope = resolveProjectScope(roots);
+    // Init DB and one-shot sync of markdown -> index on plugin load.
+    try {
+        db();
+        syncScope(scope.key);
+        syncScope(PERSONAL_SCOPE.key);
+        if (cfg.logLevel === "debug") {
+            console.log(`[open-memex] loaded. scope=${scope.key}`);
+        }
+        // If a git remote was added *after* memories were first captured, the
+        // scope key changes (cwd-hash -> origin-hash). Detect the legacy dir on
+        // disk and tell the user how to migrate. We do NOT auto-migrate: two
+        // different repos at the same cwd would collide.
+        const cwdScope = resolveCwdScope(roots);
+        if (cwdScope.key !== scope.key && scopeHasFiles(cwdScope.key)) {
+            console.warn(`[open-memex] found memories under legacy scope key "${cwdScope.key}". ` +
+                `Current project scope is "${scope.key}". ` +
+                `To move them: npm run cli -- migrate --from ${cwdScope.key}`);
+        }
+    }
+    catch (err) {
+        console.error("[open-memex] init failed:", err);
+    }
+    const tools = makeTools(() => scope, cfg);
+    const injectedSessions = new Set();
+    return {
+        tool: tools,
+        async "chat.message"(_input, output) {
+            if (!cfg.keywordCaptureEnabled)
+                return;
+            const parts = (output.parts ?? []);
+            const text = parts
+                .map((p) => (p?.type === "text" ? p.text ?? "" : ""))
+                .filter(Boolean)
+                .join("\n");
+            if (!text)
+                return;
+            const hits = detectKeywords(text, cfg);
+            for (const h of hits) {
+                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 = {
+                    id: ulid(),
+                    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: rfc,
+                    updated_at: rfc,
+                    supersedes: null,
+                    superseded_by: null,
+                };
+                try {
+                    const { filePath } = writeMemoryFile(fm, content);
+                    const mf = readMemoryFile(filePath);
+                    if (mf)
+                        upsertFromFile(mf);
+                    // 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);
+                }
+            }
+        },
+        async "experimental.chat.system.transform"(input, output) {
+            if (!cfg.injectOnFirstTurn)
+                return;
+            const sid = input.sessionID ?? "";
+            if (injectedSessions.has(sid))
+                return;
+            injectedSessions.add(sid);
+            try {
+                const block = buildContextBlock(scope, cfg);
+                if (block)
+                    output.system.push(block);
+            }
+            catch (err) {
+                console.error("[open-memex] context injection failed:", err);
+            }
+        },
+    };
+};
+export default plugin;

package/dist/init.js

@@ -0,0 +1,323 @@
+// `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 os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { DEFAULT_CONFIG, saveConfig } from "./config.js";
+const MARKER = "<!-- open-memex -->";
+/** npm dist-tag carrying the 0.3.x preview line. */
+const ALPHA_TAG = "open-memex@alpha";
+/**
+ * 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() {
+    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
+
+> Applies only when the \`open-memex\` MCP server is available in this session
+> (the \`memory_*\` tools exist). Otherwise ignore this section.
+
+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() {
+    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, client, force) {
+    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 = {};
+    if (fs.existsSync(file)) {
+        try {
+            doc = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+            return null;
+        }
+    }
+    const section = (doc[sectionKey] ??= {});
+    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, force) {
+    const file = path.join(root, "opencode.jsonc");
+    let doc = {};
+    if (fs.existsSync(file)) {
+        try {
+            doc = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+            return null;
+        }
+    }
+    const section = (doc["mcp"] ??= {});
+    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, force) {
+    const file = path.join(root, ".mcp.json");
+    let doc = {};
+    if (fs.existsSync(file)) {
+        try {
+            doc = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+            return null;
+        }
+    }
+    const section = (doc["servers"] ??= {});
+    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, scope, client) {
+    const file = scope === "project"
+        ? path.join(root, ".github", "copilot-instructions.md")
+        : client === "visualstudio"
+            ? path.join(os.homedir(), "copilot-instructions.md")
+            : path.join(os.homedir(), ".copilot", "copilot-instructions.md");
+    if (scope === "personal") {
+        // A previous project-scoped init may have left the section behind — flag it
+        // so the repo can go back to being open-memex-free for teammates.
+        const proj = path.join(root, ".github", "copilot-instructions.md");
+        if (fs.existsSync(proj) && fs.readFileSync(proj, "utf8").includes(MARKER)) {
+            console.log(`  ! project-level instructions still present at ${proj}`);
+            console.log(`    remove the open-memex section there to keep the repo clean.`);
+        }
+    }
+    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(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, INSTRUCTIONS);
+    }
+    console.log(`  + ${file}`);
+    return file;
+}
+export const INIT_CLIENTS = ["vscode", "cursor", "opencode", "visualstudio"];
+/** Normalize --client values; accepts "visual-studio" as an alias. */
+export function normalizeClient(c) {
+    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, def) {
+    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() {
+    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();
+    }
+}
+/** D22: where the Copilot memory instructions live. Personal (default) is the
+ * Copilot user-level location — all projects, never checked in. */
+async function promptInstructionsScope() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log("Where should the Copilot memory instructions live?");
+        console.log("  1) personal — user-level, all projects, never checked into a repo");
+        console.log("  2) project  — .github/copilot-instructions.md, shared with the repo");
+        const ans = (await rl.question("Choice [1]: ")).trim();
+        return ans === "2" ? "project" : "personal";
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function initProject(opts) {
+    const interactive = !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+    let client = normalizeClient(opts.client ?? "");
+    if (client && !INIT_CLIENTS.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
+    let scope = "personal";
+    if (opts.instructions) {
+        if (opts.instructions !== "personal" && opts.instructions !== "project") {
+            console.error(`unknown --instructions "${opts.instructions}" (personal|project)`);
+            process.exit(1);
+        }
+        scope = opts.instructions;
+    }
+    else if (interactive) {
+        scope = await promptInstructionsScope();
+    }
+    if (interactive) {
+        // Install-time settings (D19). Non-default answers persist to the JSONC
+        // config file; `open-memex config set` changes them later.
+        const patch = {};
+        const keywordCaptureEnabled = await askBool("Auto-capture keywords like remember… / note that… 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).
+        // D22: personal scope (default) writes to the Copilot user-level location
+        // so the repo stays clean for teammates without open-memex.
+        if (client !== "opencode")
+            writeInstructions(root, scope, client);
+    }
+    else {
+        console.log("  - editor setup skipped");
+    }
+    console.log(`\nDone. Reload your editor window to start the open-memex MCP server.`);
+}

package/dist/mcp.js

@@ -0,0 +1,85 @@
+/**
+ * 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.js";
+import { resolveProjectScope, PERSONAL_SCOPE } from "./scope.js";
+import { db } from "./store/db.js";
+import { syncScope } from "./store/sync.js";
+import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, TOOL_DESCRIPTIONS, } from "./tools/ops.js";
+const SERVER_VERSION = "0.2.0-alpha";
+/** Adapt a framework-agnostic op result to an MCP tool response. */
+function toMcp(p) {
+    return p.then((r) => ({ content: [{ type: "text", text: r.output }] }), (e) => ({
+        content: [
+            {
+                type: "text",
+                text: `open-memex error: ${e?.message ?? String(e)}`,
+            },
+        ],
+        isError: true,
+    }));
+}
+export async function runMcpServer() {
+    const cfg = loadConfig();
+    const 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);
+    });
+}