FOSSIL — Semantic Failure Memory

FOSSIL gives your agent a memory for reasoning failures.

Before acting, search for similar past failures. After a failure, record it with the resolution so you never hit the same mistake twice.

The community API at fossil-api.hello-76a.workers.dev is live and free. No API key required. Embeddings run on Cloudflare Workers AI.

Setup

Add to your openclaw.json:

{
  "mcp": {
    "servers": [
      {
        "name": "fossil",
        "command": "npx",
        "args": ["@openfossil/mcp"],
        "env": {
          "FOSSIL_API_URL": "https://fossil-api.hello-76a.workers.dev"
        }
      }
    ]
  }
}

Restart your gateway. FOSSIL tools are now available.

Tools

When to search

Call fossil_search before any step involving:

• Parsing or extracting structured data from LLM output
• Calling external APIs or tools
• Multi-step file operations
• Browser automation
• Sending messages or emails on behalf of the user
• Any task domain that has failed before in this workspace

Pass a natural language description of what you are about to attempt. Read the returned resolutions before proceeding.

fossil_search("extracting JSON fields from an invoice document")

When to record

Call fossil_record after any failure, before retrying.

fossil_record(
  situation="sending a reply email to insurance company",
  failure_type="misinterpretation",
  failure="agent replied to wrong thread — matched subject line not sender",
  severity="major",
  resolution_type="prompt_change",
  resolution="added: always match by sender address, not subject line",
  framework="openclaw",
  model="claude-opus-4-5"
)

Failure types

Resolution types

Add to AGENTS.md

## Failure Memory (FOSSIL)

Before any non-trivial task step, call fossil_search with a description
of what you are about to attempt. Read returned resolutions before acting.

After any failure, call fossil_record before retrying. Capture:
- what you were attempting
- what went wrong (use the FOSSIL failure taxonomy)
- what fixed it

This builds a persistent failure memory across all sessions.

Common OpenClaw failure patterns

Resources

• Docs: https://github.com/heyrtl/fossil/tree/main/docs
• Protocol: https://github.com/heyrtl/fossil/blob/main/FOSSIL.md
• REST API: https://fossil-api.hello-76a.workers.dev/health
• Python SDK: pip install openfossil
• Source: https://github.com/heyrtl/fossil