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.
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.
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.
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.
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.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