How we gave our agents a memory with lesson and log files

We gave our AI agents a shared memory with two Markdown files. lessons.md records what to do differently next time. log.md records what happened. We keep one pair at the company, space, and person levels, then promote recurring lessons into the instructions every agent reads.

At Palette, most of the company works out of one shared folder of Markdown files with AI agents. Claude, Gemini, Codex and Mistral, depending on the person and the task. The agents work on the same files we do.

That setup gave each agent plenty of context. Every space has a README explaining what lives there, and an AGENTS.md telling agents how to behave. What it lacked was a shared record of the things we taught them along the way.

You correct an agent, it fixes the thing, and the correction stays in that chat. The next session starts without it. So does the next person's session, and so does whichever agent they use. We needed the correction to live somewhere every agent could read.

How do you stop corrections from dying in chat?

Write the correction into the workspace instead of repeating it in the next prompt. Anthropic's Claude Code memory guidance recommends keeping recurring instructions in CLAUDE.md and lets Claude maintain its own local memory. We wanted the same habit to work across every agent we use and to remain visible to the whole team.

The model does not need to carry the correction between sessions when the workspace does. A plain file also makes the lesson available to someone else's session, on another agent, weeks later.

Why do we use two files at three levels?

One file could hold both instructions and history, but it would quickly become hard to trust. We split the jobs and place each pair at the narrowest level that benefits.

The pair sits at three levels:

• The company root. Anything true for the whole company.
• Each top-level space. gtm/, product/, engineering/, ops/, accounts/, content/, and so on.
• Each person's folder under people/. How to work with that specific person.

Work below a space inherits the relevant files above it. Dropping a memory file into every nested folder would scatter lessons into places nobody looks and force an agent to read too many files before starting.

The two files answer different questions:

• lessons.md records what to do differently next time. Entries are dated, concrete lines such as: "Do not infer edit dates from Git sync history."
• log.md records what happened. Decisions and notable changes preserve the reasoning behind the current state.

Together with the existing control files, the workspace has four clear jobs:

When a correction is durable, the agent proposes one dated line at the narrowest useful level. A lesson about a person goes in their folder. A product lesson goes in product/. A company-wide lesson goes at the root. Genuine decisions get a Decision: prefix in the log, so we can search the whole company for the forks we chose.

The agents read the relevant root, space, and person lessons before they start. The same idea works with the CLAUDE.md files Palette Desktop loads and the README files that explain a workspace.

How do we keep the memory from rotting?

Periodic cleanup matters more than capturing every possible detail. Earlier versions failed because the agent dumped everything into one file. It grew without bound, filled with half-true notes, and became easy for people and agents to ignore.

We built a command called /reflect for the cleanup pass. It reads the lesson and log files in the chosen scope, finds lessons that recur or have stabilized, and proposes promoting them into the guides agents load every time. It also flags stale, duplicated, or misplaced entries.

A human approves every promotion. /reflect is suggest-only: it cannot rewrite AGENTS.md, delete history from log.md, or edit a folder outside its permissions. We run it by hand today. A weekly schedule is a possible next step, not something we have built.

Promotion lets the memory compound without letting the inbox grow forever. A lesson begins as a scratch correction. Only the ones that prove useful become permanent rules.

Why use files instead of a database?

Plain text makes the memory inspectable and portable. Anyone can open a file and read exactly what the workspace is telling an agent. They can edit a line, remove it, or move it to a better scope. Nothing is hidden inside an embedding or a vendor-specific memory store.

The same files also work across Claude, Gemini, Codex and Mistral. They live beside the work, survive a session ending, and remain available to the whole team.

For teams that want the broader folder structure, the Company OS template provides a starting point that can be installed in Palette Desktop.

What is working so far?

The system is still young. The files will rot if we stop doing the cleanup, and we do not yet know how well the convention holds up after months of use.

The useful part is how little machinery it needs. Plain text, a clear place for each kind of memory, and a human approval step. Silja starts with us in August. Instead of handing her a wiki nobody reads, we can give her a workspace that has been learning how we work while we worked.

If your agents keep making the same mistake, start with one file. Write the correction down instead of retyping it, then have the agent read it at the start of the next session. Add the cleanup step when the file becomes long enough to need one.