Skip to main content
POST
/
user_memory
/
add_user_memory
Add User Memory
curl --request POST \
  --url https://api.usecortex.ai/user_memory/add_user_memory \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "raw_text": "<string>",
  "user_assistant_pairs": [
    {
      "user": "<user>",
      "assistant": "<assistant>"
    }
  ],
  "expiry_time": 123,
  "infer": true,
  "custom_instructions": "<string>"
}'
{
  "success": true,
  "user_memory_added": true,
  "memory_id": "memory_1234",
  "chunks_created": 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.

​
Examples

  • API Request
  • TypeScript
  • Python (Sync)
# 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."
}'

​
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

Query Parameters

​
tenant_id
string
required
Example:
​
sub_tenant_id
string
default:""
Example:

Body

application/json
​
raw_text
string | null
​
user_assistant_pairs
UserAssistantPair · object[] | null
​
expiry_time
integer | null
​
infer
boolean
default:false
Example:
​
custom_instructions
string | null

Response

​
success
boolean
required
Example:
​
user_memory_added
boolean
required
Example:
​
memory_id
string
required
Example:
​
chunks_created
integer
default:0
Example: