Memory Action 🧠

Reads from or writes to persistent AI conversation memory.

Node type: memoryAction Category: AI Actor: memoryAction (1 thread)

---

Description

The Memory Action node provides explicit control over the AI conversation memory system. While the AI Task automatically uses memory when configured, the Memory Action node lets you directly manage memory records — creating conversations, storing messages, retrieving history, and clearing memory.

Use Memory Action to:

• Pre-load context into a conversation before the first AI Task
• Read conversation history for summarization
• Clear memory after a workflow completes
• Store workflow-specific context for multi-session workflows
• Build context from structured data (e.g., store customer history as AI memory)

---

Memory Architecture

Memory is stored in two tables:

• ai_memory_conversation — a named conversation with configuration (max messages, type)
• ai_memory_message — individual messages within a conversation (role: user / assistant / system)

Conversations are identified by a conversation_id. The AI Task references this ID to load context.

---

Properties

The Memory Action's properties depend on the operation being performed. The operation is selected in the properties panel:

Operation	Description
CREATE_CONVERSATION	Create a new conversation memory slot
STORE_MESSAGE	Add a message to an existing conversation
READ_HISTORY	Retrieve message history from a conversation
CLEAR_CONVERSATION	Delete all messages from a conversation
DELETE_CONVERSATION	Delete the conversation and all its messages

---

Operations

CREATE_CONVERSATION

Creates a new conversation memory slot.

Properties:

Property	Description
conversationId	Unique ID for this conversation (use a variable like {sessionId})
conversationType	CHAT, WORKFLOW, or AGENT
maxMessages	Maximum messages to retain (sliding window)

Output: Sets {memoryConversationId} with the created conversation ID.

---

STORE_MESSAGE

Adds a message to a conversation.

Properties:

Property	Description
conversationId	Target conversation ID
role	user, assistant, or system
content	Message content. Supports {varName}

Example: Store the AI's response as a memory message:

conversationId: {sessionId}
role: assistant
content: {aiResponse}

---

READ_HISTORY

Retrieves the conversation history.

Properties:

Property	Description
conversationId	Target conversation ID
limit	Maximum number of recent messages to return

Output: Sets {memoryHistory} as an array of message objects:

[
  { "role": "user", "content": "I need help with my billing" },
  { "role": "assistant", "content": "I'd be happy to help. Can you share your account number?" },
  { "role": "user", "content": "It's ACC-12345" }
]

---

CLEAR_CONVERSATION

Deletes all messages but keeps the conversation slot.

Properties:

Property	Description
conversationId	Target conversation ID

---

DELETE_CONVERSATION

Completely removes the conversation and all messages.

Properties:

Property	Description
conversationId	Target conversation ID

---

Example: Multi-Turn Customer Support Chat

This pattern uses Memory Action to maintain conversation history across multiple workflow invocations (e.g., each customer message triggers a new workflow run):

[Start: {sessionId}, {customerMessage}]
     ↓
[Memory Action: STORE_MESSAGE]
  conversationId: {sessionId}
  role: user
  content: {customerMessage}
     ↓
[Memory Action: READ_HISTORY]
  conversationId: {sessionId}
  limit: 20
     ↓
[Set Variable: contextHistory = {memoryHistory}]
     ↓
[AI Task: Support Agent]
  systemPrompt: You are a support agent. Here is the conversation so far: {contextHistory}
  prompt: Latest message: {customerMessage}
     ↓
[Memory Action: STORE_MESSAGE]
  conversationId: {sessionId}
  role: assistant
  content: {aiResponse}
     ↓
[Output Node: Display AI response]

---

Example: Pre-Load Customer Context

Store structured context about a customer before the first AI interaction:

[Start: {customerId}]
     ↓
[SQL: Fetch customer profile → {customerProfile}]
     ↓
[Memory Action: STORE_MESSAGE]
  conversationId: {customerId}
  role: system
  content: Customer Profile: Name={customerProfile.name}, Plan={customerProfile.plan},
           Recent Issues={customerProfile.recentIssueCount}, Account Status={customerProfile.status}
     ↓
[AI Task: Begin customer conversation]

The AI Task will have the customer profile as system context before the first message.

---

Connections

Connection	Description
sequenceFlow (incoming)	Arrives from previous node
successFlow / sequenceFlow	Continues after operation
errorFlow	Taken on memory operation failure

---

Best Practices

• Use {sessionId} or {customerId} as conversation IDs — not hardcoded strings
• Set maxMessages to prevent unbounded growth (20–50 is typical for chat use cases)
• Clear conversations when a session ends (e.g., when the user says "bye" or the workflow reaches a terminal state)
• For stateless workflows, you don't need Memory Action — the AI Task's built-in memory is sufficient for single-run contexts
• Store structured data as system role messages — the AI treats these as authoritative context