SurrealDB Agent Memory exposes a REST API over HTTPS at your context host. Every SDK and harness adapter maps to these endpoints, so you can integrate from any language that can make HTTP requests.
URL structure
Your context host, shown in the SurrealDB Studio API keys view, serves:
| Path | Purpose |
|---|---|
/api/v1/{context_id}/... | End-user operations: facts, documents, query, chat, sessions, traces |
/api/v1/health | Liveness |
/mcp | MCP server (Streamable HTTP); same Bearer auth |
The {context_id} segment is the context id shown in the same view.
Authentication
Authorization: Bearer <api_key>Do not send a raw secret without the Bearer prefix. Every key is bound to one Context, and its scopes decide what it can read and write.
Optional on writes:
Idempotency-Key: <stable-id>The four verbs
| Verb | Endpoint | When to use |
|---|---|---|
| Remember | POST /api/v1/{ctx}/facts, POST .../facts/batch | Conversations, single facts, harness batch capture |
| Upload | POST /api/v1/{ctx}/documents | PDFs, manuals, code, media |
| Recall | POST /api/v1/{ctx}/query | Ranked hits over the unified substrate |
| Chat | POST /api/v1/{ctx}/chat | Let SurrealDB Agent Memory run recall + synthesis |
For formatted prompt text without raw hit lists, use POST /api/v1/{ctx}/context.
Example: remember and recall
export AGENT_MEMORY_ENDPOINT=https://<your-context-host>
export AGENT_MEMORY_API_KEY=<context-key>
export AGENT_MEMORY_CONTEXT=<your-context-id>
curl -sS "$AGENT_MEMORY_ENDPOINT/api/v1/$AGENT_MEMORY_CONTEXT/facts" \
-H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Alice was promoted to CTO.","infer":"full","scopes":["org/acme/user/alice"]}'
curl -sS "$AGENT_MEMORY_ENDPOINT/api/v1/$AGENT_MEMORY_CONTEXT/query" \
-H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"What is Alice'\''s role?","k":10,"lens":["org/acme/user/alice"]}'The agent-memory CLI wraps the same paths (agent-memory remember, agent-memory recall, agent-memory chat).
Full reference
Endpoint tables, session introspection routes, document APIs and traces are documented in REST API reference.