ricord 1.0.0

package/dist/index.js

@@ -0,0 +1,1547 @@
+#!/usr/bin/env node
+/**
+ * Ricord MCP Server — persistent memory for AI coding assistants.
+ *
+ * Install:  npx ricord-mcp --setup --client claude --api-key YOUR_KEY
+ *
+ * Core tools (9):
+ *   ricord_ingest      — Save (atomic, type=fact|preference|...) OR ingest artifacts (kind=text|url|pdf|...)
+ *   ricord_search      — Retrieve relevant knowledge (hybrid search)
+ *   ricord_correct     — Update existing knowledge
+ *   ricord_forget      — Remove knowledge items
+ *   ricord_list        — Browse stored knowledge
+ *   ricord_walk        — Walk a project, return structured per-dir bundles for the agent to summarize
+ *   ricord_ingest      — Ingest a heavyweight artifact (text/url/file/image/audio/video) into the KG
+ *   ricord_procedure   — Manage SOPs / playbooks / prompts / soul / preferences
+ *   ricord_graph       — Explore knowledge graph
+ *   ricord_usage       — Check credit balance
+ *
+ * Modes:
+ *   --mode auto     (default) Auto-save: LLM proactively saves knowledge
+ *   --mode manual   User must explicitly invoke tools
+ *   --mode hybrid   Auto-extract but mark as pending for review
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { execSync, spawnSync } from "node:child_process";
+import { basename, join, dirname } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { getCurrentSession } from "./lib/buffer.js";
+import { getActiveProject } from "./lib/active-project.js";
+import { createRequire } from "node:module";
+const _require = createRequire(import.meta.url);
+const VERSION = _require("../package.json").version;
+// ── Credentials storage ─────────────────────────────────────────────
+const CREDENTIALS_DIR = join(homedir(), ".ricord");
+const CREDENTIALS_FILE = join(CREDENTIALS_DIR, "credentials.json");
+function loadCredentials() {
+    try {
+        if (existsSync(CREDENTIALS_FILE)) {
+            return JSON.parse(readFileSync(CREDENTIALS_FILE, "utf8"));
+        }
+    }
+    catch { }
+    return null;
+}
+function saveCredentials(apiKey, apiBase) {
+    mkdirSync(CREDENTIALS_DIR, { recursive: true });
+    const creds = {
+        api_key: apiKey,
+        api_base: apiBase,
+        created_at: new Date().toISOString(),
+    };
+    writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+}
+// ── CLI args ──────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+function getArg(name, shortAlias) {
+    const candidates = [`--${name}`];
+    if (shortAlias)
+        candidates.push(`-${shortAlias}`);
+    // Also accept `-<name>` for single-letter names (e.g. -k)
+    if (name.length === 1)
+        candidates.push(`-${name}`);
+    for (const flag of candidates) {
+        const idx = args.indexOf(flag);
+        if (idx !== -1)
+            return args[idx + 1];
+    }
+    return undefined;
+}
+function hasFlag(name, shortAlias) {
+    if (args.includes(`--${name}`))
+        return true;
+    if (shortAlias && args.includes(`-${shortAlias}`))
+        return true;
+    if (name.length === 1 && args.includes(`-${name}`))
+        return true;
+    return false;
+}
+// ── Colors ──────────────────────────────────────────────────────────
+const c = (code) => (s) => `\x1b[${code}m${s}\x1b[0m`;
+const bold = c("1");
+const dim = c("2");
+const green = c("0;32");
+const cyan = c("0;36");
+const yellow = c("1;33");
+const red = c("0;31");
+const cliInfo = (msg) => console.log(`${cyan("  [*]")} ${msg}`);
+const cliOk = (msg) => console.log(`${green("  [+]")} ${msg}`);
+const cliWarn = (msg) => console.log(`${yellow("  [!]")} ${msg}`);
+const cliErr = (msg) => console.log(`${red("  [-]")} ${msg}`);
+const SITE_BASE = "https://ricord.ai";
+const API_BASE_DEFAULT = "https://api.ricord.ai";
+function openBrowser(url) {
+    // Use spawnSync with separate args to avoid shell injection via crafted URLs.
+    try {
+        if (process.platform === "darwin") {
+            spawnSync("open", [url], { stdio: "ignore" });
+        }
+        else if (process.platform === "win32") {
+            spawnSync("cmd", ["/c", "start", "", url], { stdio: "ignore", shell: false });
+        }
+        else {
+            spawnSync("xdg-open", [url], { stdio: "ignore" });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function prompt(question) {
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+    });
+}
+async function validateKey(apiKey, apiBase) {
+    try {
+        const res = await fetch(`${apiBase}/v1/usage`, {
+            headers: { Authorization: `Bearer ${apiKey}`, "User-Agent": `ricord-mcp/${VERSION}` },
+        });
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        return { tier: data.tier ?? "unknown", requests_today: data.today?.requests ?? 0 };
+    }
+    catch {
+        return null;
+    }
+}
+async function startAuthServer(apiBase) {
+    const { createServer } = await import("node:http");
+    const { randomBytes } = await import("node:crypto");
+    const state = randomBytes(16).toString("hex");
+    const LOGO_URL = "https://ricord.ai/logo.png";
+    const SUCCESS_HTML = `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Ricord — Authenticated</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:'Geist','Inter',system-ui,sans-serif;display:flex;justify-content:center;align-items:center;min-height:100vh;background:#0a0a0a;color:#fafafa}
+.card{text-align:center;padding:3rem 2.5rem;border:1px solid #1a1a1a;border-radius:16px;background:#111;max-width:400px;width:90%}
+.logo{width:64px;height:64px;margin:0 auto 1.5rem;border-radius:12px}
+h2{font-size:1.25rem;font-weight:600;margin-bottom:0.5rem;letter-spacing:-0.02em}
+p{font-size:0.875rem;color:#888;line-height:1.5}
+.brand{font-size:0.75rem;color:#444;margin-top:1.5rem;letter-spacing:0.05em;text-transform:uppercase}
+</style></head>
+<body><div class="card">
+<img src="${LOGO_URL}" alt="Ricord" class="logo" />
+<h2>Authenticated</h2>
+<p>You can close this tab and return to your terminal.</p>
+<p class="brand">Ricord</p>
+</div></body></html>`;
+    const ERROR_HTML = (msg) => `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Ricord — Error</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:'Geist','Inter',system-ui,sans-serif;display:flex;justify-content:center;align-items:center;min-height:100vh;background:#0a0a0a;color:#fafafa}
+.card{text-align:center;padding:3rem 2.5rem;border:1px solid #1a1a1a;border-radius:16px;background:#111;max-width:400px;width:90%}
+.logo{width:64px;height:64px;margin:0 auto 1.5rem;border-radius:12px}
+h2{font-size:1.25rem;font-weight:600;margin-bottom:0.5rem;letter-spacing:-0.02em}
+p{font-size:0.875rem;color:#888;line-height:1.5}
+.error{color:#f87171}
+.brand{font-size:0.75rem;color:#444;margin-top:1.5rem;letter-spacing:0.05em;text-transform:uppercase}
+</style></head>
+<body><div class="card">
+<img src="${LOGO_URL}" alt="Ricord" class="logo" />
+<h2>Authentication Failed</h2>
+<p class="error">${msg}</p>
+<p class="brand">Ricord</p>
+</div></body></html>`;
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url || "/", "http://localhost");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404);
+                res.end("Not found");
+                return;
+            }
+            const token = url.searchParams.get("token");
+            const returnedState = url.searchParams.get("state");
+            if (returnedState !== state) {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end(ERROR_HTML("State mismatch. Please try again."));
+                return;
+            }
+            if (!token) {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end(ERROR_HTML("No token received. Please try again."));
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(SUCCESS_HTML);
+            cleanup();
+            resolve(token);
+        });
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new Error("Browser login timed out (120s). Use `ricord-mcp login -k <key>` instead."));
+        }, 120_000);
+        function cleanup() { clearTimeout(timer); server.close(); }
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                cleanup();
+                reject(new Error("Failed to start auth server"));
+                return;
+            }
+            const port = addr.port;
+            const authUrl = `${SITE_BASE}/cli-auth?port=${port}&state=${state}`;
+            console.log("");
+            cliInfo("Opening browser for authentication...");
+            const opened = openBrowser(authUrl);
+            if (!opened) {
+                console.log("");
+                cliWarn("Could not open browser. Visit this URL manually:");
+                console.log(`  ${dim(authUrl)}`);
+            }
+            else {
+                console.log(`  ${dim("Waiting for browser login...")}`);
+            }
+            console.log("");
+            cliInfo(`Or paste your API key with: ${bold("ricord-mcp login -k <key>")}`);
+        });
+        server.on("error", (e) => { cleanup(); reject(e); });
+    });
+}
+// ── Version / help ──────────────────────────────────────────────────
+if (args[0] === "--version" || args[0] === "-v" || args[0] === "version") {
+    console.log(`ricord-mcp ${VERSION}`);
+    process.exit(0);
+}
+if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+    console.log(`\n${bold("ricord-mcp")} ${VERSION} — persistent memory for AI agents\n`);
+    console.log(`  ${bold("Commands:")}`);
+    console.log(`    login [-k <key>] [--no-browser]   Authenticate (browser OAuth by default, persists until revoked)`);
+    console.log(`    logout                             Remove stored credentials`);
+    console.log(`    whoami                             Show current user + credit balance`);
+    console.log(`    install <client>                   Configure Claude Code / Cursor / Windsurf / VS Code`);
+    console.log(`    init                               Retroactively index Claude Code history`);
+    console.log(`    --setup [--client <c>]            Install MCP server (auto-detects agents if --client omitted)`);
+    console.log(`    --version                          Print version`);
+    console.log(`  ${bold("Run as MCP server:")}`);
+    console.log(`    ricord-mcp [--api-key <k>] [--mode auto|manual|hybrid]`);
+    console.log(`  ${bold("Docs:")} https://ricord.ai/docs\n`);
+    process.exit(0);
+}
+// ── CLI login mode ──────────────────────────────────────────────────
+if (args[0] === "login") {
+    const apiBase = getArg("api-base") || process.env.RICORD_API_BASE || API_BASE_DEFAULT;
+    const directKey = getArg("api-key", "k");
+    console.log(`\n${bold("Ricord Login")}\n`);
+    // ── Direct key mode (-k flag) ────────────────────────
+    if (directKey) {
+        cliInfo("Validating API key...");
+        const result = await validateKey(directKey, apiBase);
+        if (!result) {
+            cliErr("Invalid API key.");
+            process.exit(1);
+        }
+        saveCredentials(directKey, apiBase !== API_BASE_DEFAULT ? apiBase : undefined);
+        cliOk(`Logged in! (tier: ${bold(result.tier)}, ${result.requests_today} requests today)`);
+        console.log("");
+        cliInfo(`Run ${bold("ricord-mcp install claude-code")} to configure your AI tools.`);
+        console.log("");
+        process.exit(0);
+    }
+    // ── Check for existing key ───────────────────────────
+    const existing = loadCredentials();
+    if (existing && !args.includes("--force")) {
+        const masked = existing.api_key.slice(0, 12) + "..." + existing.api_key.slice(-4);
+        cliInfo(`Found existing credentials: ${masked}`);
+        const result = await validateKey(existing.api_key, apiBase);
+        if (result) {
+            cliOk(`Already logged in (tier: ${bold(result.tier)}, ${result.requests_today} requests today)`);
+            process.exit(0);
+        }
+        cliWarn("Stored key is no longer valid. Re-authenticating...");
+    }
+    // ── Browser auth (default) ───────────────────────────
+    if (!args.includes("--no-browser")) {
+        try {
+            const apiKey = await startAuthServer(apiBase);
+            cliInfo("Validating...");
+            const result = await validateKey(apiKey, apiBase);
+            if (!result) {
+                cliErr("Received invalid API key from browser. Try again or use -k flag.");
+                process.exit(1);
+            }
+            saveCredentials(apiKey, apiBase !== API_BASE_DEFAULT ? apiBase : undefined);
+            console.log("");
+            cliOk(`Logged in! (tier: ${bold(result.tier)}, ${result.requests_today} requests today)`);
+            console.log("");
+            cliInfo(`Run ${bold("ricord-mcp install claude-code")} to configure your AI tools.`);
+            console.log("");
+            process.exit(0);
+        }
+        catch (e) {
+            cliWarn(e.message || "Browser auth failed.");
+            cliInfo("Falling back to manual key entry...");
+            console.log("");
+        }
+    }
+    // ── Manual key entry (fallback / --no-browser) ───────
+    console.log(`  Get your API key at ${dim(`${SITE_BASE}/dashboard`)}\n`);
+    const apiKey = await prompt("  API key (rc_live_...): ");
+    if (!apiKey) {
+        cliErr("No API key provided.");
+        process.exit(1);
+    }
+    cliInfo("Validating...");
+    const result = await validateKey(apiKey, apiBase);
+    if (!result) {
+        cliErr("Invalid API key.");
+        process.exit(1);
+    }
+    saveCredentials(apiKey, apiBase !== API_BASE_DEFAULT ? apiBase : undefined);
+    console.log("");
+    cliOk(`Logged in! (tier: ${bold(result.tier)}, ${result.requests_today} requests today)`);
+    console.log("");
+    cliInfo(`Run ${bold("ricord-mcp install claude-code")} to configure your AI tools.`);
+    console.log("");
+    process.exit(0);
+}
+// ── CLI logout mode ─────────────────────────────────────────────────
+if (args[0] === "logout") {
+    const { unlinkSync } = await import("node:fs");
+    if (existsSync(CREDENTIALS_FILE)) {
+        unlinkSync(CREDENTIALS_FILE);
+        cliOk("Logged out. Credentials removed.");
+    }
+    else {
+        cliInfo("Not logged in.");
+    }
+    process.exit(0);
+}
+// ── CLI whoami mode ─────────────────────────────────────────────────
+if (args[0] === "whoami") {
+    const creds = loadCredentials();
+    if (!creds) {
+        console.log("Not logged in. Run: ricord-mcp login");
+        process.exit(1);
+    }
+    const masked = creds.api_key.slice(0, 8) + "..." + creds.api_key.slice(-4);
+    const apiBase = creds.api_base || "https://api.ricord.ai";
+    console.log(`Key: ${masked}`);
+    console.log(`API: ${apiBase}`);
+    console.log(`Stored: ${CREDENTIALS_FILE}`);
+    try {
+        const res = await fetch(`${apiBase}/v1/usage`, {
+            headers: {
+                Authorization: `Bearer ${creds.api_key}`,
+                "Content-Type": "application/json",
+                "User-Agent": `ricord-mcp/${VERSION}`,
+            },
+        });
+        if (res.ok) {
+            const usage = await res.json();
+            const today = usage.today || {};
+            console.log(`Tier: ${usage.tier} | Today: ${today.requests ?? 0} requests`);
+        }
+    }
+    catch { }
+    process.exit(0);
+}
+// ── CLI init mode ──────────────────────────────────────────────────
+// `ricord-mcp init` — retroactively process Claude Code conversations
+if (args[0] === "init") {
+    // Delegate to the init script, passing remaining args
+    const initPath = join(dirname(new URL(import.meta.url).pathname), "init.js");
+    if (!existsSync(initPath)) {
+        console.error("Init script not found. Run `npm run build` first.");
+        process.exit(1);
+    }
+    const { fork } = await import("node:child_process");
+    const child = fork(initPath, args.slice(1), { stdio: "inherit" });
+    child.on("exit", (code) => process.exit(code || 0));
+    // Block the parent from continuing to MCP server setup
+    await new Promise(() => { });
+}
+// ── CLI install mode ────────────────────────────────────────────────
+// `ricord-mcp install claude-code` (uses stored credentials)
+if (args[0] === "install") {
+    const clientName = args[1];
+    if (!clientName) {
+        console.error("Usage: ricord-mcp install <client>");
+        console.error("\nSupported clients: claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini-cli");
+        process.exit(1);
+    }
+    // Get API key from args, env, stored credentials, or browser OAuth
+    let apiKey = getArg("api-key") || process.env.RICORD_API_KEY || loadCredentials()?.api_key || "";
+    const mode = getArg("mode") || "auto";
+    if (!apiKey) {
+        cliInfo("No API key found — opening browser to log in...");
+        try {
+            const apiBase = getArg("api-base") || process.env.RICORD_API_BASE || "https://api.ricord.ai";
+            apiKey = await startAuthServer(apiBase);
+            const result = await validateKey(apiKey, apiBase);
+            if (!result) {
+                cliErr("Received invalid API key from browser. Try again or use --api-key.");
+                process.exit(1);
+            }
+            saveCredentials(apiKey, apiBase !== "https://api.ricord.ai" ? apiBase : undefined);
+            cliInfo("Logged in successfully.");
+        }
+        catch (e) {
+            cliErr(e.message || "Browser auth failed. Use --api-key <YOUR_KEY> instead.");
+            process.exit(1);
+        }
+    }
+    // Resolve the absolute path to this script for local installs
+    const scriptPath = join(dirname(new URL(import.meta.url).pathname), "index.js");
+    const useNode = existsSync(scriptPath);
+    const mcpArgs = useNode
+        ? [scriptPath, "--api-key", apiKey, "--mode", mode]
+        : ["ricord-mcp", "--api-key", apiKey, "--mode", mode];
+    const mcpCommand = useNode ? "node" : "npx";
+    const mcpConfig = { command: mcpCommand, args: mcpArgs };
+    const clients = {
+        "claude-code": {
+            path: null,
+            key: "ricord",
+            wrap: () => ({}),
+            cmd: `claude mcp add -s user ricord -- ${mcpCommand} ${mcpArgs.join(" ")}`,
+        },
+        "claude-desktop": {
+            path: join(process.platform === "win32"
+                ? join(process.env.APPDATA || "", "Claude")
+                : process.platform === "linux"
+                    ? join(homedir(), ".config", "Claude")
+                    : join(homedir(), "Library", "Application Support", "Claude"), "claude_desktop_config.json"),
+            key: "mcpServers",
+            wrap: (entry) => ({ mcpServers: { ricord: entry } }),
+        },
+        cursor: {
+            path: join(process.cwd(), ".cursor", "mcp.json"),
+            key: "mcpServers",
+            wrap: (entry) => ({ mcpServers: { ricord: entry } }),
+        },
+        windsurf: {
+            path: join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+            key: "mcpServers",
+            wrap: (entry) => ({ mcpServers: { ricord: entry } }),
+        },
+        vscode: {
+            path: join(process.cwd(), ".vscode", "mcp.json"),
+            key: "servers",
+            wrap: (entry) => ({ servers: { ricord: entry } }),
+        },
+        codex: {
+            path: null,
+            key: "ricord",
+            wrap: () => ({}),
+            cmd: `codex mcp add ricord -- ${mcpCommand} ${mcpArgs.join(" ")}`,
+        },
+        "gemini-cli": {
+            path: join(homedir(), ".gemini", "settings.json"),
+            key: "mcpServers",
+            wrap: (entry) => ({ mcpServers: { ricord: entry } }),
+        },
+    };
+    clients["claude"] = clients["claude-code"];
+    clients["desktop"] = clients["claude-desktop"];
+    clients["code"] = clients["claude-code"];
+    clients["vs-code"] = clients["vscode"];
+    clients["gemini"] = clients["gemini-cli"];
+    const client = clients[clientName.toLowerCase()];
+    if (!client) {
+        console.error(`Unknown client: ${clientName}`);
+        console.error("Supported: claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini-cli");
+        process.exit(1);
+    }
+    if (client.cmd) {
+        // Log the command without embedding the API key to avoid key exposure in logs/history.
+        const maskedKey = apiKey.slice(0, 8) + "..." + apiKey.slice(-4);
+        console.log(`Running: ${client.cmd.replace(apiKey, maskedKey)}`);
+        try {
+            execSync(client.cmd, { stdio: "inherit" });
+            console.log("\n✓ Ricord MCP server added to Claude Code. Restart Claude Code to activate.");
+            process.exit(0);
+        }
+        catch (err) {
+            // iter30 2026-04-24: distinguish "claude CLI missing" (ENOENT) from
+            // non-zero exit (often idempotent re-add, e.g. "already exists").
+            // Post-check via `claude mcp list` before declaring failure.
+            const code = err.code;
+            if (code === "ENOENT") {
+                console.error("\nClaude CLI not found. Install Claude Code first: https://claude.com/claude-code");
+                console.error("Manual after install: " + client.cmd.replace(apiKey, maskedKey));
+                process.exit(1);
+            }
+            try {
+                const list = execSync("claude mcp list", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+                if (/ricord/i.test(list)) {
+                    console.log("\n✓ Ricord MCP server is already configured in Claude Code. Restart to activate.");
+                    process.exit(0);
+                }
+            }
+            catch { /* fall through to failure message */ }
+            console.error("\nSetup command returned non-zero. Run `claude mcp list` to verify, or re-run:");
+            console.error("  " + client.cmd.replace(apiKey, maskedKey));
+            process.exit(1);
+        }
+    }
+    const configPath = client.path;
+    const configDir = dirname(configPath);
+    let existingConfig = {};
+    if (existsSync(configPath)) {
+        try {
+            existingConfig = JSON.parse(readFileSync(configPath, "utf8"));
+        }
+        catch { }
+    }
+    const servers = existingConfig[client.key] || {};
+    servers["ricord"] = mcpConfig;
+    existingConfig[client.key] = servers;
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(configPath, JSON.stringify(existingConfig, null, 2) + "\n");
+    console.log(`Ricord MCP server configured for ${clientName}`);
+    console.log(`Config: ${configPath}`);
+    console.log(`Mode: ${mode}`);
+    console.log(`\nRestart your editor to activate.`);
+    process.exit(0);
+}
+// ── CLI setup mode (legacy) ─────────────────────────────────────────
+// `npx ricord-mcp --setup --client claude --api-key KEY`
+const SETUP_MODE = args.includes("--setup");
+const CLIENT_ARG = getArg("client");
+if (SETUP_MODE) {
+    let apiKey = getArg("api-key") || process.env.RICORD_API_KEY || "";
+    const mode = getArg("mode") || "auto";
+    // No --api-key? Try cached credentials, then fall back to browser OAuth
+    if (!apiKey) {
+        const cached = loadCredentials();
+        if (cached?.api_key) {
+            apiKey = cached.api_key;
+            cliInfo("Using cached credentials.");
+        }
+        else {
+            cliInfo("No API key found — opening browser to log in...");
+            try {
+                const apiBase = getArg("api-base") || process.env.RICORD_API_BASE || "https://api.ricord.ai";
+                apiKey = await startAuthServer(apiBase);
+                const result = await validateKey(apiKey, apiBase);
+                if (!result) {
+                    cliErr("Received invalid API key from browser. Try again or use --api-key.");
+                    process.exit(1);
+                }
+                saveCredentials(apiKey, apiBase !== "https://api.ricord.ai" ? apiBase : undefined);
+                cliInfo("Logged in successfully.");
+            }
+            catch (e) {
+                cliErr(e.message || "Browser auth failed. Use --api-key <YOUR_KEY> instead.");
+                process.exit(1);
+            }
+        }
+    }
+    const mcpArgs = ["ricord-mcp", "--api-key", apiKey, "--mode", mode];
+    const mcpConfig = { command: "npx", args: mcpArgs };
+    const clients = {
+        "claude-code": {
+            path: null,
+            key: "ricord",
+            wrap: () => ({}),
+            cmd: `claude mcp add -s user ricord -- npx -y ricord-mcp --api-key ${apiKey} --mode ${mode}`,
+        },
+        "claude-desktop": {
+            path: join(process.platform === "win32"
+                ? join(process.env.APPDATA || "", "Claude")
+                : process.platform === "linux"
+                    ? join(homedir(), ".config", "Claude")
+                    : join(homedir(), "Library", "Application Support", "Claude"), "claude_desktop_config.json"),
+            key: "mcpServers",
+            wrap: (entry) => ({ mcpServers: { ricord: entry } }),
+        },
+        cursor: {
+            path: join(process.cwd(), ".cursor", "mcp.json"),
+            key: "mcpServers",
+            wrap: (entry) => ({ mcpServers: { ricord: entry } }),
+        },
+        windsurf: {
+            path: join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+            key: "mcpServers",
+            wrap: (entry) => ({ mcpServers: { ricord: entry } }),
+        },
+        vscode: {
+            path: join(process.cwd(), ".vscode", "mcp.json"),
+            key: "servers",
+            wrap: (entry) => ({ servers: { ricord: entry } }),
+        },
+        codex: {
+            path: null,
+            key: "ricord",
+            wrap: () => ({}),
+            cmd: `codex mcp add ricord -- npx -y ricord-mcp --api-key ${apiKey} --mode ${mode}`,
+        },
+        "gemini-cli": {
+            path: join(homedir(), ".gemini", "settings.json"),
+            key: "mcpServers",
+            wrap: (entry) => ({ mcpServers: { ricord: entry } }),
+        },
+    };
+    clients["claude"] = clients["claude-code"];
+    clients["desktop"] = clients["claude-desktop"];
+    clients["code"] = clients["claude-code"];
+    clients["vs-code"] = clients["vscode"];
+    clients["gemini"] = clients["gemini-cli"];
+    // ── Auto-detect installed coding agents ──────────────────────────
+    // When --client is omitted (or set to auto/all), detect which agents
+    // are installed on this machine and install into each. Project-local
+    // clients (cursor, vscode) only count when their dir already exists
+    // in cwd, so running --setup from a random dir doesn't litter.
+    const hasBin = (name) => {
+        const r = spawnSync(process.platform === "win32" ? "where" : "which", [name], { stdio: "ignore" });
+        return r.status === 0;
+    };
+    const detectInstalled = () => {
+        const found = [];
+        if (hasBin("claude"))
+            found.push("claude-code");
+        const desktopCfg = process.platform === "win32"
+            ? join(process.env.APPDATA || "", "Claude")
+            : process.platform === "linux"
+                ? join(homedir(), ".config", "Claude")
+                : join(homedir(), "Library", "Application Support", "Claude");
+        if (existsSync(desktopCfg))
+            found.push("claude-desktop");
+        if (existsSync(join(homedir(), ".codeium", "windsurf")))
+            found.push("windsurf");
+        if (existsSync(join(process.cwd(), ".cursor")))
+            found.push("cursor");
+        if (existsSync(join(process.cwd(), ".vscode")))
+            found.push("vscode");
+        if (hasBin("codex") || existsSync(join(homedir(), ".codex")))
+            found.push("codex");
+        if (hasBin("gemini") || existsSync(join(homedir(), ".gemini")))
+            found.push("gemini-cli");
+        return found;
+    };
+    const targets = (() => {
+        const arg = CLIENT_ARG?.toLowerCase();
+        if (!arg || arg === "auto" || arg === "all") {
+            const detected = detectInstalled();
+            if (detected.length === 0) {
+                console.error("No supported coding agents detected.");
+                console.error("Install one of: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code — then re-run.");
+                console.error("Or pass --client <name> explicitly: claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini-cli");
+                process.exit(1);
+            }
+            console.log(`Detected: ${detected.join(", ")}`);
+            return detected;
+        }
+        return [arg];
+    })();
+    let installed = 0;
+    let failed = 0;
+    for (const name of targets) {
+        const client = clients[name];
+        if (!client) {
+            console.error(`Unknown client: ${name} — skipping`);
+            failed++;
+            continue;
+        }
+        if (client.cmd) {
+            const maskedKey2 = apiKey.slice(0, 8) + "..." + apiKey.slice(-4);
+            console.log(`\n[${name}] Running: ${client.cmd.replace(apiKey, maskedKey2)}`);
+            try {
+                execSync(client.cmd, { stdio: "inherit" });
+                console.log(`✓ ${name}: configured. Restart to activate.`);
+                installed++;
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === "ENOENT") {
+                    console.error(`✗ ${name}: Claude CLI not found. Install Claude Code first: https://claude.com/claude-code`);
+                    failed++;
+                    continue;
+                }
+                try {
+                    const list = execSync("claude mcp list", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+                    if (/ricord/i.test(list)) {
+                        console.log(`✓ ${name}: already configured. Restart to activate.`);
+                        installed++;
+                        continue;
+                    }
+                }
+                catch { /* fall through */ }
+                console.error(`✗ ${name}: setup returned non-zero. Re-run: ${client.cmd.replace(apiKey, maskedKey2)}`);
+                failed++;
+            }
+            continue;
+        }
+        const configPath = client.path;
+        const configDir = dirname(configPath);
+        let existing = {};
+        if (existsSync(configPath)) {
+            try {
+                existing = JSON.parse(readFileSync(configPath, "utf8"));
+            }
+            catch { }
+        }
+        const servers = existing[client.key] || {};
+        servers["ricord"] = mcpConfig;
+        existing[client.key] = servers;
+        mkdirSync(configDir, { recursive: true });
+        writeFileSync(configPath, JSON.stringify(existing, null, 2) + "\n");
+        console.log(`✓ ${name}: configured at ${configPath}`);
+        installed++;
+    }
+    console.log(`\nDone. ${installed} configured, ${failed} failed. Mode: ${mode}. Restart your editor(s) to activate.`);
+    process.exit(failed > 0 && installed === 0 ? 1 : 0);
+}
+// ── Setup hooks mode ────────────────────────────────────────────────
+// `npx ricord-mcp --setup-hooks`
+// Installs Claude Code hooks for automatic session capture + context injection.
+if (args.includes("--setup-hooks")) {
+    const hooksDir = join(process.cwd(), ".claude");
+    const settingsPath = join(hooksDir, "settings.json");
+    const pkgRoot = join(dirname(new URL(import.meta.url).pathname), "..");
+    const distHooksDir = join(pkgRoot, "dist", "hooks");
+    // Resolve hook script paths — use tsx in dev, node dist/ in production
+    const isDevMode = process.argv[1]?.endsWith(".ts");
+    const runner = isDevMode ? "npx tsx" : "node";
+    const hookDir = isDevMode ? join(pkgRoot, "src", "hooks") : distHooksDir;
+    const ext = isDevMode ? ".ts" : ".js";
+    const hookSettings = {
+        hooks: {
+            SessionStart: [{
+                    matcher: "",
+                    hooks: [{
+                            type: "command",
+                            command: `${runner} ${join(hookDir, `session-start${ext}`)}`,
+                            timeout: 15,
+                        }],
+                }],
+            PreCompact: [{
+                    matcher: "",
+                    hooks: [{
+                            type: "command",
+                            command: `${runner} ${join(hookDir, `pre-compact${ext}`)}`,
+                            timeout: 10,
+                        }],
+                }],
+            SessionEnd: [{
+                    matcher: "",
+                    hooks: [{
+                            type: "command",
+                            command: `${runner} ${join(hookDir, `session-end${ext}`)}`,
+                            timeout: 10,
+                        }],
+                }],
+            Stop: [{
+                    matcher: "",
+                    hooks: [{
+                            type: "command",
+                            command: `${runner} ${join(hookDir, `turn-end${ext}`)}`,
+                            timeout: 5,
+                        }],
+                }],
+        },
+    };
+    // Merge with existing settings if present
+    let existing = {};
+    if (existsSync(settingsPath)) {
+        try {
+            existing = JSON.parse(readFileSync(settingsPath, "utf8"));
+        }
+        catch { }
+    }
+    // Merge hooks — preserve non-Ricord hooks if any
+    const existingHooks = (existing.hooks || {});
+    existing.hooks = { ...existingHooks, ...hookSettings.hooks };
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + "\n");
+    console.log(green("✓") + " Ricord hooks installed");
+    console.log(`  Config: ${settingsPath}`);
+    console.log(`  Hooks:`);
+    console.log(`    SessionStart → loads your Ricord memories as context`);
+    console.log(`    PreCompact  → saves context before auto-compaction`);
+    console.log(`    SessionEnd  → captures conversation as episode memory`);
+    console.log(`    Stop        → ingests each Q&A pair in real time (server-coalesced)`);
+    console.log(`\n  ${dim("Your conversations will now automatically build your knowledge base.")}`);
+    process.exit(0);
+}
+// ── Server config ────────────────────────────────────────────────────
+const storedCreds = loadCredentials();
+const API_KEY = getArg("api-key") || process.env.RICORD_API_KEY || storedCreds?.api_key || "";
+const API_BASE = getArg("api-base") || process.env.RICORD_API_BASE || storedCreds?.api_base || "https://api.ricord.ai";
+const MODE = (getArg("mode") || "auto");
+const PROJECT_OVERRIDE = getArg("project") || process.env.RICORD_PROJECT || undefined;
+// ── Git auto-detection ───────────────────────────────────────────────
+function shellExec(cmd) {
+    try {
+        return execSync(cmd, { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function detectGitContext() {
+    const remoteUrl = shellExec("git remote get-url origin");
+    let gitRepo = "";
+    let projectId = "";
+    if (remoteUrl) {
+        gitRepo = remoteUrl
+            .replace(/^git@/, "").replace(/\.git$/, "")
+            .replace(/:([^/])/, "/$1").replace(/^https?:\/\//, "");
+        const parts = gitRepo.split("/");
+        projectId = parts.length >= 3 ? parts.slice(1).join("/") : gitRepo;
+    }
+    if (!projectId)
+        projectId = basename(process.cwd());
+    const gitBranch = shellExec("git rev-parse --abbrev-ref HEAD");
+    return { projectId, gitRepo, gitBranch };
+}
+const gitContext = detectGitContext();
+const PROJECT = PROJECT_OVERRIDE || gitContext.projectId;
+const GIT_REPO = gitContext.gitRepo;
+const GIT_BRANCH = gitContext.gitBranch;
+// Resolution order per call: session pin (from ricord_set_project) → CLI/env override → git/cwd.
+function currentProject() {
+    const sid = getCurrentSession();
+    if (sid) {
+        const pinned = getActiveProject(sid);
+        if (pinned !== null)
+            return pinned;
+    }
+    return PROJECT;
+}
+if (!API_KEY) {
+    console.error("Error: No API key found.");
+    console.error("Run `ricord-mcp login` to authenticate, or pass --api-key <YOUR_KEY>");
+    process.exit(1);
+}
+// ── API client ────────────────────────────────────────────────────────
+async function api(method, path, body) {
+    const res = await fetch(`${API_BASE}${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+            "User-Agent": `ricord-mcp/${VERSION}`,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        // Truncate error body to avoid leaking verbose server internals to callers.
+        throw new Error(`Ricord API ${res.status}: ${text.slice(0, 200)}`);
+    }
+    return res.json();
+}
+function ok(text) { return { content: [{ type: "text", text }] }; }
+function err(msg) { return { content: [{ type: "text", text: msg }], isError: true }; }
+// ── MCP Server ────────────────────────────────────────────────────────
+const SERVER_INSTRUCTIONS = `Ricord gives AI agents persistent memory across sessions.
+
+Session start: call ricord_get_context once before any other Ricord tool. The returned procedures catalog lists available SOPs; the instructions block is the user's always-on preferences.
+
+When the user states a new fact, preference, or decision, call ricord_save with the appropriate kind.
+
+When the user references prior knowledge ("what did we decide about X", "how do we handle X", "like last time"), call ricord_recall first.
+
+When the user corrects a saved memory, call ricord_recall to find the id, then call ricord_correct with that id. Do NOT use ricord_save to fix an existing memory — that creates a duplicate.
+
+When the user explicitly says to delete something ("forget that", "remove that preference"), call ricord_recall to find the id, then call ricord_forget.
+
+When the user's message matches a procedure trigger from ricord_get_context, call ricord_run_procedure with that procedure name.
+
+When the user asks "how many credits do I have", "what plan am I on", or "what's my usage", call ricord_usage.
+
+When the user asks about their knowledge graph shape, entity counts, or "what does my graph look like", call ricord_graph_stats.`;
+const server = new McpServer({ name: "ricord", version: VERSION }, { instructions: SERVER_INSTRUCTIONS });
+// ═══════════════════════════════════════════════════════════════════════
+// v2 tool surface — 8 tools, ordered by descending call frequency.
+// Everyday (1–5): get_context, recall, save, correct, forget
+// Occasional (6–8): run_procedure, usage, graph_stats
+// ═══════════════════════════════════════════════════════════════════════
+// ═══════════════════════════════════════════════════════════════════════
+// 1. GET CONTEXT — session start, read-only, idempotent
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_get_context", `Returns the user's always-on instruction block, active procedures catalog (names + triggers), and user preferences for this session.
+
+When to call:
+- At the very start of every conversation, before any other Ricord tool
+- When you need to know what SOPs (procedures) are available for this user
+- When you need the user's identity, preferences, or standing instructions
+
+Do NOT call when:
+- You need to retrieve past memories for a specific query (use ricord_recall instead)
+- You have already called this tool in the current session
+
+Returns: instructions string, top_procedures array (each with id, title, trigger), preferences object, active_projects array. Use the procedures list to decide whether to call ricord_run_procedure.`, {
+    project_id: z.string().optional().describe("Override the auto-detected project scope."),
+}, {
+    title: "Get session context",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async ({ project_id }) => {
+    try {
+        const proj = project_id || currentProject();
+        const qs = proj ? `?project_id=${encodeURIComponent(proj)}` : "";
+        const r = await api("GET", `/v1/user/boot-context${qs}`);
+        const lines = [];
+        if (r.instructions) {
+            lines.push("## Standing instructions");
+            lines.push(r.instructions.slice(0, 4000));
+            lines.push("");
+        }
+        if (r.preferences && Object.keys(r.preferences).length > 0) {
+            lines.push("## User preferences");
+            lines.push(JSON.stringify(r.preferences, null, 2));
+            lines.push("");
+        }
+        const procs = r.top_procedures || [];
+        if (procs.length > 0) {
+            lines.push("## Active procedures");
+            for (const p of procs) {
+                lines.push(`  • [${p.kind}] ${p.title}${p.trigger ? ` — trigger: ${p.trigger}` : ""} (id: ${p.id})`);
+            }
+            lines.push("");
+        }
+        else {
+            lines.push("## Active procedures\n  (none — skip ricord_run_procedure this session)");
+            lines.push("");
+        }
+        if (r.active_projects?.length) {
+            lines.push("## Active projects");
+            for (const p of r.active_projects)
+                lines.push(`  • ${p.title} [${p.subtype}] — ${p.sources} sources`);
+            lines.push("");
+        }
+        if (r.counts) {
+            lines.push(`Counts: ${r.counts.pages} KB pages · ${r.counts.procedures} procedures`);
+        }
+        return ok(lines.join("\n") || "(no context configured yet)");
+    }
+    catch (e) {
+        return err(`ricord_get_context failed: ${e.message}`);
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════
+// 2. RECALL — semantic search, read-only, idempotent
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_recall", `Search the user's stored knowledge for facts, preferences, decisions, and past observations relevant to a query.
+
+When to call:
+- The user references something they "told you before", "mentioned", or "discussed earlier"
+- The user asks "what did we decide about X", "how do we handle X", "what was the reason for X"
+- The user says "like last time", "like before", "previously", "remember when we"
+- Any message using "we", "our", "my X" implying prior cross-session context
+- Before writing a plan, design, or strategy (check prior iterations first)
+- The user's request is ambiguous and prior context might disambiguate
+
+Do NOT call when:
+- The user is making a fresh statement with no reference to prior knowledge (use ricord_save instead)
+- The information is already in the current conversation
+- The user is asking about general world knowledge unrelated to themselves
+- You only need to browse recent memories in order (use ricord_list via direct API)
+
+Returns: ranked memory records with id, content, kind, created_at, relevance score. Cite ids when using results so the user can correct or forget them.`, {
+    query: z.string().describe("What to search for — describe the topic, decision, or question."),
+    k: z.number().int().positive().max(50).default(10).optional().describe("Max results to return (default 10)."),
+}, {
+    title: "Search memory",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async ({ query, k }) => {
+    if (!query || !query.trim())
+        return ok("No relevant knowledge found (empty query).");
+    try {
+        const body = {
+            query,
+            question_type: "multi-session",
+        };
+        if (k !== undefined)
+            body.limit = k;
+        const result = await api("POST", "/v1/memories/search", body);
+        const context = result.context || "";
+        if (!context || context.length === 0)
+            return ok("No relevant knowledge found.");
+        return ok(context);
+    }
+    catch (e) {
+        return err(`ricord_recall failed: ${e.message}`);
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════
+// 3. SAVE — create a memory, write, not idempotent
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_save", `Creates a new memory record for a fact, preference, decision, reference, or anti-pattern.
+
+When to call:
+- The user states a preference or rule ("always use X", "never do Y", "from now on use X")
+- The user makes a decision ("we decided X", "we're going with X", "let's use Y")
+- The user corrects something about their setup or project ("actually it's X", "that's wrong — it's X")
+- The user says "save this", "remember this", "log this", "note this"
+- The user shares a non-obvious architectural fact, constraint, or coding convention
+- You discover something (an approach that failed, a root cause) that a future agent needs to know
+
+Do NOT call when:
+- You need to update an existing memory — use ricord_correct with its id instead (ricord_save always creates a new record)
+- The user is asking about prior knowledge — use ricord_recall first
+- For bulk ingestion of URLs, files, or conversation exports, use the direct API
+
+Returns: confirmation with the new memory id. Cite the id so the user can correct or forget it.`, {
+    content: z.string().describe("The memory content to save. Be specific and concrete."),
+    kind: z.enum(["fact", "preference", "decision", "reference", "anti-pattern", "observation"]).describe("Memory kind: fact=objective truth; preference=user style/taste; decision=choice made (include rationale); anti-pattern=what failed (include why); observation=passive note; reference=pointer to external resource. (For step-by-step SOPs, use POST /v1/procedures — memories are knowledge, procedures are runnable.)"),
+    title: z.string().optional().describe("Short title for this memory (defaults to first 80 chars of content)."),
+    tags: z.array(z.string()).optional().describe("Optional tags for filtering."),
+}, {
+    title: "Save to memory",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+}, async ({ content, kind, title, tags }) => {
+    if (!content || !content.trim())
+        return err("content is required and cannot be empty.");
+    try {
+        const label = title || content.slice(0, 80);
+        const fullContent = `[${kind}] ${label}: ${content}${tags?.length ? ` [tags: ${tags.join(", ")}]` : ""}`;
+        const result = await api("POST", "/v1/memories", {
+            content: fullContent,
+            type: kind,
+            tags: tags || [],
+            confidence: 0.95,
+        });
+        const id = result.id || "pending";
+        return ok(`Saved [${kind}]: "${label}" (id: ${id})`);
+    }
+    catch (e) {
+        return err(`ricord_save failed: ${e.message}`);
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════
+// 4. CORRECT — overwrite memory by id, write, idempotent
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_correct", `Overwrites the content of an existing memory by id.
+
+When to call:
+- The user says a saved memory is wrong ("that's outdated", "that's not right anymore", "update that")
+- You find a contradiction between a recalled memory and something the user just stated
+- You have a memory id from a prior ricord_recall result and the user wants it updated
+
+Do NOT call when:
+- You don't have a memory id — call ricord_recall first to get one
+- You want to add a new memory — use ricord_save (ricord_correct requires an exact id; wrong ids will error)
+- You want to delete a memory — use ricord_forget
+
+Returns: confirmation that the memory was updated. Same id, new content.`, {
+    id: z.string().describe("Memory id from a prior ricord_recall result."),
+    content: z.string().describe("New content to replace the existing memory."),
+    title: z.string().optional().describe("Optional new title."),
+}, {
+    title: "Correct a memory",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async ({ id, content, title }) => {
+    if (!id)
+        return err("id is required.");
+    if (!content || !content.trim())
+        return err("content is required.");
+    try {
+        const patch = { content };
+        if (title !== undefined)
+            patch.title = title;
+        await api("PUT", `/v1/memories/${encodeURIComponent(id)}`, patch);
+        return ok(`Corrected memory ${id}.`);
+    }
+    catch (e) {
+        return err(`ricord_correct failed: ${e.message}`);
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════
+// 5. FORGET — delete memory by id, destructive
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_forget", `Permanently deletes a memory by id.
+
+When to call:
+- The user explicitly says to delete or remove a memory ("forget that", "remove that preference", "delete that rule")
+- You have a memory id from a prior ricord_recall result and the user confirms it should be removed
+
+Do NOT call when:
+- You don't have a memory id — call ricord_recall first to get one
+- The user just wants to correct a memory — use ricord_correct instead
+- You want to delete multiple memories — call once per id (no bulk delete)
+
+Returns: confirmation of deletion. This is irreversible.`, {
+    id: z.string().describe("Memory id from a prior ricord_recall result."),
+}, {
+    title: "Delete a memory",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+}, async ({ id }) => {
+    if (!id)
+        return err("id is required.");
+    try {
+        await api("DELETE", `/v1/memories/${encodeURIComponent(id)}`);
+        return ok(`Deleted memory ${id}.`);
+    }
+    catch (e) {
+        return err(`ricord_forget failed: ${e.message}`);
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════
+// 6. RUN PROCEDURE — execute a named SOP
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_run_procedure", `Executes a named SOP or playbook, substituting template variables, and returns the step-by-step instructions.
+
+When to call:
+- The user's message matches or paraphrases a procedure trigger listed in the ricord_get_context output
+- The user explicitly requests a named procedure ("run the deploy checklist", "start the release process")
+- The user says "ready to ship", "time to deploy", "run the checklist", or any phrase that matches a known trigger
+
+Do NOT call when:
+- ricord_get_context returned no procedures this session (the call will error)
+- You are not sure a matching procedure exists — check the list from ricord_get_context first
+- The user wants to create or modify a procedure (use the direct API)
+
+Returns: the procedure's steps, pre-conditions, and template-substituted actions. Follow the steps in order.`, {
+    name: z.string().describe("Exact procedure title or a trigger phrase to match against."),
+    inputs: z.record(z.string()).optional().describe("Template variable substitutions — replaces {{key}} tokens in step actions. Example: { service: 'ricord-api', env: 'prod' }"),
+}, {
+    title: "Run procedure",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+}, async ({ name, inputs }) => {
+    if (!name || !name.trim())
+        return err("name is required.");
+    try {
+        const listR = await api("GET", "/v1/procedures?limit=200");
+        const all = listR.procedures || [];
+        if (!all.length)
+            return err("No procedures found. Call ricord_get_context first to verify procedures exist.");
+        const phrase = name.toLowerCase();
+        const match = all.find(p => p.title === name ||
+            p.title.toLowerCase() === phrase ||
+            (p.trigger && p.trigger.toLowerCase().includes(phrase)) ||
+            (p.steps || []).some(s => s.action.toLowerCase().includes(phrase)));
+        if (!match) {
+            const suggestions = all.slice(0, 5).map(p => `• ${p.title}${p.trigger ? ` (trigger: ${p.trigger})` : ""}`).join("\n");
+            return ok(`No procedure matched "${name}". Available procedures:\n${suggestions}`);
+        }
+        const walkQs = new URLSearchParams({ source: "walk" });
+        if (inputs && Object.keys(inputs).length > 0)
+            walkQs.set("inputs", JSON.stringify(inputs));
+        const proc = await api("GET", `/v1/procedures/${encodeURIComponent(match.id)}?${walkQs}`);
+        const lines = [];
+        lines.push(`## Procedure: ${proc.title}`);
+        if (proc.trigger)
+            lines.push(`**When:** ${proc.trigger}`);
+        if (proc.guards?.length)
+            lines.push(`**Pre-conditions:** ${proc.guards.join("; ")}`);
+        lines.push("\n**Steps:**");
+        for (const step of proc.steps || []) {
+            const n = step.n ?? (proc.steps.indexOf(step) + 1);
+            lines.push(`${n}. ${step.action}`);
+            if (step.expected)
+                lines.push(`   → Expected: ${step.expected}`);
+        }
+        lines.push(`\n(id: ${proc.id}, kind: ${proc.kind})`);
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`ricord_run_procedure failed: ${e.message}`);
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════
+// 7. USAGE — credit balance + plan info, read-only, idempotent
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_usage", `Returns current tier, today's request count, token usage, and rate limit information.
+
+When to call:
+- The user asks "how many credits do I have", "what plan am I on", "am I near my limit"
+- The user asks about API quota, rate limits, or request counts
+- You need to decide whether to attempt a credit-consuming operation
+
+Do NOT call when:
+- You need historical usage over time (available in the dashboard at ricord.ai)
+- You are checking the knowledge graph shape (use ricord_graph_stats instead)
+
+Returns: tier, today.requests, today.tokens_total, rate_limit (requests per minute/day), and memory quota.`, {}, {
+    title: "Check usage",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async () => {
+    try {
+        const result = await api("GET", "/v1/usage");
+        const today = result.today || {};
+        const rl = result.rate_limit || {};
+        const quota = result.quota || {};
+        const parts = [`Tier: ${result.tier ?? "unknown"}`];
+        if (today.requests !== undefined) {
+            parts.push(`Today: ${today.requests} requests, ${today.tokens_total ?? 0} tokens`);
+        }
+        if (rl.requestsPerMinute !== undefined || rl.requestsPerDay !== undefined) {
+            parts.push(`Rate limit: ${rl.requestsPerMinute ?? "?"}/min, ${rl.requestsPerDay ?? "?"}/day`);
+        }
+        if (quota.memories_used !== undefined) {
+            const cap = quota.memories_cap ?? "unlimited";
+            parts.push(`Memories: ${quota.memories_used}/${cap}${quota.over_cap ? " (over cap)" : ""}`);
+        }
+        return ok(parts.join(" | "));
+    }
+    catch (e) {
+        return err(`ricord_usage failed: ${e.message}`);
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════
+// 8. GRAPH STATS — entity/edge counts + top entities, read-only, idempotent
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_graph_stats", `Returns entity count, edge count, and edge-type breakdown for the user's knowledge graph.
+
+When to call:
+- The user asks "what does my knowledge graph look like", "how many entities do I have", "show me my graph stats"
+- The user asks about the shape or size of their knowledge base
+- You want to assess whether the knowledge graph is populated before using recall
+
+Do NOT call when:
+- You need to search for specific knowledge (use ricord_recall instead)
+- You need a full entity list or neighborhood traversal (available via the dashboard graph view)
+
+Returns: totalEntities, totalEdges, edgeTypeCounts (map of edge type to count).`, {}, {
+    title: "Knowledge graph stats",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async () => {
+    try {
+        const stats = await api("GET", "/v1/kb/graph/stats");
+        const parts = [
+            `Entities: ${stats.totalEntities ?? 0}`,
+            `Edges: ${stats.totalEdges ?? 0}`,
+        ];
+        if (stats.edgeTypeCounts && Object.keys(stats.edgeTypeCounts).length > 0) {
+            const sorted = Object.entries(stats.edgeTypeCounts)
+                .sort(([, a], [, b]) => b - a)
+                .slice(0, 8)
+                .map(([k, v]) => `${k}: ${v}`)
+                .join(", ");
+            parts.push(`Edge types: ${sorted}`);
+        }
+        return ok(parts.join(" | "));
+    }
+    catch (e) {
+        return err(`ricord_graph_stats failed: ${e.message}`);
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════
+// 9. WIKI TOPICS — Topic DAG read access (F5 / S2)
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_wiki_topics", `Returns the project's topic tree — the reading-neighborhood structure of the wiki.
+
+When to call:
+- You need to know how this user's wiki is *organized* before answering a "what do we know about X" question
+- The user mentions "topics", "areas", "categories" of their knowledge
+- You want to suggest a wiki page placement and need to know what topics already exist
+
+Do NOT call when:
+- You need a specific page (use ricord_recall)
+- You only need entity counts (use ricord_graph_stats)
+
+Returns: topics[] with slug, title, scope (project | user), page_count, and has_children flag.`, {
+    project_id: z.string().optional().describe("Override the auto-detected project scope."),
+    scope: z.enum(["project", "user", "all"]).optional().describe("Filter by topic scope (default: all)."),
+}, {
+    title: "List wiki topics",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async ({ project_id, scope }) => {
+    try {
+        const qs = new URLSearchParams();
+        if (project_id)
+            qs.set("project_id", project_id);
+        if (scope)
+            qs.set("scope", scope);
+        const r = (await api("GET", `/v1/kb/topics${qs.toString() ? "?" + qs.toString() : ""}`));
+        const topics = r.topics ?? [];
+        if (topics.length === 0)
+            return ok("No topics yet. Topics appear as you ingest memories or run `ricord ingest`.");
+        const lines = [`${topics.length} topic${topics.length === 1 ? "" : "s"}:`];
+        const sorted = [...topics].sort((a, b) => b.page_count - a.page_count);
+        for (const t of sorted.slice(0, 50)) {
+            const tag = t.scope === "user" ? " [bridge]" : "";
+            const kids = t.has_children ? " ▾" : "";
+            lines.push(`• ${t.slug}${tag}${kids} — ${t.title ?? "(untitled)"} (${t.page_count} pages)`);
+        }
+        if (sorted.length > 50)
+            lines.push(`… ${sorted.length - 50} more`);
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`ricord_wiki_topics failed: ${e.message}`);
+    }
+});
+// ═══════════════════════════════════════════════════════════════════════
+// 10. WIKI PAGES FOR FILE — file-ref lookup (F4 / S3)
+// ═══════════════════════════════════════════════════════════════════════
+server.tool("ricord_wiki_pages_for_file", `Returns every wiki page that describes a given file or folder path.
+
+When to call:
+- You are about to edit, refactor, or review a specific file and want to know what the wiki already says about it
+- A trailing slash on the path requests folder fanout — pages anywhere under that prefix
+
+Do NOT call when:
+- You only have a concept name, not a path (use ricord_recall)
+- The path is ambiguous or hypothetical — pass the real repo-relative path
+
+Returns: pages[] (direct file refs) and descendant_pages[] (folder fanout, only populated when path ends with /).`, {
+    path: z.string().describe("Repo-relative path. Trailing slash means folder, e.g. 'src/auth/' or 'src/auth/middleware.ts'."),
+    project_id: z.string().optional().describe("Override the auto-detected project scope."),
+}, {
+    title: "Wiki pages for file",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async ({ path, project_id }) => {
+    if (!path || !path.trim())
+        return err("path is required.");
+    try {
+        const qs = new URLSearchParams({ path: path.trim() });
+        if (project_id)
+            qs.set("project_id", project_id);
+        const r = (await api("GET", `/v1/kb/pages/by-file?${qs}`));
+        const pages = r.pages ?? [];
+        const desc = r.descendant_pages ?? [];
+        if (pages.length === 0 && desc.length === 0) {
+            return ok(`No wiki pages reference ${r.path}.`);
+        }
+        const lines = [];
+        if (pages.length > 0) {
+            lines.push(`${pages.length} page${pages.length === 1 ? "" : "s"} for ${r.path}:`);
+            for (const p of pages.slice(0, 20)) {
+                lines.push(`• ${p.title || p.anchor_value}${p.subtype ? ` [${p.subtype}]` : ""} — ${p.summary || "(no summary)"}`);
+            }
+        }
+        if (r.is_dir && desc.length > 0) {
+            lines.push("");
+            lines.push(`${desc.length} page${desc.length === 1 ? "" : "s"} under that folder:`);
+            for (const p of desc.slice(0, 20)) {
+                lines.push(`• ${p.title || p.anchor_value} — ${p.summary || "(no summary)"}`);
+            }
+            if (desc.length > 20)
+                lines.push(`… ${desc.length - 20} more`);
+        }
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`ricord_wiki_pages_for_file failed: ${e.message}`);
+    }
+});
+server.tool("ricord_wiki_search", `Full-text search across every wiki page in the user's account.
+
+When to call:
+- The user (or you, on the user's behalf) needs to find pages that mention a concept, name, file path, or phrase
+- Before generating an answer, you want to ground in what the wiki already knows
+- The user asks "what does my wiki say about X" or "have we written anything about X"
+
+Do NOT call when:
+- You already have the exact page id (use ricord_wiki_pages_for_file or fetch by id)
+- You need to retrieve raw conversation memories (use ricord_recall)
+
+Returns: ranked hits with title, anchor type, snippet (matches highlighted as <b>…</b>), and scope. Cross-project (scope=user) pages are marked.`, {
+    q: z.string().describe("Free-text query. Natural words, no operator syntax."),
+    project_id: z.string().optional().describe("Restrict to a single project."),
+    scope: z.enum(["project", "user"]).optional().describe("Restrict to project-scope or user-scope (cross-project) pages."),
+    limit: z.number().int().min(1).max(100).optional().describe("Max hits (default 25, cap 100)."),
+}, {
+    title: "Wiki search",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async ({ q, project_id, scope, limit }) => {
+    if (!q || !q.trim())
+        return err("q is required.");
+    try {
+        const qs = new URLSearchParams({ q: q.trim() });
+        if (project_id)
+            qs.set("project_id", project_id);
+        if (scope)
+            qs.set("scope", scope);
+        if (limit)
+            qs.set("limit", String(limit));
+        const r = (await api("GET", `/v1/kb/search?${qs}`));
+        if (r.count === 0)
+            return ok(`No wiki pages match "${r.q}".`);
+        const lines = [`${r.count} hit${r.count === 1 ? "" : "s"} for "${r.q}":`];
+        for (const h of r.hits.slice(0, 25)) {
+            const star = h.scope === "user" ? " ★" : "";
+            const snip = (h.snippet || h.summary || "").replace(/<\/?b>/g, "*").replace(/\s+/g, " ").trim();
+            lines.push(`• [${h.anchor_type}] ${h.title || h.anchor_value}${star} — ${snip}`);
+        }
+        if (r.count > 25)
+            lines.push(`… ${r.count - 25} more`);
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`ricord_wiki_search failed: ${e.message}`);
+    }
+});
+server.tool("ricord_wiki_recall", `Pull the top wiki pages for a query, with full bodies + topics ready to paste into your context.
+
+When to call:
+- Before answering a question about the user's project, codebase, or domain, ground in what the wiki knows
+- When ricord_wiki_search would just give you titles + snippets and you need the actual content
+- The user asks "what do we know about X" or "remind me how X works" and you don't have it in context
+
+Do NOT call when:
+- You only need to know whether a page exists (use ricord_wiki_search — it's lighter)
+- You already have the page id (fetch by id)
+- The query is about raw conversation memory (use ricord_recall)
+
+Returns: top hits with title, anchor type, scope, topics[], and body truncated to max_body chars. Cite the page id when you use the content.`, {
+    q: z.string().describe("Free-text query. Natural words."),
+    project_id: z.string().optional().describe("Restrict to a single project."),
+    limit: z.number().int().min(1).max(10).optional().describe("How many pages to return (default 3, max 10)."),
+    max_body: z.number().int().min(200).max(8000).optional().describe("Per-page body cap in chars (default 2000)."),
+}, {
+    title: "Wiki recall",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async ({ q, project_id, limit, max_body }) => {
+    if (!q || !q.trim())
+        return err("q is required.");
+    try {
+        const qs = new URLSearchParams({ q: q.trim() });
+        if (project_id)
+            qs.set("project_id", project_id);
+        if (limit)
+            qs.set("limit", String(limit));
+        if (max_body)
+            qs.set("max_body", String(max_body));
+        const r = (await api("GET", `/v1/kb/recall?${qs}`));
+        if (r.count === 0)
+            return ok(`No wiki pages match "${r.q}".`);
+        const sections = [];
+        for (const h of r.hits) {
+            const star = h.scope === "user" ? " ★" : "";
+            const topics = h.topics.length > 0
+                ? `_topics: ${h.topics.map((t) => t.slug).join(", ")}_\n\n`
+                : "";
+            sections.push(`## [${h.anchor_type}] ${h.title || h.anchor_value}${star}\n_page_id: ${h.id}_\n\n${topics}${h.body || "(no body)"}`);
+        }
+        return ok(sections.join("\n\n---\n\n"));
+    }
+    catch (e) {
+        return err(`ricord_wiki_recall failed: ${e.message}`);
+    }
+});
+server.tool("ricord_wiki_backlinks", `Show the wiki pages that point to (or are pointed at by) a given page.
+
+When to call:
+- You opened a page via ricord_wiki_search / ricord_wiki_recall and want to know what else references the same concept
+- You're about to rename, archive, or merge a page and need to see what depends on it
+- The user asks "what references this" / "what's linked from this" / "what's the neighborhood"
+
+Do NOT call when:
+- You only need the page body (use ricord_wiki_recall)
+- You don't have the page id yet (search for it first)
+
+Returns: inbound[] (pages that reference this) and outbound[] (pages this references), each with link_type + link_weight so you can distinguish a mention from a contradiction or supersession.`, {
+    page_id: z.string().describe("Page id (UUID) from a prior ricord_wiki_search / recall result."),
+    limit: z.number().int().min(1).max(200).optional().describe("Per-direction cap (default 50)."),
+}, {
+    title: "Wiki backlinks",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+}, async ({ page_id, limit }) => {
+    if (!page_id || !page_id.trim())
+        return err("page_id is required.");
+    try {
+        const qs = new URLSearchParams();
+        if (limit)
+            qs.set("limit", String(limit));
+        const path = `/v1/kb/pages/${encodeURIComponent(page_id.trim())}/backlinks${qs.toString() ? `?${qs}` : ""}`;
+        const r = (await api("GET", path));
+        if (r.inbound_count === 0 && r.outbound_count === 0) {
+            return ok("This page has no inbound or outbound wiki links.");
+        }
+        const lines = [];
+        if (r.inbound_count > 0) {
+            lines.push(`${r.inbound_count} inbound (pages that reference this):`);
+            for (const p of r.inbound.slice(0, 25)) {
+                lines.push(`  ← [${p.link_type}] ${p.title || p.anchor_value} (${p.id.slice(0, 8)})`);
+            }
+            if (r.inbound_count > 25)
+                lines.push(`  … ${r.inbound_count - 25} more`);
+        }
+        if (r.outbound_count > 0) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push(`${r.outbound_count} outbound (pages this references):`);
+            for (const p of r.outbound.slice(0, 25)) {
+                lines.push(`  → [${p.link_type}] ${p.title || p.anchor_value} (${p.id.slice(0, 8)})`);
+            }
+            if (r.outbound_count > 25)
+                lines.push(`  … ${r.outbound_count - 25} more`);
+        }
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(`ricord_wiki_backlinks failed: ${e.message}`);
+    }
+});
+// ── Start server ──────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const toolCount = server._registeredTools
+        ? Object.keys(server._registeredTools).length
+        : 0;
+    console.error(`Ricord MCP v${VERSION} (v2, ${toolCount} tools) — ${API_BASE}`);
+    if (PROJECT)
+        console.error(`Project: ${PROJECT}`);
+    if (GIT_REPO)
+        console.error(`Git: ${GIT_REPO} (${GIT_BRANCH || "unknown"})`);
+}
+main().catch((e) => {
+    console.error("Fatal:", e);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map