Pydantic AI

SurrealDB Agent Memory connects to Pydantic AI through the framework's own extension points, so an agent can remember facts across runs, recall them when relevant, and keep a durable record of its conversations.

Package: agent-memory-pydantic-ai (PyPI). It gives you three surfaces, usable on their own or together:

• •

  Memory tools (AgentMemoryToolset): expose recall, context, remember, and more as tools the agent calls when it decides to.

• •

  Auto-recall (agent_memory_history_processor): inject relevant memory before each model request, with no tool call required.

• •

  Persistence (store_run, store_messages): write a run's messages back to SurrealDB Agent Memory so conversations survive across sessions.

Installation

pip install agent-memory-pydantic-ai

To run against a live SurrealDB Agent Memory instance and a model provider:

pip install "agent-memory-pydantic-ai" "pydantic-ai-slim[openai]"

Quickstart

AgentMemory.connect(...) builds the client; pass the toolset to the agent:

import asyncio
from pydantic_ai import Agent
from agent_memory_pydantic_ai import AgentMemory, AgentMemoryToolset

async def main():
    memory = AgentMemory.connect(
        url="https://your-agent-memory-instance",
        namespace="your-namespace",
        token="your-token",
        user_id="ada",
    )
    agent = Agent("openai:gpt-4o", toolsets=[AgentMemoryToolset(memory)])
    result = await agent.run("Remember that I prefer window seats.")
    print(result.output)

asyncio.run(main())

The toolset exposes recall, context, and remember by default. Pass tools=ALL_TOOLS (or a subset) to also expose reflect and forget:

from agent_memory_pydantic_ai import ALL_TOOLS, AgentMemoryToolset

toolset = AgentMemoryToolset(memory, tools=ALL_TOOLS)

Auto-recall

Inject relevant memory before every run without giving the agent a tool. The processor reads the latest user message, recalls related memories, and prepends them as context:

from pydantic_ai import Agent
from pydantic_ai.capabilities import ProcessHistory
from agent_memory_pydantic_ai import agent_memory_history_processor

processor = agent_memory_history_processor(memory)
agent = Agent("openai:gpt-4o", capabilities=[ProcessHistory(processor)])

Use mode="context" to load the current working set instead of searching by the latest message.

Persistence

Store a run's messages so the next session can recall them:

from agent_memory_pydantic_ai import store_run

result = await agent.run("I am planning a trip to Tokyo.")
await store_run(memory, result)

Scoping and multi-tenancy

AgentMemory carries a scope (user_id, session_id, agent_id) added to every operation. One connection can serve many users and sessions through narrowed views:

base = AgentMemory(client)
alice = base.scoped(user_id="alice", session_id="s1")
bob = base.scoped(user_id="bob", session_id="s2")

When to use MCP or the SDK instead

• •

  For an MCP-native host, use the MCP server.

• •

  To call SurrealDB Agent Memory directly outside Pydantic AI, use the Python SDK.