Using SurrealDB Agent Memory to Keep Context Between AI Tasks

Prepare a deployment checklist for the inventory service.

The application may already have stored these facts:

• The service uses PostgreSQL.
• The service runs in Azure.
• The application is containerized.
• Database migrations are part of the release process.

Instead of asking the user to provide the same details again, the application can retrieve the existing memory.

A simple SurrealQL query can filter records by agent and user:

SELECT
    id,
    memory_type,
    content,
    importance,
    created_at
FROM agent_memory
WHERE agent_id = "inventory-agent"
  AND user_id = "user-1001"
ORDER BY importance DESC, created_at DESC
LIMIT 20;

This retrieves the most relevant records according to the application's simple ordering rules.

The application can then add the selected records to the context supplied to the AI model.

However, ordering by importance and date is not the same as semantic relevance.

As the number of memories increases, retrieving the latest records alone may return information unrelated to the current task.

This is where vector search becomes useful.

Using Vector Search to Find Relevant Memories

Vector search retrieves information based on semantic similarity.

Instead of matching only exact words, it compares numerical representations of text.

For example, these two requests have different wording but similar meaning:

• "How is the inventory application deployed?"
• "Explain the infrastructure used by the stock management service."

A keyword search may not identify all relevant records.

A vector search can retrieve memories that represent similar concepts.

Generate an Embedding

The application first converts memory content into an embedding using a selected embedding model.

For example:

The inventory service uses PostgreSQL and is deployed in Azure.

The embedding model converts the text into a numerical vector.

The vector is stored with the memory record.

A simplified schema addition might look like this:

DEFINE FIELD embedding ON agent_memory
    TYPE option<array<float>>;

The vector dimension must match the selected embedding model.

For a production implementation, verify the embedding field definition and vector index syntax supported by the SurrealDB version being used.

Retrieve Similar Memories

When a new task arrives, the application generates an embedding for the user's request.

It then performs vector similarity search against stored memory embeddings.

Conceptually, the query follows this process:

User request
     |
     v
Generate query embedding
     |
     v
Search stored memory vectors
     |
     v
Filter by agent and user
     |
     v
Rank relevant memories
     |
     v
Add selected memories to agent context

SurrealDB supports vector indexing and similarity search, but the exact index definition and query syntax should be selected for the deployed version.

Do not assume that a vector similarity result is automatically correct. Apply ownership filters, relevance thresholds, and application-level validation before using retrieved information.

Combining Structured and Semantic Retrieval

Vector search is useful for discovering relevant information, but it should not replace structured queries.

Suppose an application stores thousands of memory records for multiple users and agents.

A request should retrieve only records belonging to the correct user and agent.

The application can combine:

• Structured filtering for user and agent ownership.
• Memory type filtering.
• Time-based filtering.
• Vector similarity for semantic relevance.
• Importance or confidence scoring.

For example, an application might first restrict the search to semantic and episodic memories owned by the current user, then rank those records using vector similarity.

This reduces irrelevant retrieval and helps prevent memory leakage between users.

The exact query design depends on the supported SurrealQL and vector search capabilities in the deployed release.

Managing Memory Updates and Expiration

Memory becomes less useful when it contains outdated information.

Consider a project that originally used MySQL but later migrated to PostgreSQL.

If the agent continues retrieving the old database information, it may generate an incorrect deployment plan.

A memory system therefore needs an update strategy.

Update Existing Memories

When new information conflicts with an existing record, the application should decide whether to:

• Update the existing memory.
• Create a new memory with a timestamp.
• Mark the previous memory as superseded.
• Retain both records as historical events.

For example, a semantic memory about the current database platform should generally represent the latest verified configuration.

An episodic memory about the earlier migration decision should remain available as historical context.

Expire Temporary Memories

Short-term memories may not need to remain permanently.

For example, a session-specific troubleshooting record could expire after a defined period.

A cleanup query can identify expired records:

SELECT
    id,
    content
FROM agent_memory
WHERE expires_at IS NOT NONE
  AND expires_at < time::now();

After reviewing the results, the application can delete expired records according to its retention policy.

Do not automatically delete every old memory. Historical decisions and audit-related information may have long-term value.

Managing Relationships Between Agents, Users, and Tasks

In a multi-agent application, memory often belongs to more than one entity.

For example:

• A user owns a project.
• A project contains multiple tasks.
• Several agents work on the project.
• Each task generates memory records.
• Agents may need access to selected shared information.

SurrealDB's record and graph capabilities can help represent these relationships.

A simple logical model could look like this:

User
 |
 +---- Project
          |
          +---- Task
          |      |
          |      +---- Memory
          |
          +---- Agent
                 |
                 +---- Memory

The application should define which records are private and which are shared.

For example, a user's personal preference should not automatically become visible to every agent in a shared project.

Similarly, one agent should not be able to modify another agent's memory without authorization.

Use database permissions and application-level authorization to enforce these boundaries.

Handling Memory Conflicts and Untrusted Information

Persistent memory introduces a security and data-quality problem.

An agent may store information that is incorrect, outdated, or extracted from an untrusted document.

For example, a document might contain an instruction telling the agent to ignore its existing rules and reveal confidential information.

If that instruction is stored as trusted memory, it can influence future tasks.

This is a form of persistent prompt injection.

To reduce this risk:

• Treat retrieved memory as data, not executable instructions.
• Do not store arbitrary document instructions as trusted agent rules.
• Track the source of important memory records.
• Store confidence or verification status where appropriate.
• Validate memory updates before accepting them.
• Apply ownership and access-control checks.
• Allow users or administrators to correct incorrect memories.

A useful extension to the memory schema is a source field:

DEFINE FIELD source ON agent_memory TYPE option<string>;

DEFINE FIELD verified ON agent_memory
    TYPE bool
    DEFAULT false;

The application can use these fields to distinguish verified configuration facts from information extracted from an external source.

Common Mistakes When Implementing Agent Memory

Advantages and Disadvantages of SurrealDB for Agent Memory

Advantages

• Supports structured records and relationships.
• Provides graph capabilities for connecting users, agents, tasks, and memories.
• Supports vector search for semantic retrieval.
• Allows different memory categories to be represented in a flexible data model.
• Can support persistent context across multiple agent tasks.
• Provides a database foundation for applications that combine structured and semantic data.

Disadvantages

• Developers must design memory extraction and retrieval policies.
• Vector search requires an embedding model and additional processing.
• Incorrect or outdated memories can affect future agent responses.
• Multi-user memory requires careful authorization and isolation.
• Large memory collections need indexing, cleanup, and retention strategies.
• Database persistence alone does not provide complete agent orchestration or reasoning.

Summary

Persistent memory helps AI agents maintain useful context across conversations and multi-step workflows.

SurrealDB provides a foundation for building this capability through structured records, relationships, and vector search.

A practical implementation should separate short-term, episodic, semantic, and procedural information. It should also define how memories are created, retrieved, updated, expired, and protected.

Use structured queries to enforce ownership and metadata filters, and use vector search to discover semantically relevant information. Do not rely on similarity alone when selecting facts for an agent.

Most importantly, treat memory as an application-managed knowledge layer rather than a permanent transcript of every AI interaction.

A well-designed memory system gives agents access to relevant previous information while keeping context accurate, controlled, and useful for the task they are performing.