Building Agent Memory on SurrealDB Across Modern Agent Frameworks with SuperOptiX

Agent Memory is one of the hot topic in the Agentic AI space as everyone trying to solve this for once. AI agents usually end up with a fragmented memory stack. One system stores embeddings. Another stores structured records. A third handles graph relationships. A cache keeps short-lived context. Then application code has to stitch all of it together, keep it consistent, and explain to the agent framework where each piece of memory lives. We tried many vector databases and explored pros and cons of each. Every database has it’s own unique straights and weaknesses but when Agent Memory is the topic then SurrealDB is one that you cannot ignore.

SurrealDB is a multi-model database that brings together documents, graph traversal, vector search, full-text retrieval, and live queries in one engine. With SurrealDB 3.0, the official positioning has become even more relevant for AI systems: agent memory, richer indexing, extensions, file support, record references, live data, and more expressive ways to connect application logic to data.

SuperOptiX is a strong fit for exercising that model because it gives us one shared runtime for RAG, memory, and tool access across multiple modern agent frameworks. Instead of writing a separate SurrealDB integration for every framework, we can wire SurrealDB
into the shared runtime layer once and demonstrate the same backend across DSPy, OpenAI, Claude SDK, Microsoft, PydanticAI, CrewAI, Google ADK, and DeepAgents.

In this post, we will do three things:

Get a real SurrealDB-backed agent running end to end.
Show how the same SurrealDB backend works across multiple frameworks through SuperOptiX.
Map SurrealDB 3.0’s newest agent-memory story to what SuperOptiX supports today.

If you want the full companion docs with framework-specific commands and troubleshooting, see the SuperOptiX
SurrealDB guide.

What SurrealDB 3.0 changes for agent memory

SurrealDB’s official 3.0 page and launch materials make a simple point: agent memory works better when vectors, graph structure, documents, and live updates live together.

That matters because agent memory is not just semantic search. A real memory layer often needs:

semantic retrieval over embeddings
exact lexical retrieval when a token or identifier matters
relationships between entities, tools, and tasks
durable state that changes over time
subscriptions or live updates for coordination
safe access patterns for tools and external runtimes

SurrealDB 3.0 publicly emphasizes:

vector, graph, and SQL retrieval in a unified model
better indexing and performance
an improved in-memory engine
extensions via Surrealism
file storage
client-side transactions
custom API endpoints
record references
live data patterns and richer multi-model traversal

That does not mean every one of those features is already exposed in SuperOptiX. It does mean the direction is right, and several of the most useful pieces for agent memory are already implemented.

What SuperOptiX adds

SuperOptiX is the integration and runtime layer. The useful property of SuperOptiX here is that it gives us:

One agent spec and runtime model
Multiple target agent frameworks
One shared RAG layer
One shared memory layer
One shared tool layer

That means SurrealDB can sit behind the shared runtime, and the resulting behavior becomes available across multiple frameworks without rebuilding the integration eight times.

Today, that shared runtime already covers:

vector RAG
hybrid retrieval
GraphRAG
multi retrieval, hybrid plus graph expansion
temporal memory with version history
server-side embedding path with client fallback
live memory utility using LIVE SELECT
a read-only SurrealDB query tool
capability detection and graceful fallback when a feature is missing on the running SurrealDB server</ li>

Architecture in one view

At a high level, the integration looks like this:

SuperOptiX Playbook
      |
      v
  Framework Adapter
      |
      v
  Shared Runtime Layer
      |
      +--> RAG Runtime ------------------> SurrealDB vector, hybrid, graph, multi retrieval
      |
      +--> Memory Backend --------------> SurrealDB key-value and temporal memory
      |
      +--> MCP / Built-in Tool ---------> read-only SurrealDB query access
      |
      +--> Live Utility ----------------> LIVE SELECT subscriptions
      |
      +--> Feature Detector ------------> runtime gating for RELATE, fn::embed, live support

This is the key design choice. SurrealDB support in SuperOptiX is not implemented as isolated framework-specific integrations. It is implemented in the shared runtime layer, so the same backend behaviour can be exercised through different frameworks.

What we will build

We will use one SurrealDB instance and one shared dataset to demonstrate:

a basic SurrealDB-backed RAG run
a GraphRAG run that follows graph relationships
the same backend across modern agent frameworks
temporal memory support
optional live updates and read-only query access

Recommended Quick Start with Cloud based models

For most readers, the easiest way to get started is to use Google Gemini for inference and SurrealDB for
retrieval and memory. This avoids local model setup and makes the first successful run much simpler.

Install SuperOptiX with SurrealDB support

With uv:

uv pip install "superoptix[surrealdb]"

Or with pip:

pip install "superoptix[surrealdb]"

Set your Google API key

Use GEMINI_API_KEY as the main environment variable:

export GEMINI_API_KEY=your_key_here

If you already use Google’s other naming, this also works:

export GOOGLE_API_KEY=your_key_here

Start SurrealDB

docker run --rm -p 8000:8000 --name surrealdb-demo surrealdb/surrealdb:latest \
    start --log info --user root --pass secret memory

Seed the demo data

python -m superoptix.agents.demo.setup_surrealdb_seed
  python -m superoptix.agents.demo.setup_surrealdb_seed --graph

Exact output to look for:

SurrealDB seed complete
Inserted: 8
GraphRAG seeding:
Edges created:

Behavior to verify:

the standard seed finishes cleanly
the graph seed creates edges greater than 0

Create a SuperOptiX project

super init memory-demo
cd memory-demo

Run basic RAG with DSPy and Gemini

super agent pull rag_surrealdb_dspy_demo
  super agent compile rag_surrealdb_dspy_demo --framework dspy
  super agent run rag_surrealdb_dspy_demo \
    --framework dspy \
    --cloud \
    --provider google-genai \
    --model gemini-2.5-flash \
    --goal "What is NEON-FOX-742?"

Exact output to look for:

RAG retrieval enabled
Validation Status: ✅ PASSED

Behavior to verify:

the answer mentions NEON-FOX-742

Run GraphRAG with DSPy and Gemini

super agent pull graphrag_surrealdb_dspy_demo
  super agent compile graphrag_surrealdb_dspy_demo --framework dspy
  super agent run graphrag_surrealdb_dspy_demo \
    --framework dspy \
    --cloud \
    --provider google-genai \
    --model gemini-2.5-flash \
    --goal "What capabilities does SurrealDB provide?"

Exact output to look for:

Validation Status: ✅ PASSED

Behavior to verify:

the run does not fall back from graph mode to vector mode
the answer includes SurrealDB capabilities from graph-connected records

This same pattern works across the other SuperOptiX frameworks as well. Only the demo ID and
--framework flag change. The SurrealDB backend, seed data, retrieval behavior, and Google Gemini
model stay the same.

Quick start Local models

Prerequisites

You need Python, Docker, and a terminal with uv or pip. If you want the local model path, you also need Ollama.

Install SuperOptiX with SurrealDB support

With uv:

uv pip install "superoptix[surrealdb]"
ollama pull llama3.1:8b

Or with pip:

pip install "superoptix[surrealdb]"
ollama pull llama3.1:8b

Start the local model service

For simplicity, we will open different terminal for each tasks and let’s call it A, B, C etc.

Terminal A:

ollama serve

start the SurrealDB, Seed the data and create SuperOptiX and then pull the agents from the SuperOptiX marketplace.

super agent pull rag_surrealdb_dspy_demo
super agent compile rag_surrealdb_dspy_demo --framework dspy
super agent run rag_surrealdb_dspy_demo --framework dspy --goal "What is NEON-FOX-742?"

Exact output to look for:

RAG retrieval enabled
Validation Status: ✅ PASSED

Behavior to verify:

the answer mentions NEON-FOX-742

That token is part of the seeded dataset, so this is a grounding check. A correct answer here tells us the agent is retrieving from SurrealDB rather than guessing.

Moving from RAG to GraphRAG

Seed graph-enabled data

python -m superoptix.agents.demo.setup_surrealdb_seed --graph

Exact output to look for:

GraphRAG seeding:
Nodes created:
Edges created:

Behavior to verify:

Edges created: is greater than 0

If edge creation is zero or the command warns that RELATE is unsupported, then GraphRAG is not
truly active yet.

Run the GraphRAG demo

 super agent pull graphrag_surrealdb_dspy_demo
 super agent compile graphrag_surrealdb_dspy_demo --framework dspy
 super agent run graphrag_surrealdb_dspy_demo --framework dspy --goal "What capabilities does SurrealDB
  provide?"

Exact output to look for:

Validation Status: ✅ PASSED

Behavior to verify:

the run does not say it is falling back from graph mode to vector mode
the answer mentions SurrealDB capabilities discovered through graph-connected records

For this walkthrough, we recommend using Google Gemini or similar cloud based model for inference and SurrealDB for retrieval and memory. That gives you the simplest path to a successful first run because you do not need to download or manage a local model before testing the integration. In practice, the only change is the runtime flags passed to
super agent run: add --cloud --provider google-genai --model gemini-2.5-flash and
make sure GEMINI_API_KEY or GOOGLE_API_KEY is set in your environment. The SurrealDB setup, seed flow, playbooks, and retrieval behavior stay the same.

Run GraphRAG with Gemini

super agent pull graphrag_surrealdb_dspy_demo
  super agent compile graphrag_surrealdb_dspy_demo --framework dspy
  super agent run graphrag_surrealdb_dspy_demo \
    --framework dspy \
    --cloud \
    --provider google-genai \
    --model gemini-2.5-flash \
    --goal "What capabilities does SurrealDB provide?"

At this point, the core SurrealDB integration is working: vector retrieval, graph expansion, and framework-managed agent execution.

Watch Demo

How the data is modeled

The default SurrealDB RAG table is rag_documents.

A typical row looks like this:

{
    "content": "document text",
    "embedding": [0.123, -0.456, 0.789],
    "metadata": {
      "seed_id": "seed-001",
      "source": "superoptix_surreal_seed_v1",
      "topic": "retrieval"
    }
  }

For GraphRAG, SuperOptiX also creates graph-oriented records in the same table using deterministic IDs such
as:

rag_documents:superoptix
rag_documents:surrealdb
rag_documents:vector_search

Those graph-oriented rows also carry:

metadata.entity_id
typed relations built with RELATE

The seeding utility attempts to define:

an HNSW vector index on the embedding field
a BM25 full-text index on the content field
an index on metadata.entity_id

This lines up with SurrealDB’s own vector model guidance, where HNSW indexing is the recommended pattern for vector retrieval.

Retrieval modes in SuperOptiX

This is where SurrealDB becomes more than a plain vector store.

1. Vector retrieval

This is standard semantic retrieval. SuperOptiX creates a query embedding and ranks rows by cosine
similarity over the embedding field.

2. Hybrid retrieval

Hybrid retrieval combines vector similarity with lexical relevance from full-text search. This matters when
exact terms matter, such as product names, identifiers, and error strings.

In SuperOptiX, that is controlled by:

retrieval_mode: hybrid
hybrid_alpha

3. GraphRAG

Graph mode is a two-step flow:

retrieve the best seed records with vector search
expand those seeds by traversing configured RELATE edges

This is the mode that turns SurrealDB into a graph-aware retrieval backend rather than only an embedding
store.

4. Multi retrieval

Multi mode starts with hybrid retrieval, then expands results via graph traversal. Use it when the question
mixes semantic meaning, exact tokens, and relationships.

SurrealDB across modern agent frameworks

One of the strongest parts of this integration is that the same SurrealDB backend can be exercised across
multiple frameworks.

Framework	Basic RAG demo	GraphRAG demo
DSPy	`rag_surrealdb_dspy_demo`	`graphrag_surrealdb_dspy_demo`
OpenAI	`rag_surrealdb_openai_demo`	`graphrag_surrealdb_openai_demo`
Claude SDK	`rag_surrealdb_claude_sdk_demo`	`graphrag_surrealdb_claude_sdk_demo`
Microsoft	`rag_surrealdb_microsoft_demo`	`graphrag_surrealdb_microsoft_demo`
PydanticAI	`rag_surrealdb_pydanticai_demo`	`graphrag_surrealdb_pydanticai_demo`
CrewAI	`rag_surrealdb_crewai_demo`	`graphrag_surrealdb_crewai_demo`
Google ADK	`rag_surrealdb_adk_demo`	`graphrag_surrealdb_adk_demo`
DeepAgents	`rag_surrealdb_deepagents_demo`	`graphrag_surrealdb_deepagents_demo`

The run pattern is the same:

super agent pull <demo_id>
super agent compile <demo_id> --framework <framework>
super agent run <demo_id> --framework <framework> --goal "<question>"

Use the same two questions everywhere:

Basic RAG: What is NEON-FOX-742?
GraphRAG: What capabilities does SurrealDB provide?

That is the story worth highlighting in the blog. SurrealDB is the same backend. The seeded data is the
same. The questions are the same. SuperOptiX is the layer that makes it easy to exercise that backend
consistently across frameworks.

Agent memory beyond retrieval

SurrealDB 3.0 is not only about vector search. Its official launch story leans heavily into agent memory, and SuperOptiX already exposes several pieces of that story.

Temporal memory

The SurrealDB memory backend supports temporal versioning. In practice that means:

the primary table stores the latest value for a key
a companion versions table stores the historical writes
retrieve() returns the current value
history() returns prior versions
retrieve_at() returns the value at a point in time

Example playbook support already exists in temporal_memory_surrealdb_demo. This is a better mental model for agent memory than simple overwrite-only storage. It turns memory into a journal.

Live memory utility

SurrealDB’s LIVE SELECT is a good fit for real-time memory and coordination patterns. SuperOptiX includes aLiveMemorySubscriber utility that can subscribe to changes over WebSocket-based SurrealDB connections. This is not auto-wired into every agent runtime path, and that is the right choice for now. Live coordination is useful, but it is also operationally different from basic retrieval and memory.

Server-side embeddings

SurrealDB 3.0 and its extension story make it possible to move more logic into the database. In SuperOptiX,
the RAG runtime can try a server-side embedding path through fn::embed. If fn::embed is available, the query can be embedded inside SurrealDB. If not, SuperOptiX falls back to the client-side sentence-transformer path automatically.

MCP-style query access

SuperOptiX also includes a read-only SurrealDB query tool, surrealdb_query, which can be used
as a built-in tool configuration.

It is intentionally restricted:

only SELECT, INFO, and RETURN
row limit injection when missing
timeout protection

Important nuance: this is not the same thing as full official SurrealMCP support. SuperOptiX currently exposes a focused, built-in read-only
query tool.

A practical SuperOptiX configuration

This is a compact example that shows one SurrealDB deployment backing RAG, multi retrieval, temporal
memory, and read-only query access.

spec:
    target_framework: dspy

    language_model:
      location: cloud
      provider: google-genai
      model: gemini-2.5-flash

    memory:
      enabled: true
      backend:
        type: surrealdb
        config:
          url: ws://localhost:8000
          namespace: superoptix
          database: agents
          username: root
          password: secret
          table_name: superoptix_memory
      temporal:
        enabled: true
        max_versions_per_key: 50

    rag:
      enabled: true
      retriever_type: surrealdb
      config:
        top_k: 5
        retrieval_mode: multi
        hybrid_alpha: 0.7
        graph_depth: 2
        graph_relations:
          - integrates_with
          - provides
          - supports
          - enables
        embedding_mode: client
      vector_store:
        url: ws://localhost:8000
        namespace: superoptix
        database: knowledge
        username: root
        password: secret
        skip_signin: false
        table_name: rag_documents
        vector_field: embedding
        content_field: content
        metadata_field: metadata
        embedding_model: sentence-transformers/all-MiniLM-L6-v2

    tools:
      built_in_tools:
        - name: surrealdb_query
          config:
            url: ws://localhost:8000
            namespace: superoptix
            database: knowledge
            username: root
            password: secret

Mapping SurrealDB 3.0 to current SuperOptiX coverage

This is the most important section for credibility. We should be explicit about what is covered well, what is partial, and what is not implemented yet.

Covered well today

SurrealDB / agent-memory capability	SuperOptiX status
Vector retrieval	Supported
Hybrid retrieval	Supported
GraphRAG via `RELATE` traversal	Supported
Multi retrieval, hybrid plus graph	Supported
Temporal memory	Supported
`LIVE SELECT` utility	Supported
Server-side embedding path via `fn::embed` with fallback	Supported
Multi-framework demos	Supported across 8 frameworks
Runtime capability detection and fallback	Supported

Covered partially

SurrealDB 3.0 capability	Current state in SuperOptiX
SurrealMCP	SuperOptiX has a read-only query tool, but not full official SurrealMCP integration
Surrealism / extensions	Touched through the `fn::embed` path, not exposed as a general extension model

Not implemented yet

SurrealDB 3.0 capability	Current state in SuperOptiX
Record references with `<~`	Not yet exposed
File buckets / file storage workflows	Not yet exposed
Client-side transactions	Not yet exposed
Custom API endpoints	Not in scope today
Full record-reference lifecycle examples	Not yet exposed
Full SurrealMCP deployment integration	Not yet exposed

This is the right posture for the blog. It shows that the integration is already strong where it matters
most for agent retrieval and memory, while staying honest about what is still future work.

Production notes

Use the right connection mode

SuperOptiX can work with:

ws:// or wss:// for server mode
embedded transports such as memory or surrealkv:// for local development

Use ws:// or wss:// when you need shared access, production-like network
behavior, or live subscriptions.

Verify indexes explicitly

The demo seeder attempts to define indexes automatically, but production environments should not rely only
on that. For better retrieval behavior, explicitly verify vector indexing on embeddings, full-text indexing on
content, and stable record identifiers for graph-oriented data.

Treat GraphRAG as a capability, not an assumption

If your server does not support the graph behavior SuperOptiX expects, GraphRAG will degrade. That is a
feature, not a bug, but it means you should check the logs and seed output instead of assuming graph traversal
is active.

Keep security boundaries tight

If you expose query access to agents, keep it read-only unless you have a very strong operational reason
not to. The built-in surrealdb_query tool is intentionally conservative for that reason.

Why this combination matters

A lot of agent stacks still assume a single memory primitive. Usually that primitive is vector search. That is not enough.

Real agents need semantic retrieval, exact lookup, relations, state over time, safe data access, and a clean way to use all of the above across different runtimes. SurrealDB 3.0 is compelling because it brings those primitives closer together. SuperOptiX is useful here
because it gives us one place to test, run, and compare those behaviors across modern agent frameworks. That is the practical value of this integration: one backend, multiple retrieval styles, multiple frameworks, and one shared runtime model.

SuperOptiX Optimization Yet to take place

SuperOptiX is an agent optimization framework and we have not yet applied the optimzation techniques to the SurrealDB. Imagine , how powerful that combination would be when all the SurrealDB RAG queries, memories and prompts gets optimised by GEPA and suitable optimizers. We will cover that in the next section as we add these features and that would the super powerful feature of the SuperOptiX and SurrealDB combination

Conclusion

SurrealDB 3.0 makes a serious case for being more than a vector database in an agent stack. Its official direction is clearly about agent memory, unified retrieval, richer indexing, and bringing more intelligence closer to the data layer.

SuperOptiX makes that story concrete. Today, you can use SuperOptiX to run SurrealDB-backed vector RAG, hybrid retrieval, GraphRAG, multiretrieval, temporal memory, live memory utility, and read-only query tooling across modern agent frameworks,
not just one. That is already a strong and practical integration story.

The next layer of work is clear too:

deeper use of record references
richer SurrealMCP integration
file-backed multimodal memory patterns
transaction-aware agent workflows
Optimisation and evaluation of the RAG and Memory

But even without that future work, the current combination is already useful. You can get up and running
quickly, verify grounded retrieval, verify graph-aware retrieval, and then scale the same backend across
different frameworks through SuperOptiX.

Introducing SuperOpt: Research on Agentic Environment Optimization for Autonomous AI Agents

What SurrealDB 3.0 changes for agent memory

What SuperOptiX adds

Architecture in one view

What we will build

Recommended Quick Start with Cloud based models

Install SuperOptiX with SurrealDB support

Set your Google API key

Start SurrealDB

Seed the demo data

Create a SuperOptiX project

Run basic RAG with DSPy and Gemini

Run GraphRAG with DSPy and Gemini

Quick start Local models

Prerequisites

Install SuperOptiX with SurrealDB support

Start the local model service

Moving from RAG to GraphRAG

Seed graph-enabled data

Run the GraphRAG demo

Run GraphRAG with Gemini

Watch Demo

How the data is modeled

Retrieval modes in SuperOptiX

1. Vector retrieval

2. Hybrid retrieval

3. GraphRAG

4. Multi retrieval

SurrealDB across modern agent frameworks

Agent memory beyond retrieval

Temporal memory

Live memory utility

Server-side embeddings

MCP-style query access

A practical SuperOptiX configuration

Mapping SurrealDB 3.0 to current SuperOptiX coverage

Covered well today

Covered partially

Not implemented yet

Production notes

Use the right connection mode

Verify indexes explicitly

Treat GraphRAG as a capability, not an assumption

Keep security boundaries tight

Why this combination matters

SuperOptiX Optimization Yet to take place

Conclusion

References