Memory Configuration

Overview

The memory object turns on User Memory and sets its limits. Adding the section is what enables memory: saved entries are then added to each user's conversations, users can manage them in the Memories panel, and the Memory tool (set_memory and delete_memory) is offered in chats and agents, as long as the memory capability is enabled for the agents endpoint (it is by default).

Automatic memory extraction, where a separate memory agent reviews every exchange and saves facts without being asked, is a separate opt-in: set agent.enabled: true and give it a model.

Example

memory:
  disabled: false
  validKeys: ['user_preferences', 'conversation_context', 'personal_info']
  tokenLimit: 2000
  charLimit: 10000
  maxInputTokens: 12000
  personalize: true
  messageWindowSize: 5
  agent:
    enabled: true
    provider: 'openAI'
    model: 'gpt-4'
    instructions: 'You are a helpful assistant that remembers user preferences and context.'
    model_parameters:
      temperature: 0.7
      max_tokens: 1000

disabled

Key	Type	Description	Example
disabled	Boolean	Disables memory when set to true. Saved memories are no longer added to conversations, the Memory tool is not offered, and the memory permissions are turned off for every role.	disabled: false

Default: false

Memory is only active when a memory block is present in librechat.yaml. Omitting the block leaves memory off.

memory:
  disabled: true

validKeys

Key	Type	Description	Example
validKeys	Array of Strings	Specifies which keys are valid for memory storage. This helps control what types of information can be stored in memory.	validKeys: ["user_name", "preferences", "context"]

Default: No restriction (all keys are valid)

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

tokenLimit

Key	Type	Description	Example
tokenLimit	Number	Sets the maximum total size, in tokens, of all memories stored for a user. Saves that would go over it are rejected, and the Memories panel shows usage against it.	tokenLimit: 2000

Default: No limit

memory:
  tokenLimit: 2000

charLimit

Key	Type	Description	Example
charLimit	Number	Sets the maximum number of characters allowed for individual memory entries. This prevents oversized memory payloads that could impact performance or exceed API limits.	charLimit: 10000

Default: 10000

memory:
  charLimit: 10000

maxInputTokens

Key	Type	Description	Example
maxInputTokens	Number	Sets the maximum number of recent-chat tokens sent to the automatic memory agent before memory extraction. Long inputs are truncated from the beginning so the latest context is preserved.	maxInputTokens: 12000

Default: 12000

memory:
  maxInputTokens: 12000

personalize

Key	Type	Description	Example
personalize	Boolean	When true, users get the Use memory toggle in the Memories panel and Reference saved memories in Settings, so they can opt out of memory. When false, users cannot opt out; memory itself stays on.	personalize: true

Default: true

memory:
  personalize: false

messageWindowSize

Key	Type	Description	Example
messageWindowSize	Number	Number of recent messages the automatic memory agent reviews on each request. Only used when agent.enabled is true.	messageWindowSize: 5

Default: 5

memory:
  messageWindowSize: 10

agent

Key	Type	Description	Example
agent	Object \| Union	Configures the optional automatic memory agent. Can be either a reference to an existing agent by ID or a complete agent configuration.	agent: { enabled: true, provider: "openAI", model: "gpt-4" }

Configures the automatic memory agent. It only runs when enabled is true; an agent block without enabled is ignored and LibreChat logs a warning at startup.

When enabled, the memory agent runs at the start of every chat request, alongside the main response. It reviews the last messageWindowSize messages (capped at maxInputTokens) and saves or deletes entries on its own. It is given until the main response finishes plus up to 3 seconds; if it is still running after that, its result is dropped for that request.

The agent field supports two different configuration formats:

Agent by ID

When you have a pre-configured agent, you can reference it by its ID:

memory:
  agent:
    enabled: true
    id: 'memory-agent-001'

Custom Agent Configuration

For more control, you can define a complete agent configuration:

memory:
  agent:
    enabled: true
    provider: 'openAI'
    model: 'gpt-4'
    instructions: 'You are a memory assistant that helps maintain conversation context and user preferences.'
    model_parameters:
      temperature: 0.3
      max_tokens: 1500
      top_p: 0.9

Agent Configuration Fields

When using custom agent configuration, the following fields are available:

enabled (required to run the memory agent)

Key	Type	Description	Example
enabled	Boolean	Turns on automatic memory extraction. Also accepted alongside id. Without it, the agent block has no effect.	enabled: true

provider (required)

Key	Type	Description	Example
provider	String	Specifies the AI provider for the memory agent. Can be a built-in provider (e.g., "openAI", "anthropic", "google") or a custom endpoint name, which must match the endpoint name exactly.	provider: "openAI"

model (required)

Key	Type	Description	Example
model	String	Specifies the model to use for memory processing.	model: "gpt-4"

instructions (optional)

Key	Type	Description	Example
instructions	String	Custom instructions that replace the default instructions for when to set and/or delete memory. Should mainly be used when using validKeys that require specific information handling.	instructions: "Only store user preferences and facts when explicitly mentioned."

model_parameters (optional)

Key	Type	Description	Example
model_parameters	Object	Additional parameters to pass to the model for fine-tuning its behavior. Values must be strings, numbers, or booleans.	model_parameters: { temperature: 0.7 }

Accepted provider values are listed in the Model Spec endpoint field, and valid model parameters per provider in Model Spec preset fields.

Complete Configuration Example

An example using every memory option:

version: 1.3.18
cache: true

memory:
  disabled: false
  validKeys:
    - 'user_preferences'
    - 'conversation_context'
    - 'learned_facts'
    - 'personal_information'
  tokenLimit: 3000
  charLimit: 10000
  maxInputTokens: 12000
  personalize: true
  messageWindowSize: 8
  agent:
    enabled: true
    provider: 'openAI'
    model: 'gpt-4'
    instructions: |
      Store memory using only the specified validKeys. For user_preferences: save 
      explicitly stated preferences about communication style, topics of interest, 
      or workflow preferences. For conversation_context: save important facts or 
      ongoing projects mentioned. For learned_facts: save objective information 
      about the user. For personal_information: save only what the user explicitly 
      shares about themselves. Delete outdated or incorrect information promptly.
    model_parameters:
      temperature: 0.2
      max_tokens: 2000
      top_p: 0.8
      frequency_penalty: 0.1

Using Custom Endpoints

The memory feature supports custom endpoints. When using a custom endpoint, the provider field should match the custom endpoint's name exactly. Custom headers with environment variables and user placeholders are properly resolved.


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'

See Custom Endpoint Headers for all available placeholders

Notes

personalize controls whether users can opt out, not whether memory is on. Use disabled to turn memory off.
maxInputTokens bounds the chat context sent to the automatic memory agent, while tokenLimit caps the total size of stored memories.
Custom instructions replace the default memory instructions and are mainly useful together with validKeys.
Access is also controlled per role through the memory permissions (use, create, read, update, opt out). See interface.memories, the Admin Panel, or the admin settings at the bottom of the Memories panel.

Troubleshooting

Memory does nothing. Check that the memory section exists and disabled is not true, that the user's role has permission to use memories, and that the user has not turned off Reference saved memories. For the Memory tool, the memory capability must be in the agents endpoint capabilities list if you set one.

Nothing is saved automatically. Automatic extraction needs agent.enabled: true and a valid id, or provider and model. Without it, entries are only saved when a user asks the model to remember something with the Memory tool on, or adds them by hand.

The memory agent fails on a custom endpoint. provider must match the custom endpoint name exactly. Confirm the endpoint works for normal chats first, then check that the environment variables its headers reference are set; header placeholders are resolved the same way for memory as for chat.

Token usage is high. Lower maxInputTokens or messageWindowSize to send less chat to the memory agent, lower tokenLimit to keep the stored memories (which are added to every request) small, and restrict validKeys.

Memory Configuration

On this page