Add User Memory

Store new user memories for future reference.

This API allows you to add memories in two formats:

1. Raw text string - A single text-based memory
2. User/Assistant pairs array - Conversation pairs that will be chunked as a single memory

The stored memories will be chunked, embedded, and indexed for semantic search and retrieval.

POST /memories/add-memories

Error

A valid request URL is required to generate request examples

200

{
  "success": true,
  "user_memory_added": true,
  "memory_id": "memory_1234",
  "source_id": "CortexDoc1234",
  "chunks_created": 1,
  "original_chunks": 1,
  "inferred_chunks": 1
}

Hit the Try it button to try this API now in our playground. It’s the best way to check the full request and response in one place, customize your parameters, and generate ready-to-use code snippets.

Sample Request

curl -X 'POST' \
  'https://api.usecortex.ai/memories/add-memories' \
  -d '{
  "tenant_id": "string",
  "sub_tenant_id": "string",
  "raw_text": "string",
  "user_assistant_pairs": [
    {
      "user": "string",
      "assistant": "string"
    }
  ],
  "expiry_time": 0,
  "infer": false,
  "custom_instructions": "string",
  "user_name": "string",
  "memory_id": "string"
}'

Examples

API Request

# Using raw_text
curl --request POST \
  --url https://api.usecortex.ai/user_memory/add_user_memory \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "tenant_id": "tenant_123",
  "sub_tenant_id": "sub_tenant_123",
  "raw_text": "I wakes up early in the morning and enjoys jogging before work",
  "expiry_time": 600,
  "infer": true,
  "custom_instructions": "John is being referred in this context."
}'

# Or with user-assistant pairs:
curl --request POST \
  --url https://api.usecortex.ai/user_memory/add_user_memory \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "tenant_id": "tenant_123",
  "sub_tenant_id": "sub_tenant_123",
  "user_assistant_pairs": [
    {
      "user": "What are general work preferences at startups?",
      "assistant": "People prefer working in the morning and enjoy collaborative projects with clear deadlines."
    },
    {
      "user": "How to handle stress at work?",
      "assistant": "Take regular breaks and practice mindfulness to stay focused and productive."
    }
  ],
  "expiry_time": 600,
  "infer": true,
  "custom_instructions": "User's name is John."
}'

TypeScript

// Using raw_text
const result = await client.userMemory.addUserMemory({
  tenant_id: "tenant_123",
  sub_tenant_id: "sub_tenant_123",
  raw_text: "John wakes up early in the morning and enjoys jogging before work",
  expiry_time: 600,
  infer: true,
  custom_instructions: ""
});

// Or with user-assistant pairs:
const result = await client.userMemory.addUserMemory({
  tenant_id: "tenant_123",
  sub_tenant_id: "sub_tenant_123",
  user_assistant_pairs: [
    {
      user: "What are general work preferences at startups?",
      assistant: "People prefer working in the morning and enjoy collaborative projects with clear deadlines."
    },
    {
      user: "How to handle stress at work?",
      assistant: "Take regular breaks and practice mindfulness to stay focused and productive."
    }
  ],
  expiry_time: 600,
  infer: true,
  custom_instructions: "User's name is John."
});

Python (Sync)

# Using raw_text
# Async usage is similar, just use async_client and await
add_memory = client.user_memory.add_user_memory(
    tenant_id="tenant_123",
    sub_tenant_id="sub_tenant_123",
    raw_text="He wakes up early in the morning and enjoys jogging before work",
    custom_instructions="User's name is John.",
    infer=True,
    expiry_time=10*60,  # Memory will expire after 600 seconds
)

# Or with user-assistant pairs:
# Async usage is similar, just use async_client and await
add_conversation = client.user_memory.add_user_memory(
    tenant_id="tenant_123",
    sub_tenant_id="sub_tenant_123",
    user_assistant_pairs=[
        {
            UserAssistantPair(
                user="What are general work preferences at startups?",
                assistant="People prefer working in the morning and enjoy collaborative projects with clear deadlines.",
            ),
            UserAssistantPair(
                user="How to handle stress at work?",
                assistant="Take regular breaks and practice mindfulness to stay focused and productive.",
            )
        }
    ],
    custom_instructions="",
    infer=True,
    expiry_time=10*60,  # Memory will expire after 600 seconds
)

Overview

Store personal memories for a specific user to enhance personalization and provide context-aware responses in your AI applications.

What are User Memories?

User memories are personal, contextual information stored for individual users that help your AI system:

• Remember user preferences and past interactions
• Provide personalized responses based on user history
• Enhance user experience through adaptive behavior

Memory Types

Raw Text: Textual content that you want to save in Cortex as a memory. This can be any descriptive information about a user, such as their preferences, habits, background information, or important context that should be remembered for future interactions.

User-Assistant Pairs: Conversational exchanges between a user and an AI assistant (or any similar interaction pattern). These are structured as question-response or prompt-answer pairs that capture the flow of conversations, including responses from an LLM or any similar system.

Additional Parameters

Custom Instructions: Contextual information you provide about the text being indexed that Cortex needs to know. This helps guide how the memory should be interpreted, categorized, or retrieved later. For example, you might specify that certain information is particularly important, should be weighted more heavily, or relates to specific topics.

Infer: When set to true, Cortex will process and analyze the memory content to improve its indexing and retrieval capabilities. This includes extracting key concepts, understanding context, and optimizing how the memory is stored for better semantic search and recall.

Functionality

• Manual Memory Addition: Allows you to explicitly add specific memories for a user
• Vector Store Integration: Stores memories in a searchable vector database for semantic retrieval
• Tenant Isolation: Ensures memories are properly isolated by tenant and sub-tenant
• Automatic Provisioning: If the tenant/sub-tenant combination doesn’t exist for user memory, it will be automatically provisioned on first use

Use Cases

• Preference Storage: Store user preferences like preferred communication style, timezone, or language
• Context Preservation: Remember important details from previous conversations
• Personalization Data: Store information that helps tailor responses to individual users

Important Notes

Automatic Tenant Provisioning: If you receive an error stating “Tenant-id/sub-tenant-id combination either does not exist or is not provisioned for user memory”, this means the tenant/sub-tenant combination hasn’t been set up for user memory functionality yet. This will be automatically provisioned when you add or generate your first user memory for this combination.

Memory Persistence: User memories are stored permanently until explicitly deleted. They persist across sessions and can be retrieved using the Retrieve User Memory endpoint.

Best Practices:

• Use clear, descriptive memory content that will be useful for future AI interactions
• Consider the context in which memories will be retrieved
• Avoid storing sensitive information unless necessary
• Use consistent formatting for similar types of memories
• Choose either raw_text or user_assistant_pairs - do not provide both in the same request

Error Responses

All endpoints return consistent error responses following the standard format. For detailed error information, see our Error Responses documentation.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

tenant_id · string · required

Unique identifier for the tenant/organization

Example:

"tenant_1234"

sub_tenant_id · string | null

Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.

Example:

"sub_tenant_4567"

raw_text · string | null

Single raw text memory to store. If both raw_text and user_assistant_pairs are provided, raw_text will be used.

user_assistant_pairs · UserAssistantPair · object[] | null

Array of user/assistant conversation pairs to store as a single memory

Show child attributes

expiry_time · integer | null

Expiry time in seconds for the memory (optional)

infer · boolean · default: false

If true, process and compress chunks into inferred representations before indexing (default: False)

Example:

true

custom_instructions · string | null

Custom instructions to guide cortex

user_name · string | null

User's name for personalization

Example:

"John Doe"

memory_id · string | null

Optional custom memory ID (auto-generated if not provided)

Example:

"memory_1234"

Response

200

application/json

Successful Response

Response model for adding a new user memory.

success · boolean · default: true

Indicates whether the memory addition operation was successful

Example:

true

user_memory_added · boolean · default: true

Confirms whether the memory was successfully stored in the system

Example:

true

memory_id · string · default: ""

Unique identifier assigned to the newly created memory

Example:

"memory_1234"

source_id · string · default: ""

Source identifier from the memory service

Example:

"CortexDoc1234"

chunks_created · integer · default: 0

Total number of chunks created from the memory

Example:

1

original_chunks · integer · default: 0

Number of original (non-inferred) chunks created

Example:

1

inferred_chunks · integer · default: 0

Number of inferred chunks created

Example:

1