LlamaIndex 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 (surrealdb) exposes the memory operations you wrap as FunctionTools.
This is an integration guide. It wires the SurrealDB Agent Memory SDK into LlamaIndex's tool interface; adapt to your installed LlamaIndex version.
Installation
Spectron was the project name for SurrealDB Agent Memory. These type names
will be renamed in a future release.
pip install llama-index
pip install --pre surrealdbexport SPECTRON_ENDPOINT="https://api.spectron.example"
export SPECTRON_CONTEXT="acme-prod"
export SPECTRON_API_KEY="sk-spec-..."Memory as tools
Wrap the client in FunctionTools and hand them to an agent:
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:
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 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: the full client surface
JavaScript SDK: for LlamaIndex.TS