Pydantic AI

Spectron 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: 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 Spectron so conversations survive across sessions.

Installation

pip install spectron-pydantic-ai

To run against a live Spectron instance and a model provider:

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

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.

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 Spectron directly outside Pydantic AI, use the Python SDK.