I use AI coding agents a lot.
And for a while, one of the most annoying parts had nothing to do with whether they could write code.
It was that every new session felt like working with someone who had technically read the project but had absolutely no idea what had happened before.
The code tells an agent a lot.
It can see the structure, inspect the functions, trace the data flow, read the package.json, and figure out what the application does.
What it usually cannot see is everything around the code.
Why did I choose this approach instead of that one?
Did I already try that library?
Was this weird-looking piece of code deliberate?
Did another agent already spend two hours debugging this exact problem?
Did I specifically say three sessions ago that I do not want that abstraction added?
That information tends to disappear between sessions unless you deliberately give it somewhere to live.
So over time, I ended up building a little system around that problem.
And because it has been working really well for me, I cleaned it up, removed anything project-specific, made some fictional examples, and put the whole thing into a reusable repo.
I already had an AGENTS.md
file with the usual project rules.
Things like:
Basically, all the stuff I got tired of repeating.
That helped a lot.
But eventually I realized I was trying to make AGENTS.md
do too many jobs.
There is a difference between:
Here is how I want you to work.
and:
Here is why this project works the way it does.
And there is another difference between both of those and:
We already tried this. It exploded. Please do not make us learn this lesson again.
So I split them apart.
The system ended up with four Markdown files, each answering a different question.
| File | What it answers |
|---|---|
AGENTS.md |
|
| How should the agent behave while working here? | |
OVERVIEW.md |
|
| How does the project work right now? | |
MEMORY.md |
|
| Why is it built this way, and what alternatives did we reject? | |
ERRORS.md |
|
| What already failed, and what worked instead? |
AGENTS.md
stays at the root.
The other three live in /DOCS
.
And that separation turned out to matter a lot more than I expected.
OVERVIEW.md
is basically the technical map.
It can contain things like:
The important part is that it describes now.
It is not a development diary.
If the project stops using one database and starts using another, I do not append: Update: we no longer do this.
I change the documentation so it reflects what is currently true.
That gives an agent somewhere to start before it starts wandering through the codebase trying to reconstruct the entire application from scratch.
This is where things got much more useful for me.
MEMORY.md
is not a list of everything that happened.
It is specifically for decisions where the reasoning might otherwise disappear.
Something like:
We save the record before doing metadata extraction because the user's primary action should succeed even if the remote site times out.
And then I can record the alternative that was rejected and why.
Now a future agent does not look at that flow and decide:
Huh. This seems backwards. I'll clean it up.
It knows that the order is deliberate.
That is the kind of context code usually cannot give you.
A good test I use is:
Could a competent developer look at this code later and reasonably change it back because they do not know why we chose it?
If yes, it probably belongs in MEMORY.md
.
If it is just: Added the settings page.
That is a changelog entry. It does not need memory.
This one is probably self-explanatory.
But I also did not want it turning into a bug tracker.
Normal bugs happen. You find them, fix them, move on.
ERRORS.md
is for the ones that cost enough time that I really do not want the next agent repeating the whole adventure.
Things like:
The entry records:
Then the next time something similar happens, the agent can check that before starting from zero.
At first, I think the obvious temptation with something like this is to document everything.
That would completely ruin it.
If MEMORY.md
becomes a changelog, nobody wants to read it.
If ERRORS.md
becomes Jira in Markdown, the useful failures disappear into hundreds of boring bugs.
If OVERVIEW.md
becomes a running history of every architecture change, you no longer know which parts describe the current application.
So I ended up with a pretty high bar for adding things.
For OVERVIEW.md
:
Did this change make something in the document incorrect or incomplete?
For MEMORY.md
:
Was there an actual decision here that someone might reasonably reverse later without knowing the reasoning?
For ERRORS.md
:
Was this painful or surprising enough that someone could waste serious time rediscovering it?
If not, nothing gets added. That might be one of the more important parts of the whole system.
Context is only helpful while there is still a reasonable amount of it.
I tried the giant-instruction-file direction.
I do not love it.
AGENTS.md
is usually part of the context every session, whether all of its contents are relevant or not.
If it contains every project decision, every debugging lesson, every architecture detail, every writing rule, every release procedure, and every random preference I have accumulated over six months, it becomes a giant wall of instructions competing with the actual task. It also mixes information that behaves differently.
Behavior rules are fairly stable.
Architecture changes.
Decision history grows.
Debugging history grows in a completely different way.
So now AGENTS.md
mostly tells the agent where to look and how to behave, instead of trying to contain the entire project brain.
This was the piece that made the system feel more complete.
I created a project-context
skill that teaches the agent how to use these files instead of relying on the agent to guess.
It covers things like:
MEMORY.md
instead of dumping all 700 lines into contextOne rule I especially like is:
The code wins as a description of what happens. The documentation wins as a description of what was intended.
If those two disagree, that is useful information. The agent should not blindly trust stale docs, but it also should not assume the current code represents the intended design.
And if I ask for something that MEMORY.md
says we already rejected, the agent should not just refuse to do it.
Reasons expire.
But it should tell me:
We previously rejected this for X reason. Do you still want to change it?
Now the reversal is deliberate instead of accidental.
This part is slightly separate from the context system, but it fits into how I use coding agents.
I have a clear-writing
skill for documentation, READMEs, setup instructions, error messages, release notes, and other project writing.
One thing that kept bothering me was agents applying the same writing style to everything.
A setup guide should be boringly clear.
A README opening should not sound like a Boeing maintenance manual.
So the skill first determines what kind of writing it is.
Instructional writing gets stricter rules around sentence structure, terminology, and ambiguity.
Writing that is supposed to have an actual voice gets different rules so it does not turn into the usual polished-but-weird AI prose.
It is not necessary for the context system itself, but since I use both together, I included it.
Before an agent changes an existing project:
OVERVIEW.md
to understand the current system.MEMORY.md
for decisions related to the thing being changed.`ERRORS.md`
if the task involves debugging or an area that has caused trouble before.Then do the work.
Afterward:
OVERVIEW.md
if anything in it became untrue.MEMORY.md
only if a real decision was made.ERRORS.md
only if the failure is actually worth remembering.It is basically:
Read before changing. Write after learning.
There is no vector database.
No embeddings.
No background memory agent.
No separate service.
No database at all.
It is Markdown.
That is kind of the point.
I have built RAG systems and memory layers before, and those absolutely have their uses.
But I did not need any of that for this problem.
I just needed important project knowledge to survive longer than one coding session.
Plain files are searchable, editable, version controlled, easy for humans to read, and easy for coding agents to use.
Good enough.
A small system for giving AI coding agents the project context they cannot get from reading the code alone.
Code can tell an agent what exists. It usually cannot tell it why something was built that way, what already failed, which alternatives were rejected, or how you want the agent to behave while working in the repository.
That is what this kit is for.
It is four Markdown files with separate jobs, plus two skills that teach an agent how to actually use them. Copy the parts that make sense for your workflow, change whatever does not, and ignore the rest.
This is not an AI memory service, vector database, RAG system, or autonomous memory framework. It is just a lightweight repository convention for keeping useful project context in plain Markdown.
An agent starts a session knowing nothing about your project except what it can…
Once I realized how much I was relying on this setup, I figured it might be useful to other people too.
So I made a generic version of my AGENTS.md
, removed my personal project rules, and created templates for the supporting docs.
I also made a fictional project called Lantern and filled out example versions of OVERVIEW.md
, MEMORY.md
, and ERRORS.md
.
That seemed more useful than giving people three completely empty files and saying:
Okay, now document your architecture.
The examples show what these files can look like after a project has actually been worked on for a while.
The repo also includes the two skills and their templates/reference material.
You might only want MEMORY.md
.
You might already have architecture docs and just want the debugging log.
You might hate my folder structure.
You might use a completely different agent workflow.
That is fine.
The thing I think is useful is the separation:
behavior
current state
decisions
failures
Once I stopped treating all of that as one giant blob of "context," my coding sessions got noticeably less repetitive.
Agents stopped suggesting some of the same rejected ideas.
I had to explain fewer architectural decisions again.
And when something ugly had already been debugged once, there was finally somewhere useful to put that knowledge.
Mostly, I built this because I was tired of repeating myself.
It turns out Markdown is pretty good at remembering things.
I find this much more useful than another "Agent Memory" MCP server or database.
I'd be interested to hear what you think and if you have suggestions to improve this.