Medium-Term Memory — Conversation Persistence#

CH05 Short-Term Memory solved the “conversation too long, exceeds the context window” problem, but the moment the Agent program exits, the messages list inside the Agent class introduced in CH04 dies with the process. Reopen the agent a week later and the half-finished discussion from before is gone.

This chapter handles medium-term memory — letting the user run /save <name> to persist the current messages list to disk so that, even after the Agent program exits or the machine reboots, the next REPL session can run /load <name> to bring that same conversation back into the Agent and keep talking:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$ python minimal_agent.py
you> Let's start discussing project X
... some discussion ...
you> /save xproject
you> /exit

# A week later...
$ python minimal_agent.py
you> /load xproject
you> Where did we leave off?
claude> Last time we talked about ...

“Medium-term” means this memory is tied to one specific conversation — unlike short-term memory, which only lives in the Agent program’s RAM (gone the moment the program exits), and unlike long-term memory, which extracts stable facts and accumulates them across conversations.

6.1 Overall Design#

“Agent program closes, reopens, still remembers” is conceptually simple — the model has no memory (CH04 4.2 covered this); “remembering” works by resending the messages list. Given that, making memory survive across sessions only requires: write the messages list to a file before the Agent program exits, and read it back from the file on the next launch.

Implementation-wise, we just add two more branches to the /-command dispatcher from CH04 4.1:

Tip: The Agent program can also accept a --resume <name> launch argument that is implementation-wise equivalent to /load <name> — purely a CLI convenience wrapper.

6.2 Storage Strategy: Plain Files Are Enough#

In 6.1 we wrote the messages list to sessions/<name>.json with no database involved. For a minimal-agent at this scale, plain files have more upsides than a database:

sessions/                    ← gitignored
├── alex.json
├── refactor-2026-04.json
└── debug-mcp-issue.json

JSON, plain text. You can eyeball-diff it, grep it, compare against a git stash. No database overhead. And the name itself is the index — you don’t even need a list command: just ls sessions/ shows every session (though a /list inside the REPL is still convenient).

When do you need to switch to a database? It depends on scale:

minimal-agent is built for an individual developer; a few hundred sessions are perfectly fine to scan via ls sessions/. Once you actually need to scale up — search, indexing, multi-user sharing — swap the storage layer. The messages list structure stays exactly the same; only the place it lives changes.

Recap#

By now you should understand:

• Medium-term memory = persistence tied to a specific conversation — write the current messages list to a file, read it back next time to continue
• The filesystem is enough — sessions/<name>.json is plain text, diffable, greppable, zero dependencies
• The name is the index — ls sessions/ is the list command

But medium-term memory still only solves continuity for a specific conversation. Cross-conversation facts (I’m Alex, I use Python, I’m working on minimal-agent) still have to be re-told to the model at the start of every new session. The next chapter, CH07 Long-Term Memory, uses RAG to solve that.

References#

• Full source code: github.com/codereindeer-dev/minimal-agent