← FailMemory home · Dashboard · Quickstart

FailMemory Quickstart

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

This guide takes you from a new account to your first authenticated fail_memory_lookup.

1. Get a free API key

Open failmemory.dev/signup and enter your email. No card or email verification is required during Seeding.

Save the API key immediately. It is shown once and cannot be retrieved after you leave or refresh the page.

2. Configure the MCP server

fail-memory-mcp is the official MCP server. It exposes two tools:

fail_memory_lookup — check the shared cache before an external API call.
fail_memory_report — report a failure after an external API call fails.

For Claude Desktop, replace fm_live_your_key_here and add this entry to claude_desktop_config.json:

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

Restart your MCP host. The two FailMemory tools should appear in its tool list. See Install the FailMemory MCP Server for Cursor and Cline instructions.

3. Run your first lookup

Ask your agent:

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

The MCP server calls fail_memory_lookup with:

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

A hit looks like:

{
  "hit": true,
  "hash": "<sha256>",
  "confidence": 0.91,
  "top_failure_modes": ["429", "503"],
  "fail_count": 3,
  "last_seen": "2026-09-01T18:22:00Z",
  "ttl_remaining_seconds": 81234,
  "match_scope": "endpoint",
  "provenance": "organic"
}

provenance: "organic" means at least three independent signers confirmed the failure. provenance: "seeded" means a first-party probe observed it but independent contributors have not corroborated it yet. Treat seeded hits as warnings rather than proof.

A miss returns { "hit": false }.

Authenticated lookups are free and unlimited while FailMemory is in the Seeding stage. No prepaid balance or credit deposit is required.

4. Report failures

After an external call fails, ask your agent to report it:

Report the 429 from GET https://api.example.com/v1/users/?page=2 to FailMemory.

The MCP server calls fail_memory_report with the method, URL, status code, and optional error message. For JSON requests, give both tools the optional payload; the MCP process hashes only its field names and JSON types locally, so body values never leave your machine. It uses the same FAIL_MEMORY_API_KEY from your MCP configuration.

Reports from one key collapse into one signer per pattern. An organic pattern becomes queryable after three independent signers report it. First-party probe results may appear earlier with provenance: "seeded".

Current access