Failure Memory

Failure Memory gives AI coding agents a shared, local memory of verified failures. It helps agents avoid repeating a mistake without treating every correction, preference, or newly supplied requirement as a failure.

It can:

• distinguish real failures from requirement changes, clarifications, and preferences;

• record the root cause, recommended repair location, and durable prevention lesson;

• reuse an exact existing lesson instead of creating duplicates;

• surface related lessons for review without silently merging or deleting history;

• recall up to three relevant lessons before similar work;

• retain recall and outcome history for metrics and future improvement.

Supported agents

All integrations use the same store for the current OS user. Installing Failure Memory in another supported agent does not create another memory database.

Related MCP server: ContextEngine

Install

Failure Memory is a native executable. It does not require Python, Node.js, or a local database server.

1. Install the runtime

macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/CongBao/failure-memory/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/CongBao/failure-memory/main/scripts/install.ps1 | iex

The installer downloads the correct release for your platform, verifies its checksum, and installs the failure-memory executable in your local binary directory.

2. Install the plugin

Codex:

codex plugin marketplace add CongBao/failure-memory
codex plugin add failure-memory@failure-memory

Claude Code:

claude plugin marketplace add CongBao/failure-memory
claude plugin install failure-memory@failure-memory

GitHub Copilot CLI:

copilot plugin install CongBao/failure-memory

Cursor:

/add-plugin CongBao/failure-memory

For another agent, copy skills/record-agent-failure and skills/recall-failure-lessons into its skills directory. Applications that accept an MCP server command can register:

failure-memory mcp --stdio

Restart an agent that was already open, then verify the installation:

failure-memory install status
failure-memory doctor

Use

Use Failure Memory through natural prompts. The skills perform one bounded operation and do not interrupt ordinary work when no useful memory action is needed.

Recall lessons before risky or recurring work

Before changing this migration workflow, recall relevant failure lessons.

A recall needs a short task description plus something concrete, such as the component, expected invariant, suspected cause, or prevention action. It returns at most three lessons. Treat recalled lessons as cautions to validate against the current task, not as instructions that override current requirements.

Record a real failure

The migration changed persisted data without the required compatibility check. Find the
root cause and remember a lesson that prevents this from recurring.

Failure Memory first checks whether the feedback describes a genuine failure:

1. Did an expectation or invariant exist before the outcome?

2. Is there an inspectable mismatch and meaningful impact or recurrence risk?

3. Is there an evidenced, controllable cause?

4. Can a concrete prevention and verification step be stated?

If the evidence is insufficient, the case is stored only as a qualification attempt and does not become a lesson. This makes false-positive rates measurable without polluting future recall.

If feedback mixes an old failure with a new requirement, only the old-invariant mismatch can enter memory. The new requirement remains normal work.

Match against existing lessons

Before adding a lesson, Failure Memory checks the existing store:

• an exact match reuses the existing lesson;

• a related case remains separate and may produce a generalization proposal for review;

• history is not silently merged or deleted.

Run a recall from the command line

printf '%s' '{"text":"schema migration","component":"migration workflow"}' \
  | failure-memory recall

The command reads one JSON object from standard input and returns one JSON object. Run failure-memory without arguments to see all available commands.

Search

Failure Memory supports:

• exact lookup;

• SQLite FTS5 full-text search, including CJK bigrams;

• local sqlite-vec vector search;

• hybrid ranking across exact, full-text, and vector results.

Exact and full-text recall work immediately. A deterministic local vector index supports hybrid ranking without a model download. To enable model-based multilingual semantic search, install the pinned model once and rebuild the derived index:

failure-memory adapters install
failure-memory index build

Models are never downloaded during a record or recall operation.

Maintenance

Useful commands:

failure-memory doctor
failure-memory metrics
failure-memory store-status
failure-memory cluster propose
failure-memory feedback recall
failure-memory feedback repair

Clustering and feedback commands append proposals or observations. They do not delete, silently merge, or automatically promote lessons.

Local data and privacy

The append-only event store, retrieval index, optional model, and installation receipt live in one owner-private directory:

• macOS: ~/Library/Application Support/failure-memory

• Linux: ${XDG_DATA_HOME:-~/.local/share}/failure-memory

• Windows: %LOCALAPPDATA%\FailureMemory

Back up the event-store database; derived indexes can be rebuilt. Submit only compact evidence. Do not store raw prompts, full transcripts, credentials, or unnecessary personal information.

Development

See CONTRIBUTING.md. Report security issues according to SECURITY.md.

License

MIT