A context layer is the part of your stack that gives every AI agent the facts it needs: current, connected, permissioned and traceable to a source. To build one, model your business as typed entities and relationships, and bring your systems of record into one store. Enforce permissions inside every query, keep the history of every fact, and give agents a single interface to reach it all.
This guide walks through why agents need a context layer, how it supports context engineering, why the usual approach fails in production, and how to build one in eight steps.
Key takeaways
Agents are only as good as the context they are given. The model supplies the intelligence, and everything it reasons about has to be supplied to it.
Most teams stitch context together from several separate stores, such as a vector database, transactional databases, a data platform and a graph database. The failures live in the seams between those stores, reducing accuracy, increasing LLM token usage, and impacting performance.
A governed context layer can answer four questions about every fact: who could see it, where it came from, when it held, and what was kept out.
Those four answers let security and legal approve more data for AI, which is where the value is.
What is a context layer, and how does it fit context engineering?
A context layer is the shared system that holds what your agents need to know and serves the right slice of it to each agent at the right moment. It sits between your systems of record and your agents. Context engineering is the practice of getting the right data, with the right permissions, to an agent at the right moment. The context layer is the infrastructure that context engineering runs on.
Context covers far more than documents. An agent doing real work needs facts too fresh for the model's training data. It needs to know who the user is and what they prefer. It needs the thread of the conversation, the state of the task, and a record of what it did earlier. Retrieval-augmented generation (RAG) is one tap into that material.
Context also comes in two kinds. Some matters only for the next step, like the document open right now. The rest has to persist: who the customer is, what turned out to be true, what the agent learnt last week. That second kind is memory, and it is harder, because it accumulates, ages and contradicts itself.
Our newsletter
Get tutorials, AI agent recipes, webinars, and early product updates in your inbox every two weeks
Why not put everything in the prompt?
Context windows keep growing, so it is tempting to send everything on every call. The prompt is rebuilt each time, so you pay again for every token on every turn. Models also attend unevenly to long inputs, and the one fact you needed gets lost in the middle. The memory features built into assistants such as ChatGPT and Claude do not close the gap either. They remember one person's preferences inside one product, and that memory does not travel to your other agents or to another model. It knows nothing about your systems of record. It also gives security no way to see who can read a fact, where it came from or when it stopped being true.
The prompt is where context is used. A context layer is where it lives.
Why do agents need a context layer now?
Large organisations are moving agents from pilots into production: copilots, support, operations and compliance. In a pilot, a person reads every answer and catches the wrong ones. In production, the agent acts on its own conclusions, and a wrong fact turns into a chain of confident, wrong decisions.
A memory that is missing fails loudly, and you fix it. A memory that is wrong fails quietly. Four failures cause most of the damage:
- 1.
Entity collision. Two suppliers with similar names merge into one, and the payment terms of one attach to the other.
- 2.
Silent overwrite. A new value replaces the old one, so nobody can say what was true on the day a decision was made.
- 3.
Scope leakage. A fact from one customer surfaces in a reply to another, because the boundary lived in application code that a new query path skipped.
- 4.
Untraceable answers. The agent reports a figure, and nobody can find the document or conversation it came from.
A stronger model fixes none of these. Each one is a property of how the context was stored.
Why do stitched stacks fail in production?
Most organisations build agent context today by wiring each agent to each system: a vector database for embeddings, several transactional databases, a data platform, and a graph database fed by ETL jobs. That arrangement causes five problems.
| Problem | What happens | Impact on agents |
|---|---|---|
| Integration sprawl | Every agent wires into every system | Inconsistent answers across agents |
| Copied, stale data | ETL copies drift from the source | Confident answers built on outdated facts |
| Context in pieces | Vectors, records and graph live apart | Missed connections and more hallucination |
| Permissions that do not travel | Each agent re-implements access rules | Data leaks, or answers blocked by caution |
| Siloed memory | Each agent keeps its own memory | Agents cannot learn from each other |
Teams usually try one of three arrangements to fix this. The first is a stitched stack of specialist stores. The second is one relational database with extensions for vectors and graph. The third is a memory product layered on top of several stores.
Each is a reasonable choice, and each leaves the context spread across parts that can fall out of step. A single new fact is a document, an embedding, some relationships and a summary row. Across separate stores, that is several writes with no shared all-or-nothing. The vector index can learn about a fact that the graph never hears of.
The instinct is to manage the seams better with synchronisation jobs, message buses and reconciliation. Those reduce the drift. The seams remain, and the seams were the fault.
What makes a context layer governed?
A governed context layer can answer four questions about every fact an agent uses. These are the questions security, legal and data owners ask before they approve an AI project:
- 1.
Who could see it? The boundary has to hold on every path, including vector search, even for a confused or manipulated agent.
- 2.
Where did it come from? Every claim should point at a sentence in a document, a turn in a conversation or a row in a system of record.
- 3.
Was it true then? Audits ask about the day a decision was made. The context layer has to know what held on that date.
- 4.
What was kept out? Card numbers, credentials and privileged advice should be refused before they are stored, with no copy left in a log or cache.
In most stacks each answer lives somewhere different: a filter in application code, a metadata field on a chunk, whatever the last write left behind. The honest answer to the approver is "probably", and nobody can sign that.
Governance here widens what AI may use. Once the four answers are properties of the data, the approver can say yes to the contracts, the support history and the client files, each under a rule that can be shown.
How to build a context layer in eight steps
1. Start from the questions agents must answer
List the decisions each agent supports and the questions behind them. "Is this supplier cleared?" "What did we agree with this client in March?" "Which open tickets touch this account?" The questions tell you which entities matter, which relationships to follow, and which facts change over time.
2. Map your systems of record and how each one arrives
Most of what a company knows sits in its product databases, CRM, ticketing system, data warehouse, wiki and chat. Choose an ingest path for each source:
Change data capture or streams for operational data that changes constantly.
Batch loads for warehouses and slower systems.
API pulls for on-demand lookups.
A document pipeline that chunks and embeds files, PDFs and wiki pages.
Connectors for conversations: chat, meetings, email and code.
Keep the source on every record as it arrives: the system, the key, and when it was read. That pointer is what makes an answer traceable later.
3. Model the business as an ontology
An ontology is a typed model of the things your business talks about and how they relate: customers, facilities, invoices, incidents. Agents then query meaning instead of raw tables, and two spellings of one client resolve to one entity.
On SurrealDB, an ontology is ordinary schema. Each entity type is a table, each relationship is a typed graph edge, and each record ID is a stable identity. Permissions sit on the same definitions.
-- Entities as typed tables, with a row-level permission
DEFINE TABLE customer SCHEMAFULL
PERMISSIONS FOR select WHERE region IN $auth.regions;
DEFINE FIELD name ON customer TYPE string;
DEFINE FIELD lei ON customer TYPE option<string>;
DEFINE FIELD region ON customer TYPE string;
DEFINE TABLE facility SCHEMAFULL;
DEFINE FIELD credit_limit ON facility TYPE decimal;
-- Relationships as typed graph edges, with their own validity
DEFINE TABLE holds TYPE RELATION IN customer OUT facility SCHEMAFULL;
DEFINE FIELD valid_from ON holds TYPE datetime;
-- An agent follows meaning, not joins
SELECT name, ->holds->facility.credit_limit AS limits
FROM customer:acme;Version the model like code. A change to how the business defines a customer deserves a review, the same as a change to the application. See Modelling a financial services enterprise ontology in SurrealDB for more examples.
4. Put every data model on one substrate
Agent context is multi-model by nature. One fact is a document, a vector, a set of graph edges and a point in time. Store all of them in one engine, and write them in one transaction, so a fact lands everywhere at once or not at all.
One engine removes the seams between separate stores. One hybrid query can then combine vector similarity, full-text keyword search, graph traversal and time filters against one consistent view. The agent receives the few facts that matter, in place of pages of loosely similar chunks.
That matters for cost as well as accuracy. Similar is not the same as relevant. The right fact often shares the exact identifier, follows a relationship, or holds on a given date, and an embedding sees none of those. Precise retrieval sends the model less, so every call costs less.
In a multi-hop graph traversal benchmark on SurrealDB 3.x (September 2026), three hops from a seed record reached 512 nodes. With filters applied at every hop, one query returned the 14 entities that mattered. The same result took 6 round trips and about 4,900 bytes when the traversal ran in application code, against 1 round trip and 241 bytes inside the database.
5. Enforce permissions inside the query
Put access rules in the database, next to the data, and evaluate them on every read for the person the agent acts for. The rule then travels with the data to every agent and every interface, and database permissions hold even when the LLM is jailbroken.
Check that the permission applies inside the vector search itself. A filter that only trims results after the nearest-neighbour search can still reveal, through counts and timing, that forbidden records exist. For a small tenant, the same filter often returns nothing at all, as shown in why a filtered vector search can return nothing.
Give each agent one narrowly scoped key, and let keys narrow access but never widen it. Decide separately what may enter at all: screen incoming text for card numbers, credentials and personal data before anything is stored.
6. Supersede facts instead of overwriting them
When a fact changes, keep the old version, dated and sourced, beside the new one. Link them, and close the old one's validity window. The context layer can then answer what is true now, what was true on a given date, and what the agent believed when it acted.
Track time on more than one clock. When a fact was true in the world often differs from when you learnt it. A client who moved in 2023 and told you in 2026 has a fact valid from 2023 and known from 2026.
7. Give agents a shared memory
Agents learn during their work: a preference stated in a meeting, a conclusion reached after three tool calls. Store that memory in the context layer, scoped and sourced like any other fact, so what one agent learns can reach the others it is meant to.
Treat memory as several kinds of fact, each with its own lifespan. A person's name should last for years. Last Tuesday's task state should fade. Record what the agent does not know yet as well, so it asks instead of guessing.
8. Give agents one interface, and measure retrieval
Expose the context layer through the interfaces your agents already use: an MCP server for assistants such as Claude and Cursor, SDKs, framework adapters and an HTTP API. Every agent then reaches the same context through the same rules.
Measure retrieval quality on its own, separately from the answering model. Change one variable at a time, and record the test protocol, the judge and the date beside every score.
Which architecture should you choose?
| Approach | Consistency across models | Where permissions live | History of facts | What you operate |
|---|---|---|---|---|
| Stitched stack of specialist stores | Several writes, no shared transaction | In each store and each agent | Depends on each store | Several systems and the glue between them |
| Relational database with extensions | One transaction, one native model | In the database | Built by hand | One database, several extensions to version together |
| Memory product over separate stores | Consolidated logic, data still split underneath | In the product's application tier | Varies | A service plus the stores under it |
| Native multi-model context layer | One transaction across every model | In the query, on every read | Kept by design | One engine |
Every option has a place. If your need is semantic search over a static set of documents, a vector database alone is the right tool. A single engine also has costs: a specialist store may tune its one task harder at extreme scale, and you take on a new query language. For agent context that spans documents, relationships, history and permissions, the seams usually cost more.
How do you build a context layer on SurrealDB?
SurrealDB builds the context layer from three parts, available self-hosted or in SurrealDB Cloud.
SurrealDB, the engine. Documents, graphs, vectors, relations, time series and live queries in one engine, with one query language, SurrealQL. Full-text search and row-level permissions apply to the same records.
The ontology. The typed model of your business, built as SurrealDB tables, typed graph relations and permissions.
SurrealDB Agent Memory, for memory. It is the governed context and memory layer. It extracts entities, builds the knowledge graph, keeps temporal facts with their sources, and runs hybrid retrieval. SurrealFS gives agents and people a shared file system for Markdown and documents, stored in SurrealDB. See Building a filesystem-based agent memory on SurrealDB for how it works.
Systems of record arrive through change data capture, batch loads, API pulls and the document pipeline. Conversations from chat, meetings, email and code arrive through Agent Memory's connectors. SurrealDB and Agent Memory share one graph. Agents reach it through the Agent Memory MCP server, SDKs, framework adapters, skills and hooks, or the HTTP API.
The result for the business:
More accurate agents. Answers rest on connected, current and permissioned facts, with their sources.
Faster answers. Agents call tools in loops, so every slow lookup is paid many times over. SurrealDB answers a context request in one query, without a round trip to each store or a merge step in application code.
Graph traversals without joins. Relations are stored as edges between records, so the engine follows them directly. Walking from a customer to its facilities, owners and open tickets stays fast as the graph grows, with no join tables to scan.
Hybrid search in one pass. Vector similarity, full-text relevance and graph filters run in the same query, with the permission rules applied as it runs. Results arrive already ranked, filtered and allowed.
Fewer tokens per answer. One hybrid query returns the relevant facts and relations, in place of pages of raw chunks.
One engine in place of several. Separate vector, graph and document stores are no longer needed.
Governed by default. Permissions live in the database, with the data.
Memory that compounds. Agents reuse what they already concluded, which saves tokens on repeat questions.
Frequently asked questions
What is context engineering?
Context engineering is the practice of deciding what information an agent receives at each step: which facts, from which sources, under which permissions. A context layer is the infrastructure that makes context engineering repeatable across every agent, instead of rebuilt inside each one.
What is the difference between a context layer and RAG?
RAG retrieves passages that are similar to a question. A context layer holds everything an agent needs, including identity, task state, relationships, history and permissions, and RAG is one way of reading from it.
What is the difference between a context layer and a semantic layer?
A semantic layer defines business metrics for analytics and dashboards. A context layer serves agents, so it also carries relationships, conversations, memory, provenance and per-person permissions.
Is a context layer the same as agent memory?
Agent memory is part of a context layer. The context layer also covers systems of record, documents and the rules on who may see what. Memory is the part that persists, changes and learns across sessions.
Do I need a graph database to build a context layer?
You need relationships that agents can follow, because the right fact is often one link away from the question. A multi-model engine stores those relationships as graph edges next to the documents and vectors, so you do not need a separate graph database.
How do I stop agents seeing data the user cannot see?
Enforce permissions in the database, and run every query the agent makes as the person it acts for. Make sure the rule applies inside vector search too, so a semantic match cannot surface a row that person could not open.
What happens when two sources disagree, or a fact changes?
Give each source a level of trust, so the system of record can outrank a chat message. When a fact changes, supersede the old version instead of deleting it, so you can still answer what was believed on any date.
How do I know a context layer is working?
Test retrieval separately from the model that writes the answer. Keep a set of real questions with known answers, run them as different users to check permissions, and record the date and method beside every score.
How does MCP relate to a context layer?
MCP, the Model Context Protocol, is how assistants such as Claude, ChatGPT and Cursor reach outside themselves. It is the interface. The context layer is what sits behind it and decides what each agent is handed.
Get started
Build your first governed context layer on SurrealDB.