Pydantic AI core has no memory store. An agent remembers a conversation only when you pass the earlier messages back through the message_history argument, and the docs leave where those messages live, which conversation they belong to and when to reload them to your application. Memory that outlives a conversation comes from the separate Pydantic AI Harness, whose Memory capability is a set of Markdown notes the agent writes and reads itself, on an API that may change during 0.x releases. Maximem Synap is the other route: register_synap_tools gives the agent a search_memory and a store_memory tool, and user_id and customer_id travel in SynapDeps, so the model cannot spoof scope.
Where Pydantic AI Excels
Pydantic AI is an agent framework from the team behind Pydantic, built around type safety. Structured outputs validated against Pydantic models, dependency injection through a typed RunContext, and tool calling with proper type hints are all first-class. If your agent needs to validate inputs, enforce schemas or guarantee output structure, Pydantic AI handles the type plumbing well.
How Pydantic AI Memory Works Today
Pydantic AI treats an agent's memory of a conversation as its message history, and the persistence guide separates that from memory across conversations.
Message history is a list you manage. A run returns result.new_messages() and result.all_messages(); pass either to the next run as message_history and the agent continues the conversation. To keep the list between processes you serialize it with ModelMessagesTypeAdapter and store the JSON in your own database.
History processors keep long conversations inside the context window. The ProcessHistory capability runs your function over the message list before each model request; the documented examples keep the most recent messages or summarize the oldest ones.
Cross-conversation memory lives in Pydantic AI Harness, a separate package. Its Memory capability gives the agent a notebook of Markdown files with tools to write, read, delete and search them, backed by an in-memory, file, SQLite or Postgres store, and keyed by a namespace your code resolves from the run's dependencies, such as a user ID. Search over the notebook is literal text search; the page states that semantic ranking is not built in.
In core you own storage and scope; with the Harness you get durable notes that the model curates. Extraction from the conversation itself and retrieval by meaning are memory-layer problems that neither covers by design.
What Synap Adds
Synap is agentic context management: a hosted memory engine with open-source client packages. It does not replace Pydantic AI's message history, which keeps carrying the current conversation. It adds memory across conversations, scoped per user.
The maximem-synap-pydantic-ai package uses Pydantic AI's own mechanisms (dependencies, tools and system prompt functions):
SynapDeps is a dataclass you set as the agent's deps_type. It holds the SDK, a required user_id, and optional customer_id and conversation_id.
register_synap_tools adds two tools and a system prompt function to the agent. search_memory lets the model query the user's memories and store_memory lets it write one. The system prompt function fetches the user's context from Synap at the start of a run and injects it; a failure there is logged and the run continues.
synap_run is a drop-in for agent.run that also records the user turn and the assistant turn to Synap, which gives Synap a conversation to extract memories from; register_synap_st_system_prompt injects its compacted view of that conversation. Retrieval has two modes: fast (vector-only, 50 to 100ms) and accurate(graph traversal + reranking, 200 to 500ms). The search_memory tool uses accurate mode.
We built this because type-safe agents kept stalling in production. Not from bad validation. From missing context that lived in a different session last Tuesday. Production testing hit 92% LongMemEval, 93.2% on LoCoMo. Fast mode retrieves in under 100ms.
For why context management is infrastructure and not a feature, read What Is Agentic Context Management?. For build-versus-buy numbers, see The Real Cost of DIY Agent Memory.
What Synap Adds to Pydantic AI
Persistence
Pydantic AI Native. Message history that you serialize and store; durable notes with the Harness and a database-backed store. With Synap. Per-user memory is hosted and survives across sessions and restarts.
Entity Resolution
Pydantic AI Native. Not provided; notes hold what the model wrote. With Synap. "My manager" in one session and "Sarah" in another resolve to one person on the server.
Compaction
Pydantic AI Native. A history processor you write, such as keep-recent or summarize-oldest. With Synap. Automatic compaction per conversation, injected as a system prompt.
Retrieval Latency
Pydantic AI Native. Depends on setup. With Synap. 50 to 100ms fast mode. 200 to 500ms accurate mode.
Long-Term Recall
Pydantic AI Native. Literal text search over notes in the Harness; nothing in core. With Synap. 92% on LongMemEval.
Failure Handling
Pydantic AI Native. Your storage code, your error handling. With Synap. Context injection and turn recording log and continue. The two tools raise SynapIntegrationError.
User Scoping
Pydantic AI Native. Whatever key your application stores history under; a namespace resolver in the Harness. With Synap. user_id, conversation_id and customer_id carried in SynapDeps.
What Production Teams Gain
Cross-session continuity. Your user chats on Monday, returns on Wednesday with a new conversation_id. The system prompt function loads what Synap knows about them at the start of the run, and search_memory lets the model look up anything more specific.
Accuracy that ships. 92% LongMemEval, 93.2% on LoCoMo measures whether agents recall facts across long, multi-turn conversations spanning multiple sessions.
Latency that does not block. Fast retrieval: 50 to 100ms. Accurate mode with graph traversal and reranking: 200 to 500ms. A failed context fetch is logged and the agent answers without it.
Entity resolution. When a user says "my manager" in one session and "Sarah" in the next, Synap's engine links the two on the server, so your agent does not have to.
Scope the model cannot touch. Identity comes from RunContext[SynapDeps], which your application sets per request. A B2C instance takes user_id alone and rejects customer_id; a B2B instance requires it.
How to Get Started
Setup
Install the package alongside Pydantic AI. It needs Python 3.11 or later:
pip install maximem-synap-pydantic-ai pydantic-ai
Configure your API key. Generate one from the Synap Dashboard.
.env
SYNAP_API_KEY=synap_your_key_here
OPENAI_API_KEY=your-openai-api-key
Initialize the SDK once at application startup:
from maximem_synap import MaximemSynapSDK
sdk = MaximemSynapSDK() await sdk.initialize()
See SDK Initialization for the full lifecycle and configuration options.
Basic integration Declare an agent with deps_type=SynapDeps, call register_synap_tools(agent) once, then pass SynapDeps per request:
import uuidfrom pydantic_ai import Agent from synap_pydantic_ai import SynapDeps, register_synap_tools, synap_run
agent: Agent[SynapDeps, str] = Agent( "openai:gpt-4o", deps_type=SynapDeps, instructions="You are a helpful assistant with long-term memory.", )
register_synap_tools(agent)
deps = SynapDeps( sdk=sdk, user_id="alice", # add customer_id="acme" on a B2B instance conversation_id=str(uuid.uuid4()), # must be a valid UUID ) result = await synap_run(agent, "What do you remember about my project?", deps=deps) print(result.output)
register_synap_tools does three things:
Registers
search_memory, a tool the agent can call to retrieve memoriesRegisters
store_memory, a tool the agent can call to persist new memoriesRegisters a system prompt function that injects the user's stored context at the start of a run
The agent never sees user_id or customer_id directly; the tools pull them from RunContext[SynapDeps], so the model cannot spoof scope. One behavior to plan for: Pydantic AI does not re-run system prompt functions when you pass message_history, so the injected context is set on the first turn of a conversation and later turns rely on search_memory.
Memory Is Infrastructure
Pydantic AI gave developers type-safe agents and a clear contract about state: the framework hands you the messages, and storage is yours. Turning those messages into memory that persists per user and stays correct when facts change is a different problem.
Teams either build that pipeline on top of their own database, or they plug in a system built for the problem. What it buys is an agent that improves with every conversation, for customers who stop repeating themselves.
This is why memory is infrastructure, not a feature.
Start building Pydantic AI agents that remember across sessions → (https://synap.maximem.ai)
Synap pricing is usage-based. You pay for memory operations: storage, retrieval, compaction. No per-seat or per-framework surcharge. Starter plan:
$49/month. Every new account gets $25 in free credits to test before committing. See full pricing at https://synap.maximem.ai/pricing.
