DEV Community: Abraham Smith

Git tells you WHAT changed. I built an AI that reconstructs WHY.

Abraham Smith — Fri, 17 Jul 2026 14:16:49 +0000

Every developer has hit this. You open a project months later, stare at a commit that says "Refactor cache layer," and think... why did I do that? The diff shows you what changed, every line. It never tells you why you changed it.

That missing "why" is the thing I've been building Alpheon to fix, a tiny tool that reads your git diff and writes a handoff note. The free version fills in a template you write yourself. But I wanted to answer a harder question: could a model reconstruct the reasoning on its own, from the diff alone, without making things up?

So I stress-tested it. Here's what I learned.

The rule that matters more than the model

Before any of the results, this is the part I care about most. A tool that confidently invents a reason is worse than no tool, because now a wrong "why" is written down as if it were true, and the next person believes it.

So the instructions to the model are strict:

Base every claim on evidence in the diff. Never invent tickets, users, or motivations.
When you're inferring, say "likely" or "appears to." A hedged real reason beats a confident guess.
Reference actual code symbols and values so the reasoning stays grounded.
Don't just restate the commit message. Reason from the code itself.
Everything below lives or dies by whether the model actually respects those rules under pressure.

A real example

Take a commit whose message is just "Prevent stall when cache is full." The diff is small, a deposit path that used to write unconditionally now checks for overflow first. Here's what the tool produced:

"The change prevents the writer from stalling when the cache is full. The original code kept trying to write entries even when they could not be fully accepted, which could trap it in a loop against a full store. The path now measures capacity before and after, computes any overflow, and clears the pending entry regardless, so the writer is freed to continue.

Tried and rejected: The diff replaces an unconditional write with an overflow-aware one, which suggests the earlier straight write was the approach that caused the stall and was dropped."

That's not a paraphrase of the commit message. It read the code, identified the actual failure (the stall loop), and inferred what the old broken approach must have been. That's exactly the reasoning that normally evaporates the moment the session ends.

Stress-testing it honestly

One good example proves nothing, anyone can cherry-pick. So I ran it across a batch of commits from a real, messy codebase: everything from one-line fixes to a single refactor over 40,000 characters long. Terse commit messages, no docs to lean on, the worst-case conditions for recovering intent.

I graded every result by hand. I'm not going to pretend it was flawless, because the whole point is honesty:

Most: accurate. Real reasoning, grounded in the diff, correctly hedged where uncertain.
A few: plausible. On changes where the motivation genuinely wasn't visible in the code (a camera-bounds tweak, for instance), it played safe and mostly described the change. Not wrong, just thin.
Zero: hallucinated. Not one invented reason across the whole batch, including the 40k-character refactor big enough to choke on.

That last line is the one I lose sleep over, and the one that made me trust it. The failure mode of these tools isn't vagueness, it's being confidently wrong. Getting zero fabricated reasons across a brutal test set is the result worth reporting.

Why it runs locally, not on someone else's API

People ask this, so: the model runs on a GPU I control, not a third-party API. Your code never gets shipped off to OpenAI or anyone else. For a tool whose entire job is reading your private diffs, that felt non-negotiable.

Try it on your own forgotten repo

Here's the fun part. Go find the project whose commits stopped making sense to you, and see what the "why" actually was.

The core tool is open source, MIT, single file, zero dependencies:

github.com/BravoAlphaSix/alpheon

If the idea resonates, a star genuinely helps, it's how the next person fighting the "lost why" problem finds it. And if you run it on something and the result surprises you, good or bad, tell me in the comments. I'm building in the open, and the failure cases are the most useful thing you can hand me.

I Kept Losing the "Why" Behind My Code Every Time I Closed an AI Chat, So I Built a Tiny Tool to Save It

Abraham Smith — Thu, 16 Jul 2026 18:47:09 +0000

Last Tuesday I was deep in a session with an AI assistant, rewriting a caching layer that had been quietly leaking memory in production. We tried Redis first. It worked. Then I looked at the actual data volume (about 50MB, tops) and killed the idea, because spinning up a whole service to cache 50MB felt absurd. We landed on sqlite instead. Good call, I still think.

Two days later a teammate opened the branch, saw cache_sqlite.py sitting next to a deleted cache_memory.py, and asked why we weren't just using Redis like the rest of our stack. I didn't have a good answer ready. The reasoning had lived entirely inside a chat session that was long gone by then. I remembered making the decision. I could not reconstruct it convincingly, and "trust me, we talked about it" is not a great answer to give a teammate, or future me, three months from now.

If you've ever lost the reasoning behind your own code, Alpheon is free and open source (MIT). If it resonates, a star on GitHub genuinely helps me know it's worth building further: https://github.com/BravoAlphaSix/alpheon

That's the part most tooling misses with AI-assisted coding. The code survives. The diff survives. A wave of AI memory tools is racing to store more of what the code does, and a few (Selvedge, presence) are starting to chase the why too, which tells me the pain is real. But almost all of them are MCP servers you have to wire into a specific agent, with a database sitting beside your repo. What I wanted was dumber and more portable: the reasoning, and the approaches I tried and threw out, written in plain text I can read, next to the code, no matter which editor or agent produced it. Because that reasoning lives in a chat window, and chat windows end. You switch from Claude Code to Cursor, or you just close the laptop, and it's gone. The facts stay. The judgment behind them evaporates.

This didn't feel like a hard problem, so I built a small thing called Alpheon to fix it for myself, the simplest possible version: one Python file, no server, no database, works off git so it doesn't care what editor or agent you use.

Facts vs. reasoning

Here's the distinction that clicked for me. A fact is "cache.py was modified, cache_sqlite.py was added, cache_memory.py was deleted." Any tool can pull that from a diff. Reasoning is "we needed the cache to survive restarts, tried Redis, decided it was overkill for the data volume, and picked sqlite instead." Your repo doesn't capture that second part unless you write it down, and most people don't, because the reasoning feels obvious in the moment. It stops feeling obvious about a week later.

What Alpheon actually does

It's a CLI that reads your git diff and drafts a Handoff Note: a short markdown block covering what changed, why, what you tried and rejected, and what's left open. You review the draft, edit it if you want, and only then does it get appended to HANDOFF.md, a file that lives in your repo and gets committed like any other file.

For that caching example above, the note it would generate looks like this:

## Handoff Note (2026-07-14 22:41)

### What changed
- modified: cache.py
- added: cache_sqlite.py
- deleted: cache_memory.py

### Why
Needed the cache to survive process restarts, the in-memory dict was losing
all entries on every deploy, causing a cold-cache stampede. Sqlite gives us
persistence with zero infra to run.

### What was tried & rejected
Tried Redis first. Worked, but added a whole service to deploy, monitor, and
pay for just to cache ~50MB of data. Way too heavy for what we actually need.
Dropped it in favor of a single sqlite file that ships with the app.

### What's next / open questions
Need a TTL/eviction policy, right now the sqlite file just grows. Also
should benchmark read latency under load before trusting this in prod.

The "what changed" section comes straight from git: diff stat, changed files, recent commit messages. The "why" and "rejected" sections are where you (or your AI session, prompted at the right moment) actually explain yourself, while the explanation is still fresh. You can also just pass it in directly:

python alpheon.py --note "tried Redis, too heavy for 50MB of data, switched to sqlite"

Six months from now, that note is sitting in HANDOFF.md in plain text, versioned right next to the code it describes. No separate app, no login.

How to try it

There's nothing to install beyond Python and git, both of which you already have.

git clone https://github.com/BravoAlphaSix/alpheon.git
cd your-project
python /path/to/alpheon.py

It prints the draft note first. Nothing touches HANDOFF.md until you type yes. If you want to skip the confirmation for a pre-commit hook or similar, there's a --yes flag, but the default is review-then-approve, on purpose.

What it deliberately doesn't do

No account, no cloud, no vector database, no background syncing. It's one Python file with zero dependencies, and I'd like to keep it that way for as long as possible. The bigger reason for the confirm-before-save step isn't friction for its own sake: an AI-generated "why" that gets silently saved as fact is arguably worse than no note at all, because now you have false confidence sitting in your repo. Making a human confirm it before it's written keeps the tool honest about what it actually knows (the diff) versus what it's guessing (your reasoning).

This is genuinely early. I built it because I kept hitting this wall in my own projects, not because I think handoff notes are a market. It's MIT licensed, and I'd rather hear "this is missing X" than silence.

So: how do you currently keep track of the why behind a decision once the chat session that produced it is gone? Comments in the PR, a wiki nobody updates, just relying on memory? I'd genuinely like to know what's working for people, because "nothing" was what was working for me until a few weeks ago.

Repo's here if you want to poke at it: https://github.com/BravoAlphaSix/alpheon