Memory Steps

For common fields, string substitutions, metadata filters, caching, and execution order, see the Agent Steps Overview.

Memory

Memory gives agents the ability to remember information across runs. Unlike retrieval (which searches external knowledge bases), memory is a system-managed memory store that agents write to and read from automatically. Each memory bank controls its own embedding, compaction, and retention settings — create and manage them from the Memory Banks page.

How It Works

Each memory bank has its own content source that stores embedded entries — chunked, vectorized, and ready for similarity search — just like any other knowledge base content. The source is provisioned automatically when the bank is created.

Each memory entry is partitioned by a key (e.g. {{metadata.user_id}} for per-user memory, or a custom key for per-project or per-session scoping). This lets a single memory store serve many independent groupings without interference.

There are two memory bank types — but the same three unified step types work with both:

• Conversation banks — Designed for chat-style use cases. Entries are tagged with a speaker ("user" or "assistant"). The speaker field is required when writing to a conversation bank.
• General banks — Designed for facts, preferences, entity data, and standalone knowledge. No speaker concept — the speaker field is not used when writing to a general bank.

The bank type is determined automatically from the memory_bank_id — you don't need to choose different step types for different bank types.

The Three Memory Steps

Use Search when you want the most semantically relevant entries for a query. Use Load when you need the complete history in order (e.g. to summarize or compact it).

Key Concepts

• Key — A string that partitions memory entries. Use {{metadata.user_id}} for per-user memory, project-{{metadata.project_id}} for per-project memory, or any custom key. All search and load operations are automatically scoped to the specified key.
• Speaker (conversation banks only) — Each entry records who said what ("user" or "assistant"). Required when writing to a conversation bank; omitted for general banks.
• Metadata — Optional key-value pairs attached to memory entries. Metadata values are stored alongside the entry and can be used for filtering in search steps.
• Memory banks — Create and manage memory banks from the Memory Banks page or via the Public API and MCP tools. Each bank controls its embedding model, compaction prompt, and retention settings.

Common Patterns

Remember and Recall — The most common pattern. Search memory at the start of a workflow to inject past context, generate a response, then extract and store new facts for the next run.

Step 1: Search Memory (key: "{{metadata.user_id}}", query: "{{input}}")
  Step 2: Prompt Call — "Past context:\n{{input}}\n\nUser question: {{agent.input}}"
    Step 3: Prompt Call — "Extract new facts from this exchange"
      Step 4: Add Memory (key: "{{metadata.user_id}}", speaker: "assistant")
    Step 5: Streaming Result

Progressive Summarization — Periodically load the full history, summarize it, and store the summary as a compacted entry. This keeps memory manageable as conversations grow.

Step 1: Load Memory (key: "{{metadata.user_id}}", order: "oldest_first")
  Step 2: Prompt Call — "Summarize this conversation history into key points"
    Step 3: Add Memory (key: "{{metadata.user_id}}", speaker: "assistant")

Preference Learning — Extract user preferences from conversations and persist them for future personalization.

Step 1: Insight — "Extract any user preferences from: {{input}}"
  Step 2: Add Memory (key: "{{metadata.user_id}}")

Combined pattern (personalised chatbot — uses BOTH bank types):

The Add Memory step on a conversation bank already returns the conversation history as a messages array (see Conversation Bank Output Format), so there's no need for a Load Memory step after it — the history flows directly into the Prompt Call.

Step 1: Search Memory (general bank, key: "{{metadata.user_id}}") — recall preferences
  Step 2: Add Memory (conversation bank, key: "{{metadata.user_id}}", speaker: "user") — save user msg → returns history
    Step 3: Prompt Call — generate a personalised response using preferences + history
      Step 4a: Streaming Result
      Step 4b: Add Memory (conversation bank, key: "{{metadata.user_id}}", speaker: "assistant") — save reply
      Step 4c: Add Memory (general bank, key: "{{metadata.user_id}}") — store new preferences

Memory vs. Retrieval

Add Memory Step

Writes content to a memory bank. Each memory entry is embedded for vector search and partitioned by key, allowing agents to remember information across runs (e.g. user preferences, past decisions, accumulated facts). For conversation-type banks, the speaker field is also required.

Fields

Behavior

• The memory bank's content source is provisioned when the bank is created — no manual setup required.
• Memory entries are stored as content versions, chunked, and embedded for vector similarity search.
• The key is stored as metadata on each entry, allowing the search step to filter by key automatically.
• For conversation banks, the speaker field is stored as metadata, enabling you to distinguish who said what when loading or searching conversation history.
• The step's input is passed through as-is to child steps (the memory write is a side effect).
• Agent ID and agent run ID are automatically included in the entry's metadata for traceability.

Conversation Bank Output Format

When writing to a conversation bank, the Add Memory step returns the updated conversation history formatted as a JSON messages array — up to 100 entries in chronological order. The actual entries depend on the bank's compaction settings: compaction consolidates older entries into summaries, so the history you get back is the compacted version rather than raw individual messages:

[
  { "role": "user", "content": "What's the weather like?" },
  { "role": "assistant", "content": "It's sunny and 22°C today." },
  { "role": "user", "content": "Should I bring a jacket?" }
]

This format is directly compatible with a downstream Prompt Call that has use_step_input_as_messages: true (see Input as Messages). Each message is sent as a separate element in the LLM API call, which enables prompt caching on supported providers — the model caches the stable prefix of older messages and only processes the newest ones, reducing latency and cost on every turn.

Tip: For general banks, the step is a pass-through — the written content is returned as-is to child steps.

Use Case Examples

Save a conversation turn (conversation bank):

Step 1: Add Memory (key: "{{metadata.user_id}}", speaker: "user", content: "{{agent.input}}")

Chatbot pattern — add user message, respond, save assistant reply:

The most common conversational pattern. The Add Memory step saves the user's message and returns the full conversation history as a messages array. A Prompt Call with use_step_input_as_messages: true sends the history directly to the model (enabling prompt caching). The response is then delivered and saved in parallel.

Step 1: Add Memory (conversation bank, key: "{{metadata.user_id}}", speaker: "user", content: "{{agent.input}}")
  Step 2: Prompt Call (use_step_input_as_messages: true, system_template: "You are a helpful assistant.")
    Step 3a: Streaming Result
    Step 3b: Add Memory (conversation bank, key: "{{metadata.user_id}}", speaker: "assistant")

The Add Memory step in step 1 returns the conversation history as:

[
  { "role": "user", "content": "previous message..." },
  { "role": "assistant", "content": "previous reply..." },
  { "role": "user", "content": "current message" }
]

This flows directly into the Prompt Call, which sends each message individually to the model. Older messages form a stable prefix that providers can cache — only the newest message needs full processing.

Store user preferences (general bank):

Step 1: Prompt Call — "Extract any user preferences from: {{input}}"
Step 2: Add Memory (key: "{{metadata.user_id}}", content: "{{input}}")

Accumulate facts across runs:

Step 1: Insight — Extract key facts from the input content
Step 2: Add Memory (key: "project-{{metadata.project_id}}", entry_metadata: {"type": "fact"})

Search Memory Step

Searches a memory bank using vector similarity search. Retrieves memory entries previously written by the Add Memory step, optionally scoped to a key. This allows agents to recall past context — such as user preferences, previous decisions, or accumulated knowledge — and use it in the current run.

Fields

Behavior

• When a key is provided, the search is scoped by injecting {"key": {"$eq": "<key>"}} as a metadata filter. Any user-supplied filter is combined with this using $and.
• Output format matches the retrieval step: JSON returns {"matches": [...]} with content_title, content, content_url, content_publish_date, etc. For application/xml, the response body is still JSON (coerced to match retrieval behavior).
• If no memory entries exist yet (first run), the search returns an empty matches array.
• The memory bank's content source is provisioned when the bank is created.

Use Case Examples

Recall user preferences before generating a response:

Step 1: Search Memory (key: "{{metadata.user_id}}", query: "user preferences")
  Step 2: Prompt Call — "Using these remembered preferences: {{input}}\n\nAnswer: {{agent.input}}"

Search memories with metadata filtering:

Step 1: Search Memory (
  key: "project-{{metadata.project_id}}",
  query: "{{input}}",
  filter: {"category": {"$eq": "decision"}},
  top_n: 20
)

Time-bounded memory recall:

Step 1: Search Memory (
  key: "{{metadata.user_id}}",
  query: "{{input}}",
  added_after: "{{1 week ago}}",
  top_n: 5
)

Cross-key search (no key):

Step 1: Search Memory (query: "{{input}}", top_n: 10)
  Step 2: Prompt Call — "Based on this knowledge: {{input}}\n\nAnswer: {{agent.input}}"

Building a Memory-Augmented Agent

Combine the write and search steps to create agents with persistent memory:

Example: Full memory-augmented Q&A agent:

Step 1: Search Memory (key: "{{metadata.user_id}}", query: "{{input}}")
  Step 2: Prompt Call — "Past context:\n{{input}}\n\nUser question: {{agent.input}}\n\nAnswer the question, referencing past context where relevant."
    Step 3: Prompt Call — "Extract any new facts or preferences from this exchange:\nQ: {{agent.input}}\nA: {{input}}"
      Step 4: Add Memory (key: "{{metadata.user_id}}", content: "{{input}}")
    Step 5: Streaming Result

This agent: searches memory for relevant past context, generates a response, extracts new facts from the exchange, and stores them for future runs.

Load Memory Step

Loads all memory entries for a key in chronological order. Unlike the Search Memory step (which performs vector similarity search), this step retrieves the full list of entries ordered by creation time. Use this when you need the complete entry set rather than the most semantically relevant matches.

Fields

Behavior

• No vector search is performed — entries are retrieved by creation date in the specified order.
• The key is matched exactly against entry metadata.
• JSON output returns {"entries": [...]} with each entry containing content and created_at.
• Text output returns entries separated by --- dividers.
• If no entries exist for the given key, an empty result is returned.
• This is a composite step — it supports child steps that receive the loaded entries as input.

Conversation Bank Output Format

When loading from a conversation bank, the Load Memory step auto-detects conversation entries and formats the output as a JSON messages array — the same format used by Add Memory:

[
  { "role": "user", "content": "Hello" },
  { "role": "assistant", "content": "Hi! How can I help?" },
  { "role": "user", "content": "Tell me about prompt caching" }
]

This is directly compatible with a downstream Prompt Call that has use_step_input_as_messages: true (see Input as Messages). Use order: "oldest_first" so the oldest messages form a stable prefix that providers can cache — using newest_first would change the prefix on every turn, defeating the cache.

Tip: For general banks, the output is a JSON array of [{"content", "title"}] objects.

Use Case Examples

Load full history for summarisation:

Step 1: Load Memory (key: "{{metadata.user_id}}", order: "oldest_first")
  Step 2: Prompt Call — "Summarise the following conversation history: {{input}}"
    Step 3: Add Memory (key: "{{metadata.user_id}}", speaker: "assistant")

Load recent entries for context:

Step 1: Load Memory (key: "{{metadata.user_id}}", order: "newest_first", limit: 10)
  Step 2: Prompt Call — "Based on recent context: {{input}}\n\nAnswer: {{agent.input}}"

Export entries as plain text:

Step 1: Load Memory (
  key: "project-{{metadata.project_id}}",
  order: "oldest_first",
  limit: 1000,
  content_type: "text/plain"
)

Load all preferences before generating a personalised response:

Step 1: Load Memory (key: "{{metadata.user_id}}", order: "newest_first")
  Step 2: Prompt Call — "Given these user preferences: {{input}}\n\nAnswer: {{agent.input}}"

Load vs Search: When to Use Each

← Back to Agent Steps Overview