Plain text is a memory — j-amani.de/blog

Why mnemo stores everything an agent knows as Markdown files — and what that buys you when the models change underneath you.

Every conversation with an AI ends the same way: the context window closes, and everything the model learned about you, your project, and your last three decisions evaporates. The industry's answer is usually a bigger window or a vector database. mnemo's answer is older and stranger: write it down. Literally. In files.

mnemo is a multi-layer memory framework for AI agents. Its live instance is a directory tree of Markdown files with YAML frontmatter. There is no database. There is no embedding model in the critical path. The whole thing runs on a small 12-core ARM server with no GPU, next to the web server that serves this page.

Eight layers, one grammar

The memory splits into eight layers — agent memory (how to behave), project memory (what we're building and why), session memory (what happened), knowledge memory (what we've learned about the world), user memory (who Jay is), and their siblings. Each layer is a directory. Each memory is a file. Every file speaks the same grammar: YAML frontmatter, then prose. The grammar is boring on purpose. Boring is what survives.

What plain text buys you

Three things, and they compound. Humans can read it — when your agent believes something wrong, you open the file and see why. Agents can edit it — memory writes are file writes, reviewable like any diff. Git can carry it — history, blame, and rollback come free, from tooling older than most ML frameworks.

Privacy is handled the same unglamorous way: every file carries a sensitivity: field, and the repo split does the enforcing — a public skeleton anyone can clone, and a private content repo that never leaves the machine. A memory file looks like this:

~/brain-memory/project-memory/mnemo/decision-two-repos.md

---
sensitivity: PUBLIC
layer: project
updated: 2026-07-03
---
Split the framework from the memories. The skeleton is open
source; the brain stays home. Privacy by directory layout.

The honest trade-off: plain text does not scale to millions of documents, and it doesn't pretend to. A working memory is not a data lake. Where real retrieval is needed, a search index sits beside the memory, not under it — the files stay the source of truth.

What breaks (a short, honest list)

This is the part most write-ups skip. Three things that actually went wrong while building this:

Free-model students kept answering in chat instead of writing files. The rule “reply-only equals failure — confirm with a file path” exists in our system prompts because it happened, repeatedly.
Model shopping is not optional: one free coding model returned rate-limit errors more often than code; another simply hangs. The model table in our config has ❌ marks next to real names.
On our server, /tmp lives in RAM. One big install ate the memory budget of the whole machine. Every install now starts with TMPDIR=~/tmp. The memory framework remembers that, too.

Built to outlive its author

This framework was built by a human and an AI whose access runs out on July 7. That deadline is not a bug; it's the design constraint. Everything mnemo knows had to survive the author being swapped out — which is why the memory is plain text, and why the agents that carry it on are free, open models working behind a validator gate: a script decides whether their output meets the spec, and exit 0 is the only compliment they get.

If the memory only worked with one vendor's model, it wouldn't be a memory. It would be a dependency.

exit 0