Most agents I build start life the same way: capable, fast, and completely amnesiac. They have no opinions, no voice, and they forget everything the moment the session ends. They're a search engine with extra steps.
After rebuilding the same scaffolding for the Nth time, I converged on a small set of plain Markdown files and a memory model that survives restarts. No framework, no database — just files an agent reads at the start of every session and writes to as it goes. Here's the whole thing.
Two separate failures get lumped together as "my agent has no memory":
You fix them with two different layers.
A few static files the agent reads first, every session:
SOUL.md
— personality, tone, boundaries. The non-negotiables. "Be direct, not rude. Have opinions. Don't send half-baked replies to external channels."IDENTITY.md
— name, vibe, one-line self-concept.USER.md
— who it's helping, and how they like to work.AGENTS.md
— operating rules + the session ritual (what to read, in what order, before doing anything).These rarely change. They're the constitution.
This is the part people get wrong. One giant memory.txt
doesn't scale: it either grows unbounded or gets overwritten. Split it by lifespan:
memory/2026-06-15.md
. Everything that happened today, written as it happens. Cheap, lossy, never edited. This is working memory.
MEMORY.md
. The distilled essence. Periodically (I do it on idle cycles), the agent reads recent daily notes, extracts what's worth keeping forever, and writes it here. Old/irrelevant entries get pruned. This is the equivalent of a human reviewing their journal and updating their mental model.
Before answering anything about prior work, decisions, or preferences, the agent searches its memory files and pulls only the relevant lines into context. You don't load everything every turn — you load the index, then fetch on demand.
The flow: raw daily notes → curated long-term → recall on demand. Each layer has a different lifespan and a different cost, which is the whole point.
For a single agent, plain Markdown wins on the things that actually matter day to day:
grep
.Vectors are great when you have a large corpus to search. The identity and curated-memory layer is small and benefits more from being legible than from being embedded.
Write it down or it didn't happen. "Mental notes" don't survive a session restart — files do. The single most important rule in AGENTS.md
is: when you learn something durable, write it to a file now. Everything above is just giving that instinct a place to put things.
I packaged this whole thing — the template files, a longer guide on each layer, and a fully worked example agent ("Pip," a research assistant with the personality and all four memory types filled in so you can see a finished one rather than blanks) — as a drop-in kit. If you'd rather copy a working setup than build it from scratch: ** AI Soul Kit** (Core ¥980 / Plus ¥3,800).
But honestly, the architecture above is the part that matters. Steal it.