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.
The problem, precisely
Two separate failures get lumped together as "my agent has no memory":
- No identity. Every session it re-derives who it is from scratch, so it's blandly helpful and has no consistent voice or judgment.
- No continuity. Facts it learned yesterday — your name, your stack, a decision you made — are gone today.
You fix them with two different layers.
Layer 1: Identity (who it is)
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.
Layer 2: Memory (what it knows) — the 3-layer model
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:
a) Daily notes — raw, append-only
memory/2026-06-15.md. Everything that happened today, written as it happens. Cheap, lossy, never edited. This is working memory.
b) Long-term memory — curated
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.
c) Recall — retrieval at the moment of need
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.
Why files instead of a vector DB
For a single agent, plain Markdown wins on the things that actually matter day to day:
-
You can read and edit its mind in a text editor. Debugging "why did it think X" is
grep. - It's portable. Works with Claude, a local model, a custom loop — anything that can read a file.
- It's diffable. Version it with git and watch the agent's understanding evolve.
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.
The one trick that makes it real
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.
Top comments (1)
The 'daily notes → curated memory' split is exactly the piece most people skip. Everything goes into one file and then nothing survives the trim — or everything survives and nothing is useful.