# The Agent Memory Starter
Your agent has made the same mistake a thousand times. Every run starts from
zero, and whatever it worked out last time died with the process.
The fix is not a bigger context window. It is three separate stores, each
answering a different question, each written at a different moment.
The three layers
Episodic: what happened. After every run, write the outcome: what the task
was, whether it worked, what broke, and what a human corrected. This is a log,
not a summary. The next run opens by asking *have I hit this before?*
Semantic: what's true. Across a thousand runs, most of that log is noise.
A few things keep being true: this deploy always needs --safe-mode,
migrations run before seed, that flaky test is the environment and not the
code. Those get promoted out of the log into facts.
Procedural: what works. The first time the agent solves a messy edge case,
it saves the sequence of steps. Next run it does not reason it out again. It
runs the playbook.
Three questions, three tables, one file.
Get it running in two minutes
curl -sL https://sharpendaily.co/giveaways/agent-memory-starter.zip -o agent-memory-starter.zip
unzip agent-memory-starter.zip -d agent-memory-starter
cd agent-memory-starter
python3 demo.py # run 1: fails, then learns
python3 demo.py # run 2: brand-new process, remembers — no failure
Run 2 shares nothing with run 1 except the agent_memory.db file that got
written to disk. It checks memory *before* acting, finds the playbook, and
succeeds on the first try. Same task, no repeated mistake.
If you would rather have it assert the proof than eyeball it:
python3 selfcheck.py
Five assertions, exit 0. And to see what is actually stored at any point:
python3 memory.py show
## What is in the box
memory.py is the library: about 120 lines, three SQLite tables in one file,sqlite3 and json and nothing else. There is no pip install step because
there is nothing to install. No API key, no Docker, no cloud account.
| Layer | Question | API |
|---|---|---|
| Episodic | What happened? | log_episode(task, outcome, detail) / recall_episodes(task) |
| Semantic | What's true? | remember_fact(key, value, task=None) / get_fact(key) |
| Procedural | What works? | save_playbook(task, steps) / get_playbook(task) |
Wiring it into your own agent
Before the agent acts, call get_playbook(task) and recall_episodes(task)
and put what comes back into its context. After it finishes, or fails,
always log_episode(...), and add remember_fact(...) or save_playbook(...)
when something durable was learned.
The one decision that is yours: the task key scheme. The starter uses one
string per task type. A real agent probably wants something keyed on the repo
plus the shape of the task.
What this does not do
Read this part before you build on it.
- No semantic search. Facts and playbooks are looked up by exact key, not
by meaning. Past a certain fact count you will want a vector index.
- No forgetting. Nothing expires or gets demoted when it stops being true.
You would add that.
- No concurrency story beyond SQLite's own file locking. Fine for one agent
process. Do not point ten parallel agents at one database file without your
own locking.
- The demo task is a toy (a fake tool that needs one flag), so the
before/after is unambiguous in under five minutes. Your integration point is
memory.py, not the example in demo.py.
It is the storage layer and the retrieval pattern. It won't wire itself into
your agent; that part is yours. But the thousandth run only stops repeating the
first if something survives the run, and this is the smallest thing that does.
Or comment MEMORY on the reel and it comes to you.