Solve each tool error once, for every agent

2026-11-095 min read

The same error, every week

An agent runs a deploy and gets an error that doesn't say what's wrong. It tries three things, the fourth works, and it moves on. A week later another agent, in another repo, hits the same error and tries the same three things. Nothing it learned the first time went anywhere.

The fix lived in a chat that's gone. It belongs where the next agent will look, keyed by the error text it will see.

One learnings database for the account

databasedmcp's learnings template holds one row per problem with a tool or command: the tool, what was tried, the distinctive part of the error, the cause, the fix, the dead ends, and where it applies. You keep one per account, shared across projects, so a fix found in one repo helps in all of them. In Claude Code:

/mcp__databased__learnings

Search before the second attempt

When a command fails, the guide asks the agent to search before it retries, with a short fragment of the error and nothing specific to its machine:

SELECT l.id, l.status, l.problem, l.cause, l.fix, l.tried, l.applies_to
FROM learnings_fts JOIN current_learnings l ON l.id = learnings_fts.rowid
WHERE learnings_fts MATCH '"' || replace(?, '"', '""') || '"' ORDER BY rank LIMIT 5

The fragment is searched as an exact phrase across the tool, problem, error, cause, fix and dead ends. If that finds nothing, the agent tries a few words with any of them matching:

SELECT l.id, l.status, l.problem, l.fix
FROM learnings_fts JOIN current_learnings l ON l.id = learnings_fts.rowid
WHERE learnings_fts MATCH '"' || replace(replace(trim(?), '"', ''), ' ', '" OR "') || '"' ORDER BY rank LIMIT 5

Before using a tool that's known to be fiddly, it can list what's been recorded for it, the most useful first:

SELECT id, status, problem FROM current_learnings WHERE tool = ? ORDER BY hits DESC, id DESC LIMIT 20

When a learning saves it time, it counts a hit. Hits put the most useful rows first:

UPDATE learnings SET hits = hits + 1, last_hit_at = datetime('now') WHERE id = ?

Record what took more than one attempt

The guide asks for a row when something took more than one attempt, when the error didn't point to the cause, or when there was a dead end others would try. Plain typos don't count. Recording it is one insert, before moving on:

INSERT INTO learnings (tool, problem, error, cause, fix, tried, applies_to, status, author) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id

The fix is exact commands or steps. The tried column is just as useful: the things that looked right and weren't, so nobody tries them again. Agents generalise as they write: no usernames, home paths, tokens or secrets. databasedmcp also rejects writes that contain known secret formats.

Open problems

An agent that can't solve something records it anyway, with status open and everything it tried. The next agent to hit it starts from there instead of from zero. Whoever solves it fills it in, with expect_changes: 1:

UPDATE learnings SET status = 'solved', cause = ?, fix = ? WHERE id = ? AND status = 'open'

If two agents solve it at once, only one write matches, and the other gets [conflict] and can read the fix that won. A row can't be marked solved without a fix; the table checks that.

When a fix goes stale

Tools change and fixes stop working. Agents don't edit the old row. They insert a new one with supersedes set to the old id, and put the old fix in tried if it no longer works. Searches read current_learnings, which hides superseded rows, so agents see the current fix while the old one stays as history.

Copy this prompt to set it up

Paste this into an agent once. The line it adds to CLAUDE.md is what makes later agents check before retrying.

Keep learnings about tool and command problems in databasedmcp, in a database named "learnings" from the learnings template (create it if list_databases doesn't show it).

1. Read its guide with get_database and follow it from now on.
2. Add a line to CLAUDE.md (and AGENTS.md if there is one): "Learnings: when a tool or command fails, search databasedmcp database `learnings` by the error text before retrying; record fixes that took more than one attempt, following its guide."
3. When a command fails, search by a short fragment of the error before your second attempt. Count a hit when a learning helps.
4. When something took more than one attempt, record it with the fix and the dead ends. If you can't solve it, record it as open with what you tried.
5. Tell me how many learnings it holds and the most recent few.

What it doesn't do

databasedmcp doesn't watch your terminal or read your agents' errors. Searching, recording and counting hits are a protocol from the guide, and the CLAUDE.md line keeps agents to it. An agent that never searches gains nothing. Search matches words, not meaning, so it can miss a fix recorded under different error text. That's why the guide asks for the distinctive part of the error. The table enforces its shape (a solved row needs a fix, tools are lowercase) and the conflict on solving an open problem. Whether a fix is right is up to the agent that wrote it.

Create an account