causal_trace:
your AI already knows why this broke

Watch how a stateless AI assistant handles a recurring error. The build fails with "cannot find module'ioredis'" after a dependency change. The AI reasons it out from first principles: checks package.json, suggests reinstalling, proposes three fixes, lands on the right one after a few minutes.

Two weeks later, same error, different branch. The AI does the exact same dance — because to it, this is the first time. The knowledge from last time evaporated at the end of that session. You pay the full debugging cost again. And again.

causal_trace is the first thing cachly runs when an error shows up — before any file is read or grepped. It takes the symptom and asks the Brain a single question: have we caused and fixed this before?

causal_trace(
  problem: "build fails: cannot find module 'ioredis'"
)

// → Brain hit (confidence 0.94):
//   ROOT CAUSE: ioredis is a peerDependency, not installed by
//     'npm ci --ignore-scripts' in the publish workflow
//   FIX: add 'npm install ioredis' before build, or move it to
//     dependencies
//   First seen: 2026-05-12 · confirmed 4× · last 2026-06-01

If the Brain has the answer, your AI applies the known fix directly and skips the rediscovery entirely. If it doesn't, the AI debugs normally — and learns the lesson so the next occurrence is instant.

Plain search over past errors returns lookalikes — anything with "module not found" in it. That's noisy and often wrong. causal_trace is built around cause and effect: it stores what actually triggered a failure and what actually resolved it, linked together.

So when a similar symptom returns, you don't get "here are five vaguely related errors." You get "this specific symptom was caused by X and fixed by Y, with confidence Z, confirmed N times." That's the difference between a search index and a Brain.

Every traced fix carries a confidence score that moves with reality. A fix that's worked four times in a row sits near 0.95. One that stopped working — because the underlying cause changed — erodes as soon as a new outcome contradicts it. cachly's CI integration even confirms fixes automatically: when a previously-failing build goes green after applying a known fix, that lesson's confidence ticks up without anyone touching it.

The first time you hit a bug, causal_trace costs you nothing — the Brain is empty for that symptom, your AI debugs as usual. The compounding value shows up the second, fifth, twentieth time: the class of bugs that used to eat ten minutes each now resolve in seconds, across your whole team, in whatever tool you happen to be using that day.

That's the whole thesis of cachly in one feature: knowledge your team already paid for, captured once and reused forever, instead of re-derived on every blank-slate session.