I built a company brain that remembers why decisions were made (on FalkorDB)

You know that moment in every team when someone asks "wait, why do we do it this way?" and the room goes quiet?
Somebody knew once. It was in a Slack thread, or a PR comment, or an ADR nobody reads. And usually the person who
actually knew has already left.

That moment is what my teammate and I built Cairn for, at Graph Hacks (WeMakeDevs × FalkorDB). It's a company
brain that remembers why: you ask it a question, and it answers with the reasons, quoting the exact message where
each reason was said.

Try it here: https://cairn-nine-mu.vercel.app (no sign-up). The code is on
GitHub.

We didn't have a company, so we made one

The first problem was embarrassing: to build a company brain you need a company, and I don't have one lying around
with its Slack history. So we did two things.

We pointed Cairn at FalkorDB's own GitHub org, 13 real repositories of PRs, issues and reviews. That's a nice
test, because the people judging this hackathon know that code, so they can check whether Cairn's answers are right.

Then we generated Orbiton, a fictional 24-person logistics company, as real exports: a Slack export, a Jira CSV,
ADRs, postmortems, runbooks, an org chart. We gave it a story. A staff engineer called Priya pushed for self-managed Kafka
for the event pipeline, then left. Two weeks later the pipeline fell over during a promotion and nobody knew how to
fix it.

Here's what happens when you ask Cairn about it:

Every little number is a real source you can click: the ADR, the Slack thread where the team argued about it, the
Jira ticket where they compared MSK with Kinesis. That's the whole idea. No answer without the receipt.

The part I'm proudest of: "is that still true?"

Decisions go stale. Priya's original reasons for Kafka were "we've run Kafka in production" and "peak is about 3k
events per second". Both stopped being true: she left, and the outage hit 11k events per second. Cairn connects the
outage postmortem back to the original decision and flags it:

My teammate pushed for three everyday workflows on top of this, and they turned out to be the most useful part: a
change-impact report before you touch a service, "has this incident happened before?", and a handoff plan when
someone leaves.

Why a graph, and why FalkorDB

At first I thought of this as a search problem. It isn't. "Why did we do X" is sometimes a search problem, but "who
should I ask about payments?", "what breaks if we change the auth service?" and "what did we lose when Priya left?"
aren't. There's no paragraph anywhere that contains those answers. You have to walk relationships: who reviewed what,
which service depends on which, who decided what and based on which message.

So everything in Cairn is a graph in FalkorDB. People, teams, systems, decisions, the reasons behind them, and the
exact source each reason was quoted from:

Most of that graph is built without any AI. Who authored and reviewed a PR, which files it touched, who replied to
whom, which repos depend on which packages: that's just data, so it can't be hallucinated. The AI only does the part
that needs judgement, finding the decisions and why they were made. And then "why" is literally a walk through the
graph:

MATCH (d:Decision {uid: $decision})-[:BECAUSE]->(p:Premise)-[e:EVIDENCED_BY]->(s:Source)
OPTIONAL MATCH (later:Source)-[c:CHALLENGES]->(p)
RETURN p.text AS reason, e.quote AS quote, s.title AS source, collect(later.title) AS challenged_by

FalkorDB's graph algorithms ended up doing real work too. Betweenness finds the "bridge" people who connect teams.
Label propagation finds who actually works together. Shortest path explains how two things are connected. And every
company lives in its own graph inside one FalkorDB instance, so the real data and our fake company never mix.

When you ask "what did we lose when Priya left?", this is the graph the answer comes from:

Things that broke (a lot)

The AI kept making things up, until we stopped trusting it. The fix wasn't a better prompt. Every reason the
model pulls out has to come with a quote, and the code checks that quote against the original text word for word.
If it doesn't match, the reason is thrown away. At answer time, any citation the model invents gets stripped. That
one rule did more for trust than anything else we tried.

"Is that still true?" was full of false alarms. The first version found lots of "contradictions", and most were
nonsense. A PR that did what a decision said looked like it contradicted the decision. A README we had downloaded
during the hackathon looked "newer" than every decision, because a downloaded file carries the date you fetched it,
not the date it was written. We threw away eight false alarms before it got honest: now a second, different model has
to agree, and a PR that just implements the decision doesn't count. On the real FalkorDB data, that left exactly one
decision worth a human look. I'd rather show one real flag than twenty fake ones.

A whole feature was quietly empty. "Bridge people" returned nothing for ages, and nothing errored. It turned out
graph algorithms follow the direction of edges, and we had stored "works with" one way per pair, so no path could ever
go through a person. Storing it both ways fixed it. That one scared me, because nothing looked broken.

We crashed FalkorDB. A query that returns a property the graph has never stored, next to a count, takes down the
whole server on 6.0.x, and WHERE id(n) > -1 quietly returns nothing. Both turned out to be known issues
(#3150, #2648),
so we worked around them and wrote them down in the README.

Free AI is chaos. We ran the whole thing on free models, and every day something ran out. Gemini's free tier gave
us 20 requests a day. Groq was amazing until it hit its daily limit, and Gemini kept answering "high demand". Every "OpenAI-compatible"
API turned out to be compatible in its own special way (one model cites sources as 【1】 instead of [1]). In the
end Cairn chains five free providers (Groq, Cloudflare Workers AI, NVIDIA, Gemini and OpenRouter), waits politely on
the ones with per-minute limits, and if every model is down it still answers straight from the graph.

Even hosting fought back. Our Railway trial had expired, so our first live link was a tunnel to my laptop. We ended up on a small AWS server using free credits, with the frontend on Vercel.

Did the graph actually matter?

This is the part I wanted to be honest about. My first comparison was Cairn against keyword search plus an LLM, and
Cairn crushed it. That felt too easy, so we built a proper vector-search baseline (the thing most "chat with your
docs" tools use), stored the vectors in FalkorDB too, and wrote 40 questions with answers taken from the raw data.
A second model also graded every answer.

Vector search tied us on "why" questions (14 of 17 each). Makes sense: the answer usually sits in one paragraph,
and good retrieval finds it. But on "who knows this?", "what breaks?" and "what changed?", vector search got zero,
and Cairn got all of them. There's no paragraph to retrieve for those. The answers only exist in the relationships.
Even Cairn's graph routing with no AI at all beat vector search overall. That table is the whole argument for a graph.

It's not perfect. Questions that chain several facts together still trip it up (1 out of 4), and that's what I want to
fix next, along with live Slack and Jira connectors instead of exports.

Full disclosure: I built Cairn with Claude Code as my coding assistant. My teammate and I made the calls on what to
build, the data and the architecture, and it did a lot of the typing.

If you have ever lost the why behind something at work, tell me what you'd ask Cairn first.