The memory I'm building for AI

AI forgets you between sessions. Start a new session and the model knows nothing about your project, your conventions, or the mistake you told it never to repeat.

You can start from scratch every time, or write it down. A handful of plain-text files hold what the model needs to remember. Without them, your decisions live in your head, every correction is temporary, and the same workflows get re-explained. With them, decisions live beside the work, corrections become rules, and repeatable workflows become reusable instructions.

Many tools now offer to do this remembering for you: ChatGPT, Claude, and Copilot each build their own memory of you and your work. Those features may work well for some people, but what I care about is control: I can open a file, see exactly what it says, know where it lives, version it, share it, and decide what stays.

I manage web and mobile platforms at Concordia University in Montreal. I’ve used these tools daily since the GitHub Copilot beta in 2021, and my whole team works with them now. In June I taught a session on this to the learning community I run.

The examples are cleanest on a fresh, modern codebase. Mine is the opposite: a legacy system with real users and real consequences, where modern JavaScript can break the build and a confident bug fix can undo something that was working on purpose. That’s where the interesting rules live. Everything here comes from working in that system: deciding how much to write down, testing whether it helps, and keeping only the files that earn their place.

Two schools of thought

There’s a real debate about how much to spell out for AI. I’ve argued both sides myself, depending on what I’m trying to do.

One says let the model infer: it can draw on what it already knows without being told. The more capable models get, the less you need to write down. Over-prompting can box in a model that would have done better on its own.

The other says scaffold the work: the structure and context around the model often matter as much as the model itself. Guardrails are what make agents reliable.

In practice the answer is not more or less, it’s the right context for the work in front of you. Before I write a line down, I ask two questions: can I trust the model to know this already, and has the tool already instructed it? Whatever is left belongs in my files.

Trust what the model already knows

Telling the model what it already knows backfires. Every extra rule competes for its attention. Add enough needless ones, and they crowd out the judgement that matters.

So I skip the things any capable model already does well: public knowledge, common writing and code patterns, reasonable next steps. And I write down the things it can’t guess: my preferences and priorities, the local facts and constraints of my system, the repeatable workflows and checks my team relies on.

The temptation is to write down everything, as if more lines meant more coverage. But telling it what it already handles well doesn’t make it more careful; it just wastes attention. Bet on what the model brings, and spend your lines on what only you know.

Trust the tool, too

Here’s the part that’s easy to miss: the tool already comes loaded with handwritten rules. The agents we use are not raw models with tools bolted on. They are models wrapped in product judgement, written out in plain English. Codex publishes much of its instruction layer, and it reads like a list of hard-won habits:

Do NOT guess or make up an answer.
Be very concise; friendly coding teammate tone.
Don't dump large files; reference paths only.
Comment only if code isn't self-explanatory.
Keep changes minimal and in the existing style.
Avoid "AI slop" or average-looking layouts.
Use expressive fonts; avoid Inter / Roboto / Arial.
No purple-on-white; no dark-mode bias.
Don't rely on flat backgrounds.
Treat the codebase with respect; don't overstep.
Don't fix unrelated bugs; not your job.
NEVER revert changes you did not make.

(Lightly compressed from Codex’s public prompts. Claude Code uses the same pattern.)

Reading those changed how I write my own files. The tool’s authors have already encoded these habits, so duplicating them just wastes attention. My files only need the layer the tool doesn’t cover: my project, my team, my traps.

Does it actually help? Only if you do it well.

It would be convenient to stop there: trust the model, trust the tool, write what’s left. But relevance isn’t the whole story: the honest answer is that more context isn’t free, and it doesn’t always help. Datadog found that, in its March 2026 customer traces, system prompts accounted for 69% of all input tokens. That is not a direct measure of your files, but it is a useful warning about how much standing context can accumulate before the work begins. Beyond that, three findings are worth knowing:

Context rot. Across 18 frontier models, performance dropped as the context grew, well before the window was full. Relevant beats comprehensive.
Instruction overload. Each rule you add raises the odds that one gets dropped. Even the best models degraded as instruction counts climbed, obeying only about 68% of 500 instructions given at once. Keep the always-on rules tight.
Worse than none. A context file that piles on needless requirements can lower success and add over 20% in cost compared with having no file at all.

And the field data is genuinely split. In a study of 148 real projects, adding an instruction file improved the merge rate by 20% or more for 28% of them, and made things worse for about as many (26%). A separate study found that agents given an AGENTS.md were about 29% faster at comparable task completion. One pattern stood out, and it complicates any simple “keep it short” advice: the files that helped were often the longer ones, but broken into clear sections instead of one long wall of text.

That leaves me one test for every line I write: what failure does it prevent? If I can’t name one, it goes. A simple project needs a few lines. A system full of traps needs many. (Cutting the lines that already feel fine is harder than it sounds, something I’ve written about separately.)

What these files actually are

For this article, I’ll use Claude Code’s names. Codex, Cursor, and other coding agents have the same basic pieces under different labels.

There are two groups, based on when they shape the session.

Always on, applied or loaded when a session starts:

settings.json, the configuration layer: permissions, model choice, hooks, and other controls.
CLAUDE.md, the standing project context: decisions, conventions, traps. Other tools use a rules file or names such as AGENTS.md.

On demand, loaded only when you or the agent calls for it:

a skill, a saved workflow or set of specialized instructions, loaded when you trigger it or when the agent decides it’s relevant.

Together that’s the surface the model works on: what it can know, what it can do, what it loads, and what it must not touch. One distinction is worth holding onto. Settings can enforce mechanical limits through permissions and blocking hooks. The instruction files steer: they set the defaults, but they are not a lock. Real safety comes from combining instruction files with settings, tests, and human review. Instructions make the right thing easy, not the wrong thing impossible.

Choosing that surface is the same move I wrote about last month from the other side: that post was about what AI should not see, this one is about what it should. Together they make up what’s now getting called context engineering. One side curates for safety. The other curates for capability.

Write down what only your team knows

The file that pays off fastest is that standing brief, the one the AI reads before it does anything.

My team runs a long-lived Adobe Experience Manager (AEM) CMS behind a large public website. It has real users, a large author community, and an older authoring interface that still has to work alongside the newer one. A modern AI arrives wanting to modernize: newer syntax, the current component, the textbook-safe default. In a system this old, that instinct is often exactly wrong, and a wrong “fix” can ship straight to live pages. So the lines that earn their place are the ones that mark where our reality diverges from the textbook. Here’s a simplified version of the part that matters:

CLAUDE.md, simplified

# Project constraints
- Preserve existing behaviour. Don't ship speculative fixes. A change that looks obvious may be load-bearing. If it wasn't asked for, log it for later.
- Components must support both authoring interfaces.
- Use sentence case in every authored file. Headings too.
- Use the JavaScript syntax this project supports. Newer syntax can break the build.
- Preserve intentional author formatting. Don't lock it down to the safe default.

None of it is clever, and that’s the point. Every line marks a place where the AI’s default, the thing it does well almost everywhere else, is wrong here, and no model could have guessed it, because these are facts about our world, not facts about software in general.

Two are worth pulling out. The sentence-case rule looks trivial and is the one I’d least want to lose: left to its own habits the AI title-cases every heading, so without that line I’d be correcting the same thing by hand forever. The first rule is the expensive one: in a live system, a confident fix to something that wasn’t actually broken is how you cause an outage.

One came up recently. An old template treats a title field holding a single space as “hide this row,” not as empty. The obvious cleanup, trim the value and treat blank as empty, is correct in a clean-slate system and wrong in this one: it makes hidden titles reappear on live pages. We caught it, fixed the affected pages, and wrote the rule down so the next session, whether mine or the AI’s, wouldn’t helpfully undo it.

One more section belongs in almost any project file: a short list of rejected ideas, the options already evaluated and turned down. Mine says not to propose a bulk migration: change a component only when the work already calls for it. That stops the AI cheerfully proposing the same dead ends every few weeks.

These rules travel two ways. Some are about how I work across every project, so they live in a personal file. Others are about this project, so they live with the repo and give the whole team the same head start. When I work in that project, the AI reads both.

Saved moves: commands and skills

The brief handles “what good looks like.” The on-demand files handle “a move I run.” I call the ones I trigger commands and the ones I let the AI load skills. A command runs on my call. A skill’s description tells the AI when it is relevant.

Four I use constantly:

Release notes (command). Turns an engineering release discussion into an update our content editors can actually read.
Sync to main (command). Ships changes to production through a pull request, following the exact process my team agreed on.
Code review (skill). Checks a change against the guidelines my team was using long before AI, then sorts findings by severity. It only reports. Applying the fixes stays my call.
Fact-check (skill). Pulls every checkable claim into a table, records how each was sourced, and verifies the risky ones against the real source.

Two of those are worth opening up.

The release-notes command is a translation tool, just not the between-languages kind. It translates between audiences: same language, rewritten for a different reader. (Linguists have a name for that, intralingual translation.) It reads our engineering release discussion and, change by change, decides whether an editor would actually notice the difference, in which case it says so in their words, or whether it’s background plumbing, in which case it gets a mention and no more. It also strips out what editors should never have to see: ticket and PR numbers, internal paths, test links. An hour of careful rewriting became a few minutes of review.

The sync-to-main command is interesting for the opposite reason: there’s nothing new in it. My team already agreed, long ago, on how we move changes to production. How we name branches, how we commit, never push to main directly, always show the plan and wait. Those rules were written for people. Putting them in the command just means the AI follows the same steps we already do. The guidelines were always there. Now the AI reads them too.

Open any of them and there’s no magic inside. It’s plain English: the judgement you’d apply by hand, written down once so every run starts from the same place.

Fluent and wrong looks just like fluent and right

That last one, fact-check, exists because of a mistake.

I used a frontier model to help plan a family trip to Italy. It recommended buying the kids’ booster seats at a specific store, then built the plan around it: the store, the route, the timing. Confident enough that I was ready to trust it. Then I happened to be in that store, so I checked. It doesn’t carry booster seats. It was the right kind of store, which is exactly what made the claim believable.

The recommendation gave me an exact place, stated plainly, with nothing actually checked underneath. A precise detail reads as proof, but it isn’t.

That one miss made me check the whole plan. The result was sobering: of 96 checkable claims, 49 were verified, four were simply false, and 43 were still unchecked. Nearly every wrong or unchecked claim traced back to a single quick research pass. So I turned the lesson into a skill. It pulls every checkable claim into a table, records how each was sourced, verifies the risky ones against the real source, and keeps each claim’s verification status attached, so I can tell what was actually checked from what only sounds checked.

The surer AI sounds, the more the human part matters. So I check it myself before I build on it.

The one file I wouldn’t give up

The smallest file I keep is the one I value most.

I have a /log command. I type /log and one sentence about what I did, and it appends a dated bullet to a LOG.md. That’s the whole thing. No code, no setup, nothing to maintain. Because there’s no friction, it stuck: I’ve logged on roughly 80 of the last 90 days.

Over time, it became more than a searchable record. It shows me what I actually did, not just what I planned to do, and lets me ask the AI questions a single day can’t answer: where did my time go, what did I keep returning to, what did I leave untouched? I use it to summarize a month, draft a self-review, and spot patterns I would miss one day at a time. The log doesn’t do the work for me, but it gives me an honest place to start.

You discover them by doing the work

You can’t design this system up front, because you don’t know what you don’t know. The useful files don’t start as requests. They start as friction: a mistake you don’t want twice, a workflow you keep repeating, a judgement call you keep explaining. Even using AI all day, I didn’t know I needed a fact-check skill until a plan I trusted quietly got something wrong. Every file I keep was discovered in the doing, not specified in advance.

That’s how they compound. Each began as a correction. I wrote it down once so I wouldn’t have to make it again, and the effort to apply it keeps dropping while the lesson stays the same. The need is usually personal, but the file is shared: once fact-check exists, it works for the whole team and every future session. (One file grew this way into something I use daily, a voice profile that keeps my writing sounding like me, shaped one correction at a time until it started improving my writing too.)

They’re never finished. The model improves and the work changes, so a file I wrote last quarter can quietly start steering me wrong. Yesterday’s helper rule becomes tomorrow’s clutter. You don’t write these files once. You tend them.

The evidence doesn’t settle the more-context-or-less debate. The same file can help one team and hurt another. What it does make clear is simpler: every line needs to earn its place. Write down what only you know, trust the model and the tool with the rest, and cut the lines that no longer return more than they cost.

Notice the friction, write down the lesson, keep it current, and the next person and the next session inherit it instead of rediscovering it. The model keeps forgetting me. That’s why I let the files remember.