Memory

Memory lets AI agents retain information about a user across conversations and use it to personalize future interactions. Without memory, agents start fresh with every conversation:

Lost context: agents lose context, requiring users to repeat information
Repetitive interactions: agents ask the same questions in every session
Missed opportunities: agents can’t provide personalized recommendations based on past behavior
Poor user experience: the experience may feel impersonal

How memory works

A user interacts with your agent. Memory then operates in these stages:

Retrieval (automatic). The agent loads memories for context in two modes: preload fetches recent memories at conversation start, preflight fetches query-relevant memories before each response.
Tools (optional). During a conversation, agents can use the following memory tools:
- algolia_memorize: saves semantic memories (facts, preferences)
- algolia_ponder: saves episodic memories (experiences, observations)
- algolia_memory_search: searches existing memories

For example, a user mentions “I’m vegetarian” in one conversation. In the next conversation, the user asks for restaurant recommendations. The agent recalls this preference and suggests vegetarian options.

Memory types

Agent Studio supports two types of memory, inspired by human cognitive architecture: semantic and episodic.

Semantic memory

Stores timeless facts, preferences, and general knowledge about the user. For example:

“User is allergic to peanuts”
“User prefers dark mode in apps”
“User lives in Madrid and speaks Spanish and English”
“User’s job title is Software Engineer”

Use cases:

User profile information
Preferences and settings
Dietary restrictions
Accessibility needs
Communication style

Semantic memory structure

JSON

{
  "text": "User prefers organic vegetables and shops at farmer's markets weekly",
  "rawExtract": "I love buying organic vegetables at the farmer's market every Saturday",
  "keywords": ["organic", "vegetables", "farmer's market", "weekly", "shopping"],
  "topics": ["food", "preferences", "shopping"],
  "recallTriggers": ["vegetables", "shopping habits", "organic food"],
  "memoryType": "semantic"
}

Semantic memories are self-contained facts that remain useful across conversations.

Episodic memory

Captures the agent’s reasoning chain from conversations. This includes what it observed, thought, did, and learned. Use episodic memory to extract meta-learnings for process improvement and analysis. Use episodic memory to understand the agent’s reasoning process. Agent Studio structures this information. It uses the OTAR pattern:

Observation: what happened (user input, context, problem)
Thoughts: why the agent chose this approach (reasoning, constraints)
Action: what the agent did (tool calls, responses, workflow)
Result: what happened and what the agent learned

Use cases:

Analyze agent performance across user segments
Identify successful problem-solving patterns
Review conversations to improve prompts and instructions
Answer questions like “How does prompt A perform for premium customers asking about returns?”

Episodic memory structure

JSON

{
  "text": "Experience: Resolved account lockout via password reset",
  "episode": {
    "observation": "User unable to log in despite correct password. Error: 'invalid credentials'. User tried 3 times.",
    "thoughts": "Account lockout likely triggered by security measure after multiple failed attempts. Password reset would unlock account, not just retry.",
    "action": "search_kb(query:'account locked') → found lockout policy → Explained 3-attempt limit → Sent password reset link → User confirmed receipt",
    "result": "User successfully logged in with new password. Learning: account locks after 3 failed attempts always require password reset."
  },
  "keywords": ["login", "account lock", "password reset", "security"],
  "topics": ["technical"],
  "memoryType": "episodic"
}

OTAR captures reasoning chains to inform similar future situations.

Enable memory

To enable memory, you must:

Enable the feature on your agent
Verify data retention
Set up user authentication

Enable on your agent

From the dashboard
With the API

From the Agent Studio agent edit view:

Open your agent’s settings
Go to the Customizations section
Find the Memory toggle
Click Configure to check prerequisites
Enable memory once you meet the prerequisites
Save changes

The dashboard validates prerequisites automatically. It also guides you through any missing configuration.

Enable memory when creating or updating an agent:

JSON

{
  "name": "My Agent",
  "config": {
    "memory": {
      "enabled": true,
      "toolsEnabled": true,
      "preload": {
        "limit": 10,
        "type": "semantic"
      },
      "preflight": {
        "limit": 5,
        "conversationWindow": 3
      }
    }
  }
}

enabled: activates memory retrieval
toolsEnabled: gives the agent access to memory tools
preload.limit: number of recent memories to load at conversation start
preload.type: "semantic", "episodic", or "all"
preflight.limit: maximum memories to retrieve per (semantic search)
preflight.conversationWindow: recent messages to use as search context

The memory configuration is nested inside config. It isn’t a top-level field.For more information, see the Agent Studio API reference.

Verify data retention

Memory learns from conversation history. To use it, you must store conversations (set the retention period to more than 0 days).From the Algolia dashboard, go to Agent Studio > Settings:

Check the Retention period is set to 30, 60, or 90 days. If you set it to 0, Algolia doesn’t store conversation history. As a result, memory can’t extract information from past conversations.

Retention applies to all agents in your Algolia application. Supported values are 0, 30, 60, and 90 days.

Application-wide setting: retention applies to all agents in your Algolia application, not individual agents.

You need this because:

Memory extracts information from past conversations A longer retention period helps memory. It gives memory more conversation history to draw on. It can then extract and combine more information from that history.
Longer retention enables better memory extraction and consolidation

A 30-day retention period balances memory quality, privacy, and compliance.

Set up user authentication

Memory requires user authentication. This identifies which user’s memories to load and save. Memory keeps stored information separate for each user.For complete setup instructions, see User authentication. This guide covers:

Getting your secret key from the dashboard
Generating JWTs (JSON Web Tokens) on your backend
Security guidance and token management

The same secure JWTs work for both memory and conversations. You might already have JWT authentication set up for conversations. If so, reuse that setup.

Set this up first. Then include the X-Algolia-Secure-User-Token header in your completion requests. This enables user-scoped memory:

JavaScript

const appID = "ALGOLIA_APPLICATION_ID";
const agentId = "AGENT_ID";
const apiKey = "ALGOLIA_SEARCH_API_KEY";

const response = await fetch(
  `https://${appID}.algolia.net/agent-studio/1/agents/${agentId}/completions`,
  {
    method: 'POST',
    headers: {
      'X-Algolia-Application-Id': appID,
      'X-Algolia-API-Key': apiKey,
      'X-Algolia-Secure-User-Token': userToken  // Enables user-scoped memory
    },
    body: JSON.stringify({
      messages: [{ role: 'user', content: 'Hello' }]
    })
  }
);

Memory tools

Set toolsEnabled to true to give your agent access to three memory tools. Each tool has default activation conditions that you can customize in the agent instructions

`algolia_memorize`

Saves semantic memories (facts and preferences) during conversation. Default triggers (built into tool prompt):

User explicitly says “remember X”
Agent detects a stable preference or fact (for example, dietary restrictions, account type)
User provides information useful for future interactions

For example, a user might say “I’m allergic to shellfish.” The agent then calls algolia_memorize. This saves the fact for later use.

`algolia_ponder`

Saves episodic memories (the agent’s reasoning chain) during conversation. Default triggers (built into tool prompt):

User says “remember this conversation” or “learn from this interaction”
After solving a problem worth learning from
After a successful workflow that could help similar future cases

For example, after resolving a support ticket, the agent calls algolia_ponder. It records what it observed. It also notes how it reasoned and what it did. It also records what it learned (OTAR pattern).

`algolia_memory_search`

Searches existing memories during conversation using Algolia Search. Default triggers (built into tool prompt):

Before claiming “I don’t know” about the user
Before answering questions about user preferences or history
When user asks “what did I say about X?”
When context from previous sessions would improve the response

For example, a user might ask “What restaurants would I like?” The agent then calls algolia_memory_search. This finds dietary preferences before the agent recommends anything.

Customizing tool behavior

The default triggers work for most cases. You can override them in your agent’s instructions:

# Memory guidelines
- Always ponder after resolving support tickets
- Memorize product preferences when users browse categories
- Never memorize payment information

This lets you control what the agent remembers and when.

Use cases

Personalize user experiences

Problem: generic responses don’t account for individual user preferences and context.Solution: memory enables agents to tailor responses. Agents base these responses on what they know about each user.For example, an ecommerce agent remembers a user’s size preferences and favorite brands. It also remembers past purchases. Then it provides relevant recommendations without asking repetitive questions.

Reduce repetitive questions

Problem: users get frustrated repeating the same information in every conversation.Solution: agents recall information shared earlier, eliminating redundant questions.For example, a support agent remembers a user’s account type and previous issues. It also remembers the preferred contact method. It then jumps straight to solving the current problem.

Improve agent performance through analysis

Problem: you can’t see how your agent reasons through problems. You also can’t identify what approaches work best.Solution: episodic memory captures the agent’s reasoning chain (OTAR) for each conversation. This enables analysis across user segments and scenarios.For example, you can export episodic memories. These come from users who mentioned “returns.” You might focus especially on those with premium accounts. Then, analyze how the agent handled those conversations:

Did it resolve return requests effectively?
Are there patterns in failed resolutions?

Enable continuous conversations

Problem: conversations reset with every new session, breaking continuity.Solution: memory retains user context between sessions. It does this even long after the initial conversation.For example, a user was considering a laptop last week. The shopping agent recalls this. It then proactively asks if they’re still interested. It also asks if they need more information.

How memory extraction works

When the agent calls a memory tool, Agent Studio doesn’t store the raw input. It runs the information through a quality filter, extracts the memory, and generates metadata before storing it. Quality filters evaluate whether information is useful enough to store.

Utility: would this fact improve future responses?
Specificity: is it concrete and factual (not mood or chitchat)?
Effect on behavior: can you think of a query where it changes behavior?

What gets extracted:

Factual statements about user preferences
Important events and interactions
Skills, knowledge, and relationships
Patterns inferred from past experiences

What gets filtered out:

Greetings and pleasantries (“Hello”, “I appreciate it”)
Generic traits without specifics (“User is friendly”)
Temporary moods or states
Duplicate information already stored

Memory lifecycle

Memory retrieval happens automatically before the agent generates a response. You can configure two retrieval modes: preload (recent memories) and preflight (query-relevant memories).

Retrieval modes compared

Feature	Preload	Preflight	Tools
Timing	Conversation start	Before each response	During response
Search method	Most recent N	Query-based semantic search	Agent-initiated
Extra latency	None	None	+1 roundtrip
Best for	Always-on context, few memories	Large memory sets (100+)	Dynamic, explicit recall

You can enable both modes together. Preload provides baseline context, and preflight adds query-specific memories.

Recent memories (preload)

Preload retrieves up to the configured number of recent memories when a conversation starts. It does this no matter what the user asks.

Identify user: extract user ID from the JWT token
Retrieve memories: fetch up to N recent memories (configurable limit)
Filter by type: semantic, episodic, or both
Include in context: the agent adds memories to its initial prompt

Configuration example:

JSON

{
  "memory": {
    "enabled": true,
    "preload": {
      "limit": 10,
      "type": "semantic"
    }
  }
}

When to use preload:

Small memory sets where all memories fit in context
Always-on personalization (user preferences should always be available)
Predictable use cases where recent memories are likely relevant

Query-based retrieval (preflight)

Preflight searches memories based on what the user is asking. It doesn’t rely on recency alone. It runs before the agent responds. It adds memories retrieved for the current query to the agent’s context. Configuration example:

JSON

{
  "memory": {
    "enabled": true,
    "preflight": {
      "limit": 5,
      "conversationWindow": 3
    }
  }
}

limit: maximum memories to retrieve per query
conversationWindow: number of recent messages to analyze for search context

When to use preflight:

Large memory sets (100+ memories) where loading all recent memories is less useful
Diverse memory content where only some memories apply to each query
When you want to maximize relevant context without wasting tokens

During conversation (tools)

Agents can dynamically save and search memories during the conversation. They do this using memory tools. For example, a user might report an error. It could be similar to one resolved before. The agent then calls algolia_memory_search to find past resolutions with matching symptoms.

Common integration issues

Memory not enabled - prerequisites not met

Symptoms: can’t enable memory toggle in dashboard.If you can’t enable the memory toggle in the dashboard, check the following:

Verify data retention is greater than 0 days
Ensure you have settingsRanking permission to modify retention settings

Solution: follow the configuration modal’s guidance to set up missing prerequisites.

Agent doesn't remember information

Symptoms: the agent doesn’t recall previous information. This happens even when memory is enabled.Possible causes:

No JWT token passed: conversations must include X-Algolia-Secure-User-Token header
Memory tools not enabled: set toolsEnabled: true in the agent configuration
Preload limit too low: increase the number of memories loaded at conversation start
Wrong memory type: if you set the preload type to semantic, episodic memories won’t load

Solution: verify JWT authentication is working, and ensure memory tools are enabled. Then, adjust your preload configuration.

Memories not relevant to user's query

Symptoms: the agent loads memories. They aren’t relevant to what the user is asking about.Possible causes:

Using preload with large memory sets: preload fetches recent memories, not the most relevant
Preflight not configured: query-based retrieval isn’t enabled

Solution: for users with many memories (100+), enable preflight to retrieve query-relevant memories:

JSON

{
  "memory": {
    "enabled": true,
    "preflight": {
      "limit": 5,
      "conversationWindow": 3
    }
  }
}

You can use both preload and preflight together. Preload provides baseline context, and preflight adds query-specific memories.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

How memory works

Memory types

Semantic memory

Episodic memory

Enable memory

Memory tools

`algolia_memorize`

`algolia_ponder`

`algolia_memory_search`

Customizing tool behavior

Use cases

How memory extraction works

Memory lifecycle

Retrieval modes compared

Recent memories (preload)

Query-based retrieval (preflight)

During conversation (tools)

Common integration issues

See also

​How memory works

​Memory types

​Semantic memory

​Episodic memory

​Enable memory

​Memory tools

​algolia_memorize

​algolia_ponder

​algolia_memory_search

​Customizing tool behavior

​Use cases

​How memory extraction works

​Memory lifecycle

​Retrieval modes compared

​Recent memories (preload)

​Query-based retrieval (preflight)

​During conversation (tools)

​Common integration issues

​See also

How memory works

Memory types

Semantic memory

Episodic memory

Enable memory

Memory tools

`algolia_memorize`

`algolia_ponder`

`algolia_memory_search`

Customizing tool behavior

Use cases

How memory extraction works

Memory lifecycle

Retrieval modes compared

Recent memories (preload)

Query-based retrieval (preflight)

During conversation (tools)

Common integration issues

See also