Skip to main content

​
Overview

The Memories API allows AI assistants to remember information about users across conversations, enabling personalized and context-aware interactions. All memory endpoints are prefixed with /api/memories.

​
Get All Memories

Retrieve all memories for the authenticated user: 
GET /api/memories
Authorization: Bearer <token>

​
Response

{
  "memories": [
    {
      "key": "user_preferences",
      "value": "Prefers concise technical explanations",
      "updated_at": "2024-03-01T10:00:00Z"
    },
    {
      "key": "project_context",
      "value": "Working on a React Native mobile app",
      "updated_at": "2024-02-28T15:30:00Z"
    }
  ],
  "usage": {
    "tokens_used": 1250,
    "tokens_limit": 10000,
    "percentage": 12.5
  }
}
​
memories
array
Array of memory objects
​
memories[].key
string
Unique identifier for the memory
​
memories[].value
string
Memory content
​
memories[].updated_at
string
ISO 8601 timestamp of last update
​
usage.tokens_used
number
Total tokens used by all memories
​
usage.tokens_limit
number
Maximum tokens allowed for memories
​
usage.percentage
number
Percentage of limit used

​
Create Memory

Create a new memory: 
POST /api/memories
Authorization: Bearer <token>
Content-Type: application/json

​
Request Body

​
key
string
required
Unique identifier for the memory
​
value
string
required
Memory content (max 100KB)

​
Example

{
  "key": "coding_style",
  "value": "Prefers functional programming with TypeScript"
}

​
Response

{
  "key": "coding_style",
  "value": "Prefers functional programming with TypeScript",
  "updated_at": "2024-03-03T12:00:00Z"
}

​
Update Memory

Update an existing memory: 
PATCH /api/memories/:key
Authorization: Bearer <token>
Content-Type: application/json

​
Path Parameters

​
key
string
required
Memory key to update

​
Request Body

​
value
string
required
New memory content

​
Example

{
  "value": "Updated: Prefers functional programming with TypeScript and React hooks"
}

​
Delete Memory

Delete a specific memory: 
DELETE /api/memories/:key
Authorization: Bearer <token>

​
Path Parameters

​
key
string
required
Memory key to delete

​
Response

{
  "message": "Memory deleted successfully",
  "key": "coding_style"
}

​
Update Memory Preferences

Toggle memory functionality on/off for the user: 
PATCH /api/memories/preferences
Authorization: Bearer <token>
Content-Type: application/json

​
Request Body

​
enabled
boolean
required
Enable or disable memory functionality

​
Example

{
  "enabled": false
}

​
Response

{
  "memories_enabled": false,
  "message": "Memory preferences updated"
}

​
Memory Configuration

Memory functionality can be configured in librechat.yaml:
librechat.yaml
memory:
  disabled: false                     # Enable/disable memory
  validKeys:                          # Restrict memory keys
    - user_preferences
    - project_context
    - coding_style

​
Permissions

Memory operations require specific permissions:
  • USE - Use memory functionality
  • READ - View existing memories
  • CREATE - Create new memories
  • UPDATE - Update existing memories
  • OPT_OUT - Disable memory functionality
Permissions can be configured per role in librechat.yaml.

​
Token Limits

Memories are stored with token counting to prevent excessive usage:
  • Maximum payload size: 100KB per memory
  • Total token limit: Configurable per user/role
  • Token counting includes both key and value
When memory usage approaches the limit, the AI may need to consolidate or remove old memories to stay within quota.

​
Use Cases

Remember user communication preferences, time zones, language preferences, etc.
{
  "key": "communication_style",
  "value": "Prefers detailed explanations with code examples. Works in EST timezone."
}
Store ongoing project information for consistent assistance.
{
  "key": "current_project",
  "value": "Building an e-commerce platform with Next.js 14, Stripe integration, and PostgreSQL"
}
Remember the user’s tech stack and preferences.
{
  "key": "tech_stack",
  "value": "Primary: TypeScript, React, Node.js. Database: PostgreSQL. Deployment: Vercel"
}
Track what the user is learning or wants to focus on.
{
  "key": "learning_focus",
  "value": "Currently learning Rust and exploring WebAssembly for performance optimization"
}

​
Best Practices

1

Use Descriptive Keys

Choose clear, meaningful keys like coding_style instead of generic ones like pref1.
2

Keep Values Concise

Store only essential information to maximize token efficiency.
3

Update Regularly

Update memories when user preferences or context changes.
4

Respect User Privacy

Allow users to opt out of memory functionality if desired.

​
Error Responses

{
  "error": "Insufficient permissions",
  "message": "User does not have permission to create memories"
}
User lacks required memory permissions.
{
  "error": "Payload too large",
  "message": "Memory value exceeds 100KB limit"
}
Memory content exceeds the 100KB limit.
{
  "error": "Token limit exceeded",
  "message": "Total memory usage exceeds quota. Remove old memories or request limit increase."
}
Total memory token usage exceeds user quota.

Build docs developers (and LLMs) love

Get started for freeTalk to us