Workflow Memory Management#

Overview#

Three workflow node types handle conversation memory through distinct mechanisms with different user-control surfaces:

Both AgentNode v1 and DifyAgentNode v2 share BuiltinNodeTypes.AGENT and are differentiated by version string in the node registry — see resolve_workflow_node_class().

LLM Node Memory (TokenBufferMemory)#

Applies to: LLM, QUESTION_CLASSIFIER, PARAMETER_EXTRACTOR nodes with memory set.

DifyNodeFactory._build_memory_for_llm_node() reads conversation_id from the variable pool, fetches the Conversation ORM row, and constructs a TokenBufferMemory object that is injected at node construction time. If memory config or conversation_id is absent, it returns None and no history is prepended.

TokenBufferMemory.get_history_prompt_messages() 1 fetches up to 500 prior messages, then applies two limits in sequence:

1. Message count — MemoryConfig.window.size (when window.enabled=True)
2. Token budget — pops the oldest messages until within max_token_limit

MemoryConfig (imported in AgentNodeData from core.prompt.entities.advanced_prompt_entities) 2 controls:

• window.enabled / window.size — sliding message window
• role_prefix.user / role_prefix.assistant — text prefixes when formatting history as plain text

Key design constraint: All LLM nodes in a chatflow share the same conversation history because only the final Answer node output is saved as message.answer. An intermediate LLM node therefore reads the last turn's final reply, not its own prior outputs 3. Workarounds: disable memory on intermediate nodes, use Conversation Variables, or replace with an Agent node.

Preloading at construction time: get_node_creation_preload_selectors() ensures CONVERSATION_ID is inserted into the variable pool before DifyNodeFactory.create_node() runs for any memory-using node 4.

Legacy Agent Node Memory (AgentNode v1)#

Applies to: AgentNode registered at version "1".

AgentNodeData.memory is typed MemoryConfig | None = None. When set, the memory config is forwarded through the plugin-strategy adapter to the underlying agent runner, using the same MemoryConfig envelope as LLM nodes (window size, role prefix).

Node construction branches on issubclass(node_class, DifyAgentNode) inside _build_agent_node_init_kwargs(). For v1 nodes it supplies strategy_resolver, presentation_provider, runtime_support, and message_transformer — no session store is involved.

Agent V2 Node Memory (DifyAgentNode)#

Applies to: DifyAgentNode registered at version "2".

Agent V2 uses a session snapshot model: after each run the CompositorSessionSnapshot (from the agenton compositor inside the dify-agent service) is serialized to JSON and saved to AgentWorkspaceBinding.session_snapshot (a LongText column) by WorkflowAgentWorkspaceStore.save_active_snapshot(). On the next execution it is deserialized and forwarded in the CreateRunRequest to the dify-agent FastAPI service 5.

Inside dify-agent, PydanticAIHistoryLayer (type ID pydantic_ai.history) stores runtime_state.messages as a Pydantic model within the snapshot, providing automatic history reconstruction across turns 6.

Memory is currently reserved, not user-configurable. runtime_feature_manifest.py lists "memory" in RESERVED_AGENT_BACKEND_FEATURES with status "reserved_not_executed" — it is saved in Agent Soul config but not yet executed by the agent backend. The snapshot mechanism provides implicit multi-turn continuity without an explicit user-facing toggle.

DifyAgentNodeData carries no memory configuration fields; the node data model is intentionally minimal (agent_node_kind = "dify_agent", version = "2") 7.

Key Files#