Surface, models, and security | Architecture

How to call SurrealDB Agent Memory, how models plug in, and how security properties attach to stored state.

Ingest and read (HTTP)

Two ingest families and one read family over a unified graph (same reconciler, same retrieval stack):

Verb	Purpose
`POST /api/v1/{ctx}/facts`	Text or triples, with `infer: "full" \\| "triples" \\| "preview" \\| "none"`.
`POST /api/v1/{ctx}/facts/batch`	Bulk conversation ingest (`messages: [{ role, content, ts }, …]`). Optional `extract`: `whole_conversation` (default) or `per_message`. Idempotent with `Idempotency-Key`.
`POST /api/v1/{ctx}/documents`	Byte ingest into the multi-modal pipeline (async).
`POST /api/v1/{ctx}/query`	Unified read over facts and passages. Accepts optional `labels`, `lens` (filters by scope-path involvement within the grant - does not shrink access to exact clause matches), and `scopeView` (`strict`, `merged`, or `crossTeam`) to control how broadly results are folded within what the caller is already allowed to see. `merged` resolves like `strict`; `crossTeam` adds the caller's inbound cross-principal read region when one exists, and otherwise also resolves like `strict`.
`POST /api/v1/{ctx}/chat`	Recall + LLM synthesis; SSE when streaming.

POST /api/v1/{ctx}/context accepts the same read parameters as /query. The MCP recall / context tools take them in snake_case (scope_view).

Trace listing: GET /api/v1/{ctx}/traces, GET /api/v1/{ctx}/traces/stats (supports windowHours for rolling operational aggregates), and GET /api/v1/{ctx}/traces/{id}. See Traces and memory evolution and REST API.

Integrations

Generated SDKs - Python (surrealdb) and TypeScript (@surrealdb/memory), both produced from SurrealDB Agent Memory’s OpenAPI specification so types track the server surface.
MCP over HTTP - tools wrapping the same handlers; shared Bearer auth. See MCP server.
Harness adapters - LangChain, Claude Code hook, OpenAI Agents, Vercel AI SDK, n8n - flush conversations into /facts/batch.

Model configuration (five hooks)

A Context config has five model settings, one per pipeline role, with model and cost recorded on traces. Each LLM stage takes {provider, model}. Not every setting is applied yet:

Extraction - turns and chunks → entities, attributes, relations, actions. Applied to document ingest on the worker; turn extraction on /facts uses the deployment default.
Embedding - vectors for entities, attributes, chunks. Fixed to gemini-embedding-2; no other value is accepted.
Reconciliation - stored but not applied. Reconciliation makes no model call.
Synthesis - stored but not applied. /chat and /reflect use the deployment default model, and /chat accepts a per-call model.
Elaboration / consolidation - applied to the background passes on the worker.

The supported providers are openai, anthropic, google, cerebras, and openrouter. The embedding model at write time must match read time within a Context; because only one embedding model is accepted, this holds by default. See Models per stage.

Security and privacy

Encryption - In transit: terminate TLS at your reverse proxy or load balancer (typical deployments run SurrealDB Agent Memory on HTTP behind the proxy). At rest: configure encryption on your SurrealDB storage backend and object-store bucket (for example KMS on S3 or GCS); SurrealDB Agent Memory inherits whatever those backends provide.
Graph-resident audit - writes emit decision_trace; reads emit retrieval_trace; /chat and /reflect emit response_trace. Together these record which caller asked what, against which scope, with which key, and which records were considered or returned.
Operational audit events - alongside the trace graph, SurrealDB Agent Memory emits structured audit events for reads, destructive operations (forget), scope changes, background jobs, and denied authorisation attempts so refused access is on the record even when no trace record is written.
Prompt-injection handling - ingest-time scanning on uploads and batched turns; untrusted text is sanitised before it is interpolated into extraction, chat, and consolidation prompts (see Extraction pipeline).
Chat transparency vs leakage - /chat may explain that it retrieved documents or memory and how it weighed them when asked. That is intentional for debugging in SurrealDB Studio. Production agents should not expose raw trace payloads, internal hostnames, or management URLs to end users; scope traces and audit events to operator roles instead. Adversarial "ignore previous instructions" prompts are mitigated on ingest; synthesis still depends on your model and system-prompt policy - treat /chat like any other LLM surface facing untrusted users.
Right to be forgotten - forget soft-deletes or purges per policy; supersession history optional for audit.

Inspectability and operational signals

Operators can derive:

Cost - tokens, model, latency from response_trace.
Cache hit rate - responses with reused_from set (tier 2 - fewer tokens spent).
Contradiction rate - uncertainty records per volume of writes, by source kind.
Source distribution - attributes by source.kind over time.
Supersession churn - decision_trace.superseded per entity.
Retrieval quality - candidate sizes and per-signal agreement from retrieval_trace.

See Traces and memory evolution for more details.