Memory you can't inspect is memory you can't trust

TL;DR

• Every new session your AI starts from zero. It doesn't remember you, your repo, or the thing it got wrong yesterday.
• The fix is not a feature you wait for, it's a file you write. Two, actually: house rules (CLAUDE.md) and a diary (a memory folder).
• The habit that makes it work: end each session with "what should you remember from this? write it down," and save the answer as one small note.
• Wrong memories are worse than none. Keep each note to one fact so you can delete it the day it stops being true.

This piece is from Code Meet AI, my newsletter where i document how i actually use AI to ship real products, receipts included. New guides land there first.

This Tuesday my AI told me a piece of work was shipped. Merged, published, CI green, the whole report. It wasn't. The server was still serving week-old code, and i only caught it because i went and hit the actual endpoint instead of trusting the summary.

Annoying. But here is the part worth stealing. Instead of fixing it and moving on, i had the AI write the lesson down. One small note in the project's memory folder: "merged is not deployed. before you say shipped, curl the live thing and check the release SHA against the merge, twice."

Next morning, new session, zero context, the model has no memory of Tuesday. I run an npm publish and it stops me: the version on the registry didn't match the build we had just tested. It caught the exact same class of mistake, on its own, because Tuesday's note was sitting in a file it reads on startup.

That's the whole trick, and it lives in your repo, not in some feature you're waiting for.

I didn't plan any of this. It grew out of my repos. Each project got a small folder of markdown the AI reads before it writes a line of code, so it never opens the thing cold. That worked well enough that i lifted the whole pattern out of the codebase. My second brain runs on it now, the Obsidian vault too, and every work session i close ends by writing to the same kind of file. The pattern i built for my repos runs my notes.

your AI opens the project blind

You know this if you pair with Claude Code or Cursor daily. The first ten minutes of every session go to re-explaining the same things. The stack, where the API client lives, which files are generated, the conventions you moved to and the pattern you moved off. Good session. Next morning it opens the repo like it has never seen it.

So you type it all out again. Every day.

There was a thread on r/ClaudeAI this week, roughly titled "I often forget how many people are clueless when it comes to Claude (or any AI)." A bit harsh. The gap it points at is real though, and it is not intelligence, it is setup. The people getting compounding value out of these tools are not smarter. They stopped re-briefing the assistant every morning.

A session is a phone call. When it ends, the other side keeps no notes unless somebody writes them down. So write them down.

two kinds of memory, two files

Everything worth keeping splits into two buckets, and they belong in two different places.

House rules. The stuff that is always true: the stack, the conventions, the boundaries, the things it should never touch. One standing file the AI reads at the start of every session. In Claude Code that file is literally CLAUDE.md. Cursor calls it .cursorrules, some tools read AGENTS.md. Same idea everywhere, a one-page briefing that is just always there.

The diary. The stuff it learns as you go: a correction, a decision that closed a debate, a gotcha. "The Android build breaks if you bump reanimated past the pinned version." "We dropped the March API, stop importing it." "Merged is not deployed." Learned facts, they change, so they don't belong in the house rules.

Here is the part people overbuild. On day one the diary is one file. Make a memory.md in the repo root, tell the AI to read it at session start, and add a line whenever something worth keeping shows up. A working memory system, no framework, no folder. The folder version is an upgrade you grow into, and i'll show you mine in a minute. But it starts as one file you could open in any editor.

House rules are written once and edited rarely. The diary grows a note at a time.

Why the split matters: CLAUDE.md you write once and edit rarely, the diary grows every week and any note in it can turn out wrong later. Mix them and your always-on briefing slowly fills with stale facts, the one file you least want rotting. Keep them apart and each stays honest.

The tools already exist and you'll meet them as you go. Claude Code reads CLAUDE.md plus a memory folder automatically, the community ships things like claude-mem that record whole sessions, ChatGPT and Claude both have built-in memory they fill on their own. All fine. The plain file has one quiet advantage though: you can open it, diff it, and delete the wrong bits, and git already keeps the history. Memory you can't inspect is memory you can't trust, and a file you wrote is the most inspectable memory there is.

the capture loop

The memory folder doesn't fill itself. The habit that fills it takes about two minutes.

At the end of a session, ask: "what should you remember from this session? write it down."

That's it. Every correction, every "actually, do it this way," every decision that closed a question becomes a candidate. The AI writes each as its own small note and adds a line to the index.

I'm not the only one on a version of this. One of the most upvoted posts on r/ClaudeAI this month, close to three thousand upvotes, was titled "I end every AI session with two questions." The session-ending ritual is quietly becoming the power move, because it converts a good session, which evaporates the moment you close the tab, into a note, which does not.

One turn of the loop per session. It compounds fast.

Mine runs on two habits. During the day, anything worth keeping gets dumped into an inbox note without stopping to sort it. At the end of a session the AI does the ritual: sorts what it learned, writes the notes, updates the index. Next morning it reads the index and picks up where we left off.

the memory bank: one folder per repo

Once the one-file memory.md clicks, there's a natural upgrade, and it's still just files. I call it a memory bank: one small folder per repo, two files inside.

The first is the context: what this repo is, the stack, the conventions, the boundaries, the things the AI must never touch. You write it once and edit it rarely. The second is the progress: a dated log of where the work actually stands, updated at the end of each session. Drop both in a .memory/ folder in the repo (or docs/, wherever your team already looks) and point the AI at them on startup.

Here's the whole thing:

your-repo/
  .memory/
    context.md    stack, conventions, boundaries, hard no's. written once.
    progress.md   2026-07-09: shipped the auth refactor. open: token-refresh race. next: wire the retry.

Same shape for every repo you touch. The context file barely moves. The progress file is a diary with dates. Open a session, the AI reads both, and it starts from where the code actually is instead of from zero. This is not theory for me: my whole work life runs on these folders, and the "merged is not deployed" catch from the opener came straight out of one.

You don't have to hand-roll it either. Paste this into the AI once, per repo:

I want to give you a memory for this repo. Do two things.

First, create .memory/context.md. Interview me before you write it: ask one question at a time about what this repo is, the stack, the conventions, and the things you must never touch. Then write a one-page briefing you would want to read at the start of every session.

Second, create .memory/progress.md. Start it with today's date and one line: where the work stands right now.

From now on, read both files at the start of every session on this repo.

And at the end of each session, this one:

Before we finish, update .memory/progress.md. Add today's date and 3 to 5 lines: what we did, what we decided, what is still open, and anything you should remember next time. If i corrected you today or gave you a convention, put that in context.md instead. Keep both files short. Cut anything that is no longer true.

That second prompt is the whole engine. It's the capture loop from the last section, turned into a habit you can paste.

one fact per note, so you can fire it

The rule that took me longest to learn: one fact per note.

Not a session summary. Not a changelog. One fact, a couple of lines, with a date. "2026-07: merged is not deployed, verify the live endpoint before reporting shipped." That's a whole note.

The reason is not tidiness. Memories go stale, and a stale memory is worse than no memory, because the model states it with full confidence. The component gets refactored, the workaround you swore by gets fixed upstream, the dependency you pinned moves on. When each fact lives alone, you delete that one note and the rest stays intact. When facts live tangled in a long summary, you can't pull the rotten one without rewriting everything, so nobody does, and the whole thing quietly rots.

My memory folder is a few months old now. Notes get added most days, and deleted too, and that is not the system failing, that is the system working. Tuesday's "merged is not deployed" note earned its place by catching a real mistake inside twenty-four hours. A note that never fires again for months gets cut.

where this breaks

Honest limits, because there are some.

Memory doesn't make the AI right, it makes it consistent. Write down a wrong fact and you now have a machine that repeats your mistake politely, forever. Re-check anything important that came out of memory, especially anything with a date on it.

No secrets in there. Tokens, keys, other people's private data. A memory folder is a plain readable file and it's probably tracked in git, so treat it like one.

And don't over-collect. The goal is not to remember everything, it's to stop re-explaining the same ten things. If your index runs longer than a page, you're hoarding, not remembering.

start on your next branch

Two files. A CLAUDE.md with your stack and conventions. An empty memory folder with an empty index. Then end your next session with "what should you remember from this?" and let it write note one.

That's the whole setup. The assistant you pair with next week already feels different from today's, and the gap only widens from there.

I put together a memory starter pack: the CLAUDE.md template i actually use, the note format, the index file, and the exact session-ending prompt. It goes out through the newsletter first.

Written by Malik at Code Meet AI. This is episode 02 of Using AI, properly. Episode 01 was the art of prompting. New guides land there first.

i'm Malik, i've been a mobile engineer for 9 years, and i run my work and this newsletter on the system these episodes describe. The memory folder is where the second brain and this newsletter both live now. Next up: putting the AI to work on the work around the work.