Memory

Overview

Memory in LibreChat allows the system to remember information across conversations, providing a more personalized and context-aware experience. When enabled, the AI can recall user preferences, important facts, and conversation context to enhance future interactions.

Key Features

• Persistent Context: Information learned in one conversation can be recalled in future conversations
• User Control: When enabled, users can toggle memory on/off for their individual chats
• Customizable Storage: Control what types of information can be stored using valid keys
• Token Management: Set limits on memory usage to control costs
• Agent Integration: Use AI agents to intelligently manage what gets remembered

Configuration

To enable memory features, you need to add the memory configuration to your librechat.yaml file:

version: 1.2.8
cache: true
 
memory:
  disabled: false  # Set to true to completely disable memory
  personalize: true  # Gives users the ability to toggle memory on/off, true by default
  tokenLimit: 2000  # Maximum tokens for memory storage
  messageWindowSize: 5  # Number of recent messages to consider
  agent:
    provider: "openAI"
    model: "gpt-4"

The provider field should match the accepted values as defined in the Model Spec Guide.

Note: If you are using a custom endpoint, the endpoint value must match the defined custom endpoint name exactly.

See the Memory Configuration Guide for detailed configuration options.

How It Works

1. Information Storage

When memory is enabled, the system can store:

• User preferences (communication style, topics of interest)
• Important facts and context from conversations
• Personal information explicitly shared by users
• Ongoing projects or tasks mentioned

2. Context Window

The messageWindowSize parameter determines how many recent messages are analyzed for memory updates. This helps the system decide what information is worth remembering.

3. User Control

When personalize is set to true:

• Users see a memory toggle in their chat interface
• They can enable/disable memory for individual conversations
• Memory settings persist across sessions

4. Valid Keys

You can restrict what types of information are stored by specifying validKeys:

memory:
  validKeys:
    - "user_preferences"
    - "conversation_context"
    - "learned_facts"
    - "personal_information"

Best Practices

1. Token Limits

Set appropriate token limits to balance functionality with cost:

• Higher limits allow more comprehensive memory
• Lower limits reduce processing costs
• Consider your usage patterns and budget

2. Custom Instructions

When using validKeys, provide custom instructions to the memory agent:

memory:
  agent:
    provider: "openAI"
    model: "gpt-4"
    instructions: |
      Store information only in the specified validKeys categories.
      Focus on explicitly stated preferences and important facts.
      Delete outdated or corrected information promptly.

3. Privacy Considerations

• Memory stores user information across conversations
• Ensure users understand what information is being stored
• Consider implementing data retention policies
• Provide clear documentation about memory usage

Examples

Basic Configuration

Enable memory with default settings:

memory:
  tokenLimit: 2000
  agent:
    provider: "openAI"
    model: "gpt-4.1-mini"

Advanced Configuration

Full configuration with all options:

memory:
  disabled: false
  validKeys: ["preferences", "context", "facts"]
  tokenLimit: 3000
  personalize: true
  messageWindowSize: 10
  agent:
    provider: "anthropic"
    model: "claude-3-opus-20240229"
    instructions: "Remember only explicitly stated preferences and key facts."
    model_parameters:
      temperature: 0.3

For valid model parameters per provider, see the Model Spec Preset Fields.

Using Predefined Agents

Reference an existing agent by ID:

memory:
  agent:
    id: "memory-specialist-001"

Custom Endpoints with Memory

Memory fully supports custom endpoints, including those with custom headers and environment variables. When using a custom endpoint, header placeholders and environment variables are properly resolved during memory processing.

 
endpoints:
    custom:
        - name: 'Custom Memory Endpoint'
           apiKey: 'dummy'
           baseURL: 'https://api.gateway.ai/v1'
           headers:
             x-gateway-api-key: '${GATEWAY_API_KEY}'
             x-gateway-virtual-key: '${GATEWAY_OPENAI_VIRTUAL_KEY}'
             X-User-Identifier: '{{LIBRECHAT_USER_EMAIL}}'
             X-Application-Identifier: 'LibreChat - Test'
             api-key: '${TEST_CUSTOM_API_KEY}' 
           models:
             default:
               - 'gpt-4o-mini'
               - 'gpt-4o'
             fetch: false
  
memory:
  disabled: false
  tokenLimit: 3000
  personalize: true
  messageWindowSize: 10
  agent:
    provider: 'Custom Memory Endpoint'
    model: 'gpt-4o-mini'

• All custom endpoint headers are supported

Troubleshooting

Memory Not Working

1. Verify memory is configured in librechat.yaml
2. Check that disabled is set to false
3. Ensure the configured agent/model is available
4. Verify users have enabled memory in their chat interface
5. For custom endpoints: ensure the provider name matches the custom endpoint name exactly

High Token Usage

1. Reduce tokenLimit to control costs
2. Decrease messageWindowSize to analyze fewer messages
3. Use validKeys to restrict what gets stored
4. Review and optimize agent instructions

Inconsistent Memory

1. Check if users are toggling memory on/off
2. Verify token limits aren’t being exceeded
3. Ensure consistent agent configuration
4. Review stored memory for conflicts

Custom Endpoint Authentication Issues

1. Verify environment variables are set correctly in your .env file
2. Ensure custom headers use the correct syntax (${ENV_VAR} for environment variables, {{LIBRECHAT_USER_*}} for user placeholders)
3. Check that the custom endpoint is working for regular chat completions before testing with memory
4. Review server logs for authentication errors from the custom endpoint API

Related Features

• Agents - Build custom AI assistants
• Presets - Save conversation settings
• Fork Messages - Branch conversations while maintaining context