rohitg00/agentmemory · error · Error

Unknown tool: ${toolName} (local fallback supports only ${[.

Error message

Unknown tool: ${toolName} (local fallback supports only ${[...IMPLEMENTED_TOOLS].join(", ")}; start an agentmemory server and set AGENTMEMORY_URL to use the full tool set)

What it means

`handleToolCall` first validates the tool name against IMPLEMENTED_TOOLS (the locally implemented subset); if the name is not there it tries the proxy to the full server, and only when the proxy is unavailable or fails does it throw this enriched error. It tells you the tool is not implemented locally and lists the allowed local tools, directing you to start a server and set AGENTMEMORY_URL for the full set.

Source

Thrown at src/mcp/standalone.ts:397

  const handle = await resolveHandle();
  announceMode(handle);

  // Tools the local InMemoryKV fallback doesn't implement: forward straight
  // to the server. Local validation would otherwise raise "Unknown tool"
  // (issue #234).
  if (!IMPLEMENTED_TOOLS.has(toolName)) {
    if (handle.mode === "proxy") {
      try {
        return await handleProxyGeneric(toolName, args, handle);
      } catch (err) {
        process.stderr.write(
          `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}\n`,
        );
        invalidateHandle();
        throw err;
      }
    }
    throw new Error(
      `Unknown tool: ${toolName} (local fallback supports only ${[...IMPLEMENTED_TOOLS].join(", ")}; start an agentmemory server and set AGENTMEMORY_URL to use the full tool set)`,
    );
  }

  const validated = validate(toolName, args);
  if (handle.mode === "proxy") {
    try {
      return await handleProxy(validated, handle);
    } catch (err) {
      process.stderr.write(
        `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}; invalidating handle and falling back to local KV\n`,
      );
      invalidateHandle();
    }
  }
  return handleLocal(validated, kvInstance);
}

View on GitHub (pinned to e04ba88819)

Solutions

1. Start the agentmemory daemon: `npx @agentmemory/agentmemory`, then set `AGENTMEMORY_URL` (e.g. http://localhost:49134) and retry.
2. Verify AGENTMEMORY_URL is reachable: `curl $AGENTMEMORY_URL/agentmemory/health`.
3. Restrict your tool calls to the locally implemented set printed in the error (IMPLEMENTED_TOOLS).
4. Update the standalone server package so IMPLEMENTED_TOOLS covers the tools your client lists.

Example fix

// before
// no daemon; AGENTMEMORY_URL unset or stale
callTool("memory_recall_by_concept", { concept: "auth" });
// after
// terminal 1: npx @agentmemory/agentmemory
// terminal 2:
process.env.AGENTMEMORY_URL = "http://localhost:49134";
callTool("memory_recall_by_concept", { concept: "auth" });

async function ensureServerReady(url = process.env.AGENTMEMORY_URL) {
  if (!url) throw new Error("AGENTMEMORY_URL not set; full tool set unavailable");
  const res = await fetch(`${url}/agentmemory/health`, { signal: AbortSignal.timeout(2000) });
  if (!res.ok) throw new Error(`agentmemory server unhealthy: ${res.status}`);
}

try {
  return await callTool(tool, args);
} catch (e) {
  if (e instanceof Error && e.message.startsWith("Unknown tool:")) {
    await ensureServerReady(); // retry once with the full server
    return await callTool(tool, args);
  }
  throw e;
}

When it happens

Trigger: Calling tools/call with a tool name outside IMPLEMENTED_TOOLS while no agentmemory server is reachable at AGENTMEMORY_URL (proxy call fails or is skipped). The validated name then falls through to the final throw at standalone.ts:397.

Common situations: CI or a fresh checkout where the daemon was never started; AGENTMEMORY_URL pointing at a dead port or wrong host so proxy calls fail; calling newer tools (e.g. audit/crystallize family) against an old standalone bundle running in reduced mode.

Related errors

• Unknown tool: ${v.tool}
• mem::search: token_budget must be a positive integer
• mem::smart-search: AGENTMEMORY_AGENT_SCOPE=isolated is set b
• Unknown tool: ${toolName}
• content is required

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/6f71bee63da60205. Report an issue: GitHub.