Retrieval Memory

ResearchX integrates mem0 for retrieval-augmented memory across chat conversations. When enabled, the system automatically searches historical memories before each chat turn and injects relevant context, then asynchronously writes new memories after the turn completes — enabling cross-session knowledge accumulation and reuse.

How It Works

1. Search memories: Before each chat turn, the system searches for relevant historical memories based on the current user message and appends them to the system prompt as a "Retrieved Memory" section
2. Write memories: After a conversation turn completes, the system asynchronously writes the user/assistant message pair as a memory — non-blocking, so it does not affect conversation responsiveness
3. Project isolation: Memory is scoped per-project, so each project has its own isolated memory store

Admin Configuration

Entry: Admin → Retrieval Memory (/workspace/admin/retrieval-memory)

Global Toggle

Embedder Configuration

The system supports two embedder providers:

OpenAI

• Uses the text-embedding-3-small model by default
• Requires a valid OpenAI API Key
• Can use the system API Key or a custom key

Ollama (Self-hosted)

• Requires an Ollama service Base URL
• Requires specifying embedding dimensions
• Suitable for local deployments or intranet environments

Connection Test

Admins can click the test button on the configuration page to verify that the embedder service is reachable and working correctly.

Project-Level Control

Each project can independently control whether retrieval memory is active:

• Toggle the Project Memory switch in the project settings
• Defaults to disabled for new projects, even when the admin has globally enabled retrieval memory
• When disabled at the project level, both memory search and writes are paused for that project

For more on project-level memory management, see Project Management — Project Memory.

Storage Notes

• Memory data is stored in ./data/mem0/ by default
• Paths can be customized via MEM0_VECTOR_DB_PATH and MEM0_HISTORY_DB_PATH environment variables
• mem0 upstream telemetry is disabled by default with MEM0_TELEMETRY=false
• Vector database and memory history database are stored separately
• Client instances are cached by configuration hash to avoid re-initialization

Docker Compose Deployment Notes

• scripts/deploy.sh and docker/docker-compose.server.yml now persist mem0 data under ${DATA_DIR}/mem0 on the host
• The in-container path is fixed at /data/mem0
• The app reads and writes mem0 data through these environment variables:
  • MEM0_VECTOR_DB_PATH=/data/mem0/vector_store.db
  • MEM0_HISTORY_DB_PATH=/data/mem0/memory.db
  • MEM0_TELEMETRY=false
• This avoids writing to the image-internal default path /app/data/mem0, which can fail with permission errors in container deployments
• If you are upgrading an older compose deployment, recreate the app container so the new bind mount and environment variables take effect

Typical Use Cases

Case 1: Long-running Research Project

1. Admin enables retrieval memory globally and configures the embedder
2. In long-running research projects, the Agent automatically recalls previous analysis conclusions, data processing approaches, etc.
3. New conversations can reference historical memories without repeating context

Case 2: Team Collaboration Project

1. Team members interact with the Agent in separate conversations
2. The system accumulates project-relevant preferences and conventions
3. Later members' conversations benefit from prior interaction memories

Notes

• Memory writes are asynchronous (fire-and-forget) and do not block conversation responses
• Memory is isolated per-project; cross-project retrieval does not occur
• After changing embedder configuration, memories must be re-vectorized to take effect
• If retrieval memory is globally disabled, all project-level memory features are paused
• In Docker Compose deployments, if testing an Ollama embedder fails with EACCES: permission denied, mkdir '/app/data/mem0', the container is usually still running with the older mem0 path configuration and should be updated to use /data/mem0

Related Docs

• Project Management
• Conversations and Messages
• FAQ