Vibe Scribe
Living project memory for AI-assisted development.
When software is built with an AI assistant, code tends to arrive faster than understanding does. The system grows quickly, but the reasoning behind it — why it is shaped this way, what was tried and abandoned, how the pieces connect — lives only in the conversation, and conversations end. The developer forgets over time or never truly understands to begin with; the assistant forgets the moment its context resets. What remains is working code that neither party fully understands, which becomes a problem the first time something has to change.
Vibe Scribe treats understanding as something a project records as it is built, rather than something reconstructed afterward. It maintains two plain-text documents in the repository — a journal of what changed and why, and a current map of how the system fits together, including plain-text diagrams of how its parts connect — and keeps them up to date automatically, as a side effect of the work. The assistant writes them and the developer reads them: the understanding the AI holds while building is captured and surfaced back to the person, in plain language and at whatever level of detail suits the reader. Because the documents are ordinary markdown in the project itself, that understanding carries across sessions and survives the context resets that would otherwise wipe the assistant's memory — continuity for both parties, rather than a snapshot that vanishes when the conversation ends.
There is a quieter effect as well. Producing those documents forces the assistant to step back and examine what it has built — to name the parts, trace how they connect, and account for why each decision was made. That act of articulation tends to surface structure and perspective it would not have reached while heads-down in the work, so the record becomes not only a memory but a way of seeing the system anew.
The underlying claim is that the gap between the code that exists and the understanding that exists is a property of AI-assisted development itself, not a matter of skill — a beginner meets it as a wall, an experienced engineer as a steady drag, but it is the same gap. A shared, current record of a system's design gives the developer and the AI a common reference to work from, and keeps that reference from quietly going stale. Vibe Scribe is open-source, works across Claude Code, Codex, and Cursor, and produces nothing but plain markdown that stays in the repository.
Why I built it
I built Vibe Scribe because it felt less like a feature than a missing primitive. Building software by describing it to an AI arrived fast and capable, but with a gap in its foundation: nothing held on to the understanding. Version control, package managers, type systems — the primitives we take for granted — are what everything else rests on, and keeping a project's understanding current as it is built felt like it belonged among them. It was not there, and that absence is what I wanted to close.
It did not arrive fully formed. Months ago, I kept running into bugs that recurred across sessions — each time, the assistant had to rediscover what was broken and work out the fix all over again. So I had the idea for a dev journal: a session-agnostic record of bugs and how they had been fixed, so the same problem would not have to be solved twice. But once it existed, I saw it could be more than a bug log — something the assistant could lean on, in several different ways, to make the whole experience better.
It worked quietly in the background for months. Then, recently, my computer restarted without warning and killed an important session mid-stride. The dev journal, unexpectedly, came to the rescue — it let the assistant and me pick up exactly where we had left off, as though the interruption had never happened. That was the moment I understood what it really was. I began thinking about how to harness it further, paired with a system-overview document I had been toying with separately, and realized that the two together could give vibe coders of every skill level something genuinely new.
What surprised me
What surprised me was how obvious it felt once it existed. At conception it was not obvious at all; in hindsight it is almost embarrassingly so — the kind of idea that makes you wonder why you had not thought of it sooner, or why no one else had. That gap — unobvious going in, inevitable looking back — turned out to be the tell. The most basic things tend to hide in plain sight until someone names them, and then they seem as though they were always there.