Skip to main content

​
Overview

Memory nodes enable stateful conversations by storing and retrieving chat history for LLM nodes.

Chat Memory Node

Store and retrieve conversation history with automatic trimming and summarization

​
Chat Memory Node

Purpose: Manage chat history and conversation context Memory nodes store and retrieve conversation history for LLM nodes, enabling stateful conversations.
Memory node visual representation
Memory node visual representation

​
Configuration

​
Chat Memory Node

​
Common Configuration

Description: A user-defined name to identify this memory node in your workflow.Type: StringRequired: YesExample:
"Conversation Memory"
"Support Chat History"
"Session Context"
Description: Choose how the memory size should be limited.Type: SelectRequired: YesDefault: MessagesOptions:
  • By Message Count - Keep last N messages
  • By Token Count - Keep messages within token limit
When to Use:
  • Message Count: Simple, predictable memory management
  • Token Count: Precise control for model context windows
Description: The content to store as the user message in chat history.Type: Editor (Pongo template)Required: YesDefault: {{ start | json }}How It Works: Defines what gets stored as the user’s message. By default captures the start node input.Example:
{{ start | json }}
{{ start.query }}
{{ start.user_input }}
Use Pongo templates to extract specific fields from the start node input.
Description: Unique identifier for this chat/conversation session.Type: Editor (Pongo template)Required: YesHow It Works: Groups messages into conversations. Same Chat ID = same conversation history.Template Variables: Use variables to create isolated contexts per user/session.Examples:
{{ start.chat_id }}
user-{{ start.user_id }}-session-{{ start.session_id }}
{{ start.external_chat_id }}
workflow-{{ workflow_request.id }}
Multi-User Support: Use user IDs in Chat ID to isolate conversations between different users.
Description: How to select which messages to remove when trimming.Type: SelectRequired: YesDefault: Drop OldestOptions:
  • Drop Oldest (keep recent) - Remove oldest messages first, keep most recent
  • Drop Middle (keep first & recent) - Keep first few messages + most recent, remove middle
When to Use:
  • Drop Oldest: Standard conversations - recent context most important
  • Drop Middle: Preserve initial context (system instructions, persona) + recent messages
Description: Empty all tool result contents before trimming to reduce token count.Type: BooleanRequired: NoDefault: falseHow It Works: Preserves tool call structure (names, arguments) but removes result content to save tokens.Use Case: Long tool outputs (API responses, file contents) that don’t need to be kept in context.Example:
Before: { tool_name: "search", result: "...5000 tokens..." }
After:  { tool_name: "search", result: "" }
Description: Summarize removed messages to preserve context when trimming.Type: BooleanRequired: NoDefault: falseHow It Works: Before trimming old messages, send them to LLM for summarization. Replace trimmed messages with summary.Benefits:
  • Preserve important context from old messages
  • Reduce token count while maintaining conversation continuity
  • Keep decisions, facts, and key points
Cost: Additional LLM API call for each summarization.
Description: Instructions for how to summarize removed messages.Type: EditorRequired: NoDefault: “Summarize the key points of the removed messages, preserving important context and decisions made.”Visibility: Only when Enable Summarization = trueBest Practices:
  • Be specific about what to preserve
  • Mention format preferences
  • Guide tone and style
Example:
Summarize the key points from these messages:
- Important decisions made
- Facts and data mentioned
- User preferences expressed
- Ongoing context needed for future messages

Keep the summary concise (under 200 tokens).
Description: Include predefined messages at the beginning of the memory context.Type: BooleanRequired: NoDefault: falseUse Cases:
  • Few-shot examples (show LLM example conversations)
  • Persona messages (establish character/tone)
  • Initial instructions (supplement system prompt)
  • Conversation templates
Description: Custom messages to add at the beginning of the memory context.Type: Memory Messages BuilderRequired: NoDefault: []Visibility: Only when Use Predefined Messages = trueHow It Works: These messages appear before actual chat history. They’re combined with chat history and subject to trimming limits.Format:
[
  {
    "role": "user",
    "content": "How do I reset my password?"
  },
  {
    "role": "assistant",
    "content": "To reset your password, visit the account settings page..."
  }
]
Use Cases:
  • Few-shot learning: Show examples of desired responses
  • Persona: Establish assistant personality through example exchanges
  • Instructions: Add context that supplements system prompt
Use predefined messages sparingly - they count toward your token limit and can be trimmed.

​
Message Limit Configuration

These fields appear when Memory Limit Type = “By Message Count”
Description: When to trim old messages from memory.Type: SelectRequired: NoDefault: ContinuousOptions:
  • Continuous (trim at limit) - Remove oldest message immediately when limit reached
  • Threshold (batch trim) - Wait until threshold reached, then batch trim to target
When to Use:
  • Continuous: Standard conversations, predictable memory size
  • Threshold: High-volume chats, reduce trimming overhead
Example:
Continuous: Always keep exactly 20 messages
Threshold: Keep up to 500 messages, trim to 100 when reached
Description: Maximum number of messages to retain in memory.Type: NumberRequired: YesDefault: 20Visibility: Only when Trim Mode = “Continuous”Example:
20   # Keep last 20 messages
50   # Keep last 50 messages
100  # Keep last 100 messages
Description: Number of messages that triggers batch trimming.Type: NumberRequired: YesDefault: 500Visibility: Only when Trim Mode = “Threshold”How It Works: When message count reaches this threshold, trim down to “Threshold Target” value.Example:
500  # Trim when 500 messages accumulated
Description: Number of messages to keep after threshold trimming.Type: NumberRequired: YesDefault: 100Visibility: Only when Trim Mode = “Threshold”Example:
100  # Keep 100 messages after trimming
Threshold Example: Trigger=500, Target=100 means: Let messages grow to 500, then trim down to 100 most recent.
Description: Maximum number of images to retain in memory.Type: NumberRequired: NoDefault: 1How It Works: Images consume significant tokens. This limits how many image messages to keep.Example:
1   # Keep only last image
3   # Keep last 3 images
0   # Remove all images from memory
Images can be 500-2000 tokens each. Limit image retention to manage token usage.

​
Token Limit Configuration

These fields appear when Memory Limit Type = “By Token Count”
Description: Maximum number of tokens to retain in memory.Type: NumberRequired: YesDefault: 2000How It Works: Automatically counts tokens in messages and trims oldest when limit exceeded.Model Context Windows:
  • GPT-4o: 128K tokens
  • Claude 3.5 Sonnet: 200K tokens
  • GPT-3.5 Turbo: 16K tokens
Recommendation: Leave headroom for system prompt and response (e.g., use 4000 tokens for 8K context model).Example:
2000   # Standard short conversations
4000   # Medium conversations
10000  # Long context conversations
Description: Minimum number of messages to keep even if they exceed token limit.Type: NumberRequired: NoDefault: 0Use Case: Ensures critical recent context is never trimmed, even if messages are very long.Example:
0   # No minimum (strict token limit)
5   # Always keep at least 5 messages
10  # Always keep at least 10 messages

​
Add Memory Node

Manually add messages to chat memory (for programmatic memory injection).
Description: Name to identify this Add Memory node.Type: StringRequired: Yes
Description: Select which Chat Memory node to add messages to.Type: Select (Dynamic)Required: YesOptions: Shows Chat Memory nodes from your workflow (backward nodes only)
Description: Chat/conversation ID to add the message to.Type: Editor (Pongo template)Required: YesExample:
{{ request.external_chat_id }}
user-{{ start.user_id }}
Description: Message role (user or assistant).Type: SelectRequired: YesOptions:
  • User - Message from the user
  • Assistant - Message from the AI assistant
Description: The message content to add.Type: Editor (Pongo template)Required: YesExample:
{{ start.user_message }}
Generated summary: {{ summary_result }}
Description: Toggle to enable attaching files to this message.Type: BooleanRequired: NoDefault: false
Description: List of files to attach to the message.Type: Editor (JSON)Required: NoVisibility: Only when Enable Files = trueFormat:
{
  "files": [
    {
      "url": "https://example.com/file.pdf",
      "metadata": {},
      "file_name": "document.pdf",
      "file_size": 123456,
      "content_type": "application/pdf"
    }
  ]
}

​
Get Memory Data Node

Retrieve messages from chat memory for inspection or processing.
Description: Name to identify this Get Memory Data node.Type: StringRequired: Yes
Description: Select which Chat Memory node to retrieve data from.Type: Select (Dynamic)Required: YesOptions: Shows Chat Memory nodes from your workflow
Description: Chat/conversation ID to retrieve messages from.Type: Editor (Pongo template)Required: YesExample:
{{ request.external_chat_id }}
Description: Maximum number of messages to retrieve.Type: NumberRequired: NoDefault: 50Example:
50   # Get last 50 messages
100  # Get last 100 messages
Description: Number of messages to skip from the beginning.Type: NumberRequired: NoDefault: 0Use Case: Pagination - retrieve messages in chunks.Example:
0    # Start from beginning
50   # Skip first 50 messages
100  # Skip first 100 messages

​
Delete Memory Node

Remove messages from chat memory.
Description: Name to identify this Delete Memory node.Type: StringRequired: Yes
Description: Select which Chat Memory node to delete from.Type: Select (Dynamic)Required: YesOptions: Shows Chat Memory nodes from your workflow
Description: Chat/conversation ID to delete messages from.Type: Editor (Pongo template)Required: YesExample:
{{ request.external_chat_id }}
Description: How to select which messages to delete.Type: SelectRequired: YesOptions:
  • By Latest Workflow Request - Delete messages from the most recent workflow execution
  • All - Delete all messages from this chat
When to Use:
  • By Latest: Undo last interaction
  • All: Reset conversation, clear history
Description: Which message roles to delete.Type: Multi-SelectRequired: YesOptions:
  • User - Delete user messages
  • Assistant - Delete assistant messages
Example:
  • Select both: Delete all messages
  • Select User only: Keep assistant responses, remove user inputs
  • Select Assistant only: Keep user inputs, remove assistant responses

​
Node Handles

Memory nodes use a special bidirectional connection to the LLM’s MEMORY handle. They don’t have traditional PARALLEL or ERROR output handles - the memory connection handles all data flow.

​
Memory Limit Types

Keep last N messages
  • Simple message-based trimming
  • Maintains recent context
  • Predictable memory usage
Example: Keep last 10 messages

​
Summarization

When messages are trimmed, enable summarization to condense old context: 
{
  "enable_summarization": true,
  "summarize_prompt": "Summarize the key points from this conversation..."
}
The summarization runs automatically and replaces trimmed messages with a concise summary, preserving important context while reducing token usage.

​
Chat IDs

Memory nodes use Chat IDs to group conversations: 
chat_id: "user-{{user_id}}-session-{{session_id}}"
This enables:
  • Multi-user conversations
  • Session management
  • Conversation history across workflow executions
  • Isolated contexts per user/session
Use template variables in Chat ID to dynamically create isolated conversation contexts for each user or session.

​
What’s Next?

AI Nodes

Learn how LLM nodes use memory for context

Variable Mappings

Use templates in chat IDs and prompts

Chats

Explore the Chats feature for end-user conversations

Back to Overview

Return to nodes overview