brain_predict: Predict Software Failures
Before They Reach Production

The recurring failure problem

Most production incidents are not novel. Studies consistently show that 60–80% of production failures are caused by patterns that have occurred before in the same codebase. The problem is not that developers don't know about these patterns — it's that the knowledge lives in Slack threads, post-mortems, and individual memory, not somewhere an AI can see before you push.

cachly solves this by building a Causal Knowledge Graph (CKG) from your entire history — git commits, session lessons, bug fixes, reverts — and then reasoning over it with brain_predict at deploy time.

How brain_predict works

When you call brain_predict, cachly does three things:

1. Pattern matching.It scans your focus area (the files or services you're currently working on) against known failure patterns stored in the CKG — patterns tagged with the causal edges that preceded past incidents.
2. Confidence scoring. Each warning is weighted by how often the pattern has led to failure historically, how recently it occurred, and how similar the current context is to past failure contexts.
3. Actionable output. Rather than generic advice, the output names the specific pattern, the historical incident it maps to, the confidence score, and the remediation that worked last time.

Example output

brain_predict(focus_area="payments/webhook.go")

⚠️  HIGH (0.87) — Retry loop without idempotency key
    Pattern last triggered: 2026-03-14 (commit a3f91c)
    Historical outcome: 500 on 2nd+ delivery attempt
    Remediation: Add X-Idempotency-Key header check before processing
    Reference fix: payments/webhook.go:L144 (commit d7e22a)

⚠️  MEDIUM (0.61) — DB transaction missing rollback on partial write
    Pattern last triggered: 2026-01-08 (commit f88b3d)
    Historical outcome: Silent data corruption on concurrent requests
    Remediation: Wrap in explicit tx.Rollback() deferred call

ℹ️  LOW (0.34) — Env var read outside initialization
    Pattern: Seen 2× in this file, 0 recent incidents

Each warning links back to the original commit and fix — so your AI assistant (or you) can pull up the exact remediation with one more tool call.

What feeds brain_predict

1. Automatic git learning

When you run the cachly setup, it installs a git post-commit hook. Every commit is processed by learn_from_attempts — extracting failure patterns from bug-fix commits, rollbacks, reverts, and commit messages that mention incident keywords. The brain builds a picture of what breaks and why, automatically.

2. brain_from_git: historical bootstrap

On first setup, brain_from_git reads your entire git history — years of commits — and bootstraps the CKG from your past incidents. By the time you run your first brain_predict, cachly already knows about patterns from hundreds of commits.

3. Session lessons

Every lesson your AI assistant captures during a coding session — every bug description, every explained root cause, every "never do X because it causes Y" — is stored in the graph and contributes to future predictions.

Integrating brain_predict into your workflow

Pre-deploy check in Claude Code or Cursor

Simply ask your AI assistant to run a pre-deploy check before pushing:

# In a Claude Code or Cursor session:
"Before I push this PR, run brain_predict on the changed files
and tell me what might break in production."

The AI calls brain_predict, receives the weighted warnings, and presents them to you in plain language with specific remediation steps — no manual tool invocation required.

CI/CD integration via M2M API

For automated pipelines, cachly supports machine-to-machine (M2M) authentication via OAuth2 client credentials. You can call brain_predict directly from CI before a deploy and fail the pipeline on high-confidence warnings:

# In your CI pipeline (GitHub Actions, etc.)
- name: Brain predict check
  run: |
    curl -X GET "$CACHLY_API/predict?focus=$CHANGED_FILES" \
      -H "Authorization: Bearer $CACHLY_M2M_TOKEN" \
      | jq -e '.predictions[] | select(.confidence > 0.80) | .warning'

Session start warnings

If your focus area has known failure patterns, session_startautomatically includes predictive pre-warnings in the opening briefing — so your AI starts every session already aware of the landmines in the code you're about to touch.

The confidence model

Every prediction carries a confidence score from 0 to 1. The score is computed from:

• Historical frequency — how often this pattern has led to an incident
• Recency — more recent incidents carry higher weight (exponential decay)
• Context similarity — semantic similarity between current code context and past failure context
• Beta smoothing — prevents over-fitting on single occurrences; a pattern seen once never scores above 0.5

By default, brain_predict returns warnings at all confidence levels. You can filter with min_confidence to focus on high-signal warnings only — useful in CI where you want zero noise.

Get started

brain_predict is available on all cachly plans, including the free tier. Run setup, let brain_from_git bootstrap from your history, and your first predictions are ready in minutes.

npx @cachly-dev/mcp-server@latest autopilot