I have Claude Code produce a session summary in blog-post format after almost every real work session, because nothing about how Claude Code stores history on its own is actually built for reading or searching later. The model itself starts every session with a blank slate. Claude Code covers for that by saving a raw transcript to disk, so claude --resume <id> can hand the old conversation back in as context, but that only helps if the transcript still exists and you remember which session ID it lives under, and by default it’s gone after 30 days anyway. A dated, searchable blog entry doesn’t have either problem. Fine on a project you touch daily. A real problem on the dozen side projects you touch once a quarter, which is exactly where this pays off.
Key Takeaways#
- Every meaningful session ends with a structured write-up saved to a dedicated Hugo site, not left buried in a chat transcript I’ll never scroll back through
- Each entry covers what got built, the key decisions and the non-obvious gotchas, and what state things were left in when I stopped
- It’s a static site with built-in search, so “did we ever figure out X” is a search away instead of a memory I have to trust
- This is different from the model’s own persistent memory (standing preferences, who I am, how I like to work). The session log is project narrative: what happened and why
- It costs a couple minutes at the end of a session and pays for itself the first time you open a project you haven’t touched in three months
- The raw chat isn’t a permanent record either. Claude Code deletes local session transcripts after 30 days by default, quietly, at startup. If it matters, save it somewhere durable yourself
The problem it solves#
I run a lot of small projects. Some get worked on for a week straight, then sit untouched for months. When I come back, the code tells me what the system does, but not why it’s built that way. Why did I reject the obvious approach. What was the actual bug behind that weird workaround. What was I in the middle of when I stopped.
None of that lives in the code. Some of it used to live in my head, until it didn’t anymore.
The fix: a searchable log, not a pile of chat transcripts#
I have a skill, session-summary, that Claude Code runs at the end of a productive session (or whenever I ask for it). It writes a dated entry into a separate Hugo site I use as nothing but an engineering log: one project’s worth of history, one post at a time, all of it searchable.
Each entry follows the same shape, because consistency is what makes it skimmable later:
- What was built, a short overview, two to four sentences, no padding
- One section per distinct piece of work, covering the actual problem, the decision that got made and why, what shipped, and what got rejected along the way (and why that got rejected too, since “we tried X, it didn’t work” is exactly the thing you’ll forget and re-attempt otherwise)
- Key technical decisions and gotchas, the highest-value section. API quirks, version pins, footguns, the “this looks wrong but it’s wrong on purpose because of Y” notes that never make it into a commit message
- Current state, meaning what’s committed, what’s tested, what’s deployed versus still local-only, what’s explicitly left for next time
That last section matters more than it sounds like it should. Coming back to a project cold, the first question isn’t “how does this work,” it’s “where did I leave off,” and that’s the one thing git history alone won’t tell you.
Why not just read the old chat, or just read the code#
Both of those are real options and both fall short in the same way: they make you reconstruct the why by re-deriving it, every single time. Reading raw chat history means wading through the actual conversation, false starts included, to extract the two decisions that mattered. Reading the code tells you what exists but not what got tried and abandoned, which means you’re at real risk of re-discovering the same dead end a future version of you already found.
There’s also a harder problem: the raw chat history might not even be there anymore. Claude Code auto-deletes local session transcripts after 30 days by default, and that cleanup runs quietly at startup. Nothing tells you it happened. If you want to keep something past that window, you have to actually save it somewhere durable yourself, which is exactly what this skill does on the way out of a session instead of leaving it to chance.
And even when the history is still there, re-deriving the why from it isn’t free. Pointing an agent at a sprawling old transcript or a pile of large source files and asking it to re-read everything cold burns real tokens, and it’s not a one-time cost. A 150k-token file re-read at the start of every session you come back to that project adds up fast. A short, structured summary is a fraction of that, every time.
A structured summary is the distilled version: someone (an AI, in this case, prompted to write it like an engineer leaving notes for their own future self) already did the extraction work. I just have to read it.
How it fits the rest of the workflow#
This is the same instinct behind everything else I do to keep AI-assisted development disciplined: don’t trust the tool to just remember things correctly, build an explicit, external record instead. The same way I ask Claude to write me a README or an architecture doc for a project I’m about to walk away from, I ask it to write me the session log on the way out the door. Different artifact, same reason: future-me is going to show up with zero context, and the artifact is what gets him back up to speed instead of starting from scratch.
This is the kind of process discipline I bring to client engagements too. If your team’s institutional knowledge lives entirely in Slack threads and one person’s head, that’s a risk worth talking about before it becomes an incident. Reach out.