knowledge-base/docs/api-reference-add-memories.md

Mem0 API Reference - Add Memories

Overview

The Add Memories API endpoint allows you to store memories in the Mem0 system. This endpoint processes messages and converts them into structured memories that can be later retrieved and used for contextual AI interactions.

Endpoint

POST /v1/memories/

Authentication

• Authorization: API key authentication required
• Header: Authorization: Token your_api_key
• Format: Prefix your Mem0 API key with 'Token '. Example: 'Token your_api_key'

Python SDK Usage

# To use the Python SDK, install the package:
# pip install mem0ai

from mem0 import MemoryClient

client = MemoryClient(api_key="your_api_key", org_id="your_org_id", project_id="your_project_id")

messages = [
    {"role": "user", "content": "<user-message>"},
    {"role": "assistant", "content": "<assistant-response>"}
]

client.add(messages, user_id="<user-id>", version="v2")

Request Body Parameters

Required Parameters

messages (object[])

An array of message objects representing the content of the memory. Each message object typically contains 'role' and 'content' fields, where 'role' indicates the sender either 'user' or 'assistant' and 'content' contains the actual message text. This structure allows for the representation of conversations or multi-part memories.

• messages.{key}: string | null

Optional Parameters

Identifiers

• agent_id (string | null): The unique identifier of the agent associated with this memory
• user_id (string | null): The unique identifier of the user associated with this memory
• app_id (string | null): The unique identifier of the application associated with this memory
• run_id (string | null): The unique identifier of the run associated with this memory
• org_id (string | null): The unique identifier of the organization associated with this memory
• project_id (string | null): The unique identifier of the project associated with this memory

Configuration Options

• metadata (object | null): Additional metadata associated with the memory, which can be used to store any additional information or context about the memory. Best practice for incorporating additional information is through metadata (e.g. location, time, ids, etc.). During retrieval, you can either use these metadata alongside the query to fetch relevant memories or retrieve memories based on the query first and then refine the results using metadata during post-processing.

• includes (string | null): String to include the specific preferences in the memory. Minimum length: 1

• excludes (string | null): String to exclude the specific preferences in the memory. Minimum length: 1

• infer (boolean, default: true): Whether to infer the memories or directly store the messages

• output_format (string | null, default: v1.0): Output format options: v1.0 (default) and v1.1. We recommend using v1.1 as v1.0 will be deprecated soon.

• custom_categories (object | null): A list of categories with category name and its description

• custom_instructions (string | null): Defines project-specific guidelines for handling and organizing memories. When set at the project level, they apply to all new memories in that project.

• immutable (boolean, default: false): Whether the memory is immutable

• async_mode (boolean, default: false): Whether to add the memory completely asynchronously

• timestamp (integer | null): The timestamp of the memory. Format: Unix timestamp

• expiration_date (string | null): The date and time when the memory will expire. Format: YYYY-MM-DD

• version (string | null): The version of the memory to use. The default version is v1, which is deprecated. We recommend using v2 for new applications.

Response

Success Response (200)

[
  {
    "id": "<string>",
    "data": {
      "memory": "<string>"
    },
    "event": "ADD"
  }
]

Response Fields

• id (string, required): Unique identifier for the created memory
• data (object, required): Contains the memory data
  • memory (string, required): The processed memory content
• event (enum, required): The type of operation performed
  • Available options: ADD, UPDATE, DELETE

Error Response (400)

Bad request - Invalid parameters or malformed request

Best Practices

1. Use Version v2: The v1 API is deprecated. Always use version="v2" for new applications.

2. Output Format: Use output_format="v1.1" as the v1.0 format will be deprecated soon.

3. Metadata Usage: Store additional context information in metadata for better memory organization and retrieval.

4. Message Structure: Follow the standard conversation format with 'role' and 'content' fields for optimal memory processing.

5. Async Mode: Use async mode for bulk memory operations to improve performance.