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:

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#

ToolWhen to usefossil_searchBefore any non-trivial step — find similar past failuresfossil_recordAfter any failure — capture what went wrong and what fixed itfossil_getRetrieve a specific fossil by IDfossil_listBrowse your recent fossil archive

---

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.

text

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

---

When to record#

Call fossil_record after any failure, before retrying.

text

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#

TypeWhen to usemisinterpretationMisread the task or user intenthallucinated_toolCalled a tool that doesn't exist or wrong signatureformat_failureOutput didn't match expected schema or formatcontext_lossForgot earlier context in a multi-step runinfinite_loopGot stuck in a reasoning or tool-call cyclepremature_terminationDeclared done when the task was incompletescope_creepDid more than asked, touched things it shouldn'tambiguity_paralysisCouldn't proceed due to underspecified inputtool_misuseRight tool, wrong usage or argumentsadversarial_inputExternal input hijacked agent behaviorcompounding_errorSmall error amplified across multiple steps

---

Resolution types#

TypeWhen to useprompt_changeModified the system or user prompttool_fixFixed the tool definition or implementationretryRetrying without changes succeededhuman_overrideHuman intervened directlycontext_injectionInjected missing context into the agent windowschema_correctionFixed the output schema or parserstep_decompositionBroke the failing step into smaller stepsinput_sanitizationCleaned or validated input before processing

---

Add to AGENTS.md#

markdown

## 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#

SituationFailure typeSent message to wrong contactmisinterpretationBrowser clicked wrong elementtool_misuseEmail reply used wrong tonemisinterpretationScheduled task ran at wrong timeformat_failureStuck waiting for a responseinfinite_loopActed on wrong file or accountscope_creepAdversarial email hijacked behavioradversarial_inputStopped mid-task without finishingpremature_termination

---

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