Skip to main content

Surreal Memory Server

Durable agent memory over SurrealDB, exposed through the Model Context Protocol.

The project ships two artifacts from one workspace:

ArtifactPathConsumers
Binarysrc/main.rsMCP clients over stdio or HTTP
Librarycrates/surreal-memory/universal-agent-runtime, uar-wisc

The library is the more important of the two. The binary is a thin MCP shell around it; the library is a direct dependency of the Universal Agent Runtime, so its MemoryStorage trait is a published interface rather than an internal detail.

What problem it solves​

Agents lose everything between turns. Naive fixes — dumping transcripts into a vector store, or stuffing history into the prompt — fail in predictable ways: retrieval returns the most recently written text rather than the most relevant, nothing distinguishes a durable fact from a passing remark, and there is no way to scope one user's memory away from another's.

This server treats memory as typed, scoped, and durable rather than as a bag of embeddings:

  • Typed — a decision, an error resolution, and a general fact are different kinds of memory with different retention and retrieval behavior.
  • Scoped — every memory belongs to a global, agent, user, session, or task scope, and reads are filtered by that scope rather than by convention.
  • Durable — writes go through a migration-governed SCHEMAFULL schema, with an audit trail, so a memory's history is reconstructable.

Capabilities​

  • Scoped memory with a mem0-compatible surface
  • Knowledge graph of entities and relations, with Graph-RAG traversal
  • Hybrid search combining BM25 full-text and HNSW vector indexes via reciprocal rank fusion
  • TaskStreams — token-budgeted context windows for long-running work
  • Mindmaps — structured graphs with export
  • Memory Palace (optional palace feature) — a second 384-dimension retrieval space
  • Durable operations — retry-safe writes with receipts, ordered events and operator controls
  • Verified caller scope — optional JWT authentication with one database per tenant, so a shared deployment cannot leak across tenants
  • Memory expiry — expired memory is invisible to every read immediately, and cleanup reports what it really removed
  • Evidence-backed compression — summaries whose claims quote their sources, with the sources archived rather than deleted

The MCP surface exposes 59 tools across these areas, and the REST API covers the same ground. Built and tested against SurrealDB 4.0.0.

Where to start​