Research memory
Every research project needs a CHANGELOG
Record research decisions the way developers record code changes.
Six months later, a reviewer asks why you excluded smokers from the sensitivity analysis. You remember making the decision. You do not remember why. That is not a memory problem. It is a missing changelog.
The problemDevelopers keep one. Researchers almost never do.
Software developers routinely keep a CHANGELOG: a dated, human-readable list of what changed and why, one file, kept next to the work. Researchers almost never do, even though a research project changes continuously. Outcomes shift, criteria tighten, models get replaced, themes get reclassified. Each change was reasoned at the time; the reasoning then evaporates, because it was never anyone's job to write it down.
This is not about version control. Git can tell you what a file looked like in March. It cannot tell you why the primary outcome changed that week. A research changelog records the decisions, so it is scientific memory, kept deliberately.
The formatWhat one entry looks like
Instead of recording code changes, record research decisions. Four lines carry everything a future reader, including future you, will need: what changed, why, on what evidence, and what it touched downstream.
CHANGELOG.md · one dated entry
2026-03-14 Changed: Primary outcome changed from X to Y. Why: Outcome X showed ceiling effects in the pilot. Evidence: Smith et al. 2024 Pilot dataset v0.3 Impact: Power calculation repeated. Protocol updated.
Plain text, dated, newest first, in the project folder. No tool required.
What countsDecisions that belong in the log
Any change a reviewer, a supervisor, or an ethics committee could reasonably ask about belongs here. In practice that includes:
- Changed inclusion or exclusion criteria.
- Replaced a statistical model, or removed a variable.
- Reclassified themes in a qualitative analysis.
- Updated your interpretation of the literature after new reading.
- Accepted a reviewer suggestion, or rejected one, with the reason.
- Switched a software version, or corrected a coding error.
- AI-assisted rewrite of a section, checked line by line by a person.
The last one matters more every month. When AI touches the work, the log is where the human check gets recorded, so the boundary between suggestion and decision stays visible.
We version our code. Version your thinking.
The payoffWhat the log buys you
A changelog is cheap to keep, a few minutes per decision, and it pays out at exactly the moments that otherwise cost days:
- Reviewer questions get answered in minutes, from the entry, with the evidence attached.
- Every important decision can be reconstructed, dated, in order.
- Supervisor meetings start from the log instead of from memory.
- The methods section becomes a summary of entries you already wrote.
- Anyone repeating the work can follow the decisions, not just the endpoints.
- AI collaboration improves, because the reasoning history is there for the model to work from instead of guessing.
One honest limit: a changelog cannot make a decision correct; it keeps the decision open to review, which is what a reviewer is actually asking for.
The pairCurrent state, plus history
A changelog pairs naturally with epistemic notes. A note captures what you know today and why you believe it. A changelog captures how what you know has changed. Together they hold both the current state and the history of your reasoning, and neither needs more than plain files and the habit of writing the reason down while you still have it.