Every new session with an AI assistant starts with the same ritual: explaining the project again, the decisions already made, the preferences already agreed. In the post about agents outside the lab I listed context that evaporates as one of the four classic gaps. Between one session and the next, the gap becomes the rule: everything evaporates. The solution I use every day on this blog is not a new platform or a vector database: it is a Markdown file versioned in git.
Starting over costs more than it seems
The visible cost is the time spent explaining it again. The invisible cost is worse: a lesson paid for once gets charged again. A real example from here: “an old image after publishing is almost always browser cache, not a defect”. That lesson cost a hunt for a bug that did not exist. Without memory, each new session would have repeated the hunt — with memory, it became a line the assistant reads before starting, and the false defect died there.
The same goes for decisions. A choice discussed and closed on one day reappears as an open question the following week, because the person who asked forgot there was already an answer. Reopening a decision without need is not only waste: it is the risk of deciding differently without noticing.
A Markdown file, versioned with the project
The implementation fits in one sentence: a MEMORIA-PROJETO.md file at the repository root, which the assistant reads in full at the start of each session and returns updated at the end. At publication, it was on the seventh version, with the date and history of each consolidation in the footer.
The file holds four types of content, all short and direct:
- Preferences — how the project owner likes the work to be done;
- Lessons — the bug that was fixed and its cause, the approach that failed, the correction that came from outside;
- Conventions — the flows and patterns that repeat;
- Decisions with a reason — what was chosen and why, so it is not debated again from scratch.
Versioning it with the project changes the nature of the memory. Each update becomes a reviewable diff, like any code change. Memory stops being a black box of the tool and becomes a project artifact that any person (or any assistant) can open, audit, and correct.
The seven-day test decides what gets in
The cutoff rule is one question: will this information still be valid a week from now? If not, it does not belong in the memory. Task progress, a pending item, the next step — all of that ages in days and lives in another file, a state tracker of its own, updated with each advance.
The separation looks like bureaucracy and is the opposite: it is what keeps the file alive. Mixing the two buries the permanent lessons under status that rots. A memory file that becomes a dump for everything stops being read — and memory that is not read is not memory.
A declarative fact, never an order for the future
How each item is written matters more than it seems. Recording “the owner prefers short answers” works; recording “always answer short” breaks. The difference: the imperative order is re-executed in every future session without the context in which it made sense, including on the days when the answer needed to be long.
A declarative fact is context; a recorded order is a blind command. And from that comes the conflict rule: when the instruction of the moment contradicts what is recorded, the instruction of the moment wins — and the conflict is declared out loud, never resolved in silence. Memory guides; the present is in charge.
What never goes into the file
A secret does not go in. A password, a token, an API key: in a versioned file, a recorded secret is a leaked secret. What gets recorded is the convention around it — “the keys live in environment variables” — never the value.
And nothing goes in on its own. The assistant proposes what to record; the owner is the one who approves, and the update diff shows exactly what changed. It is the same principle as the human gate that protects what this blog publishes: the agent lays the proposal on the table, and the decision stays with whoever is accountable for it.
Where the file does not reach
The limits are real, and it is worth stating them. The method requires consolidation discipline: without the ritual of updating at the end of the session, the file freezes and lies. It grows, and it needs periodic pruning to stay readable. And it is context for one project — it does not replace semantic search over a large knowledge base, and it does not solve shared memory for an entire team.
AI platforms tend to offer their own automatic memory, and it helps. The manual file keeps two advantages that none of them deliver: it is inspectable (you can read exactly what the tool “knows” and correct whatever is wrong) and it is portable (the memory belongs to the project, not to the vendor — switching tools does not erase what was learned).
To start today
- Create a
MEMORIA-PROJETO.mdat the project root with three sections: preferences, lessons learned, conventions. - Agree on the ritual with the assistant: read the file at the start of the session and confirm in one line.
- During the work, note what passes the seven-day test — and only that.
- At the end of the session, consolidate: merge with what exists (never duplicate), date it, and increment the version.
- Task progress goes into a separate state file; a secret goes into neither.
A larger model does not solve forgetting between sessions; a simple file does. Project memory is not only reused context — it is the difference between an assistant that works on your project and one that starts over on it every morning.
Sources
- Piece based on firsthand experience: the practice described is in use on this blog, with the project memory file on its seventh version on the publication date (verified on 2026-07-27). No third-party number or claim was cited.
