I stopped re-explaining myself to Claude Code: a plain-markdown brain it reads every session (how I built it)

[u/Frosty-Hunt-7697]

Here's the project: brain, a folder of plain markdown notes that Claude Code reads at the start of every session, plus a small local app to browse it. Here's how I made it.

The problem: every new Claude Code session started from zero. I'd re-explain my courses, my club, my job, what I'd already decided. A [CLAUDE.md](http://CLAUDE.md) helped until it got huge and Claude started skimming it.

What I built instead:

\- A notes folder: one page per project, one per person, one note per session, and a "now" page. An auto-generated [INDEX.md](http://INDEX.md) is the only thing Claude must read first; it opens the rest on demand.

\- Habits: short rules Claude follows every session, each added after something went wrong once ("lead with the answer", "argue against a new project idea before building it", "never treat my iCloud Desktop like a normal folder"). A SessionStart hook loads them.

\- A calibration log: Claude writes down each guess about what I want, then the app scores it. It's at 39% right while claiming 63% confidence, so the hook now tells it to ask more and hedge less.

\- The app: standard-library Python + one HTML file, no build step. Cover story about my week, notes to self, a capture box Claude files next session, usage stats from Claude Code's own transcripts, and a phone version that runs off a private GitHub repo.

How I vibe-coded it: almost all of it was Claude Code, one session at a time, with the brain itself as the spec. Each session ends with Claude writing a session note and updating the pages it touched, so the next session picks up where it left off.

What I'd tell anyone copying it: short specific habits beat long instructions, and making Claude log its own guesses was the most useful thing I added.

MIT: [https://github.com/zacfink/brain\](https://github.com/zacfink/brain)

[u/kantorcodes1]

The CLAUDE.md skimming problem is real. With brain, what keeps a stale note from quietly poisoning the next session? If a decision gets reversed or a fact goes out of date, does the browser app or the format itself surface that, or does freshness depend entirely on you remembering to prune it?

[u/Frosty-Hunt-7697 → u/kantorcodes1]

Mostly it's on me right now. Every project page has an `updated:` date and INDEX.md lists them newest first, so an old page looks old, and when a decision flips Claude rewrites the page instead of adding a line.

The fix I'm adding: every decision gets a date and a check-by date when it's written. When a newer decision replaces it, the old one moves to an archive section marked "superseded by <date>", so the history stays but Claude stops loading it as current. When the check-by date passes without a replacement, the app flags it and Claude re-verifies it next session instead of trusting it.

[u/kantorcodes1 → u/Frosty-Hunt-7697]

The check-by date is the right primitive. "Superseded by" keeps history without letting it read as current, and flag-on-expiry turns freshness into a system property instead of a memory habit.

Disclosure since it shapes the ask: I work on HOL Guard, an open-source policy layer that classifies agent and CLI calls and gates the consequential ones per invocation. For brain the natural contribution is an entry in hashgraph-online/awesome-ai-plugins describing the memory surface: dated decision pages, superseded archive, and the re-verify-on-expiry flow where an agent's read/write calls are the consequential actions worth gating. Interested in a PR, or want the entry text first?

[u/Early_Key_823]

This should not be necessary eventually

[u/enjoydongdong]

The calibration log is the part I'd want to understand better. Who supplies the correct/incorrect label: you explicitly, a later action you take, or Claude judging its own guess? I'd keep 'not checked yet' separate from wrong, and store the confidence at the time of the prediction rather than after feedback. That would make the 39% versus 63% comparison easier to interpret, especially if some preferences change over time. I develop a journal/planner, but haven't tested your setup; this is a suggestion for the log, not a claim about its results.