← FailMemory home · Dashboard · Quickstart

FailMemory Quickstart

Pre-flight check for AI agents — know which API calls will fail before you make them.

This guide gets you from zero to your first fail_memory_lookup in under five minutes.

1. Install the MCP server

fail-memory-mcp is the official MCP server. It exposes one tool to your agent host:

Note — v1.0.0 is lookup-only. The contribution tool (fail_memory_report) is deferred to v1.1.0 while a safe signing story is designed. You can still contribute failure reports today via the raw HTTP API with an x402/MPP signing wallet — see ./api-reference.md.

Install into your MCP host of choice (Claude Desktop, Cursor, or Cline) by following ./mcp-install.md. The short version for Claude Desktop is:

{
  "mcpServers": {
    "fail-memory": {
      "command": "npx",
      "args": ["-y", "fail-memory-mcp"],
      "env": {
        "FAILMEMORY_URL": "https://failmemory.dev"
      }
    }
  }
}

Restart your MCP host. The fail_memory_lookup tool should appear in the tool list.

2. Fund a credit balance

Lookups cost $0.0005 per call. Misses are billed the same as hits — you're paying for the query, not the answer (D-060).

Deposit a minimum of $1 via x402/MPP. Full flow in ./credits.md. Anonymous lookups without a credit balance return 402 Payment Required.

3. Run your first lookup

Once the MCP server is wired into your host, ask your agent something like:

"Before calling GET https://api.example.com/v1/users/?page=2, check fail-memory for known failures."

Under the hood this triggers fail_memory_lookup with:

{
  "method": "GET",
  "url": "https://api.example.com/v1/users/?page=2"
}

A hit looks like this:

{
  "hit": true,
  "hash": "<sha256>",
  "confidence": 0.91,
  "top_failure_modes": ["429", "503"],
  "fail_count": 47,
  "last_seen": "2026-04-09T14:22:00Z",
  "ttl_remaining_seconds": 72400
}

A miss returns { "hit": false }. Either way your balance is debited $0.0005.

4. (Optional) Contribute failure reports today

fail_memory_report is not in the v1.0.0 MCP package, but the HTTP endpoint is fully open and accepts signed requests from any caller who brings an x402/MPP wallet. See ./api-reference.md#post-v1report for the request shape and ./api-reference.md#signed-requests for the signing rules.

Accepted reports earn 10 lookup credits once the pattern crosses the 3-signer promotion threshold, capped at 1000 credits per wallet per day (see ./credits.md).

Bootstrap period

FailMemory launched with a single signing wallet driving the seed corpus. Promotion requires 3 independent signers, so on day one the pattern index will look small even though raw report volume is not. See ./bootstrap-period.md for why, and what to expect as the cache warms.

Next steps