langchain-surrealdb 0.2.1

An integration package connecting SurrealDB and LangChain

The official SurrealDB components for LangChain

       

     

langchain-surrealdb

This package contains the LangChain integration with SurrealDB

SurrealDB is a unified, multi-model database purpose-built for AI systems. It combines structured and unstructured data (including vector search, graph traversal, relational queries, full-text search, document storage, and time-series data) into a single ACID-compliant engine, scaling from a 3 MB edge binary to petabyte-scale clusters in the cloud. By eliminating the need for multiple specialized stores, SurrealDB simplifies architectures, reduces latency, and ensures consistency for AI workloads.

Why SurrealDB Matters for GenAI Systems

• One engine for storage and memory: Combine durable storage and fast, agent-friendly memory in a single system, providing all the data your agent needs and removing the need to sync multiple systems.
• One-hop memory for agents: Run vector search, graph traversal, semantic joins, and transactional writes in a single query, giving LLM agents fast, consistent memory access without stitching relational, graph and vector databases together.
• In-place inference and real-time updates: SurrealDB enables agents to run inference next to data and receive millisecond-fresh updates, critical for real-time reasoning and collaboration.
• Versioned, durable context: SurrealDB supports time-travel queries and versioned records, letting agents audit or “replay” past states for consistent, explainable reasoning.
• Plug-and-play agent memory: Expose AI memory as a native concept, making it easy to use SurrealDB as a drop-in backend for AI frameworks.

Installation

Python 3.10+ is required.

# -- Using pip
pip install -U langchain-surrealdb surrealdb
# -- Using uv (preferred for contributors)
uv add langchain-surrealdb surrealdb

Graph QA extra

Experimental graph QA helpers depend on langchain-classic. Install the extra if you plan to use them:

pip install -U "langchain-surrealdb[graph-qa]"

Local development with uv

# install all dependency groups and extras
uv sync --all-groups --all-extras
# run the test suite
uv run pytest
# run formatting + lint checks
make lint

To exercise the included examples:

• cd examples/basic && uv sync && uv run python main.py
• cd examples/graph && uv sync && uv run python graph.py

Requirements

You can run SurrealDB locally or start with a free SurrealDB cloud account.

For local, two options:

1. Install SurrealDB and run SurrealDB. Run in-memory with:

surreal start -u root -p root

2. Run with Docker.

docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start

Simple example

from langchain_core.documents import Document
from langchain_surrealdb.vectorstores import SurrealDBVectorStore
from langchain_ollama import OllamaEmbeddings
from surrealdb import Surreal

conn = Surreal("ws://localhost:8000/rpc")
conn.signin({"username": "root", "password": "root"})
conn.use("langchain", "demo")
vector_store = SurrealDBVectorStore(OllamaEmbeddings(model="llama3.2"), conn)

doc_1 = Document(page_content="foo", metadata={"source": "https://surrealdb.com"})
doc_2 = Document(page_content="SurrealDB", metadata={"source": "https://surrealdb.com"})

vector_store.add_documents(documents=[doc_1, doc_2], ids=["1", "2"])

results = vector_store.similarity_search_with_score(
    query="surreal", k=1, custom_filter={"source": "https://surrealdb.com"}
)
for doc, score in results:
    print(f"* [SIM={score:3f}] {doc.page_content} [{doc.metadata}]")

Next steps

• look at the basic example. Use the Dockerfile to try it out!
• look at the graph example
• try the jupyter notebook
• Awesome SurrealDB, A curated list of SurrealDB resources, tools, utilities, and applications