RunDB

The local-first database for AI agents. Every run, retry, fork, trace and lesson learned, in one SQLite file.

Why RunDB?

Agents fail, retry and branch dozens of times per task, then the next agent starts from zero and makes the same mistake again.

RunDB gives agents a memory they can query:

• 🗂 One file, zero setup. SQLite under the hood. Works offline. No server.
• 🔁 Runs, retries and forks. Every attempt is kept and linked to the one it came from.
• 🔎 Full-text search over every step, error and memory. Hits come back with run_id and span_id.
• 🧠 Memories that outlive failed runs, so the fix is found next time.
• 🩺 what_failed() returns recent errors plus a suggested next step.
• 🔌 MCP server built in, so Claude Code, Cursor and other agents can use it with no glue code.
• 📦 Zero dependencies. Pure Python standard library.

Install

pip install rundb-ai

This installs the rundb Python package and the rundb command. Python 3.10+.

Quickstart

from rundb import connect

db = connect("agent.db")  # created on first use
run = db.start_run("my-repo", goal="make tests pass")

db.log_span(run, "tool", "pytest",
            error="ModuleNotFoundError: No module named 'requests'")
print(db.what_failed(run)["suggested_next_step"])

retry = db.fork_run(run, goal="install deps first")
db.remember("my-repo", "tests.setup",
            "pip install -r requirements.txt before pytest",
            kind="constraint")
db.end_run(retry, "succeeded")

for hit in db.search("ModuleNotFoundError"):
    print(hit["source"], hit["run_id"], hit["snippet"])

Use it from your coding agent (MCP)

Claude Code

claude mcp add rundb -- rundb mcp

Cursor, Windsurf or any MCP client

{
  "mcpServers": {
    "rundb": { "command": "rundb", "args": ["mcp"] }
  }
}

Tools: start_run, log_span, end_run, fork_run, what_failed, remember, recall, search, list_runs, get_run, sql (read-only).

CLI

rundb init                  # create agent.db
rundb runs                  # recent runs
rundb tail -f               # follow the latest run live
rundb search "timeout"      # full-text search
rundb failed my-repo        # errors plus a suggested next step
rundb sql "select * from runs limit 5"

API at a glance

Also available

• TypeScript SDK: npm install rundb. It uses the same file format, so Python and Node agents can share one database.
• Full docs, benchmarks and design notes: github.com/ashishjsharda/rundb

If RunDB saves your agent a retry loop, a ⭐ on GitHub helps others find it.

Apache-2.0 · Built by Ashish Sharda