Agno | Agent frameworks

Agno is a high-performance Python framework for building agents. SurrealDB Agent Memory adds long-term memory that persists across sessions and agents. There is no dedicated adapter. The Python SDK (surrealdb) exposes the memory operations you attach as Agno tools.

Note

This is an integration guide. It wires the SurrealDB Agent Memory SDK into Agno's tool interface; adapt to your installed Agno version.

Installation

Note

Spectron was the project name for SurrealDB Agent Memory. These type names
will be renamed in a future release.

pip install agno openai
pip install --pre surrealdb

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

Memory as tools

Agno agents take a tools list. Pass functions that call the SurrealDB Agent Memory client, and Agno exposes them to the model:

import os
from agno.agent import Agent
from agno.models.openai import OpenAIChat
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 = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[remember, recall],
    instructions="Use recall before answering and remember anything worth keeping.",
    markdown=True,
)

agent.print_response("What do you know about Alice's role?")

Recall around a run

Recall first, add the context to the agent's instructions, then store the exchange after the response:

block = memory.query_context(user_message, k=8, lens=scope)

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    instructions=f"You are a helpful assistant.\n\n## Memory\n{block}",
)
response = agent.run(user_message)

memory.remember_many(
    [{"role": "user", "content": user_message}, {"role": "assistant", "content": response.content}],
    scopes=scope,
)

Note

Agno ships its own session storage and user-memory primitives (enable_user_memories=True). Use SurrealDB Agent Memory when you want a shared, provenance-first memory that several agents or services read and write, with server-side extraction and hybrid recall.

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
MCP server: if your host speaks MCP instead