User Memory

Overview

User Memory in LibreChat is a key/value store that persists user-specific information across conversations. Users can manage entries directly, an optional memory agent can extract updates from chats, and Agents can use memory tools when explicitly asked to remember or forget something.

Key Features

• Optional Automatic Extraction: Set memory.agent.enabled: true to run the configured memory agent with chat requests
• Key/Value Storage: Information is stored as structured key/value pairs, not as raw conversation logs
• Manual Entries: Users can manually add, edit, or remove memory entries directly, giving full control over what the AI remembers
• User Control: When enabled, users can toggle memory on/off for their individual chats
• Customizable Keys: Restrict what categories of information can be stored using validKeys
• Token Management: Set limits on memory usage to control costs
• Agent Tools: Agents can save or delete memories when the user explicitly requests it
• Agent Partitions: Keep an agent's memories separate from the user's shared personal pool

Configuration

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

version: 1.3.14
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
  maxInputTokens: 12000 # Maximum recent-chat tokens sent to the memory agent
  messageWindowSize: 5 # Number of recent messages to consider
  agent:
    enabled: true # Automatic extraction is opt-in
    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

Agent Memory

The Agents endpoint includes a memory capability. When memory is configured, the user has memory write permissions, and personalization is enabled, adding Memory to an agent gives it set_memory and delete_memory tools. The agent is instructed to use these tools only when the user explicitly asks it to remember, update, or forget something.

Agents use the user's shared personal memory pool by default. In the Agent Builder's Memory settings, enable Keep memories separate for this agent to isolate storage by user and agent. An isolated agent does not see existing personal memories or memories belonging to other isolated agents. Agent-scoped entries appear with the agent's name in the Memory panel and can be filtered by partition.

The automatic memory agent and inline Agent memory tools are independent. memory.agent.enabled: true controls automatic extraction, while the Agents endpoint's memory capability controls whether saved Agents can manage memories during a conversation.

1. Key/Value Storage

Memory entries are stored as key/value pairs. When memory is enabled, the system can store entries such as:

• User preferences (communication style, topics of interest)
• Important facts explicitly shared by users
• Ongoing projects or tasks mentioned
• Any category you define via validKeys

Users can also manually create, edit, and delete memory entries through the interface, giving direct control over what the AI knows about them.

2. Context Window

The messageWindowSize parameter determines how many recent messages are analyzed for memory updates. This helps the memory agent decide what information is worth storing or updating in the key/value store.

The maxInputTokens parameter caps the recent-chat text sent to the automatic memory agent before extraction. If the selected message window is still too large, LibreChat preserves the newest context and omits earlier chat content before invoking the memory agent.

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 categories 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:
    enabled: true
    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
  maxInputTokens: 12000
  agent:
    enabled: true
    provider: 'openAI'
    model: 'gpt-4.1-mini'

Advanced Configuration

Full configuration with all options:

memory:
  disabled: false
  validKeys: ['preferences', 'context', 'facts']
  tokenLimit: 3000
  maxInputTokens: 12000
  personalize: true
  messageWindowSize: 10
  agent:
    enabled: true
    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:
    enabled: true
    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
  maxInputTokens: 12000
  personalize: true
  messageWindowSize: 10
  agent:
    enabled: true
    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. Reduce maxInputTokens to cap how much recent chat is sent to the memory agent
3. Decrease messageWindowSize to analyze fewer messages
4. Use validKeys to restrict what gets stored
5. 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

Future Improvements

The current implementation runs the memory agent on every chat request unconditionally. Planned improvements include:

• Semantic Trigger for Writes: Detect when a user has explicitly asked the model to remember something (e.g., "Remember that I prefer Python") and only run the memory write agent in those cases, reducing unnecessary processing on routine messages.
• Vector Similarity Recall: Instead of injecting all stored memory entries into every request, use vector embeddings to retrieve only the entries most relevant to the current conversation context, improving both efficiency and relevance.

Related Features

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