Memory

Memory is a runtime feature of the DeerFlow Harness. It is not a simple conversation log — it is a structured store of facts and context summaries that persist across separate sessions and inform the agent’s behavior in future conversations.

What memory stores

The memory store holds several categories of information:

• Work context: summaries of ongoing projects, goals, and recurring topics the user works on.
• Personal context: preferences, communication style, and other user-specific details the agent has learned.
• Top of mind: the most recent focus areas and active tasks.
• History: recent months’ context, earlier background, and long-term facts.
• Facts: discrete, specific facts the agent has extracted from conversations (e.g., preferred tools, team names, project constraints).

Each category is updated over time as the agent learns from ongoing conversations.

How it works

Memory is managed by MemoryMiddleware, which runs on every Lead Agent turn:

1. Injection: at the start of each conversation, the agent’s current memory is injected into the system prompt at a controlled token budget (max_injection_tokens).
2. Learning: after a conversation, a background job extracts new facts and updates the relevant memory categories. Updates are debounced by debounce_seconds to batch rapid changes.
3. Per-agent memory: when a custom agent is active, its memory is stored separately from the global memory. This keeps different agents’ knowledge isolated.

Configuration

memory:
  enabled: true
 
  # Storage path for the global memory file.
  # Default: {base_dir}/memory.json  (resolves to backend/.deer-flow/memory.json)
  # Absolute paths are used as-is.
  # Relative paths are resolved against base_dir (not the backend working directory).
  storage_path: memory.json
 
  # Storage class (default: file-based JSON storage)
  storage_class: deerflow.agents.memory.storage.FileMemoryStorage
 
  # Seconds to wait before processing queued memory updates (debounce)
  debounce_seconds: 30
 
  # Model for memory update extraction (null = use default model)
  model_name: null
 
  # Maximum number of facts to store
  max_facts: 100
 
  # Minimum confidence score required to store a fact (0.0–1.0)
  fact_confidence_threshold: 0.7
 
  # Whether to inject memory into the system prompt
  injection_enabled: true
 
  # Maximum tokens to use for memory injection into system prompt
  max_injection_tokens: 2000

Global vs per-agent memory

DeerFlow supports two levels of memory:

• Global memory: stored at {base_dir}/memory.json. Used when no specific agent is active or when the agent has no per-agent memory file.
• Per-agent memory: stored at {base_dir}/agents/{agent_name}/memory.json. Used when a custom agent is active, keeping that agent’s learned knowledge separate.

The MemoryMiddleware automatically selects the correct memory file based on the active agent_name in the request configuration.

Agent names used for memory storage are validated against AGENT_NAME_PATTERN to ensure filesystem safety.

Storage location

By default, memory files are stored under the backend base directory:

• Base directory: backend/.deer-flow/
• Global memory: backend/.deer-flow/memory.json
• Per-agent memory: backend/.deer-flow/agents/{agent_name}/memory.json

You can change the storage path with the storage_path field. Relative paths are resolved against the base directory. Use an absolute path to store memory in a custom location.

Custom storage backend

The storage_class field allows you to replace the default file-based storage with a custom implementation. Any class that extends MemoryStorage and implements load(), reload(), and save() methods can be used:

memory:
  storage_class: mypackage.storage.RedisMemoryStorage

If the configured class cannot be loaded, the system falls back to the default FileMemoryStorage and logs an error.

Disabling memory

To disable memory entirely:

memory:
  enabled: false

To keep memory storage but prevent injection into the system prompt:

memory:
  enabled: true
  injection_enabled: false