Building Agent Memory on SurrealDB Across Modern Agent Frameworks with SuperOptiX

Agent Memory is one of the hot topics in the Agentic AI space as everyone tries 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 the pros and cons of each. Every database has its own unique strengths and weaknesses - but when Agent Memory is the topic, SurrealDB is one you cannot ignore.

What SurrealDB 3.0 Changes for Agent Memory

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

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

What SuperOptiX Adds

SuperOptiX is the integration and runtime layer. Its useful property here is that SurrealDB can sit behind one shared runtime and the same behaviour becomes available across DSPy, OpenAI, Claude SDK, Microsoft, PydanticAI, CrewAI, Google ADK, and DeepAgents - without rebuilding the integration eight times.

Architecture in One View

SurrealDB support in SuperOptiX is not implemented as isolated framework-specific integrations. It lives in the shared runtime layer, so the same backend behaviour is exercised across all frameworks.

Recommended Quick Start - Cloud Models

The easiest path is Google Gemini for inference and SurrealDB for retrieval and memory. This avoids local model setup. Only the runtime flags change - everything else stays the same.

uv pip install "superoptix[surrealdb]"

pip install "superoptix[surrealdb]"

export GEMINI_API_KEY=your_key_here
# or
export GOOGLE_API_KEY=your_key_here

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

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

super init memory-demo
cd memory-demo

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?"

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?"

Quick Start - Local Models

You need Python, Docker, and a terminal with uv or pip. For the local model path, also install Ollama.

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

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

ollama serve

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?"

Moving from RAG to GraphRAG

Seed graph-enabled data

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

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?"

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 integration is working: vector retrieval, graph expansion, and framework-managed agent execution.

Watch Demo

See the SurrealDB integration in action - RAG, GraphRAG, and temporal memory running across agent frameworks with SuperOptiX.

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 creates graph-oriented records using deterministic IDs:

Retrieval Modes in SuperOptiX

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

SurrealDB Across Modern Agent Frameworks

The same SurrealDB backend is exercised across all frameworks. The seed data, retrieval behaviour, and Gemini model stay the same - only the demo ID and --framework flag change.

Click any framework name in the table below to jump directly to its step-by-step implementation in the docs.

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

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

Agent Memory Beyond Retrieval

SurrealDB 3.0 is not only about vector search. SuperOptiX already exposes several pieces of its broader agent memory story.

A Practical SuperOptiX Configuration

One SurrealDB deployment backing RAG, multi retrieval, temporal memory, and read-only query access - all in one SuperSpec YAML.

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
      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

Explicit about what is covered well, what is partial, and what is not implemented yet.

Covered well today

Covered partially

Not implemented yet

The integration is already strong where it matters most for agent retrieval and memory, while being honest about what is still future work.

Production Notes

Why This Combination Matters

SuperOptiX Optimization - What's Coming

Conclusion

References