# Strands Agents

SurrealDB Agent Memory as tools for the Strands Agents SDK.

SurrealDB Agent Memory exposes its memory operations as [Strands Agents](https://strandsagents.com) tools, so any Strands agent can store and retrieve long-term memory with a single line of setup.

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

Package: **`spectron-strands-agents`** (PyPI). It pulls in `strands-agents` and `surrealdb` (which provides the SurrealDB Agent Memory client).

```python
from strands import Agent
from spectron_strands import spectron_tools

agent = Agent(tools=spectron_tools())

agent("Remember that we signed a contract with Meditech Solutions for 1.2M GBP.")
print(agent("What is the value of the Meditech Solutions contract?"))
```

## Installation

```bash
pip install spectron-strands-agents
```

To run the examples with Amazon Bedrock (Strands' default model provider):

```bash
pip install "spectron-strands-agents[bedrock]"
```

Requires Python 3.10+.

## Environment

With these set, `spectron_tools()` builds the client for you:

```bash
export SPECTRON_ENDPOINT="https://api.spectron.example"
export SPECTRON_API_KEY="your-bearer-token"
export SPECTRON_CONTEXT="acme-prod"
```

You can also pass the values directly, or hand in a client you already have:

```python
from surrealdb import Spectron
from spectron_strands import spectron_tools

# From explicit arguments.
tools = spectron_tools(
    endpoint="https://api.spectron.example",
    api_key="your-bearer-token",
    context="acme-prod",
)

# Or reuse an existing client.
client = Spectron(context="acme-prod", endpoint="...", api_key="...")
tools = spectron_tools(client=client)
```

## Tools

`spectron_tools()` returns seven tools by default, one per SurrealDB Agent Memory operation:

| Tool | Purpose |
| --- | --- |
| `spectron_remember` | Store a fact or observation for later recall. |
| `spectron_recall` | Search memory and return the most relevant stored information. |
| `spectron_context` | Assemble a working-memory context block for a query. |
| `spectron_reflect` | Run a synthesis pass that consolidates and connects memories. |
| `spectron_forget` | Delete memories that match a query. |
| `spectron_upload` | Ingest a document so its contents become recallable. |
| `spectron_inspect` | Browse the substrate as queryable data for debugging or audit. |

Choose a subset with `include` or `exclude`:

```python
# Only the everyday read/write pair.
tools = spectron_tools(include=["remember", "recall"])

# Everything except deletion and inspection.
tools = spectron_tools(exclude=["forget", "inspect"])
```

## Scopes

Scopes isolate memory by principal, tenant, or session. A scope is a path string such as `"org/acme/user/alice"`, or a list of paths. Set a default for all tools and let the agent override it per call:

```python
tools = spectron_tools(scope="org/acme/user/alice")
```

Every tool also accepts a `scope` argument, so a multi-user agent can direct a single operation at a specific principal.

## 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).