Content Organization
Use containerTags for grouping/partitioning
Optional tags (array of strings) to group memories.
Can be a user ID, project ID, or any other identifier.
Allows filtering for memories that share specific tags.
Example: ["user_123", "project_alpha"]
Read more about filtering
Performance Tips
Batch Operations
You can add multiple items in parallel
Use different containerTags for different spaces
Don’t wait for processing to complete unless needed
Search Optimization
{ "q" : "error logs" , "documentThreshold" : 0.7 , // Higher = more precise "limit" : 5 , // Keep it small "onlyMatchingChunks" : true // Skip extra context if not needed }
URL Content
Send clean URLs without tracking parameters
Use article URLs, not homepage URLs
Check URL accessibility before sending
Basic Usage To add a memory, send a POST request to /add with your content:
curl https://api.supermemory.ai/v3/memories \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \ --data '{ "customId": "xyz-my-db-id", "content": "This is the content of my memory", "metadata": { "category": "technology", "tag_1": "ai", "tag_2": "machine-learning", }, "containerTags": ["user_123", "project_xyz"] }'
The API will return a response with an ID and initial status:
{ "id" : "mem_abc123" , "status" : "queued" } curl https://api.supermemory.ai/v3/memories \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \ -d '{ "content": "https://example.com/article", "metadata": { "source": "web", # Just example metadata "category": "technology" # NOT required }, "containerTags": ["user_456", "research_papers"] }'
You can add rich metadata to organize your content:
{ "metadata" : { "source" : "string" , // String "priority" : 1234 , // Custom numeric field "custom_field" : "any" // Any custom field } } Partitioning by user You can attribute and partition your data by providing a userId:
curl https://api.supermemory.ai/v3/memories \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \ -d '{ "content": "This is space-specific content", "userId": "space_123", "metadata": { "category": "space-content" } }'
When searching, if you provide a userId, only memories from that space will be returned.
Grouping You can group memories by providing an array of containerTags:
curl https://api.supermemory.ai/v3/memories \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \ -d '{ "content": "This is space-specific content", "containerTags": ["user_123", "project_xyz"] }'
Checking Status Check status using the memory ID:
curl https://api.supermemory.ai/v3/memories/mem_abc123 \ --request GET \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
Memories are deleted after 2 minutes if an irrecoverable error occurs.
Next Steps Explore more advanced features in our API Reference
