An interactive textbook
AI Agent Memory
Novice to Ninja
How an AI assistant remembers you, taught from zero with one card box, one secretary, one librarian, and numbers you can move with your own hands.
Start readingOpen the memory lab
25 chapters · about 5.0 hours · 45 interactives · no background needed
The library behind the book
hanumemAI
Remember everything. Inject almost nothing.
A plug-and-play memory layer for AI agents: one Python package, one SQLite file, any OpenAI-compatible model. It was tuned by 121 logged experiments, and this book teaches every idea inside it.
Scores are LLM-judged accuracy. Each tile names its answer model, its judge and its context tokens per question, because a score without those is a rumour. Where other systems score higher we say so in Chapter 18.
How to read this book
- In order. Each chapter uses only what the earlier ones taught.
- With your hands. Chapters marked interactive have sliders and small simulators. Move them before you read on.
- Answer before you look. Every chapter ends with questions and folded answers. Recalling beats re-reading.
Part I · Novice
Why models forget, and the one idea that fixes it.
01The genius with amnesiaWhy the smartest AI model cannot remember your name tomorrow, shown with one real experiment and one long division.8 min · interactive02Three fixes that failResend the history, buy a bigger window, or train a model per user. We test each with arithmetic, and each failure hands us a rule for the design.9 min · interactive03The card box: recall, answer, rememberOne loop sits under every memory system: recall before the answer, remember after it. We meet the secretary, the librarian and the millisecond budget.9 min · interactive04Four kinds of memoryThe sticky note and the card box: short-term memory, and the three colours of long-term memory, with a real experiment on rolling summaries.10 min · interactive05Requirements and the scale mathWhat the memory layer must do, how fast, and how big it gets. Every number is derived from five inputs, so you can derive them again for any system.10 min · interactive
Part II · Apprentice
The secretary, the box and the librarian, piece by piece.
06The secretary: fact extractionOne model reads the chat once and decides what is worth a card. We watch it turn 221 tokens into 39, and learn why its mistakes are the ones nobody sees.10 min · interactive07Where memories liveOpen the box and look at one card, field by field. Learn what an embedding is with a map and two arrows, and count the bytes all the way to 664 GB.11 min · interactive08The librarian: retrieval at inferenceFollow one question through the read path: embed, search, pick the top few, inject, answer. All of it in the time the cursor blinks.11 min · interactive09Scoring beyond similaritySimilarity finds the topic. It cannot tell a birthday from printer ink. We add recency and importance, then search by meaning, words and names at once.12 min · interactive10Update or add: consolidationA store that only grows stops being true. Four verbs keep it honest, one experiment shows them at work, and then the industry changes its mind.10 min · interactive11Time and truth: two clocksFacts change. Overwriting loses the past. Two clocks on every card, and a pointer from the old card to the new, keep both the present and the history.11 min · interactive12Forgetting and decayA memory that never forgets gets worse, not better. Four tools keep the store small and the top three cards correct: dedup, supersede, decay and erase.11 min · interactive
Part III · Journeyman
Latency, prompts, privacy, scale, cost and evaluation.
13The write path nobody waits forRecall happens before the answer and must be fast. Remembering happens after the answer and may take seconds. One experiment shows 58 % of the wait disappear.10 min · interactive14Models and promptsThree model roles, four prompts, and what our experiments say about which words and which models actually move the score.11 min · interactive15Guardrails: privacy and poisoningOne missing filter leaks a life. What must never be stored, how a user takes it all back, and how an attacker plants a memory.12 min · interactive16Scaling and costFrom one laptop to a million users: where the 664 GB comes from, how rounding shrinks it, and the daily bill derived line by line.12 min · interactive17Monitoring and evaluationEight dials to watch, two layers of tests, and a routine that turns every wrong answer into the name of the part that failed.12 min · interactive
Part IV · Ninja
Benchmarks, other systems, our own library and its 121 experiments.
18Benchmarks are claimsThree public exams for memory, how a machine grades them, and why a score means nothing until it names its models, its judge and its token cost.12 min · interactive19How others do it: Mem0, HydraDB, ZepTwo opposite bets on the same problem, the research systems around them, and what hanumemAI took from each.13 min · interactive20hanumemAI: the hybrid designOne Python package, one SQLite file, and one fact followed from the moment Maya says it to the moment the assistant reads it.13 min · interactive21What 121 experiments taught usOne idea, one run, keep or discard: the loop that tuned hanumemAI for about 25 dollars, what moved the score, what never did, and the mistakes we made on the way.14 min · interactive
Part V · Practice
Build it, play with the numbers, and answer it cold.
22Build an assistant that remembersSixty lines of Python, four sessions in Maya's life, and the real output: what worked, what the box kept, and two honest flaws.12 min23The memory labA whole memory layer that runs in your browser, and the main calculators of the book in one place. Learn memory by moving its numbers.25 min · interactive24Questions readers askSixty questions that remain after the last chapter, each answered in a few plain sentences, with a number where one exists and the chapter that teaches it.20 min25Whiteboard it coldThe whole book on a few pages: one paragraph, one picture, the pocket numbers, twelve sentences, a 45-minute interview script and the ten mistakes to avoid.14 min