ContextQMD
Back to Supermemory

Adding Memories

apps/docs/memory-api/creation/adding-memories.mdx

latest8.1 KB
Original Source
<Accordion title="Best Practices" icon="sparkles"> 1. **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](/memory-api/features/filtering)

2. 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

    json
    {
  "q": "error logs",
  "documentThreshold": 0.7, // Higher = more precise
  "limit": 5, // Keep it small
  "onlyMatchingChunks": true // Skip extra context if not needed
}
  1. URL Content
    • Send clean URLs without tracking parameters
    • Use article URLs, not homepage URLs
    • Check URL accessibility before sending
</Accordion>

Basic Usage

To add a memory, send a POST request to /add with your content:

<CodeGroup>
bash
curl https://api.supermemory.ai/v3/documents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  --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"]
}'
typescript
await client.memory.create({
	customId: "xyz-mydb-id",
	content: "This is the content of my memory",
	metadata: {
		category: "technology",
		tag_1": "ai",
    tag_2": "machine-learning",
	},
	containerTags: ["user_123", "project_xyz"]
})
python
client.memory.create(
    customId="xyz-mydb-id",
    content="documents related to python",
    metadata={
        "category": "datascience",
        "tag_1": "ai",
        "tag_2": "machine-learning",
    },
    containerTags=["user_123", "project_xyz"]
)
</CodeGroup>

The API will return a response with an ID and initial status:

json
{
  "id": "mem_abc123",
  "status": "queued"
}
<CodeGroup>
bash
curl https://api.supermemory.ai/v3/documents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  -d '{
    "content": "https://example.com/article",
    "metadata": {
      "source": "web",			# Just example metadata
      "category": "technology"	# NOT required
    },
    "containerTags": ["user_456", "research_papers"]
  }'
typescript
await client.memory.create({
  content: "https://example.com/article",
  userId: "user_456",
  metadata: {
    source: "web", // Just example metadata
    category: "technology", // NOT required
  },
  containerTags: ["user_456", "research_papers"],
});
python
client.memory.create(
    content="https://example.com/article",
    userId="user_456",
    metadata={
        "source": "web",
        "category": "technology"
    },
    containerTags=["user_456", "research_papers"]
)
</CodeGroup>

Metadata and Organization

You can add rich metadata to organize your content:

json
{
  "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:

<CodeGroup>
bash
curl https://api.supermemory.ai/v3/documents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  -d '{
    "content": "This is space-specific content",
    "userId": "space_123",
    "metadata": {
      "category": "space-content"
    }
  }'
typescript
await client.memory.create({
  content: "This is space-specific content",
  userId: "space_123",
  metadata: {
    category: "space-content",
  },
});
python
client.memory.create(
    content="This is space-specific content",
    userId="space_123",
    metadata={
        "category": "space-content"
    }
)
</CodeGroup> <Note> When searching, if you provide a `userId`, only memories from that space will be returned. </Note>

Grouping

You can group memories by providing an array of containerTags:

<CodeGroup>
bash
curl https://api.supermemory.ai/v3/documents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  -d '{
    "content": "This is space-specific content",
    "containerTags": ["user_123", "project_xyz"]
  }'
typescript
await client.memory.create({
  content: "This is space-specific content",
  containerTags: ["user_123", "project_xyz"],
});
python
client.memory.create(
    content="This is space-specific content",
    containerTags=["user_123", "project_xyz"]
)
</CodeGroup>

Checking Status

Check status using the memory ID:

<CodeGroup>
bash
curl https://api.supermemory.ai/v3/documents/mem_abc123 \
  --request GET \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY'
typescript
await client.memory.get("mem_abc123");
python
client.memory.get("mem_abc123")
</CodeGroup> <Warning>

Memories are deleted after 2 minutes if an irrecoverable error occurs.

</Warning>

File Uploads

For file uploads, use the dedicated file upload endpoint. You can include containerTags directly in the form data:

<CodeGroup>
bash
curl https://api.supermemory.ai/v3/documents/file \
  --request POST \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  --form 'file=@/path/to/your/file.pdf' \
  --form 'containerTags=["user_123", "project_xyz"]'
typescript
const formData = new FormData();
formData.append("file", fileBlob);
formData.append("containerTags", JSON.stringify(["user_123", "project_xyz"]));

const response = await fetch("https://api.supermemory.ai/v3/documents/file", {
  method: "POST",
  headers: {
    Authorization: "Bearer SUPERMEMORY_API_KEY",
  },
  body: formData,
});
python
import requests
import json

with open('/path/to/your/file.pdf', 'rb') as f:
    files = {'file': f}
    data = {'containerTags': json.dumps(["user_123", "project_xyz"])}
    response = requests.post(
        'https://api.supermemory.ai/v3/documents/file',
        headers={'Authorization': 'Bearer SUPERMEMORY_API_KEY'},
        files=files,
        data=data
    )
</CodeGroup>

Adding Additional Metadata to Files

If you need to add additional metadata (like title or description) after upload, you can use the PATCH endpoint:

<CodeGroup>
bash
curl https://api.supermemory.ai/v3/documents/MEMORY_ID \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  --data '{
    "metadata": {
      "title": "My Document",
      "description": "Important project document"
    }
  }'
typescript
await fetch(`https://api.supermemory.ai/v3/documents/${memoryId}`, {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer SUPERMEMORY_API_KEY",
  },
  body: JSON.stringify({
    metadata: {
      title: "My Document",
      description: "Important project document",
    },
  }),
});
python
import requests

requests.patch(
    f'https://api.supermemory.ai/v3/documents/{memory_id}',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SUPERMEMORY_API_KEY'
    },
    json={
        'metadata': {
            'title': 'My Document',
            'description': 'Important project document'
        }
    }
)
</CodeGroup> <Note> Metadata-only PATCH updates the document in place—no reindexing. Use this when adding or changing metadata (e.g. `accepted`, `title`, `description`) without modifying the document content. </Note>

Next Steps

Explore more advanced features in our API Reference tab.