I Built a Second Brain That Writes My PRs For Me

The pull requests on this site's repository — the SEO overhauls, the blog redesign, the services cleanup — have descriptions I mostly didn't write. Claude Code wrote them, and they're specific: they name the middleware that was changed and why, the cache keys that needed busting, the migration that accompanies the schema change. Not because the model is magic, but because by the time a PR gets opened, the system already knows the why. It has been accumulating that knowledge for months, across hundreds of sessions, in plain files on my disk.

Here's the thesis I'll defend: a "second brain" for an AI coding agent is not a note-taking app and not a clever prompt. It is three layers of state that the agent itself maintains — conventions, episodic memory, and job state — and once those exist, well-written PRs, handoffs, and status updates fall out as a byproduct. Most developers are stuck re-explaining their project to a goldfish every morning. The fix is embarrassingly low-tech.

Why pasting diffs into a chatbot never worked

A diff shows what changed. It cannot show why. It doesn't know the auth middleware was refactored because of a flagged vulnerability, or that this PR is part three of a five-part migration. So you type three paragraphs of background to get two paragraphs of description — a net loss, plus the context-switch tax. Prompt templates go stale in days. Generic "memory" features remember that you like TypeScript and nothing that matters.

The bottleneck is structural: the context lives in your head, and every request pays an extraction fee. The whole point of a second brain is that the context lives in the system, updated as a side effect of working, and the extraction fee drops to zero.

The three layers I actually run

This isn't a concept. You can find each layer on my machine right now.

Layer 1: Conventions — CLAUDE.md as a lessons file

The project's CLAUDE.md holds the rules that never change mid-session: which test command to run, which directory patterns to follow, what to verify before committing. But the most valuable section of mine is called Quirks — a running list of lessons this specific codebase has taught, each one added the day it burned me:

• composer test runs PHPStan here, not PHPUnit — a trap for every fresh session until I wrote it down.
• The blog controller caches rendered content per post and locale, and the model observer doesn't bust that key — so a session editing content must Cache::forget explicitly or stare at stale output wondering why its edit "didn't work."
• Guest pages get public cache headers from middleware, so changes look stale to logged-out visitors for a few minutes by design.

Every one of those entries has saved N future sessions from rediscovering the same failure. That's the test for what belongs in this layer: is it a permanent truth about this project that a competent newcomer would trip over?

Layer 2: Episodic memory — an index file plus topic files

This is the layer people mean when they say "second brain," and mine is a directory of markdown files that Claude Code maintains across conversations. The structure matters more than the tooling:

• MEMORY.md is an index, not a journal. One line per project effort, with a status and a link: "Sitemap audit — DONE June: all 8 sitemaps verified, 62 duplicate-tag groups merged." Twenty-some lines cover months of work. An index this size loads into any session for a trivial token cost.
• Topic files hold the depth. Each significant effort gets its own file — the translation pipeline, the SEO recovery, the production cron outage — with what was done, what's still pending, and crucially the gotchas: "the shared host caches Laravel config, run config:cache after any .env edit," "ssh inside a while-read loop eats stdin — use ssh -n." The kind of details that are worthless in the moment you learn them and priceless three months later.

The maintenance ritual is the end-of-session update: the session appends what changed, what was decided, and what's still open. Thirty seconds of instruction from me. The compounding effect is that a brand-new session, with zero conversation history, can answer "where did we leave the newsletter fix?" correctly — because the answer is in a file, not in a context window that died with the last terminal.

The failure mode to respect: memory can lie. Record an approach you explored but abandoned, and future sessions will treat it as a decision. I review memory updates the way I review diffs, because a wrong "fact" in this layer propagates into every future PR description and plan.

Layer 3: Job state — resume manifests for anything longer than one session

This is the layer nobody writes about, and it's the one that makes big work possible. Any task too large for a single session gets a durable, machine-readable manifest in the repo's storage directory. When I rewrote 84 blog posts across seven batches, the whole operation hung off a JSON status file — every post ID marked DONE or PENDING, with a small script to flip the flag as each one landed. Sessions crashed, hit context limits, got interrupted. Didn't matter. The next session read the manifest and continued from reality instead of reconstructing it from a rotting transcript.

The blog redesign runs the same way — a STATUS.md that opens with the two facts a resuming session needs most ("Gate 1 approved · nothing committed, nothing pushed") before the phase table. The pipeline that produced the post you're reading is a task graph on disk with workers writing their status back. Manifests are what let me treat sessions as disposable: context rot stops being an emergency when no session is load-bearing.

Why the PRs come out good

Put the three layers together and watch what happens at PR time. The agent composing the description has: the conventions layer (so it knows what verification ran and can say so), the episodic layer (so it knows this change is part of a larger effort and why the approach was chosen), and the job-state layer (so it knows what's done versus deferred). The description that falls out references the actual middleware, the actual cache behavior, the actual follow-up items — because none of that had to be re-explained. Same model, same diff a cold chatbot would see. The difference is entirely in what the system already knew.

The lesson that took me longest to accept: context quality beats prompt quality, and it isn't close. My PR flow uses a plain instruction. No role-play, no forty-line prompt template. All the engineering went into the memory layers instead, and that's where yours should go too. Elaborate prompting is what people do when their agent has amnesia.

Build yours this week

The order matters — each layer makes the next one cheaper:

1. Day one: conventions. Have Claude Code scan your codebase and draft a CLAUDE.md. Correct it. Add a Quirks section immediately, even if it's empty — the header is a standing invitation to record the next lesson.
2. Every session: the 30-second update. End each work session with "update the project memory with what we did and decided." Consistency is the entire trick. My memory index only works because it's fed as a side effect of working, not as a separate documentation chore I'd skip.
3. First multi-session task: a manifest. Next time a job spans sessions, make the agent write a status file first — items, states, next step — and update it as it works. You'll never run a batch job without one again.
4. Monthly: condense. Memory grows; indexes shouldn't. Roll finished efforts into one-line summaries and archive the detail. An index that takes a full screen to read has stopped being an index.

Two weeks of this, then run the test that convinced me: ask for a PR description and compare it with what you'd have written by hand. If yours is better, your memory layers are thin — feed them. If the agent's is better, welcome to the right side of the gap.

Three adjacent pieces go deeper. My Obsidian variant of this system suits people who want the memory human-browsable; the handoff skill packages the layer-3 pattern; and the six levels of Claude Code memory maps where this architecture sits among the alternatives. The whole thing plugs into my daily Claude Code workflow as its persistence layer.

One more piece of the same philosophy: reusable knowledge shouldn't stay trapped in one person's setup. The public half of my externalized memory is the prompt library on this site — hundreds of the prompts and agent briefs I actually use, structured so you can steal them instead of re-deriving them. Borrowing a working memory beats bootstrapping one from scratch.