# LlamaIndex

Adding persistent memory to LlamaIndex agents with the SurrealDB Agent Memory SDK.

[LlamaIndex](https://www.llamaindex.ai/) builds RAG and agent applications in Python. SurrealDB Agent Memory gives a LlamaIndex agent long-term memory that persists across sessions. There is no dedicated adapter. The [Python SDK](/docs/agent-memory/integrations/sdks/python.md) (`surrealdb`) exposes the memory operations you wrap as `FunctionTool`s.

> [!NOTE]
> This is an integration guide. It wires the SurrealDB Agent Memory SDK into LlamaIndex's tool interface; adapt to your installed LlamaIndex version.

## Installation

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

```bash
pip install llama-index
pip install --pre surrealdb
```

```bash
export SPECTRON_ENDPOINT="https://api.spectron.example"
export SPECTRON_CONTEXT="acme-prod"
export SPECTRON_API_KEY="sk-spec-..."
```

## Memory as tools

Wrap the client in `FunctionTool`s and hand them to an agent:

```python
import os
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI
from surrealdb import Spectron

memory = Spectron(
    endpoint=os.environ["SPECTRON_ENDPOINT"],
    context=os.environ["SPECTRON_CONTEXT"],
    api_key=os.environ["SPECTRON_API_KEY"],
)
scope = ["org/acme/user/alice"]

def remember(text: str) -> str:
    """Store a durable fact for later recall."""
    memory.remember(text, scopes=scope)
    return "stored"

def recall(query: str) -> str:
    """Retrieve relevant memory for a query."""
    return memory.query_context(query, k=8, lens=scope)

agent = FunctionAgent(
    llm=OpenAI(model="gpt-4o"),
    tools=[FunctionTool.from_defaults(remember), FunctionTool.from_defaults(recall)],
    system_prompt="Use recall before answering and remember anything worth keeping.",
)
```

## Recall for retrieval

Because SurrealDB Agent Memory already ranks across semantic, lexical, graph, and temporal signals server-side, call `query_context` (or `recall`) directly rather than wiring it into a `VectorStoreIndex`:

```python
block = memory.query_context("what is the return policy?", k=8, lens=["org/acme"])
# inject `block` into your prompt, or return it from a query tool
```

> [!NOTE]
> LlamaIndex's built-in `Memory` stores chat history in a SQL database. SurrealDB Agent Memory is a separate, hosted memory tier with server-side extraction and hybrid retrieval. Use it when memory should be shared across agents and survive process restarts.

## Scope per user

Pass a `scope` on every call to isolate memory. A scope is a slash path or an array of paths, for example `["org/acme/user/alice"]`. Register paths with `spectron scopes create` before first use.

## Next steps

- [Python SDK](/docs/agent-memory/integrations/sdks/python.md): the full client surface
- [JavaScript SDK](/docs/agent-memory/integrations/sdks/javascript-and-typescript.md): for LlamaIndex.TS