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.jsonindex 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.mdindex 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.mdindex 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 todiff --git a/.claude/.codebase-info/entry-points.md b/.claude/.codebase-info/entry-points.mdindex 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.mdindex 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.mdindex 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*## AtomicityBuild 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`, …)