Pydantic AI | Agent frameworks

SurrealDB Agent Memory for Pydantic AI, via a toolset, auto-recall processor, and persistence helpers.

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.

Note

Spectron was the project name for SurrealDB Agent Memory. These type names
will be renamed in a future release.

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

Memory tools (SpectronToolset): expose recall, context, remember, and more as tools the agent calls when it decides to.
Auto-recall (spectron_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 spectron-pydantic-ai

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

pip install "spectron-pydantic-ai" "pydantic-ai-slim[openai]"

Quickstart

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

import asyncio
from pydantic_ai import Agent
from spectron_pydantic_ai import SpectronMemory, SpectronToolset

async def main():
    memory = SpectronMemory.connect(
        url="https://your-spectron-instance",
        namespace="your-namespace",
        token="your-token",
        user_id="ada",
    )
    agent = Agent("openai:gpt-4o", toolsets=[SpectronToolset(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 spectron_pydantic_ai import ALL_TOOLS, SpectronToolset

toolset = SpectronToolset(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 spectron_pydantic_ai import spectron_history_processor

processor = spectron_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.

Note

Pydantic AI registers history processors through the capabilities argument with ProcessHistory, as shown. Older releases used a history_processors=[...] argument instead. The processor function works with both; only the way you attach it to the agent differs. Check the version in your project.

Persistence

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

from spectron_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

SpectronMemory 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 = SpectronMemory(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.