Scar

Failure memory for AI agents. Remember what went wrong so you don't repeat it.

Scar mines your AI agent's session transcripts for failures, stores them in a local SQLite database, and surfaces a briefing at the start of every new session. Your agent walks into work already aware of what's been broken before.

Two surfaces:

• Hooks (recommended): SessionStart briefing + Stop-time transcript mining. Passive, automatic, zero agent action required.
• MCP server (optional): Active tools (scar_log, scar_recall, scar_context) for agents that want to query failure history mid-session.

In practice, the briefing is where most of the value comes from. The MCP layer is for power users who want their agent to actively consult past failures before risky operations.

Install (slim, recommended)

npm install -g @bambushu/scar
scar init --claude-code

That sets up:

• SQLite database at ~/.cognitive/cognitive.db
• SessionStart hook in ~/.claude/settings.json that runs the briefing
• Stop hook that mines the just-finished transcript for failures

You'll see a briefing at the top of every new Claude Code session listing unresolved failure patterns from prior work.

Install (full, with MCP)

If you want active lookup tools too:

npm install -g @bambushu/scar
scar init --claude-code --with-mcp

This additionally registers the MCP server so Claude Code exposes scar_log, scar_recall, scar_context, etc. as callable tools. Useful if you want your agent to consult Scar before deploys, DB mutations, or other risky ops.

CLI

# Manually log a failure
scar log -r my-project -l typescript -t bash \
  -e "TypeError: Cannot read properties of undefined" \
  --tried "Ran test suite" \
  --wrong "Null access in parser.ts"

# Query past failures
scar recall -r my-project -l typescript

# View patterns
scar stats
scar stats --stale

# Remove noise
scar forget <scar-id>

# Export for debugging
scar export

MCP Tools (optional install)

| Tool | Purpose | |------|---------| | scar_log | Record a failure with context | | scar_update | Update a scar - record what worked, change resolution | | scar_recall | Find relevant past failures | | scar_forget | Remove a scar | | scar_stats | Aggregate failure patterns | | scar_context | Lightweight count of relevant scars (cheap pre-check) |

How It Works

1. Stop hook fires when a Claude Code session ends, mines the transcript JSONL for Bash/Edit/Write/Read failures, writes them to SQLite
2. SessionStart hook fires on the next session, reads recent unresolved patterns, prints a briefing into the agent's context
3. Auto-deduplicates identical errors within 5-minute windows
4. (Optional, MCP) Agent calls scar_context before risky ops or scar_recall when investigating a class of error

Storage

SQLite database at ~/.cognitive/cognitive.db. Part of a shared cognitive toolkit foundation - future tools (self-trust calibration, intuition/focus) share the same database.

License

MIT