Memory API - DeerFlow

Overview

The Memory API provides endpoints to retrieve and manage DeerFlow’s global memory system. Memory stores user context, conversation history, and facts across all threads for personalized AI interactions.

Get Memory Data

GET /api/memory

Retrieve the current global memory data including user context, history, and facts

Response

string

default:"1.0"

Memory schema version

string

Last update timestamp (ISO 8601 format)

object

User context sections

Show User Context

object

Work-related context

Show Context Section

string

Summary content

string

Last update timestamp

object

Personal preferences and context

object

Current priorities and focus areas

object

Historical context sections

Show History Context

object

Recent development activities

object

Earlier historical context

object

Long-term background information

array

List of memory facts

Show Fact Object

string

required

Unique identifier for the fact

string

required

Fact content

string

default:"context"

Fact category (e.g., preference, context, skill)

number

default:"0.5"

Confidence score (0-1)

string

Creation timestamp

string

default:"unknown"

Source thread ID

Example Request

curl http://localhost:8001/api/memory

Example Response

{
  "version": "1.0",
  "lastUpdated": "2024-01-15T10:30:00Z",
  "user": {
    "workContext": {
      "summary": "Working on DeerFlow documentation and API development",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "personalContext": {
      "summary": "Prefers concise responses with code examples",
      "updatedAt": "2024-01-14T15:20:00Z"
    },
    "topOfMind": {
      "summary": "Building Gateway API documentation",
      "updatedAt": "2024-01-15T09:00:00Z"
    }
  },
  "history": {
    "recentMonths": {
      "summary": "Recent development activities on DeerFlow project",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "earlierContext": {
      "summary": "",
      "updatedAt": ""
    },
    "longTermBackground": {
      "summary": "",
      "updatedAt": ""
    }
  },
  "facts": [
    {
      "id": "fact_abc123",
      "content": "User prefers TypeScript over JavaScript",
      "category": "preference",
      "confidence": 0.9,
      "createdAt": "2024-01-15T10:30:00Z",
      "source": "thread_xyz"
    },
    {
      "id": "fact_def456",
      "content": "User is experienced with FastAPI and Python",
      "category": "skill",
      "confidence": 0.85,
      "createdAt": "2024-01-14T14:20:00Z",
      "source": "thread_abc"
    }
  ]
}

Reload Memory Data

POST /api/memory/reload

Reload memory data from the storage file, refreshing the in-memory cache

Response

Returns the reloaded memory data (same structure as GET /api/memory).

Example Request

curl -X POST http://localhost:8001/api/memory/reload

Use Case

Use this endpoint when the memory file has been modified externally and you need to refresh the cached data without restarting the server.

Get Memory Configuration

GET /api/memory/config

Retrieve the current memory system configuration

Response

boolean

required

Whether memory is enabled

string

required

Path to memory storage file (relative to project root)

integer

required

Debounce time for memory updates (seconds)

integer

required

Maximum number of facts to store

number

required

Minimum confidence threshold for facts (0-1)

boolean

required

Whether memory injection is enabled

integer

required

Maximum tokens for memory injection into prompts

Example Request

curl http://localhost:8001/api/memory/config

Example Response

{
  "enabled": true,
  "storage_path": ".deer-flow/memory.json",
  "debounce_seconds": 30,
  "max_facts": 100,
  "fact_confidence_threshold": 0.7,
  "injection_enabled": true,
  "max_injection_tokens": 2000
}

Get Memory Status

GET /api/memory/status

Retrieve both memory configuration and current data in a single request

Response

object

Memory configuration (same as GET /api/memory/config)

object

Memory data (same as GET /api/memory)

Example Request

curl http://localhost:8001/api/memory/status

Example Response

{
  "config": {
    "enabled": true,
    "storage_path": ".deer-flow/memory.json",
    "debounce_seconds": 30,
    "max_facts": 100,
    "fact_confidence_threshold": 0.7,
    "injection_enabled": true,
    "max_injection_tokens": 2000
  },
  "data": {
    "version": "1.0",
    "lastUpdated": "2024-01-15T10:30:00Z",
    "user": {
      "workContext": {
        "summary": "Working on DeerFlow project",
        "updatedAt": "2024-01-15T10:30:00Z"
      },
      "personalContext": {
        "summary": "",
        "updatedAt": ""
      },
      "topOfMind": {
        "summary": "",
        "updatedAt": ""
      }
    },
    "history": {
      "recentMonths": {
        "summary": "",
        "updatedAt": ""
      },
      "earlierContext": {
        "summary": "",
        "updatedAt": ""
      },
      "longTermBackground": {
        "summary": "",
        "updatedAt": ""
      }
    },
    "facts": []
  }
}

Memory System

How Memory Works

Collection: Memory is collected from conversations across all threads
Storage: Memory data is persisted to a JSON file (.deer-flow/memory.json)
Injection: Memory is automatically injected into AI prompts when enabled
Updates: Memory is updated with debouncing to prevent excessive writes

Memory Categories

User Context

workContext: Work-related information and current projects
personalContext: Personal preferences, communication style
topOfMind: Current priorities and focus areas

History Context

recentMonths: Recent development activities and conversations
earlierContext: Historical context from earlier periods
longTermBackground: Long-term background information

Facts

Structured facts extracted from conversations:

preference: User preferences (e.g., coding style, tools)
skill: User skills and expertise
context: General contextual information
goal: User goals and objectives

Confidence Scores

Facts have confidence scores (0-1) indicating reliability:

0.9-1.0: High confidence (explicitly stated by user)
0.7-0.9: Medium confidence (inferred from behavior)
0.5-0.7: Low confidence (weak signals)
< 0.5: Very low confidence (filtered out by default)

Configuration

Memory can be configured in your application config:

memory:
  enabled: true
  storage_path: ".deer-flow/memory.json"
  debounce_seconds: 30
  max_facts: 100
  fact_confidence_threshold: 0.7
  injection_enabled: true
  max_injection_tokens: 2000

Parameters

enabled: Enable/disable memory system
storage_path: Path to memory JSON file
debounce_seconds: Wait time before writing updates
max_facts: Maximum number of facts to store
fact_confidence_threshold: Minimum confidence to keep facts
injection_enabled: Enable/disable memory injection into prompts
max_injection_tokens: Maximum tokens to inject

Use Cases

Display Memory Data

const response = await fetch('http://localhost:8001/api/memory');
const memory = await response.json();

console.log('User Context:', memory.user.workContext.summary);
console.log('Total Facts:', memory.facts.length);

Filter High-Confidence Facts

const response = await fetch('http://localhost:8001/api/memory');
const { facts } = await response.json();

const highConfidenceFacts = facts.filter(f => f.confidence >= 0.8);
const preferences = facts.filter(f => f.category === 'preference');

Check Memory Status

const response = await fetch('http://localhost:8001/api/memory/status');
const { config, data } = await response.json();

if (config.enabled && config.injection_enabled) {
  console.log('Memory is active and injecting context');
  console.log(`Last updated: ${data.lastUpdated}`);
}

Reload Memory

// After external modification
const response = await fetch('http://localhost:8001/api/memory/reload', {
  method: 'POST'
});
const refreshedMemory = await response.json();

Memory System

Learn about the memory system

Gateway Overview

Learn about the Gateway API

​Overview

​Get Memory Data

GET /api/memory

​Response

​Example Request

​Example Response

​Reload Memory Data

POST /api/memory/reload

​Response

​Example Request

​Use Case

​Get Memory Configuration

GET /api/memory/config

​Response

​Example Request

​Example Response

​Get Memory Status

GET /api/memory/status

​Response

​Example Request

​Example Response

​Memory System

​How Memory Works

​Memory Categories

​User Context

​History Context

​Facts

​Confidence Scores

​Configuration

​Parameters

​Use Cases

​Display Memory Data

​Filter High-Confidence Facts

​Check Memory Status

​Reload Memory

​Related

Memory System

Gateway Overview

Overview

Get Memory Data

Response

Example Request

Example Response

Reload Memory Data

Response

Example Request

Use Case

Get Memory Configuration

Response

Example Request

Example Response

Get Memory Status

Response

Example Request

Example Response

Memory System

How Memory Works

Memory Categories

User Context

History Context

Facts

Confidence Scores

Configuration

Parameters

Use Cases

Display Memory Data

Filter High-Confidence Facts

Check Memory Status

Reload Memory

Related