---
title: "Surface, models, and security"
description: "HTTP ingest and read verbs, integrations, and model hooks. Security properties are covered too."
canonical_url: "https://surrealdb.com/docs/agent-memory/learn/architecture/surface-security-and-models"
section: "Agent Memory"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Surface, models, and security

HTTP ingest and read verbs, integrations, and model hooks. Security properties are covered too.

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](/docs/agent-memory/learn/architecture/traces-and-evolution.md) and [REST API](/docs/agent-memory/reference/rest-api.md).

## 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](/docs/agent-memory/integrations/mcp-server/install.md).
- **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:

1. **Extraction** - turns and chunks → entities, attributes, relations, actions. Applied to document ingest on the worker; turn extraction on `/facts` uses the deployment default.
2. **Embedding** - vectors for entities, attributes, chunks. Fixed to `gemini-embedding-2`; no other value is accepted.
3. **Reconciliation** - stored but not applied. Reconciliation makes no model call.
4. **Synthesis** - stored but not applied. `/chat` and `/reflect` use the deployment default model, and `/chat` accepts a per-call `model`.
5. **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](/docs/agent-memory/learn/tuning/models-per-stage.md).

## 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](/docs/agent-memory/learn/reasoning/extraction-pipeline.md#untrusted-metadata-in-prompts)).
- **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](/docs/agent-memory/learn/architecture/traces-and-evolution.md) for more details.
