Need help? Read this
Read this first. This is a real, working setup — and it's both easy and not. The ideas are simple; making them robust takes care and iteration. So treat this as a guide, not an invitation to use me as customer service.
Straight with you: I'd genuinely rather not rebuild for hire what I've already built — I want to make new things. That's the whole reason this guide exists, so you can do it yourself. The $750/hour isn't some fancy consulting pitch; my time is just extremely limited. So if you'd still rather I set it up with you one-on-one over Zoom — insist, and I'll happily take the money. Otherwise it's all here. Go build.
How agent memory works.
If you want a fleet of always-on agents that don't wake up as strangers every morning, memory is the whole game. The model that holds up isn't a pipeline that processes your data into an opaque store — it's a library of files you can read. It's built from a few small primitives that stack: an instruction hierarchy that's always on, a fact directory recalled by relevance, and one boundary that keeps the shared parts honest. Each is simple; stacked, they're a memory that survives.
This is the companion to Build Your Own Agent Fleet — the part that survives restarts, context compaction, and reboots.
Facts go in the databases. Standing behavior goes in a file that reloads every session. Everything diffable, version-controllable, and yours.
Files, not a pipeline.
The durable design treats memory as two cooperating ideas, both just text on disk:
- Instruction memory — files loaded into context at the start of every session. Always-on, hierarchical, the house rules.
- Recalled memory — a directory of small fact files the model reads and writes on demand, surfaced by relevance during a session.
There's no opaque database you can't inspect, no embedding blob you can't open. You can read any of it, edit it by hand, commit it to git, and move it between machines. That legibility is the design — memory you can trust because you can see it.
The standing-instructions hierarchy.
Instruction memory cascades from broad to specific, and it composes — every layer in scope is concatenated into context at launch, with the more-specific files refining the ones above them.
# each layer in scope is concatenated at session start user memory ~/.../CLAUDE.md — all your projects ▼ project memory ./CLAUDE.md — checked into the repo (the team) ▼ local / subtree ./sub/dir/CLAUDE.md — loaded when relevant
Two mechanics make it powerful. Imports: any file can pull in another with @path/to/file.md, several hops deep, so you compose memory instead of writing one monster file. Always-on: these sit in context from the first token, which makes them perfect for standing rules and conventions — and costly if you let them bloat. Keep the always-on layer lean; push everything else to recall.
The fact directory.
The second system is a model-managed folder of small, single-fact files with structured frontmatter, plus an index that's loaded each session. The model reads the index, decides which facts are relevant, pulls them in — and writes new ones as it learns. Recall by relevance, not by always-on bulk.
--- name: feedback-pace description: process one chunk at a time; avoid scope creep metadata: type: feedback --- Don't rush. Finish one chunk before starting the next. # body holds the fact, with [[links]] to related memories
An index file — one line per fact — is the only part loaded every session. It's cheap to scan; the model expands only what's relevant and leaves the rest on disk. Pointers in context, full content on demand. That's how you keep a thousand facts available without paying for a thousand facts every turn.
Propose, then own.
Here's the failure mode that turns shared memory into a junk drawer: agents writing straight into it. When every agent can commit a durable "fact" directly, a guessed inference — "this person is based in Russia" — lands next to verified ones and gets trusted forever. The cost shows up weeks later, when something downstream is built on a guess.
The fix is a strong boundary. Agents don't write durable memory; they propose to a staging layer. A single consolidation pass — run by one owner, the orchestrator — is what promotes a proposal into durable memory: deduping, attaching scope, and reconciling it against what's already known. One writer to the canonical store, many proposers. That's the difference between memory that compounds and memory that rots.
- Propose — any agent stages a candidate fact, with its source.
- Consolidate — one owner reviews, merges duplicates, sets scope, resolves conflicts.
- Own — only promoted facts become durable and recallable.
Provenance and a job ledger.
Two habits keep a growing store trustworthy and alive.
Provenance. Tag every fact with how you know it — fact, inference, unverified — plus a confidence and a source. It sounds bureaucratic; it's the thing that lets you catch a bad inference before it becomes load-bearing. A claim that can't name its source is a claim you can quarantine.
A real job ledger. The background work that feeds memory — ingestion, consolidation passes, expiry — should run off one ledger with leases and retries, not a scattering of ad-hoc progress keys. One place to see what's running, what's stuck, and what to retry. Memory you can't see being maintained is memory you'll stop trusting.
Lowest risk first.
If you already run a fragmented version of this — most people do, spread across a facts table, some files, and a pile of watermark keys — don't big-bang it. Sequence the change so the riskiest piece lands last, on a substrate that's already proven.
- Phase 1 — reliability. Stand up the job ledger; migrate scattered progress keys into it. Pure infra, no change to how memory is written, immediate payoff in crash-safety. Reversible.
- Phase 2 — the boundary. Route writes to staging; have the orchestrator run the consolidation pass. This is the real architecture shift — roll it out one agent at a time.
- Phase 3 — recall & lifecycle. Add semantic recall, populate scope, and let consolidation supersede stale facts. Additive; do it after the boundary settles.
Each phase is useful on its own and safe to stop at. That's what makes it a migration you'll actually finish.
That's the whole game.
Three small primitives, stacked: memory you can read, a boundary that keeps it honest, a ledger that keeps it running. None is complicated alone — but compose them and your fleet stops waking up as strangers. It accumulates.