Skip to main content

Quickstart

Run the server locally, store a memory, find it again, and connect an MCP client. Every command on this page was run against a real server.

1. Start the server​

For a single machine with an embedded database:

export SURREAL_MODE=embedded
export SURREAL_PATH="$HOME/.surreal-memory/db"
export EMBEDDING_PROVIDER=local # BAAI/bge-small-en-v1.5, 384 dimensions
export API_PORT=3001

cargo build --release --features embedded,local-embeddings
./target/release/surreal-memory-server

With no other settings the server binds to 127.0.0.1 in AUTH_MODE=local, which serves an unauthenticated API for the trusted local client. To run a database server instead, use SURREAL_MODE=server and see Configuration.

Check it is up:

curl -s http://127.0.0.1:3001/health
# {"service":"surreal-memory-server","status":"ok","version":"1.11.0"}

curl -s http://127.0.0.1:3001/ready
# {"capabilities":{"coordinator":true,"ledger":true,"model_executor":true,
# "search_index":true,"storage":true,"tokenizer":true},"status":"ready", ...}

/ready reports 503 until the database handle and embedding model are usable.

2. Store a memory​

curl -s -X POST http://127.0.0.1:3001/api/v1/memory \
-H 'content-type: application/json' \
-d '{
"content": "Alice prefers dark mode in the editor",
"user_id": "alice",
"agent_id": "claude-code",
"categories": ["preference"]
}'

The response is the stored memory, with version: 1, a memory_type of semantic, and an id you can use for GET, PUT, DELETE and /history:

{
"id": { "table": "memory", "key": { "String": "949ae93e-62b2-467a-8937-51739d240d9a" } },
"content": "Alice prefers dark mode in the editor",
"user_id": "alice",
"agent_id": "claude-code",
"categories": ["preference"],
"memory_type": "semantic",
"importance": 0.5,
"version": 1
}

In a URL the id is memory:<key> or just <key>:

curl -s http://127.0.0.1:3001/api/v1/memory/memory:949ae93e-62b2-467a-8937-51739d240d9a

Hybrid search merges BM25 and vector results by reciprocal rank fusion, so the query does not need to share words with the memory:

curl -s -X POST http://127.0.0.1:3001/api/v1/search \
-H 'content-type: application/json' \
-d '{"query": "editor theme", "user_id": "alice", "limit": 3}'

Embedding vectors are left out of the response unless you pass "include_embeddings": true.

4. Connect an MCP client​

Over HTTP, point the client at the streamable endpoint:

{
"mcpServers": {
"surreal-memory": { "type": "http", "url": "http://127.0.0.1:3001/mcp/http" }
}
}

Over stdio, run the binary as the server process (the default when MCP_STDIO is not false):

{
"mcpServers": {
"surreal-memory": {
"command": "/usr/local/bin/surreal-memory-server",
"env": { "SURREAL_MODE": "embedded", "SURREAL_PATH": "/Users/me/.surreal-memory/db" }
}
}
}

The legacy SSE transport is at /mcp/sse and /mcp/messages. See MCP tools for the tools and example calls.

Next​