If you hired an employee who showed up every morning with zero memory of yesterday, you'd fire them by Friday.
Well, every chat with a memoryless AI is that employee's first day on the job. Forever.
That's what most people are running their business on.
When I first started using AI this drove me crazy. The chat apps try to remember a little about you (your name, your industry, that you asked about golf clubs once in 2024), but I'm talking about REAL memory.
I expect (and need) my agents to remember what I wrote in Build Notes #013 so they can pull quotes and lessons from it without me digging through old drafts. I need my support agent to remember when a customer hits their 2nd refund of the year, because that's where our policy draws the line. We honor our 30 day money back guarantee every single time, but 2 refunds in a year gets you blacklisted from future purchases. That's how we stop serial refunders from robbing us politely.
Let's fix your agents' memory today.
Two Geniuses, One Weekend, Two Answers
Agent memory grew up fast one weekend back in April.
On April 4th, Andrej Karpathy (founding team at OpenAI, ex-head of AI at Tesla) published a little gist he called the LLM Wiki. On April 5th, one day later, Garry Tan (the guy who runs Y Combinator) open-sourced GBrain, the memory system behind his own agents.
One day apart. And both landed on the same foundation: markdown files.
Karpathy's version: the model IS the librarian. A raw/ folder of sources the agent reads but never edits. A wiki/ folder of markdown pages the agent writes and maintains itself (index.md as the card catalog, log.md as the diary). A schema file with the house rules. You never (or rarely) write the wiki yourself. In his words, LLMs "don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass."
Tan's version: give the librarian a search engine. GBrain also stores everything as markdown in a git repo (a folder that keeps its own change history). But Garry's own GBrain is up past 146,000 pages, and at that scale "just open the right file" stops working. So GBrain adds vector search for meaning, keyword search for exact terms, and a knowledge graph that links every person and company with typed relationships (works_at, invested_in, founded). On their own published benchmark, that graph layer scored 31.4 points higher on retrieval precision than vector search alone.
His pitch line: "Search gives you raw pages. GBrain gives you the answer."
Notice what they AGREE on though. Neither picked a proprietary database as the source of truth. Both picked plain markdown files you could open in Notepad.
Folders and Markdown Are the New Database
Why did two of the smartest guys in AI both land on the most boring file format on Earth?
Because markdown checks every box:
- You can read it. Open the file, see exactly what your agent believes.
- Every model can read it. Your memory survives model swaps, so it's memory you OWN.
- You can diff it. Every change shows up, which gives you an audit trail.
- It's free. A folder of text files costs nothing and can never get acquired and shut down.
Writing about this markdown memory wave, The New Stack said the moat is shifting from the model to the markdown a team owns and accumulates.
Models are like employees now. Brilliant, and they change every 6 months. Your markdown is the filing cabinet each new hire inherits on day one. Actually, it's more than a filing cabinet... it's grandma's recipe book. Twenty years of "here's how WE do it" that makes the new cook as good as the old one by dinner time.
Your competitors can rent the same model you rent. They cannot rent your accumulated memory.
So Where Do Vectors Fit?
A vector database converts your text into coordinates (meaning math) so the agent can find things by SIMILARITY instead of exact words. Ask "what did that Nashville guy complain about" and vector search surfaces the webhook ticket even though your question shares almost no words with it. Grep can't do that. Fuzzy recall at scale is the superpower.
Standalone though, a vector database is a brain in a jar. Impressive recall, but you can't crack it open and read what it believes, can't diff it, can't fix one bad fact with a text editor.
So here's the answer to the folders vs vectors debate: the winners run BOTH. Markdown as the source of truth you can read and own, plus an index (vectors, keywords, graph) on top for recall at scale. That's GBrain's entire design, and it's why I use it.
soul.md vs claude.md vs memory.md
Every framework names things differently, and this is where beginners drown. Three files, three lanes:
soul.md is the identity. WHO the agent is. Name, personality, values, how it talks.
user.md is you. Your preferences, your businesses, your pet peeves.
memory.md is the scratchpad. What the agent is holding RIGHT NOW. Rewritten constantly, on purpose.
But none of those files are a memory system, they're configuration. An employee handbook is not the employee's memory of working with you. A TRUE memory system (GBrain, MemPalace, Karpathy's wiki pattern) is where experience accumulates daily without you editing anything.
If you're still pasting context into your prompts every morning, you don't have an agent with memory. You have an intern with amnesia and a sticky note habit.
You might be wondering then, what is claude.md? It's the Anthropic version of soul.md, and it only works with Claude. soul.md is what OpenClaw, Hermes, and most other agent harnesses use. Same job, different badge. Everything in this article works in either one.
The 4 Memory Rules I Run In My Hermes Agents
My agents run on Hermes (an open-source agent framework by Nous Research), and these four rules live in their SOUL.md, so every agent is BORN knowing how to manage its own memory. The rules sit in soul.md on purpose: it's the one file the agent can't edit, so it can't talk itself out of them.
Steal these word for word:
MEMORY RULES
1. GBRAIN (DEFAULT MEMORY)
The primary long-term store. Durable facts, project context,
brand knowledge, customer history, tool configs. When in doubt
about where to put something persistent, it goes to GBrain.
2. USER.MD (OWNER PROFILE. PROTECTED)
Facts about the owner: preferences, businesses, style, goals,
pet peeves. Read-only by default. New fact? Flag it and ask.
3. MEMORY.MD (WORKING SCRATCHPAD. REWRITABLE)
Current task context and short-lived facts. Freely rewritable.
When it fills up, durable facts graduate to GBrain and noise
gets dropped.
4. SOUL.MD (IDENTITY. PROTECTED)
Defines who the agent is. Read-only by default. No changes
without explicit permission.
Install GBrain first (it's open source and free), then copy those four rules straight into your agent's soul.md. Every agent I launch ships with them from day one. That's how each one knows exactly where every new fact goes, and why my agents never hit "memory full" and grind to a halt.
Why protect the identity files? Because self-editing agents drift. Small edit by small edit, your pit bull becomes a golden retriever, and you won't notice until it approves a refund it should have fought.
Identity, owner profile, scratchpad, long-term store. Four layers, each with its own rule.
My favorite GBrain habit is the over/under line: every page keeps the current truth OVER a line and the dated receipts for each fact UNDER it, so you can audit your agent's memory like a bank statement.
None of this is theory either. GBrain powers our support agents at AdSkills (my ads training company) right now. Every customer gets their own file with every ticket and every product they've bought. Every refund request gets honored (that's the promise of our 30 day guarantee), but the 2nd refund inside a year flips a flag in that customer's file: blacklisted from future purchases. When a serial refunder shows up to buy again, my agent checks the file, not a vibe. That's memory defending my business while I sleep.
Do This Tonight
You don't need GBrain on day one. You need the layers in the right order:
- Make a memory/ folder next to your agent. Markdown files, an index.md listing what's in there, a log.md diary. Takes 30 minutes.
- Paste my 4 rules into your agent's soul.md (claude.md if you build on Claude). Not running GBrain yet? Change rule 1 to "the memory/ folder."
- Protect your identity files starting TODAY, before drift starts.
- When the folder outgrows simple search, install GBrain and point it at the same markdown.
Do steps 1 and 2 tonight and your agents wake up tomorrow with a better memory than most of the agents being sold on the internet right now.
Continue with Build Notes+
This Monday deep dive is free in full. For complete Thursday builds and supporting files, join Build Notes+.
