Why plain text beats a black box for agent memory
And the cases where it doesn't. The aim is to help you pick the right tool, not to win an argument.
The problem isn't remembering, it's trusting what was remembered
Give an agent a memory and it will, sooner or later, remember something wrong: a decision that was reversed, a preference that was only true last month, a "fact" it inferred and never confirmed. With a conventional memory layer you usually find out by watching the agent behave strangely, then trying to work out which stored fragment is responsible.
The things you want when that happens are the same things you want for code: to see the current state, to see what changed and when, to fix one thing without disturbing the rest, and to undo. Source control already solves all four, for text.
What you get from plain text
- Inspection without tooling. A memory is a node in a file. You can read it in the editor you already have, search it with
grep, and open the whole graph in a viewer. - Review. At the end of a week you can read
git difffor the memory folder and see what the agent decided was worth keeping. Wrong things are visible before they cause trouble. - Surgical correction. Fixing a belief is editing a line or calling
delete_memory. Nothing needs re-embedding by hand. - History and blame. Which session introduced this belief?
git blameknows. - Relationships as structure. Memories link to each other with typed edges (
[about],[supersedes],[relates_to]). "Supersedes" is how a corrected belief replaces an old one without erasing the audit trail. - Ownership. It's a folder. It lives in your repo, your backups and your jurisdiction. No account needed to read your own memory.
What it costs
- Scale. Attelium is built for the memory of one person or one project: thousands of nodes, not millions. Search is a local index over the files and is fast at that size. If you need to retrieve across a huge corpus, use a database built for that.
- Semantic recall is optional. By default search is lexical (bag-of-words) with zero dependencies. Real semantic matching needs the optional
[semantic]extra and a small local model. Lexical search can miss a memory worded very differently from the query. - Agents still have to write good notes. A transparent memory full of poor notes is still poor memory. Attelium nudges (server instructions, an optional Stop hook) but the quality depends on the agent and your prompts.
- Merge conflicts are possible if several people's agents write to the same graph on different branches. They're ordinary text conflicts, which you can resolve, but they exist.
- It's alpha. The tools and file layout work and are tested, and may still change.
When you should pick something else
- You need retrieval across millions of documents. Use a vector database or search engine.
- You never want a human to look at the memory, and don't care to audit it.
- Your memory contains data that must not sit in a git repo at all. (You can keep the graph outside git, but then you lose the main advantage.)
The sweet spot
A coding agent working on a project over weeks. A personal assistant that should know your preferences. A research agent accumulating notes. In each, the memory is small enough to hold in your head and valuable enough that you want to know what's in it.