Building AI agents, atomically
Persistent Memory Example
This example demonstrates how to plug a custom, persistent memory backend into Atomic Agents so a conversation survives across separate process runs (cross-session recall).
It shows:
- Subclassing
ChatHistoryto add persistence, following the pluggableBaseChatHistoryextension point - A
SQLiteChatHistorybackend built with zero extra dependencies, using only the Python standard library'ssqlite3module - Persisting on every
add_messagecall and rehydrating the full history on startup via the inheriteddump()/load()
See the Memory guide's "Writing a Custom Memory Backend" section for the full write-up of this pattern.
Getting Started
Clone the main Atomic Agents repository:
git clone https://github.com/eigenwise/atomic-agentsNavigate to this example's directory:
cd atomic-agents/atomic-examples/persistent-memoryInstall the dependencies using uv:
uv syncSet your
OPENAI_API_KEYenvironment variable (or put it in a.envfile in this directory).
Running the Example
uv run python persistent_memory/main.py
Chat with the agent, then exit with /exit. A chat_history.db file is created in the current directory.
Run it a second time and the agent picks up right where you left off: it prints the number of restored messages at startup and remembers everything from the previous run, because the conversation was persisted to chat_history.db under the demo session ID.
How It Works
SQLiteChatHistory (in persistent_memory/main.py) subclasses ChatHistory instead of reimplementing the memory contract from scratch:
__init__opens (or creates) a SQLite database with a singlesessions(session_id TEXT PRIMARY KEY, data TEXT)table, and loads any existing row for the givensession_idvia the inheritedload().add_messagecallssuper().add_message(...)to reuseChatHistory's turn handling, then saves the entire history to SQLite viaself.dump().
Because dump()/load() already handle serialization, the persistence layer only has to move a single JSON string in and out of storage. The same pattern works for any store (Redis, Postgres, a hosted memory service) by swapping out what _save/__init__ talk to.