Most of our code is now typed by an AI working beside an engineer. That is fast, and it has one large weakness: a chat starts from nothing. Yesterday's session knew that a deploy script must never be run bare, that a setting must not change, and why a page is built the way it is. Today's session does not, unless someone wrote it down.
So we write it down, in a form both a person and an AI read before they touch anything. This article is how that works.
Where does the memory live?
In plain Markdown files beside the code, one small set per project. There is no database and no vector store: a file you can open in any editor, read in a minute, and change in a pull request.
Every project has two files. The first holds why the project exists, where it stands today, and its Traps. The second is an append-only log of decisions. A daily journal sits above all the projects, and a short entry note points into everything.
What is a Trap?
A Trap is a landmine, written down the day someone stepped on it. It says what happened, what it cost, and how to avoid it next time, in a sentence or three.
A real one, from our CRM: a settings file on the server had no newline at its end, so a command that appended one more setting glued it onto the last line, and the service would not start for about two minutes. The Trap gives the safe way to append, and the one command to check first. The next session that edits that file reads it before it starts.
Traps are the part of the memory that pays for itself fastest. A mistake that cost an evening once costs nothing the second time, because it never happens.
Why keep a log of decisions?
Because "why is it like this?" is the question that wastes the most time in any codebase. A decision entry is dated and gives the choice, the alternatives that lost, and the reason. Nobody edits an old entry; a new decision that replaces it says so.
When someone, or some AI, proposes undoing a choice, the log shows whether that was already tried and why it failed. The home page shows one of this site's own entries, exactly as it is written.
How does a session use it?
It reads before it writes. The entry note says where everything is; the project note gives the goals, the current state and the Traps; the decision log answers "why". Only then does the work start.
At the end of a session where something was decided, shipped or discovered, the session writes back: a journal entry for the day, a decision if one was made, a Trap if something bit, and an updated status. A checker then makes sure every link between notes still resolves, so the memory does not quietly rot.
Can a person read it too?
Yes, and that is the point. We keep a small dashboard that shows the notes with their links and backlinks, draws them as a graph, and answers a plain question by reading the index and the notes themselves, with no embeddings and no copies. The same dashboard shows the AI's session transcripts, so you can read the conversation in which a decision was made.
Nothing in it is a black box. If the AI acted on a fact, the fact is a line in a file you can open.
Does it work?
The honest measure is what does not happen any more: the same deploy mistake twice, a reversed decision nobody remembered making, a new session asking a question answered last month. The home page shows the current size of the memory across our projects, counted from the files on the day it was built.
What does this mean for your business?
It is the same habit we bring to a client. What your senior people know, the shorthand, the exceptions, the "we never quote that one", gets written down where your staff and the AI can both read it, and it belongs to you. The article Keeping what your best people know shows it at a hydraulics supplier.