# Pydantic AI

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

SurrealDB Agent Memory connects to [Pydantic AI](https://ai.pydantic.dev) 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

```bash
pip install spectron-pydantic-ai
```

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

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

## Quickstart

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

```python
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`:

```python
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:

```python
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:

```python
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:

```python
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](/docs/agent-memory/integrations/mcp-server/install.md).
- To call SurrealDB Agent Memory directly outside Pydantic AI, use the [Python SDK](/docs/agent-memory/integrations/sdks/python.md).