@finchagentic/mcp 4.0.0 → 4.1.0

package/dist/cli.js

@@ -44,6 +44,7 @@ const tool_filter_js_1 = require("./tool-filter.js");
 const config_js_1 = require("./config.js");
 const local_memory_js_1 = require("./local-memory.js");
 const clink_input_js_1 = require("./clink-input.js");
+const wallet_js_1 = require("./wallet.js");
 const child_process = __importStar(require("child_process"));
 (0, config_js_1.hydrateEnvFromConfig)();
 // Derived tool counts - single source of truth, kept in sync with the
@@ -117,8 +118,8 @@ async function loginWithApiKey(rl) {
     }
     const email = data.email ?? "api-key-user";
     const name = data.displayName ?? undefined;
-    (0, config_js_1.writeConfig)({ sessionToken: data.token, email, name });
-    printLoginSuccess({ email, name });
+    (0, config_js_1.writeConfig)({ sessionToken: data.token, email, name, walletAddress: data.walletAddress });
+    printLoginSuccess({ email, name, walletAddress: data.walletAddress });
 }
 async function loginFlow(loginRl) {
     const rl = loginRl ?? readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -136,8 +137,8 @@ async function loginFlow(loginRl) {
         if (res.ok && data.token) {
             const email = data.email ?? "api-key-user";
             const name = data.displayName ?? undefined;
-            (0, config_js_1.writeConfig)({ sessionToken: data.token, email, name });
-            printLoginSuccess({ email, name });
+            (0, config_js_1.writeConfig)({ sessionToken: data.token, email, name, walletAddress: data.walletAddress });
+            printLoginSuccess({ email, name, walletAddress: data.walletAddress });
             rl.close();
             return;
         }
@@ -210,10 +211,16 @@ async function setupFlow() {
         console.log(`\n  ${C.dim}Skipped - using Finch proxy.${C.reset}\n`);
     }
     // ── Step 2: local memory ──────────────────────────────────────────────────
-    console.log(`  ${C.cyan}${C.bold}Local memory${C.reset}  ${C.dim}(self-hosted supermemory - github.com/supermemoryai/supermemory)${C.reset}`);
-    console.log(`  ${C.dim}Runs on your machine, MIT licensed, free. Replaces the Finch-hosted memory proxy.${C.reset}\n`);
-    const enableLocal = (0, clink_input_js_1.dedupClinkInput)((await ask(`  Enable local memory? [y/N]: `)).trim()).toLowerCase();
-    if (enableLocal === "y" || enableLocal === "yes") {
+    console.log(`  ${C.cyan}${C.bold}Local memory${C.reset}  ${C.dim}(self-hosted - your choice of backend)${C.reset}`);
+    console.log(`  ${C.dim}[1] Simple file-based (recommended) - zero dependency, JSON on disk at ~/.finch/memory/, keyword search only.${C.reset}`);
+    console.log(`  ${C.dim}[2] Supermemory server - real semantic/embedding search, but you run a separate process yourself.${C.reset}`);
+    console.log(`  ${C.dim}[3] Skip - memory tools use the Finch-hosted proxy.${C.reset}\n`);
+    const memChoice = (0, clink_input_js_1.dedupClinkInput)((await ask(`  Choose [1-3]: `)).trim());
+    if (memChoice === "1") {
+        (0, config_js_1.writeConfig)({ memoryBackend: "local-file" });
+        console.log(`\n  ${C.green}✓${C.reset} Local file memory enabled at ~/.finch/memory/. No server, no key - memory tools run fully local.\n`);
+    }
+    else if (memChoice === "2") {
         const url = "http://localhost:6767";
         console.log(`\n  ${C.dim}Checking ${url}...${C.reset}`);
         let reachable = await isLocalMemoryReachableRaw(url);
@@ -389,16 +396,21 @@ const C = {
 //   ██║ ╚████║╚██████╔╝███████╗███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝
 //   ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝
 const LOGO_LINES = [
-    `  ███╗   ██╗ ██████╗ ███████╗██╗      ██████╗██╗      █████╗ ██╗    ██╗`,
-    `  ████╗  ██║██╔═══██╗██╔════╝██║     ██╔════╝██║     ██╔══██╗██║    ██║`,
-    `  ██╔██╗ ██║██║   ██║█████╗  ██║     ██║     ██║     ███████║██║ █╗ ██║`,
-    `  ██║╚██╗██║██║   ██║██╔══╝  ██║     ██║     ██║     ██╔══██║██║███╗██║`,
-    `  ██║ ╚████║╚██████╔╝███████╗███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝`,
-    `  ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝`,
+    `  ███████╗ ██╗ ███╗   ██╗  ██████╗ ██╗  ██╗`,
+    `  ██╔════╝ ██║ ████╗  ██║ ██╔════╝ ██║  ██║`,
+    `  █████╗   ██║ ██╔██╗ ██║ ██║      ███████║`,
+    `  ██╔══╝   ██║ ██║╚██╗██║ ██║      ██╔══██║`,
+    `  ██║      ██║ ██║ ╚████║ ╚██████╗ ██║  ██║`,
+    `  ╚═╝      ╚═╝ ╚═╝  ╚═══╝  ╚═════╝ ╚═╝  ╚═╝`,
 ];
 const SEP = `  ${"─".repeat(70)}`;
 function buildBanner() {
     const cfg = (0, config_js_1.readConfig)();
+    // Every base_mcp_*/rh_mcp_* tool signs locally via getOrCreateWallet()
+    // (~/.finch/wallet.json) on BOTH Base and Robinhood Chain (RH reuses the
+    // same local address) - this CLI never touches the account's custodial
+    // webapp wallet. Showing that other address here would mismatch what
+    // every tool call actually reports and operates on.
     const walletAddr = getLocalWalletAddress();
     const provider = process.env.BANKR_API_KEY ? "Bankr"
         : process.env.ANTHROPIC_API_KEY ? "Anthropic"
@@ -415,8 +427,9 @@ function buildBanner() {
         const nameLine = displayName
             ? `  ${C.green}●${C.reset}  ${displayName}  ${displayEmail}`
             : `  ${C.green}●${C.reset}  ${displayEmail || `${C.green}Signed in${C.reset}`}`;
+        const walletNote = "Base + Robinhood Chain · local device wallet · keys never leave your machine";
         const walletLine = walletAddr
-            ? `     ${C.dim}Wallet${C.reset}  ${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· Base mainnet · keys never leave your machine${C.reset}`
+            ? `     ${C.dim}Wallet${C.reset}  ${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· ${walletNote}${C.reset}`
             : `     ${C.dim}Wallet  not created yet · auto-creates on first DeFi call${C.reset}`;
         const llmLine = `     ${C.dim}LLM     ${C.reset}${C.green}${provider}${C.reset}  ${C.dim}· ${TOTAL_TOOL_COUNT} tools active${C.reset}`;
         authBlock = `\n${nameLine}\n${walletLine}\n${llmLine}`;
@@ -434,6 +447,10 @@ function buildBanner() {
 }
 // ── Post-login success block ──────────────────────────────────────────────────
 function printLoginSuccess({ email, name }) {
+    // Always show the local per-device wallet: every base_mcp_*/rh_mcp_* tool
+    // signs with it on BOTH chains. The account's custodial webapp wallet is a
+    // separate address this CLI never touches - showing it here would mismatch
+    // what every subsequent tool call actually reports.
     const walletAddr = getLocalWalletAddress();
     const displayName = name ?? "";
     console.log(`\n${SEP}`);
@@ -444,7 +461,8 @@ function printLoginSuccess({ email, name }) {
         console.log(`  ${C.green}✓${C.reset}  ${C.green}${C.bold}Signed in${C.reset}  ${C.dim}as ${email}${C.reset}`);
     }
     if (walletAddr) {
-        console.log(`     ${C.dim}Wallet${C.reset}  ${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· Base mainnet${C.reset}`);
+        const note = "Base + Robinhood Chain · local device wallet";
+        console.log(`     ${C.dim}Wallet${C.reset}  ${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· ${note}${C.reset}`);
     }
     else {
         console.log(`     ${C.dim}Wallet  auto-creates on first DeFi tool call${C.reset}`);
@@ -527,7 +545,7 @@ async function main() {
             });
             const data = await res.json();
             if (res.ok && data.token) {
-                (0, config_js_1.writeConfig)({ sessionToken: data.token, email: data.email ?? "api-key-user", name: data.displayName ?? undefined });
+                (0, config_js_1.writeConfig)({ sessionToken: data.token, email: data.email ?? "api-key-user", name: data.displayName ?? undefined, walletAddress: data.walletAddress });
                 console.log(`${C.green}✓${C.reset} ${C.dim}Signed in as ${data.email}${C.reset}`);
             }
             else {
@@ -539,6 +557,8 @@ async function main() {
         }
     }
     process.stdout.write(buildBanner());
+    // Once, here, so it doesn't interrupt the first tool reply mid-conversation.
+    (0, wallet_js_1.warnIfNoPassphrase)();
     // Check for updates in background - shows after banner, doesn't block prompt
     checkForUpdate().catch(() => { });
     const history = [];
@@ -998,10 +1018,17 @@ async function doctorFlow() {
             fix: `Optional. Create at https://github.com/settings/tokens (scopes: public_repo) and add to MCP env.`,
         });
     }
-    // 9. Local memory (self-hosted supermemory) - optional, zero-cost alternative
-    // to the Convex-proxied cloud memory backend.
+    // 9. Local memory (self-hosted) - optional, zero-cost alternative to the
+    // Convex-proxied cloud memory backend. Two flavors: zero-dependency file
+    // store, or a separately-run supermemory server.
     const localMemCfg = (0, local_memory_js_1.getLocalMemoryConfig)();
-    if (localMemCfg) {
+    if (localMemCfg?.kind === "file") {
+        checks.push({
+            name: "Local memory", status: "✓",
+            detail: `file-based at ~/.finch/memory - memory tools run fully local, zero cost, no server`,
+        });
+    }
+    else if (localMemCfg?.kind === "supermemory") {
         const reachable = await (0, local_memory_js_1.isLocalMemoryReachable)(localMemCfg);
         checks.push(reachable ? {
             name: "Local memory", status: "✓",
@@ -1143,6 +1170,9 @@ else if (cmd === "logout") {
 }
 else if (cmd === "status") {
     const cfg = (0, config_js_1.readConfig)();
+    // Every base_mcp_*/rh_mcp_* tool signs locally on BOTH chains - the
+    // account's custodial webapp wallet is a separate address this CLI never
+    // touches, so always show the local one to match what tools report.
     const walletAddr = getLocalWalletAddress();
     const provider = process.env.BANKR_API_KEY ? "Bankr"
         : process.env.ANTHROPIC_API_KEY ? "Anthropic"
@@ -1155,7 +1185,8 @@ else if (cmd === "status") {
         const displayEmail = cfg.email ? `${C.dim}${cfg.email}${C.reset}` : "";
         console.log(`  ${C.green}●${C.reset}  ${displayName}${displayEmail}`);
         if (walletAddr) {
-            console.log(`     ${C.dim}Wallet  ${C.reset}${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· Base mainnet${C.reset}`);
+            const note = "Base + Robinhood Chain · local device wallet";
+            console.log(`     ${C.dim}Wallet  ${C.reset}${C.cyan}${walletAddr.slice(0, 6)}...${walletAddr.slice(-4)}${C.reset}  ${C.dim}· ${note}${C.reset}`);
         }
         else {
             console.log(`     ${C.dim}Wallet  not created yet${C.reset}`);
@@ -1169,12 +1200,38 @@ else if (cmd === "status") {
     }
     console.log(`${SEP_S}\n`);
 }
+else if (cmd === "run") {
+    const prompt = process.argv.slice(3).join(" ");
+    if (!prompt) {
+        console.error(`  ${C.red}✗ usage: finch run "your prompt"${C.reset}\n`);
+        process.exit(1);
+    }
+    (0, wallet_js_1.warnIfNoPassphrase)();
+    (async () => {
+        const history = [];
+        const stop = spinner("thinking");
+        try {
+            const result = await (0, agent_loop_js_1.runAgent)(prompt, history, (toolName) => {
+                stop();
+                process.stdout.write(`  ${C.dim}✦ ${toolName}${C.reset}\n`);
+            });
+            stop();
+            console.log(`\n${result.text}\n`);
+        }
+        catch (err) {
+            stop();
+            console.error(`  ${C.red}✗ run error: ${err.message || err}${C.reset}\n`);
+            process.exit(1);
+        }
+    })();
+}
 else if (cmd === "help" || cmd === "--help" || cmd === "-h") {
     console.log(`
   ${C.cyan}${C.bold}finch${C.reset}  ${C.dim}runtime layer for Agentic AI · terminal CLI${C.reset}
 
   ${C.cyan}Commands:${C.reset}
     finch              Start interactive AI terminal
+    finch run "..."    Run a single prompt and exit (scripting/CI-friendly)
     finch install      Auto-configure all detected MCP clients
     finch login        Sign in to unlock all tools
     finch logout       Sign out and clear saved token

package/dist/config.js

@@ -43,10 +43,10 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const CONFIG_DIR = path.join(os.homedir(), ".finch");
-const LEGACY_DIR = path.join(os.homedir(), ".noelclaw");
+const LEGACY_DIR = path.join(os.homedir(), ".finch");
 const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
 const LEGACY_FILE = path.join(LEGACY_DIR, "config.json");
-/** Prefer FINCH_* env, fall back to legacy NOELCLAW_* during rebrand. */
+/** Prefer FINCH_* env, fall back to legacy FINCH_* during rebrand. */
 function env(name, legacy) {
     const primary = process.env[name];
     if (primary !== undefined && primary !== "")
@@ -56,9 +56,9 @@ function env(name, legacy) {
         if (v !== undefined && v !== "")
             return v;
     }
-    // Auto-map FINCH_X → NOELCLAW_X when legacy not passed
+    // Auto-map FINCH_X → FINCH_X when legacy not passed
     if (name.startsWith("FINCH_")) {
-        const auto = "NOELCLAW_" + name.slice("FINCH_".length);
+        const auto = "FINCH_" + name.slice("FINCH_".length);
         const v = process.env[auto];
         if (v !== undefined && v !== "")
             return v;
@@ -70,7 +70,7 @@ function readConfig() {
         if (fs.existsSync(CONFIG_FILE)) {
             return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
         }
-        // migrate-read: still pick up old ~/.noelclaw/config.json
+        // migrate-read: still pick up old ~/.finch/config.json
         if (fs.existsSync(LEGACY_FILE)) {
             return JSON.parse(fs.readFileSync(LEGACY_FILE, "utf8"));
         }
@@ -89,7 +89,7 @@ function writeConfig(patch) {
 }
 function getSavedToken() {
     // env var always wins over saved config
-    return env("FINCH_SESSION_TOKEN", "NOELCLAW_SESSION_TOKEN") ?? readConfig().sessionToken;
+    return env("FINCH_SESSION_TOKEN", "FINCH_SESSION_TOKEN") ?? readConfig().sessionToken;
 }
 /** Accept finch_sk_* (new) and noel_sk_* (backend still issues these). */
 function isApiKey(value) {
@@ -114,16 +114,16 @@ function hydrateEnvFromConfig() {
         process.env.OPENAI_BASE_URL = cfg.openaiBaseUrl;
     // Bridge legacy env into FINCH_* so the rest of the codebase can read one name.
     const bridges = [
-        ["FINCH_SESSION_TOKEN", "NOELCLAW_SESSION_TOKEN"],
-        ["FINCH_API_KEY", "NOELCLAW_API_KEY"],
-        ["FINCH_CONVEX_URL", "NOELCLAW_CONVEX_URL"],
-        ["FINCH_TOOLS", "NOELCLAW_TOOLS"],
-        ["FINCH_PROVIDER", "NOELCLAW_PROVIDER"],
-        ["FINCH_MODEL", "NOELCLAW_MODEL"],
-        ["FINCH_RPC_URL", "NOELCLAW_RPC_URL"],
-        ["FINCH_BROADCAST_RPC", "NOELCLAW_BROADCAST_RPC"],
-        ["FINCH_WALLET_PASSPHRASE", "NOELCLAW_WALLET_PASSPHRASE"],
-        ["FINCH_PAYMENT_HEADER", "NOELCLAW_PAYMENT_HEADER"],
+        ["FINCH_SESSION_TOKEN", "FINCH_SESSION_TOKEN"],
+        ["FINCH_API_KEY", "FINCH_API_KEY"],
+        ["FINCH_CONVEX_URL", "FINCH_CONVEX_URL"],
+        ["FINCH_TOOLS", "FINCH_TOOLS"],
+        ["FINCH_PROVIDER", "FINCH_PROVIDER"],
+        ["FINCH_MODEL", "FINCH_MODEL"],
+        ["FINCH_RPC_URL", "FINCH_RPC_URL"],
+        ["FINCH_BROADCAST_RPC", "FINCH_BROADCAST_RPC"],
+        ["FINCH_WALLET_PASSPHRASE", "FINCH_WALLET_PASSPHRASE"],
+        ["FINCH_PAYMENT_HEADER", "FINCH_PAYMENT_HEADER"],
     ];
     for (const [fin, leg] of bridges) {
         if (!process.env[fin] && process.env[leg])

package/dist/llm.js

@@ -4,13 +4,10 @@ exports.hasDirectLLMKey = hasDirectLLMKey;
 exports.grokLiveSearchHits = grokLiveSearchHits;
 exports.isGrokActive = isGrokActive;
 exports.callLLM = callLLM;
-const wallet_js_1 = require("./wallet.js");
-const config_js_1 = require("./config.js");
 const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
 const BANKR_URL = "https://llm.bankr.bot/v1/chat/completions";
 const GROK_URL = "https://api.x.ai/v1/chat/completions";
 const OPENAI_URL = "https://api.openai.com/v1/chat/completions";
-const CONVEX_SITE = process.env.FINCH_CONVEX_URL ?? "https://befitting-porcupine-276.convex.site";
 /**
  * Returns true if Grok is the currently active LLM provider, based on env.
  * Useful for tools that want to conditionally enable Grok-specific features
@@ -145,51 +142,18 @@ async function callLLM(systemPrompt, userPrompt, maxTokens = 1024, history = [],
         return callOpenAI(openaiKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.model);
     if (grokKey)
         return callGrok(grokKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.liveSearch, options.model);
-    // Fallback: route through Convex backend - owner covers cost
-    return callViaConvex(systemPrompt, userPrompt, history, timeoutMs);
-}
-async function callViaConvex(systemPrompt, userPrompt, history, timeoutMs) {
-    const fullQuestion = systemPrompt
-        ? `[System: ${systemPrompt}]\n\n${userPrompt}`
-        : userPrompt;
-    const headers = { "Content-Type": "application/json" };
-    const apiKey = process.env.FINCH_API_KEY;
-    let sessionToken = process.env.FINCH_SESSION_TOKEN;
-    // Read from config file — this is the resolved session token after login
-    try {
-        const cfg = (0, config_js_1.readConfig)();
-        if (cfg.sessionToken)
-            sessionToken = cfg.sessionToken;
-    }
-    catch { /* ignore */ }
-    // Prefer session token (resolved by backend) over API key for /mcp/chat
-    if (sessionToken) {
-        headers["Authorization"] = `Bearer ${sessionToken}`;
-    }
-    else if (apiKey) {
-        headers["Authorization"] = `Bearer ${apiKey}`;
-    }
-    else {
-        try {
-            const { address, signature, timestamp } = await (0, wallet_js_1.signRequest)("ask_finch");
-            headers["X-Wallet-Address"] = address;
-            headers["X-Wallet-Signature"] = signature;
-            headers["X-Wallet-Timestamp"] = timestamp;
-        }
-        catch { /* proceed without wallet auth */ }
-    }
-    const res = await fetch(`${CONVEX_SITE}/mcp/chat`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({ question: fullQuestion, messages: history }),
-        signal: AbortSignal.timeout(timeoutMs),
-    });
-    if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw new Error(`LLM error ${res.status}: ${body.slice(0, 200)}`);
-    }
-    const data = await res.json();
-    return data.answer ?? "";
+    // No provider key configured - BYOK is required. This tool needs its own
+    // multi-step reasoning (planning, synthesis, critique) that an MCP host's
+    // model cannot do on the tool's behalf, so there is no free path: bring
+    // your own key or don't use tools that need one (ask_finch, deep_research,
+    // market_thesis, trade_plan, scheduled agent runs). Fails clearly instead
+    // of silently billing the Finch deployment owner for every anonymous
+    // install of this package.
+    throw new Error("No LLM provider configured. This tool needs its own key to do multi-step " +
+        "reasoning server-side - set one of BANKR_API_KEY, ANTHROPIC_API_KEY, " +
+        "OPENAI_API_KEY, or GROK_API_KEY as an environment variable (see the " +
+        "Configuration section of the README), then retry. Most other Finch tools " +
+        "don't need this - only ones that do their own internal LLM reasoning do.");
 }
 async function callAnthropic(apiKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, modelOverride) {
     const messages = [...history, { role: "user", content: userPrompt }];

package/dist/local-memory-file.js

@@ -0,0 +1,134 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLocalMemoryFileConfig = getLocalMemoryFileConfig;
+exports.fileMemoryAdd = fileMemoryAdd;
+exports.fileMemorySearch = fileMemorySearch;
+exports.fileMemoryList = fileMemoryList;
+exports.fileMemoryDelete = fileMemoryDelete;
+exports.fileMemoryProfile = fileMemoryProfile;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+function getLocalMemoryFileConfig() {
+    return { dir: path.join(os.homedir(), ".finch", "memory") };
+}
+function indexPath(cfg) {
+    return path.join(cfg.dir, "index.json");
+}
+function readIndex(cfg) {
+    try {
+        const raw = fs.readFileSync(indexPath(cfg), "utf8");
+        const parsed = JSON.parse(raw);
+        return { memories: parsed.memories ?? [] };
+    }
+    catch {
+        return { memories: [] };
+    }
+}
+// Atomic write: temp file + rename, matching local-vault.ts's pattern so a
+// crash mid-write can't corrupt the index every memory depends on.
+function writeIndex(cfg, idx) {
+    fs.mkdirSync(cfg.dir, { recursive: true });
+    const tmp = indexPath(cfg) + `.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(idx, null, 2), "utf8");
+    fs.renameSync(tmp, indexPath(cfg));
+}
+function toResult(m) {
+    return {
+        id: m.id,
+        content: m.content,
+        metadata: { title: m.title, tags: m.tags, source: m.source, sourceUrl: m.sourceUrl, contentHash: m.contentHash, pinned: m.pinned, addedAt: m.addedAt },
+    };
+}
+function fileMemoryAdd(cfg, content, metadata, sourceUrl) {
+    const idx = readIndex(cfg);
+    const id = crypto.randomBytes(8).toString("hex");
+    const row = {
+        id,
+        content,
+        title: metadata.title,
+        tags: metadata.tags,
+        source: metadata.source,
+        sourceUrl,
+        contentHash: metadata.contentHash ?? "",
+        pinned: metadata.pinned,
+        addedAt: metadata.addedAt ?? Date.now(),
+    };
+    idx.memories.push(row);
+    writeIndex(cfg, idx);
+    return { id };
+}
+function fileMemorySearch(cfg, query, limit) {
+    const idx = readIndex(cfg);
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const scored = [];
+    for (const m of idx.memories) {
+        const hay = `${m.title ?? ""}\n${(m.tags ?? []).join(" ")}\n${m.content}`.toLowerCase();
+        let score = 0;
+        for (const t of terms) {
+            if ((m.title ?? "").toLowerCase().includes(t))
+                score += 3;
+            if ((m.tags ?? []).some((tag) => tag.toLowerCase().includes(t)))
+                score += 2;
+            score += Math.min(hay.split(t).length - 1, 5);
+        }
+        if (score > 0)
+            scored.push({ m, score });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    const top = scored.slice(0, limit);
+    const maxScore = top[0]?.score || 1;
+    return top.map(({ m, score }) => ({ ...toResult(m), score: score / maxScore }));
+}
+function fileMemoryList(cfg, limit, tag) {
+    const idx = readIndex(cfg);
+    let rows = [...idx.memories].sort((a, b) => b.addedAt - a.addedAt);
+    if (tag)
+        rows = rows.filter((m) => (m.tags ?? []).includes(tag));
+    return rows.slice(0, limit).map(toResult);
+}
+function fileMemoryDelete(cfg, id) {
+    const idx = readIndex(cfg);
+    const next = idx.memories.filter((m) => m.id !== id);
+    if (next.length === idx.memories.length)
+        throw new Error(`Memory not found: ${id}`);
+    writeIndex(cfg, { memories: next });
+}
+function fileMemoryProfile(cfg) {
+    const idx = readIndex(cfg);
+    return { total: idx.memories.length, status: "ok", space: "local" };
+}

package/dist/local-memory.js

@@ -8,18 +8,22 @@ exports.localMemoryList = localMemoryList;
 exports.localMemoryDelete = localMemoryDelete;
 exports.localMemoryProfile = localMemoryProfile;
 const config_js_1 = require("./config.js");
+const local_memory_file_js_1 = require("./local-memory-file.js");
 const DEFAULT_URL = "http://localhost:6767";
 const REACHABILITY_TIMEOUT_MS = 1500;
 const CALL_TIMEOUT_MS = 15000;
-// Returns config only when the user has explicitly opted into local memory
-// (memoryBackend: "local") and a key is present. Callers should still treat
-// a null return as "use Convex" - this never throws.
+// Returns config only when the user has explicitly opted into a local
+// backend. Callers should still treat a null return as "use Convex" - this
+// never throws.
 function getLocalMemoryConfig() {
     try {
         const cfg = (0, config_js_1.readConfig)();
-        if (cfg.memoryBackend !== "local" || !cfg.supermemoryApiKey)
-            return null;
-        return { url: cfg.supermemoryUrl ?? DEFAULT_URL, apiKey: cfg.supermemoryApiKey };
+        if (cfg.memoryBackend === "local-file")
+            return { kind: "file", ...(0, local_memory_file_js_1.getLocalMemoryFileConfig)() };
+        if (cfg.memoryBackend === "local" && cfg.supermemoryApiKey) {
+            return { kind: "supermemory", url: cfg.supermemoryUrl ?? DEFAULT_URL, apiKey: cfg.supermemoryApiKey };
+        }
+        return null;
     }
     catch {
         return null;
@@ -28,7 +32,10 @@ function getLocalMemoryConfig() {
 // Requires a genuine 2xx, not just "something answered" - a stale/wrong
 // supermemoryApiKey returns 401 (server is up, but every real memory call
 // will fail the same way), and that must show as unhealthy, not healthy.
+// The file backend is always "reachable" - it's a directory, not a server.
 async function isLocalMemoryReachable(cfg) {
+    if (cfg.kind === "file")
+        return true;
     try {
         const res = await fetch(`${cfg.url}/v3/search`, {
             method: "POST",
@@ -43,6 +50,8 @@ async function isLocalMemoryReachable(cfg) {
     }
 }
 async function localMemoryAdd(cfg, content, metadata, sourceUrl) {
+    if (cfg.kind === "file")
+        return (0, local_memory_file_js_1.fileMemoryAdd)(cfg, content, metadata, sourceUrl);
     const res = await fetch(`${cfg.url}/v3/documents`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
@@ -55,6 +64,8 @@ async function localMemoryAdd(cfg, content, metadata, sourceUrl) {
     return { id: data.id ?? data.documentId ?? "saved" };
 }
 async function localMemorySearch(cfg, query, limit) {
+    if (cfg.kind === "file")
+        return (0, local_memory_file_js_1.fileMemorySearch)(cfg, query, limit);
     const res = await fetch(`${cfg.url}/v3/search`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
@@ -76,6 +87,8 @@ async function localMemorySearch(cfg, query, limit) {
 // server, so callers pass "*" and post-filter by tag client-side, matching
 // how the Convex-side /memory/list already does its own tag post-filter.
 async function localMemoryList(cfg, limit, tag) {
+    if (cfg.kind === "file")
+        return (0, local_memory_file_js_1.fileMemoryList)(cfg, limit, tag);
     const rows = await localMemorySearch(cfg, "*", Math.max(limit * (tag ? 3 : 1), limit));
     const filtered = tag ? rows.filter((r) => Array.isArray(r.metadata?.tags) && r.metadata.tags.includes(tag)) : rows;
     return filtered.slice(0, limit);
@@ -84,6 +97,10 @@ async function localMemoryList(cfg, limit, tag) {
 // time this was written - throws a distinct error so callers can surface a
 // clear "not supported locally yet" message instead of a generic failure.
 async function localMemoryDelete(cfg, id) {
+    if (cfg.kind === "file") {
+        (0, local_memory_file_js_1.fileMemoryDelete)(cfg, id);
+        return;
+    }
     const res = await fetch(`${cfg.url}/v3/documents/${encodeURIComponent(id)}`, {
         method: "DELETE",
         headers: { Authorization: `Bearer ${cfg.apiKey}` },
@@ -92,11 +109,14 @@ async function localMemoryDelete(cfg, id) {
     if (!res.ok)
         throw new Error(`local supermemory delete failed: HTTP ${res.status}`);
 }
-// No dedicated count endpoint is documented for the local server, so this
-// approximates via a capped wildcard search - accurate up to `SAMPLE_LIMIT`,
-// reported as a floor ("200+") beyond that rather than a false exact count.
+// No dedicated count endpoint is documented for the local supermemory server,
+// so that path approximates via a capped wildcard search - accurate up to
+// `PROFILE_SAMPLE_LIMIT`, reported as a floor ("200+") beyond that rather
+// than a false exact count. The file backend counts exactly.
 const PROFILE_SAMPLE_LIMIT = 200;
 async function localMemoryProfile(cfg) {
+    if (cfg.kind === "file")
+        return { ...(0, local_memory_file_js_1.fileMemoryProfile)(cfg), approximate: false };
     const rows = await localMemorySearch(cfg, "*", PROFILE_SAMPLE_LIMIT);
     return { total: rows.length, status: "ok", space: "local", approximate: rows.length >= PROFILE_SAMPLE_LIMIT };
 }

package/dist/resources.js

@@ -50,7 +50,7 @@ async function listVaultResources(cursor) {
     try {
         const offset = decodeCursor(cursor);
         // Over-fetch by 1 so we can tell if there's another page without a count call.
-        const data = await (0, convex_js_1.callConvex)(`/vault/list?limit=${PAGE_SIZE + 1}&offset=${offset}`, "GET", undefined, "list_resources");
+        const data = await (0, convex_js_1.callConvex)(`/vault/list?limit=${PAGE_SIZE + 1}&offset=${offset}`, "GET", undefined, "vault_list");
         const allEntries = data.entries ?? data.results ?? [];
         const hasMore = allEntries.length > PAGE_SIZE;
         const entries = hasMore ? allEntries.slice(0, PAGE_SIZE) : allEntries;
@@ -77,7 +77,7 @@ async function readVaultResource(uri) {
         throw new Error(`Unknown resource URI: ${uri}`);
     }
     const key = decodeURIComponent(uri.slice(URI_PREFIX.length));
-    const data = await (0, convex_js_1.callConvex)(`/vault/entry?key=${encodeURIComponent(key)}`, "GET", undefined, "read_resource");
+    const data = await (0, convex_js_1.callConvex)(`/vault/entry?key=${encodeURIComponent(key)}`, "GET", undefined, "vault_read");
     if (data.error) {
         throw new Error(`Vault entry not found: ${key}`);
     }

package/dist/tools/agents.js

@@ -38,10 +38,10 @@ const LEARNING_SYSTEM_PROMPT = [
     "- Do not output explanations, prefixes, or quotation marks. Just the sentence or NONE.",
 ].join("\n");
 async function extractLearning(goal, priorUpdates, priorLearnings, latest) {
-    // Fast skip when no LLM key is configured. Without a key, callLLM falls
-    // through to the finch-proxy path which may also be unconfigured for
-    // this user - every agent_update would otherwise pay an 8s timeout for
-    // nothing. Cheap, correct, and keeps update latency low.
+    // Fast skip when no LLM key is configured - callLLM() now throws
+    // immediately rather than proxying through Finch (BYOK is required), and
+    // the catch below swallows that into a silent skip. This early return just
+    // avoids building the prompt for a call we already know will fail.
     const hasLLM = !!(process.env.BANKR_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.GROK_API_KEY);
     if (!hasLLM && !process.env.FINCH_SESSION_TOKEN) {
         return null;