# CrewAI

CrewAI integration for SurrealDB Agent Memory, with memory tools and automatic per-task memory.

SurrealDB Agent Memory gives [CrewAI](https://www.crewai.com/) agents persistent, provenance-first memory. The integration offers two approaches that compose: tools an agent calls explicitly, and automatic memory that recalls before each task, writes back after it, and consolidates when the crew finishes, without changing your agents or tasks.

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

Package: **`spectron-crew-ai`** (PyPI). It pulls in CrewAI and the SurrealDB SDK (`surrealdb` v3, which bundles SurrealDB Agent Memory).

## Requirements

- Python 3.10+
- CrewAI 1.5+
- SurrealDB Agent Memory access: endpoint, context, and API key

## Installation

```bash
pip install spectron-crew-ai
```

## Environment

| Variable | Purpose |
| --- | --- |
| `SPECTRON_ENDPOINT` | Server URL |
| `SPECTRON_CONTEXT` | Context id |
| `SPECTRON_API_KEY` | Context API key (keep it in `.env`, not source) |
| `SPECTRON_DEFAULT_SCOPE` | Optional. Scope for writes and lens for reads, for example `user/tobie`. |
| `SPECTRON_TOP_K` | Optional. Memories recalled per query (default `5`). |

You can also pass any of these directly to `SpectronMemory(...)` or `SpectronConfig(...)` instead of using the environment.

## Memory as tools

Attach the SurrealDB Agent Memory tools and let the agent decide when to use memory:

```python
from crewai import Agent, Task, Crew
from spectron_crewai import get_spectron_tools

agent = Agent(
    role="Research Analyst",
    goal="Answer questions using long-term memory",
    backstory="You recall what you have learned before and store new findings.",
    tools=get_spectron_tools(scope="user/tobie"),
    verbose=True,
)

task = Task(
    description="What do we know about Tobie's role? Store any new facts you learn.",
    expected_output="A short summary.",
    agent=agent,
)

Crew(agents=[agent], tasks=[task]).kickoff()
```

To isolate memory per user or session, use the sessionized factory:

```python
from spectron_crewai import get_sessionized_spectron_tools

tools = get_sessionized_spectron_tools("user-123")
```

The tools map onto SurrealDB Agent Memory operations: `spectron_recall`, `spectron_remember`, `spectron_context`, `spectron_forget`, `spectron_reflect`, and `spectron_upload`.

## Automatic memory

Enable automatic memory once and run the crew as usual. Recall happens before each task, write-back runs on a background thread after each task, and consolidation runs when the crew finishes:

```python
from crewai import Agent, Task, Crew
from spectron_crewai import SpectronMemory

memory = SpectronMemory(default_scope="user/tobie")
memory.attach(verbose=True)   # register the event listener

agent = Agent(
    role="Travel Planning Specialist",
    goal="Plan trips that respect the traveller's known preferences",
    backstory="You remember past trips and preferences.",
    tools=memory.tools(),     # optional: also expose the explicit tools
)

task = Task(
    description="Plan a weekend trip for Tobie.",
    expected_output="A day-by-day plan.",
    agent=agent,
)

Crew(agents=[agent], tasks=[task]).kickoff()
memory.close()                # flush background writes on shutdown
```

`SpectronMemory` is also usable directly:

```python
memory.remember("Tobie prefers window seats", scopes="user/tobie")
hits = memory.recall("seat preference", lens="user/tobie")
answer = memory.context("What are Tobie's travel preferences?")
```

> [!NOTE]
> SurrealDB Agent Memory is exposed as tools and an event-driven memory layer rather than as a CrewAI `StorageBackend`. CrewAI's built-in storage is embedding-centric: it hands the store a vector, never the query text, whereas SurrealDB Agent Memory embeds and ranks server-side across semantic, lexical, graph, and temporal signals.

## Reliability

Writes run on a background daemon thread, so tasks never block on SurrealDB Agent Memory I/O. Every call is wrapped: failures are logged and degrade to an empty or error result rather than raising into the crew loop, and a circuit breaker disables memory for the rest of the process after repeated failures or an authentication error.

## When to use MCP or the SDK instead

- For an MCP-native host, prefer the [MCP server](/docs/agent-memory/integrations/mcp-server/install.md).
- To call SurrealDB Agent Memory directly outside CrewAI, use the [Python SDK](/docs/agent-memory/integrations/sdks/python.md).