Skip to content

Building AI agents, atomically

Update codebase map for BaseChatHistory + persistent-memory example

Eigenwise933f13ad2c7b
diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.json
index b836798..2d058f0 100644
--- a/.claude/.codebase-info/.map-state.json
+++ b/.claude/.codebase-info/.map-state.json
@@ -1,8 +1,8 @@
{
"tool": "codebase-mapper",
"version": "2.0.0",
- "mappedAt": "2026-06-13",
- "gitCommit": "3d33e62f2b6796b7259c1e3e5d77c4313a56f22d",
+ "mappedAt": "2026-07-05",
+ "gitCommit": "28099f5aa6eccb491c66be4bcd22532f15bb407f",
"documents": [
"architecture.md",
"tech-landscape.md",
diff --git a/.claude/.codebase-info/architecture.md b/.claude/.codebase-info/architecture.md
index e36947a..d09f077 100644
--- a/.claude/.codebase-info/architecture.md
+++ b/.claude/.codebase-info/architecture.md
@@ -1,6 +1,6 @@
# Architecture
-*Last Updated: 2026-06-13*
+*Last Updated: 2026-07-05*
## Summary
@@ -47,7 +47,7 @@ Tool install (atomic-assembler TUI):
|-----------|------|----------------|
| Core agent | `atomic-agents/atomic_agents/agents/atomic_agent.py` | `AtomicAgent`, `AgentConfig`, run / stream / async methods |
| Base contracts | `atomic-agents/atomic_agents/base/` | `BaseIOSchema`, `BaseTool`, `BaseToolConfig`, `BaseResource`, `BasePrompt` |
-| Context | `atomic-agents/atomic_agents/context/` | `SystemPromptGenerator`, `BaseDynamicContextProvider`, `ChatHistory` |
+| Context | `atomic-agents/atomic_agents/context/` | `SystemPromptGenerator`, `BaseDynamicContextProvider`, `BaseChatHistory` (pluggable memory contract) + `ChatHistory` |
| Connectors | `atomic-agents/atomic_agents/connectors/mcp/` | Model Context Protocol tools / resources / prompts |
| Utils | `atomic-agents/atomic_agents/utils/` | Token counting (LiteLLM), tool-message formatting |
| Assembler (CLI) | `atomic-assembler/atomic_assembler/` | Textual TUI to fetch/install forge tools |
diff --git a/.claude/.codebase-info/directory-structure.md b/.claude/.codebase-info/directory-structure.md
index 09585ca..6a82c41 100644
--- a/.claude/.codebase-info/directory-structure.md
+++ b/.claude/.codebase-info/directory-structure.md
@@ -1,6 +1,6 @@
# Directory Structure
-*Last Updated: 2026-06-13*
+*Last Updated: 2026-07-05*
## Root Layout
@@ -10,7 +10,7 @@ atomic-agents/ # repo root (uv workspace)
│ └── atomic_agents/ # import package
│ ├── agents/ # AtomicAgent, AgentConfig
│ ├── base/ # BaseIOSchema, BaseTool, BaseResource, BasePrompt
-│ ├── context/ # SystemPromptGenerator, ChatHistory, context providers
+│ ├── context/ # SystemPromptGenerator, BaseChatHistory/ChatHistory, context providers
│ ├── connectors/mcp/ # Model Context Protocol integration
│ └── utils/ # token counter, tool-message formatting
│ └── tests/ # pytest suite (agents/, base/, context/, connectors/, utils/)
@@ -19,7 +19,7 @@ atomic-agents/ # repo root (uv workspace)
├── atomic-forge/ # library of standalone tools (NOT a package)
│ ├── tools/<tool>/ # one folder per tool: tool/<tool>.py, tests/, pyproject.toml
│ └── guides/ # tool authoring guides (e.g. tool_structure.md)
-├── atomic-examples/ # 15 runnable example apps (each its own project)
+├── atomic-examples/ # 16 runnable example apps (each its own project)
├── docs/ # Sphinx + MyST documentation (api/, guides/, examples/)
├── guides/ # DEV_GUIDE.md and contributor guides
├── scripts/ # sync_version.py, generate_llms_files.py
@@ -49,9 +49,9 @@ and copies a selected tool into the user's project.
`pyproject.toml`/`requirements.txt`. Tools are copied into user projects, not pip-installed.
### `atomic-examples/`
-15 standalone example apps (`quickstart`, `rag-chatbot`, `deep-research`, `web-search-agent`,
-`mcp-agent`, `fastapi-memory`, `youtube-summarizer`, …), each with its own `pyproject.toml`. These
-are excluded from the workspace build.
+16 standalone example apps (`quickstart`, `rag-chatbot`, `deep-research`, `web-search-agent`,
+`mcp-agent`, `fastapi-memory`, `persistent-memory`, `youtube-summarizer`, …), each with its own
+`pyproject.toml`. These are excluded from the workspace build.
### `docs/` and `guides/`
`docs/` is a Sphinx + MyST site (`api/` reference, `guides/`, `examples/`, `conf.py`), deployed to
diff --git a/.claude/.codebase-info/entry-points.md b/.claude/.codebase-info/entry-points.md
index 8dbf194..e112912 100644
--- a/.claude/.codebase-info/entry-points.md
+++ b/.claude/.codebase-info/entry-points.md
@@ -1,6 +1,6 @@
# Entry Points
-*Last Updated: 2026-06-13*
+*Last Updated: 2026-07-05*
## 1. Library API (the primary entry point)
@@ -45,6 +45,7 @@ MCP server tools/resources/prompts become agent components via `atomic_agents.co
| `mcp-agent` | MCP client/server, multiple transports |
| `progressive-disclosure` | efficient MCP tool loading (3 servers, 24 tools) |
| `fastapi-memory` | multi-user / multi-session memory behind a FastAPI service |
+| `persistent-memory` | custom `BaseChatHistory` backend: cross-session recall via stdlib `sqlite3` (no extra deps) |
| `hooks-example` | monitoring, error handling, retry via hooks |
| `basic-multimodal` / `nested-multimodal` | images / PDFs in (nested) schemas |
| `basic-pdf-analysis` | PDF analysis with a multimodal model |
diff --git a/.claude/.codebase-info/modules.md b/.claude/.codebase-info/modules.md
index b335683..05be8b8 100644
--- a/.claude/.codebase-info/modules.md
+++ b/.claude/.codebase-info/modules.md
@@ -1,6 +1,6 @@
# Key Modules
-*Last Updated: 2026-06-13*
+*Last Updated: 2026-07-05*
## Core framework — `atomic-agents/atomic_agents/`
@@ -24,8 +24,11 @@
- **Location:** `atomic-agents/atomic_agents/context/`
- **Purpose:** System-prompt assembly and conversation memory.
- **Key files:** `system_prompt_generator.py` (`SystemPromptGenerator`, `BaseDynamicContextProvider`),
- `chat_history.py` (`ChatHistory`, `Message` — multimodal Image/Audio/PDF, turn grouping,
- `dump()`/`load()` serialization).
+ `base_chat_history.py` (`BaseChatHistory` — interface-only ABC declaring the memory contract
+ `AtomicAgent` depends on; the pluggable seam for custom/persistent backends),
+ `chat_history.py` (`ChatHistory`, `Message` — the built-in in-memory implementation of
+ `BaseChatHistory`: multimodal Image/Audio/PDF, turn grouping, `dump()`/`load()` serialization).
+- **Note:** `AgentConfig.history` is typed to `BaseChatHistory`, so any conforming backend drops in.
### connectors/mcp
- **Location:** `atomic-agents/atomic_agents/connectors/mcp/`
@@ -58,4 +61,4 @@
### atomic-examples
- **Location:** `atomic-examples/`
-- **Purpose:** 15 runnable reference apps. Catalog in `entry-points.md`.
+- **Purpose:** 16 runnable reference apps. Catalog in `entry-points.md`.
diff --git a/.claude/.codebase-info/patterns.md b/.claude/.codebase-info/patterns.md
index 7267dc0..d179729 100644
--- a/.claude/.codebase-info/patterns.md
+++ b/.claude/.codebase-info/patterns.md
@@ -1,6 +1,6 @@
# Patterns & Conventions
-*Last Updated: 2026-06-13*
+*Last Updated: 2026-07-05*
## Atomicity
Build with small, single-purpose, composable parts ("LEGO blocks"): each agent, tool, and context
@@ -25,9 +25,15 @@ the next's input. See `atomic-examples/deep-research` and `orchestration-agent`.
schema(s) → config → tool class + logic → example usage.
## Memory
-- `ChatHistory` stores typed `Message`s grouped into turns (a user+assistant pair shares a `turn_id`),
- is multimodal-aware (Image/Audio/PDF), and supports `dump()`/`load()`. `AtomicAgent` trims the
- oldest whole turns to honor `max_context_tokens`.
+- `BaseChatHistory` (`context/base_chat_history.py`) is an interface-only ABC declaring the memory
+ contract `AtomicAgent` relies on (`add_message`, `get_history`, turn handling, `dump()`/`load()`,
+ `copy()`, plus the `history`/`current_turn_id` attributes). It is the documented, dependency-free
+ seam for plugging in custom/persistent backends; `AgentConfig.history` is typed to it.
+- `ChatHistory` is the built-in implementation: stores typed `Message`s grouped into turns (a
+ user+assistant pair shares a `turn_id`), is multimodal-aware (Image/Audio/PDF), and supports
+ `dump()`/`load()`. `AtomicAgent` trims the oldest whole turns to honor `max_context_tokens`.
+- Custom backend pattern: subclass `ChatHistory` and override `add_message`/`load` to persist (see
+ the `persistent-memory` example and the "Writing a Custom Memory Backend" guide section).
## Error handling & retries
- Lean on Instructor's validation/retry of structured outputs, plus hook events (`parse:error`, …)