Braid

Version control for the decisions you make with AI.

Comment

Braid is version control for the decisions you make with an AI. It reads your chat history, pulls out every decision you made, and ties each one to the exact message where you made it. The reasoning that normally scrolls out of reach becomes a graph you can search, question, and check your code against.

[Image: Braid's decision graph. Your reasoning as a commit graph, one column per subject, with a reversed decision struck through and its receipt open.]

Inspiration

A couple of months into a project, we went looking for why we had picked Postgres. We knew we had talked it through. But the decision, and the reasoning behind it, was buried in a wall of old chat messages, and we could not find either one.

That is the gap. When you build with an AI, you make real choices, not only code. You pick a database, decide how auth works, and choose what to ship next. The chat keeps every message and forgets every decision. We built Braid to remember them.

What it does

Braid turns your exported AI chats into version control for your decision-making. A pipeline of agents reads your history and pulls out the decisions inside it. Each one is grounded in the message that made it.

  • Groups decisions onto subject rails. Related choices about the database, auth, or caching line up on one rail, so you see how a subject changed over time instead of scattered messages.
  • Supersedes old calls. When a newer decision replaces an older one, Braid strikes the old one through and keeps both, so the history stays honest.
  • Catches contradictions. Settle on Firestore, then start arguing back toward Postgres a month later, and Braid interrupts as you type with the earlier call and its receipt.
  • Keeps receipts. Every decision links to the exact message behind it. Nothing on the graph is a claim you cannot trace to the source.
  • Asks what only you can answer. Undecided forks, commitments you never followed up on, and reasoning whose premise died all show up as a short morning list.
  • Checks your code against your words. Point it at a GitHub repo and it flags drift, for example you decided Postgres but your code ships MongoDB, with a pre-commit hook that warns you before you commit.
  • Answers from your history only. Ask what you decided about auth and it replies from your real decisions, or tells you it has none instead of making something up.
  • Comes with git commands. Use /log for a decision's history, /blame to see when and why you made it, /revert to undo it, or branch to weigh an alternative.

The part we are proudest of: it learns how you decide

The Collaborative Partner track asks for an agent that adapts to the user's way of thinking. Braid does this literally. It builds a profile of your decision style from what you keep, re-open, commit, and wave off, and then it changes how loudly it speaks.

The update is deterministic. There is no model call in the loop. Each dimension starts at a neutral prior and has a target that your signals point to. The value it shows you is the neutral prior pulled toward that target by how much evidence stands behind it:

$$ \text{value} = \text{neutral} + (\text{target} - \text{neutral}) \times \text{confidence}, \qquad \text{confidence} = \frac{n}{n + K} $$

Here $n$ is how many signals stand behind the dimension and $K$ is a smoothing constant (we use $K = 6$, so 2 signals give about $0.25$ confidence, 6 give $0.5$, and 18 give $0.75$). With no evidence, confidence is $0$ and the value sits at neutral. As signals add up, the value slides toward the target, but confidence stays below $1$, so it can never fully break from its prior on a run of extreme signals. A couple of signals barely move it, and it can never swing on one bad data point. Dismiss a subject enough and Braid goes quiet there. Keep reversing yourself on another and it speaks up sooner. A brand-new project starts neutral and grows into your style over time.

[Image: The "You" page. The decision style Braid has learned, each dimension shown with its evidence and a plain-English reason.]

How we built it

Braid is two pieces. A Python engine does the real work: reading exports, running the agents, storing decisions, and serving an API. A React front end draws the graph, the ledger, the chat, and the morning questions on top of it.

The engine works offline by default. Every model call is stubbed with deterministic output, so almost all of it was written and tested with no cloud spend. One flag flips the same code path to live Gemini on Vertex AI. In production the engine runs on Cloud Run, with Firestore for state.

The one rule we never broke: nothing becomes a decision unless it is grounded in a real message. A Synthesizer drafts each claim with a citation, an Auditor checks it against the source text, and anything it cannot support is dropped and counted. A decision engine that invents decisions would be worse than useless, so most of the work went into making sure it does not.

Layer Technology Role
Reasoning Gemini 3.x Flash (Vertex AI, GenAI SDK) Extract decisions, write cards, answer grounded questions
Classification Gemma Tag each decision's firmness, type, and subject
Embeddings Gemini embeddings Cluster related chats and retrieve for questions
Agent framework GenAI SDK The one seam every agent calls
Hosting Cloud Run The FastAPI engine
State Firestore Decisions, subjects, scans, events, and the learned profile
Frontend React + Vite The decision graph, ledger, morning, and chat
Source access GitHub The public-repo clone for the code-vs-decisions join

[Image: Braid's architecture. The agent pipeline on Vertex AI, with Cloud Run, Firestore, Gemini, Gemma, and GitHub.]

How this maps to the Collaborative Partner track

Track requirement What Braid does
Leads the way and takes notes The night shift extracts and organizes your decisions while you are away, then surfaces only what needs you
Asks clarifying questions The morning list asks about undecided forks, orphaned commitments, and dead premises; the chat interjects when you re-litigate a settled call
Guides the user step-by-step The commit graph, one-tap morning questions, and in-chat interjection show you what is settled and what is still open
Captures feedback Keep, Re-open, dismiss, and resolve; /revert and branches; your answers persist across imports
Constantly adapts to how you think The adaptation loop learns your decision style and tunes when it speaks up, quieter where you wave things off, louder where you keep reversing

It also clears the track's innovation bar. Braid does not just read the graph, it synthesizes and mutates it. It extracts, reconciles, and supersedes decisions, and rewrites them on write-back. And it does this over messy, unstructured input: raw AI chat logs.

[Image: The morning list. The questions only you can answer, each with a one-tap resolve and a receipt into the source conversation.]

Challenges we ran into

Ingest was slow. A cold run took about five minutes for twenty conversations. The bottleneck was a stack of independent model calls running one at a time. We ran them concurrently with a bounded worker pool and kept every database write on the main thread. That cut the wait to roughly a third without changing a single output.

Human answers silently vanished on re-import. We keyed a person's answer by the decision's wording, but the extractor rephrases that wording on every run, so a re-import failed to match and quietly brought back a decision the user had already overruled. The fix was to anchor each answer to the stable decision id, which is derived from content, instead.

Grounding is boring, and it is most of the work. The Auditor that throws away unsupported claims is not a flashy feature, but it is the only reason the rest of the product can be trusted. Cutting that corner would have made a demo that lies.

Accomplishments that we are proud of

Every claim on the graph can be checked at both ends, without trusting the model. Each decision is pinned to an exact message span, and the Synthesizer and Auditor throw away and count anything they cannot support against the source text. Attach a repo and each live decision gets a second anchor, the commit that put it into the code, so a reviewer can confirm the reasoning and the code on their own.

We built and tested the whole engine at zero cloud spend, on the same code path that runs live. Every model call is stubbed with deterministic output by default, and one flag flips the same pipeline to Gemini on Vertex AI. There is no gap between what we developed offline and what ships.

The adaptation loop is deterministic and you can read it. It learns your decision style from what you keep, re-open, commit, and wave off, with no model call in the loop, so it cannot swing on one bad data point. The "You" page shows every dimension's value, the evidence behind it, and a plain reason you can correct. A learned profile you cannot inspect is one nobody should trust. This one you can.

Re-importing your history is safe. Each import is its own namespaced transaction, and your answers survive re-extraction because they are keyed to a content-derived decision id, not the model's wording. Overrule a decision once and it stays overruled, even after the extractor rephrases it on the next run.

It says "I do not have that" instead of guessing. The Auditor drops unsupported claims, ask-anything refuses when your history holds no decision on the topic, and the repo join reports honest drift instead of a false match. A decision engine that makes up decisions would be worse than none, so we built it to fail empty rather than confident and wrong.

What we learned

Grounding is not a feature you add. It is the ground the product stands on. The moment a decision engine invents a single decision, every other decision becomes a maybe. The Auditor that quietly throws away unsupported claims is the least demo-able thing we built, and the only reason the graph is worth trusting. Most of the work went into making the system say "I do not have that" instead of filling the gap.

Making the adaptation deterministic is what made it trustworthy. Our first instinct was to let a model judge how you decide. What earned trust was the opposite: a loop with no model in it, where every move traces to a signal you can count and lands on a reason you can read. "It learns you" is only reassuring if you can see what it learned and fix it.

Identity has to come from content, not wording. The bug that brought back decisions users had already killed taught us a general rule. Anything that must survive reprocessing has to be keyed on stable content, never on a phrasing the model rewrites every run. The same lesson showed up with our tools: give each model the job it is good at, and stop fighting a tool that is telling you no. When the contradiction check kept flaking, we stopped coaxing it and moved that work to a deterministic pass.

What's next for Braid

  1. Team decisions, not just solo. Braid assumes one developer's history today. The next step is shared subject rails across a team: whose call it was, where two people's decisions collide, and one graph per project instead of per person. The branch and fork primitives are already in the engine.
  2. Incremental linking. A nightly run should reprocess only what changed instead of re-reading the whole history. That is the difference between seconds and minutes as your log grows.
  3. More sources. Beyond Claude and ChatGPT: Cursor, Copilot, Windsurf, Aider, and raw git plus PR history, so the graph reflects everywhere you actually decide.
  4. Inline in the pull request and the editor. The drift check and the interjection already run when you commit. Next is posting them as review comments on the PR and firing the interjection in your editor as you type, not only on re-import.
  5. A learned adaptation policy. Promote today's hand-tuned targets into a policy we can test against real outcomes, instead of setting them by hand.

Try it out

The code and a step-by-step spin-up guide are in the repo. Drop in one of the example chat exports and you land on a real decision graph in a couple of minutes.

Built With

Share this project:

Updates