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, installed from GitHub. 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 "git+https://github.com/surrealdb/agent-memory-pydantic-ai"

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

pip install "git+https://github.com/surrealdb/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(
        context="your-context",
        endpoint="https://your-agent-memory-instance",
        api_key="your-api-key",
        scope="user/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 session_id, a scope, and an on_behalf_of principal, added to every operation that accepts them. The scope is applied as scopes on writes and as lens on reads. One connection can serve many users and sessions through narrowed views:

base = AgentMemory(client)
alice = base.scoped(scope="user/alice", session_id="s1")
bob = base.scoped(scope="user/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.