# OpenAI Agents SDK

SurrealDB Agent Memory for agents built with the OpenAI Agents SDK.

SurrealDB Agent Memory gives agents built with the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) a durable, shared memory. An agent can remember across runs, recall what it needs before answering, and share memory with other agents through a common scope.

> [!NOTE]
> `Spectron` was the project name for SurrealDB Agent Memory. These type names
> will be renamed in a future release.

Package: **`spectron-openai-agents-sdk`** (PyPI). Memory works two ways, and they compose: function tools the agent calls itself, and automatic memory wrapped around a run.

## Installation

```bash
pip install spectron-openai-agents-sdk
```

## Environment

```bash
export OPENAI_API_KEY="your-openai-api-key"
export SPECTRON_URL="https://your-spectron-endpoint"
export SPECTRON_NAMESPACE="your-namespace"
export SPECTRON_DATABASE="your-database"
export SPECTRON_TOKEN="your-token"   # optional for local, unsecured instances
```

## Memory as function tools

The agent decides when to `remember`, `recall`, `context`, `reflect`, or `forget`. `get_spectron_tools` builds the tools from the `SPECTRON_*` environment by default; pass `client=` for an explicit `SpectronClient` or `include=` to expose a subset:

```python
from agents import Agent, Runner
from spectron_openai_agents_sdk import get_spectron_tools

agent = Agent(
    name="assistant",
    instructions=(
        "You are a helpful assistant. Use recall to check memory before you "
        "answer, and use remember to store anything worth keeping."
    ),
    tools=get_spectron_tools(session_id="user-123"),
)

Runner.run_sync(agent, "My name is Ada and I work on databases.")

result = Runner.run_sync(agent, "What do you know about me?")
print(result.final_output)
```

## Automatic memory around a run

`run_with_memory` recalls memory relevant to the input, injects it into the prompt, runs the agent, and stores the result. The agent needs no memory tools of its own:

```python
import asyncio
from agents import Agent
from spectron_openai_agents_sdk import MemoryScope, run_with_memory

agent = Agent(name="assistant", instructions="You are a helpful assistant.")
scope = MemoryScope(session_id="user-123")

async def main():
    await run_with_memory(agent, "My name is Ada.", scope=scope)

    result = await run_with_memory(agent, "What is my name?", scope=scope)
    print(result.final_output)

asyncio.run(main())
```

## Persisting output with hooks

To save an agent's output while running it yourself, attach `SpectronMemoryHooks`:

```python
from agents import Runner
from spectron_openai_agents_sdk import SpectronClient, SpectronMemoryHooks, MemoryScope

client = SpectronClient.from_env()
hooks = SpectronMemoryHooks(client, MemoryScope(session_id="user-123"))

await Runner.run(agent, "Summarize our project decisions.", hooks=hooks)
```

## Multi-agent shared memory

Both approaches talk to SurrealDB Agent Memory through a single `SpectronClient`, scoped by a `MemoryScope` (`agent_id`, `session_id`, `user_id`). Agents that share a `MemoryScope` read and write the same memory, so what one agent stores is available to another.

## 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, use the [Python SDK](/docs/agent-memory/integrations/sdks/python.md).