Memory System

The Memory System in RAGFlow provides a persistent, searchable storage layer for agentic workflows. Unlike standard conversation history, which is often ephemeral or limited by context window sizes, the Memory System treats dialogue and extracted insights as structured data. It allows agents to maintain long-term state, recall past interactions across sessions, and organize information into different cognitive categories (e.g., raw dialogue vs. semantic facts).

System Overview

The memory subsystem bridges the gap between the LLM's "Natural Language Space" and the "Code Entity Space" by mapping conversation turns into vector-searchable documents stored in specialized indices. The system is implemented in both Python and Go to support the dual-backend architecture.

Title: Memory System Architecture

Sources: memory/services/messages.py25-34 api/db/joint_services/memory_message_service.py39-67 internal/service/memory.go17-35 internal/handler/memory.go39-54

Memory Types and Storage

RAGFlow categorizes memory into four distinct types to optimize how agents retrieve information:

1. Raw: The literal transcript of the conversation api/db/joint_services/memory_message_service.py68-83 internal/dao/memory.go31
2. Semantic: Universal facts, definitions, and time-invariant concepts internal/service/memory.go124-132 api/db/joint_services/memory_message_service.py56-66
3. Episodic: Specific experiences, events, and contextual personal stories internal/service/memory.go133-141 api/db/joint_services/memory_message_service.py56-66
4. Procedural: Actionable methods, processes, and step-by-step instructions internal/service/memory.go142-150 api/db/joint_services/memory_message_service.py56-66

When a message is processed via save_to_memory, the system uses an LLM to extract content unless the memory type is strictly RAW api/db/joint_services/memory_message_service.py39-67 Messages are stored in the document store using per-user indices named via index_name(uid) which adds a memory_ prefix memory/services/messages.py29-31 The MessageService acts as the primary interface for CRUD operations on these messages, abstracting the underlying msgStoreConn memory/services/messages.py34-69

For a deep dive into the underlying storage schemas and the extraction pipeline, see Memory Types and Storage.

Sources: api/db/joint_services/memory_message_service.py39-102 memory/services/messages.py25-69 internal/service/memory.go101-157 internal/dao/memory.go30-44

Memory Management UI and API

The system provides a REST API and a React-based frontend for managing these persistent states. Users can configure memory parameters, such as forgetting policies and storage types, through the UI.

Core Management Flow

Title: Memory Configuration and Storage Flow

Key management features include:

• Memory CRUD: Endpoints for creating, updating, listing, and deleting memories are defined in memory_api.py api/apps/restful_apis/memory_api.py30-130 and handled by MemoryHandler in Go internal/handler/memory.go82-169
• Forgetting Policies: Support for managing memory lifecycle via parameters like forgetting_policy (e.g., FIFO) and memory_size internal/service/memory.go75-86 api/apps/services/memory_api_service.py181-188
• Message Inspection: Retrieving detailed message history for a specific memory via get_memory_messages, including filtering by agent_ids or keywords api/apps/restful_apis/memory_api.py157-175 internal/handler/memory.go264-280
• Advanced Configuration: Tuning parameters like temperature for extraction and defining system_prompt or user_prompt via the PromptAssembler internal/service/memory.go102-120 api/db/services/memory_service.py130-135
• Permissions: Granular control to restrict memory access to me, team, or all via TenantPermission internal/service/memory.go49-60 api/apps/services/memory_api_service.py53-59

For details on the API endpoints and frontend configuration, see Memory Management UI and API.

Sources: api/apps/restful_apis/memory_api.py30-175 internal/handler/memory.go82-280 internal/service/memory.go38-86 api/apps/services/memory_api_service.py75-188 web/src/routes.tsx26-30

Integration in Workflows

The Memory System is integrated into agent workflows to provide long-term context:

• Automated Extraction: The AssembleSystemPrompt function generates instructions that guide the LLM in identifying semantic, episodic, or procedural information from raw dialogues internal/service/memory.go160-188 api/db/joint_services/memory_message_service.py158-171
• Hybrid Retrieval: Agents retrieve memories using search interfaces that support both keyword filtering and vector similarity memory/services/messages.py151-171 internal/service/memory.go62-66
• Embedding Support: All extracted memories are vectorized before storage using the tenant's configured embedding model to enable semantic search api/db/joint_services/memory_message_service.py189-195 internal/service/memory.go125-129
• Storage Mapping: The ESConnection maps message fields like message_type to message_type_kwd and content to content_ltks for optimized search memory/utils/es_conn.py38-50
• Dynamic Templates: The system uses dynamic templates in mapping.json to ensure memory fields like *_ltks (text) and *_vec (vectors) are correctly indexed in the document store conf/mapping.json83-201

Sources: api/db/joint_services/memory_message_service.py158-195 internal/service/memory.go160-188 memory/services/messages.py151-171 conf/mapping.json83-201 memory/utils/es_conn.py38-77