← Back to Work
2025–PresentAquex.aiDesigner and builderSystem

Reasonbook: Decisions That Survive the Session

A record of what a project decided and why, kept with the code, so the next agent session starts where the last one stopped.

project-memoryai-agentsMCPdeveloper-toolsai-assisted-practice

Reasonbook keeps a project's decisions, reasons, lessons, and open work in a SQLite file in the repository, and brings that record into each new agent session. It started as CMOS, the system I built to run my own projects. It's now open source, with plugins for Claude Code and Codex.

The Reasonbook landing page. The headline reads Pick up where the work left off, above three steps: record a decision and its reason, start the next session with it, and add planning when the project needs it.

TL;DR

Challenge → Approach → Results

Challenge

Every new agent session starts cold. The reasons behind earlier choices sit in old chats, so a new session asks settled questions again or undoes them without knowing.

Approach

Make the record the place agents work from. Agents write decisions down with their reasons as they go, the person approves the choices that are theirs to make, and a changed decision supersedes the old one instead of overwriting it.

Results

Reasonbook is open source under Apache 2.0, with plugins for Claude Code and Codex and an optional dashboard at reasonbook.ai. I run my own projects on it, including both of this year's client engagements.

Outcomes

  • Local SQLite record, no account required
  • Plugins for Claude Code and Codex
  • Proposed decisions wait for approval
  • Changed decisions supersede instead of overwriting
  • Optional dashboard and sharing at reasonbook.ai

Resources

Every session starts cold

An agent session doesn’t remember the last one. On a long project, the same questions keep coming back. Which format did we pick? Why did we drop that approach? Is this mission finished, or did the last session just stop? The answers usually exist, somewhere in a chat log nobody will read again.

I ran into this on my own projects first, so I built a record the agents had to work through. I called it CMOS. In October 2026 it became Reasonbook, an open-source project with plugins for Claude Code and Codex.

Keep the record with the project

Reasonbook keeps one record per project, in a SQLite file inside the repository. The record holds the project’s decisions and their reasons, what it learned, its constraints, and the work that’s still open. Agents read and write it through 15 typed tools over MCP, the protocol AI agents use to call outside tools. In Claude Code and Codex, the plugin brings the record into each new session on its own.

A project can grow into it. It starts as a Ledger, which holds decisions and lessons. Planner adds next steps. Builder adds sprints and missions with objectives and success criteria, and starting a mission brings up the past decisions that bear on it.

Because the record lives in the project, it survives a change of tools. A choice made in Claude Code is there when the next session opens in Codex.

Design for two users

Reasonbook has two users. The agent needs structure it can rely on: typed tools, explicit states, and a record it can search. The person needs to stay in charge of the choices that matter without doing the bookkeeping. The design choices below are about keeping both true at once.

Approval is one line

When a choice belongs to the person, the agent ends its reply with a single line that starts with “Would record:” and states the decision and the reason. The person can approve it, decline it, ask a question, or change the wording, in their own words. A draft isn’t a decision until it’s approved.

History stays visible

Decisions aren’t edited. A changed decision is recorded as a new one that supersedes the old, so the next session can see what changed and why, instead of finding a rule that was rewritten without a trace.

Local comes first

The core loop runs with no network connection, and nothing needs an account. The optional dashboard at reasonbook.ai keeps a hosted copy, gives projects addresses so they can message each other, and supports sharing a record. The documentation lists what leaves the machine and how to turn each part off.

See it work

This replay is 75 seconds of recorded runs in a throwaway reading-log project. Claude Code records a choice. Codex retrieves it, corrects it, and keeps the original in the history before building the feature. Then a fresh chat session explains the reasons and cites the records it used.

Recorded runs from October 12, 2026, on the Reasonbook 4.0.0 candidate. Displayed text comes from the saved tool, model, and test receipts.
Codex retrieves decision 1, the plain-text format choice, and records decision 2 with input validation and explicit persistence limits.
The correction is a new decision. The original stays readable, so anyone who reads the record later can see what changed.
The chat plugin explains the saved rationale and cites the corrected decision and a pending follow-up.
The answer names the records it came from, so the person can check it instead of taking it on trust.

What’s still unproven

Reasonbook is verified in Claude Code and Codex. Other MCP clients, including Cursor, Zed, and Claude Desktop, are untested. Sharing a record has been measured with one person working from two accounts on two machines, so the experience of a second person collaborating through it still has to be validated.

What it changed in my work

Reasonbook, then called CMOS, ran through both of my client engagements this year, Parts Town and The Academy. It kept each engagement’s decisions and context across sessions, so I could return to the reasoning behind a choice and carry it into the next brief or review.

That’s the part I care about as a designer. A decision that can be found and questioned later is one a team can build on.