I run turva.dev with Claude Code sessions and a memory made of plain files on my disk. Every project sits in the same folder, beside 1 419 122 words of rules and logs. The memory is why a new session starts where the last one stopped. Keeping it current is constant work, and nobody outside can make sense of its language.
What does agent memory give a session?
It gives a new session everything the earlier sessions learned. The session starts with 476 numbered decisions and 662 recorded traps in reach, and its 22 procedures load when a task needs them.
A Claude Code session remembers nothing from yesterday. Without the files every session would be a capable stranger, and I would explain the same things again and watch the same mistakes happen again. With them, a session already knows how I publish and which mistakes were made once before. A mistake becomes an entry in the trap log and usually a rule. A rule that matters becomes a gate that stops the next session before it repeats the mistake, and the gates have written 713 entries into their log.
I get far more out of the same model with this memory than a session could give me without it. Much of that difference is work I can hand over whole, because the checks are written down and many of them run by themselves.
Where does the memory live?
It lives in plain Markdown files in a folder on my machine. There is no memory service or database behind it.
A rules file of 6 545 words is the first thing every session reads. An index of 8 986 words points to 173 memory facts, one fact per file, and 68 closed facts sit in an archive folder. The gates are local as well. A plugin runs them as scripts on my machine before and after a session's tool calls. A private repository on GitHub keeps the history. Every night a local clone of the folder goes to a disk that keeps ten versions, and Proton Drive holds a copy offsite. The model itself runs at Anthropic, so local here means the storage and the rules.
What else lives in the workspace?
Every project I work on lives there too. The code, the memory and the history share one folder, so a session that opens one project has the rules and the history of all of them in reach.
- The website, one Cloudflare Worker whose source file had 13 107 lines when these figures were counted.
- The MCP server, which runs as a second Worker.
- Two open source npm packages, an llms.txt validator and a Markdown parity check.
- A public reference project and a local prototype.
- 81 scripts and 682 task folders.
Counted without git data and installed dependencies, the folder holds 29 508 files. The repositories on GitHub are copies pushed from this folder.
Why does the workspace need constant upkeep?
Every session trusts what it reads. An out of date fact steers the next session as firmly as a correct one does, so the memory is worth only as much as its upkeep, and the upkeep never ends.
Every session that changes something ends with a documentation round, and each kind of information has one home file. A hook stops a session once at the end if it changed work files and wrote nothing down. Closed facts move to the archive so that the index lists only what is still live, and the session log is rotated into an archive file when it grows.
Audits read the whole workspace against the disk. The latest one used 178 agents and produced 220 findings, and one or two further agents tried to refute each finding.
A sync tool once put 1 380 files back to an older state, 52 of them in the memory folder with the index among them. The next session would have read old facts as current ones. A script restored all 1 380 the same evening. Every project in the folder stands on this upkeep, and I count it as part of the work itself.
How big has it grown?
Reading it once would take about 95 hours at 250 words a minute, and that is the written knowledge alone without any code. A script counted these figures on 25 September 2026.
| What was counted | Count |
|---|---|
| Words in the knowledge base, 251 Markdown files | 1 419 122 |
| Numbered decisions with their reasoning | 476 |
| Recorded traps, each a mistake and the rule it left | 662 |
| Recorded measurements | 464 |
| Dated entries in the session log | 1 101 |
| Memory facts in use | 173 |
| Memory facts in the archive | 68 |
| Places where a text cites a decision by its number | 6 384 |
| Different Finnish words for a gate | 108 |
| Entries in the gates' log, warnings included | 713 |
| Files in the workspace, without git data and dependencies | 29 508 |
What does it look like to someone else?
It looks like this sentence from the rules file: "The day-plus-jatko tag is not reserved this way, because renumbering it costs one line while renumbering a Tek touches every file that cites it."
Every log entry carries a tag. A decision is Tek plus a number. Everything else is a date plus jatko, the Finnish word for continuation, so a later entry on the same day is written 2026-09-12 (jatko 5). Several sessions write to the same logs at the same time, and two of them can take the same number. The sentence tells a session which of its numbers it may simply change afterwards and which one it has to reserve before it starts. It is exact. I understand it because I was there when each part of it was decided.
The word for gate is portti, and the knowledge base uses 108 different compound words built on it. A tunnisteportti checks tags and a varausportti checks reservations. A kulttuuriportti catches PowerShell code that a Finnish locale would print with periods where a timestamp needs colons. Three of them have two spellings. The memory index mixes Finnish and English, sometimes inside one line.
Why does it look normal to me?
Every word in it arrived with a reason I remember. A trap entry is written on the day a session makes the mistake, and each new term made sense at the moment it was named. Read one at a time, they never piled up in front of me.
The reader these files are written for is not a person either. It is the next agent session. It reads fast and forgets everything when it ends, so it needs each rule together with the incident behind it. Dense cross references suit that reader, and for a person they are a wall.
It is hard for me too in places. The memory index grew to 79 KB, and the hook that loads it at the start of a session now loads a shorter map of titles, because the whole index had grown too large to put in front of every session. Many things in it I would have to look up before I could explain them to someone else.
What does this have to do with agent readiness?
My site publishes a Markdown version of every page, so that a person and an agent read the same content, and a check compares the two. The workspace behind the site has no version for a person.
Everything in the workspace is shaped for the agent. The site's code is public and a buyer can read every line of it. The workspace is private and far too long for that. It is the case I know best when I write about data that agents act on. Text written by agents for agents keeps growing, and each reasonable entry makes the whole a little harder for a person to check.
What does this not show?
It does not show that any of it is good. A word count says nothing about whether the rules are right, and one incident can leave entries in two or three logs at once, each in the home for its kind.
The gates' log mixes stops with warnings about a write already made, and it does not say whether a stop was right. When new gate versions were replayed against old sessions, some of their new stops were real catches and some were false, and I have no such total for the whole log. I have no measurement of the same work done without the memory, so the difference in the first section is my own judgement. These are the counts of one person's workspace on one day.
Frequently asked
What is agent memory in this workspace?
A folder of Markdown files with one fact in each, and an index file that every Claude Code session is pointed to when it starts. It is how a session that remembers nothing from yesterday knows what was already decided.
Does the memory leave my machine?
The working files stay in a local folder. A private repository on GitHub and a backup on Proton Drive hold copies of them, and a local clone is taken every night. What a session reads from them is sent to the model as part of that session. Local describes where the memory is worked on, and the model runs at Anthropic.
Who wrote the knowledge base?
Almost all of it was written by AI agent sessions as the last step of their own work. I decide what gets recorded and where, and the sessions write it.
Why not delete most of it?
The scripts and gates check new work against the old entries. A shorter log would be easier to read and harder to check, and a decision that was later replaced still records why the first way failed.
Related
- HTML and Markdown can disagree
- Serving Markdown to AI clients
- Define what an agent may do with your data
Originally published at https://turva.dev/blog/local-agent-memory
Top comments (0)