Skip to content
Ayush Gupta

· 4 min read

Claude Code keeps forgetting your decisions. Two files fix it.

By Ayush Gupta, AI Engineer in Bengaluru

TL;DR

  • Long Claude Code sessions get compacted, and compaction can quietly drop decisions you already made. A ledger file fixes that: decisions go in a file, and Claude re-reads it after every compaction.
  • Skills start from zero on every run, so you keep making the same corrections. Give a skill a learnings.md and it writes down what it got wrong and reads it next time.
  • Both are plain Markdown and take about two minutes to set up. A ready-made self-improving skill is free to download below.

Two hours into a session, Claude suggests switching your auth to JWT. You settled on session cookies an hour ago, with a reason. Claude isn't being careless. Its context filled up, it compacted the conversation into a summary, and your decision didn't make the summary.

The same thing happens on a smaller scale with skills. You correct a skill's output, it does better, and next week it makes the exact same mistake, because nothing it learned was written down.

Both problems have the same fix: put the memory in a file, not in the chat.

1. Why long sessions forget

When a session gets close to the context limit, Claude Code compacts it: it replaces the conversation so far with a summary and keeps going. A summary is lossy by design. The broad strokes survive. A one-line decision from an hour ago, with its reason, often doesn't.

What compaction keepsWithout a ledger, a decision lives only in the chat. Compaction summarises the chat, the decision gets dropped, and Claude redoes or contradicts it. With a ledger, the decision is also saved to ledger.md. After compaction Claude re-reads the ledger, so the decision survives.Without a ledgerDecisionsaid once in chatCompactionchat summarisedDecision lostClaude redoes itWith a ledgerDecisionsaved to ledger.mdCompactionchat summarisedDecision keptledger.md re-readThe summary is lossy. The file is not.
Compaction summarises the chat. Anything that only lived in the chat can disappear.

You can't stop compaction from summarising. You can make sure the things that matter don't depend on the summary.

2. Fix 1: the ledger

A ledger is an append-only file of decisions, flows and facts. Claude writes to it as things get settled and reads all of it after every compaction.

  1. Create ledger.md in your project root.
  2. Add this to your CLAUDE.md:
Markdown
## Ledger
- ledger.md is the source of truth for decisions, flows and facts in this project.
- Whenever a major decision, flow decision or fact is settled, append it to ledger.md with the date and time.
- Never edit or delete old entries. If something changes, add a new entry that replaces it and say which one.
- After every compaction, read ledger.md in full before doing anything else.
  1. Entries look like this:
Markdown
## 2026-10-29 16:40
- DECISION: Auth uses session cookies, not JWT. Reason: simpler logout.
- FLOW: Signup goes email, then OTP, then profile.
- FACT: The staging database is read-only.

Three entry types cover almost everything:

Type
DECISION
What goes in it
A choice, and the reason for it
Example
Session cookies, not JWT
Type
FLOW
What goes in it
The order things happen in
Example
Email, then OTP, then profile
Type
FACT
What goes in it
Something true that Claude can't guess
Example
Staging is read-only

Why append-only? If Claude can edit old entries, a bad summary can overwrite a good decision. With append-only, a change is a new entry that says what it replaces, so you can always see what was decided, when, and why it changed.

Keep it short. One line per entry. If the file grows long, ask Claude to write a dated summary entry at the top. Old entries stay below it.

3. Why skills never get better on their own

A skill is a folder with a SKILL.md file of instructions. Every run reads the same instructions, so every run makes the same assumptions. When you fix its output, that fix lives in one chat and is gone when the chat ends.

The fix is a second file the skill owns: learnings.md. The skill reads it before it starts and writes to it when it finishes.

4. Fix 2: a skill that improves itself every run

A skill that improves itselfEach run: read learnings.md and apply every lesson, run the skill, review the result (in review mode, ask the user up to 3 questions first), then append 1 to 3 dated lessons to learnings.md. The next run starts by reading them. When the same lesson shows up across several runs, it is promoted into the SKILL.md instructions.Read learnings.mdapply every lessonRun the skilldo the actual jobReview the resultwith "review on", ask you firstAppend 1 to 3 lessonsdated, to learnings.mdSame lesson, several runs?Promote it into SKILL.mdYesnext run
Every run reads the lessons, does the job, then writes new lessons for next time.
  1. In your skill folder, create learnings.md.
  2. Add this to your SKILL.md:
Markdown
## Before you start
Read learnings.md in this folder and apply every lesson in it.

## After every run
1. Review your result against this skill's goal. Note what worked and what fell short.
2. If the user said "review on", ask them up to 3 short questions about the result and wait for answers.
3. Append 1 to 3 concrete lessons to learnings.md with today's date. In review mode, record only lessons the user approved.
4. If the same lesson shows up across several runs, move it into the instructions above and note the change in learnings.md.
  1. Use it: run the skill as usual. Add "review on" when you want to check what it learns.
  2. Read learnings.md now and then. Delete any lesson that is wrong.

Step 4 of the snippet is the important one. Lessons that keep coming back stop being notes and become part of the skill's instructions, so learnings.md stays short and the skill itself gets better.

5. Download a ready-made self-improving skill

Want to see it working before you change your own skills? This kit has a complete skill that writes git commit messages and learns your style, plus the ledger files ready to drop in.

To install it:

Terminal
unzip claude-code-kit.zip
mkdir -p ~/.claude/skills
cp -r claude-code-kit/commit-message ~/.claude/skills/

Then stage some changes and run /commit-message in Claude Code. Run /commit-message review on to approve each lesson yourself. After a few runs, open ~/.claude/skills/commit-message/learnings.md and you'll see what it picked up, like your preferred subject length or whether you use prefixes.

To turn any of your own skills into a self-improving one, copy the "Before you start" and "After every run" sections into its SKILL.md and add an empty learnings.md next to it.

6. Keep both files honest

  • Read them. Both files are short on purpose. Skim them now and then, the same way you'd review a teammate's notes.
  • Delete wrong lessons. A wrong lesson is worse than none, because the skill applies it every run.
  • Use review mode early. The first few runs of a new skill are where it learns the most. "review on" keeps you in charge of what it learns.
  • No secrets. Both files are plain text in your project or home folder. Write "the API key is in the env", never the key.

Memory in the chat is temporary. Memory in a file lasts. For the rest of my setup, including the other memory files I keep, see how I use Claude Code.

Follow @itsayush__ for the next one.