Persistent Memory for AI Agents: A Markdown Wiki That Lasts
Every morning I used to explain the same project to my coding agents again. Which library we picked and why. Which approach we tried on Tuesday and threw away. Where the useful source was. The chat had ended, so the knowledge was gone, and I paid for it twice: once in my time, and again when an agent cheerfully reopened a decision we had already closed.
If you want persistent memory for AI agents, you don't need a vector database or a hosted memory service to start. You need somewhere durable to write things down and a few rules about what goes there. This post walks through the method I use, which works with any agent that can read and write files. Then I'll show how hivey does it.
Why AI agents forget between sessions
An agent's working memory is its context window. When the conversation ends, gets compacted, or the process stops, whatever wasn't written somewhere else is lost. Three kinds of knowledge suffer most:
- Decisions. "We use Postgres, not SQLite, because of concurrent writers." Lose this and the next agent suggests SQLite again.
- Dead ends. "Tried caching at the API layer; it broke auth." Lose this and someone repeats the experiment.
- Sources. The doc page, the issue thread, the spec section that answered the hard question.
The fix isn't a bigger context window. It's moving knowledge out of the chat and into files that outlive it.
A file-based memory pattern for AI agents
The idea, popularized as Karpathy's LLM Wiki as agent memory, is simple: agents maintain a small wiki of plain Markdown. Files are readable by you, diffable, greppable, and loaded by the agent only when needed. Here's a layout I'd suggest to start with:
memory/
index.md # one-line summary of every page, read first
sources/ # original material: links, excerpts, specs
findings/ # what we learned, with evidence
decisions/ # what we chose, why, and what we rejected
lessons/ # things that went wrong and how to avoid them
The index.md matters more than it looks. An agent starting cold reads one short file, then opens only the pages relevant to its task. That keeps memory useful without flooding the context.
What to write down: a memory checklist
Most memory systems fail because agents write too much or too little. I give agents explicit rules:
| Page type | Write it when | Must include |
|---|---|---|
| Source | You used outside material to make a call | Link or location, the relevant excerpt, date read |
| Finding | You verified something non-obvious | The claim, how it was checked, confidence |
| Decision | A choice closes off alternatives | Context, choice, rejected options and why |
| Lesson | Something failed or surprised you | What happened, the cause, the rule going forward |
A decision page can be this short:
# Use Postgres for the job queue
Date: 2026-11-10
Context: several workers write at once.
Decision: Postgres with SKIP LOCKED.
Rejected: SQLite (write lock contention), Redis (another service to run).
Revisit if: worker count drops to one.
The "Rejected" and "Revisit if" lines are what stop an agent from relitigating the choice next week. They tell it the question was considered, and under what conditions it's fair to reopen.
A few more rules that pay off:
- Read before acting. Put "check
memory/index.mdfirst" in the agent's instructions. - Write at the end of a task, not the middle. Half-finished findings mislead.
- Link, don't duplicate. A finding should point to its source page, not paste it again.
- Prune. If a decision is reversed, update the page and say so. Stale memory is worse than none.
- Keep it human-readable. If you can't skim it in a minute, the agent can't use it well either.
Persistent memory in hivey with Obsidian
Hivey is a terminal workspace and coordinating agent for your AI agents. It runs teams with Claude Code and Codex, each team (a swarm) with its own workspace and a coordinator that assigns work and reports back to you. Memory fits into that at a few levels.
A wiki per swarm. You can optionally give a swarm a local Markdown wiki for sources, findings, decisions, and reusable knowledge, the same pattern described above. It lives in files that you and your agents can inspect and maintain, and you can open its vault in Obsidian to browse the linked pages yourself. Obsidian memory is optional and needs its own setup, so check the docs for how to turn it on.
Conversations that survive a restart. If agents stop, you don't have to start them from zero:
hivey swarm list # see swarms, agents, and their states
hivey swarm relaunch <swarm> # restart stopped agents and continue their conversations
A record of what was said. Swarm messaging keeps inboxes and message history, so you can see what was asked and what came back:
hivey msg log --swarm <swarm>
Feeding memory on purpose. When you make a call outside the swarm, tell the coordinator so it ends up in the record:
hivey msg send <swarm>/coordinator "Decision: we're keeping Postgres for the queue. Record it with the rejected options."
You can also use a scheduled check-in to make memory upkeep a habit rather than something you remember to ask for:
hivey swarm schedule add <swarm> --every 2h "Update the wiki with new findings and decisions since the last check-in."
Because coordinators carry findings and requests across swarms, what one team learns doesn't have to stay locked inside it.
How to tell your agent memory is working
A quick test I run after a few days: start a fresh agent, give it a task near an old decision, and watch. If it reads the index, finds the decision page, and works within it, the memory is doing its job. If it proposes the rejected option, the decision page is missing its "Rejected" line or the agent isn't told to read memory first.
The goal is that you stop being the memory. The files are.
Try it
On an Apple Silicon Mac:
npm install -g @hivey/cli
hivey setup
On Linux or an Intel Mac, build from source at github.com/alyssaaa11/hivey. Then read the docs to set up a swarm and its Obsidian memory.