> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SuperMemory
> Using SuperMemory as a vector database provider
## Overview
SuperMemory is a managed memory API that handles embedding, chunking, and indexing internally. Unlike traditional vector databases, you send raw text and SuperMemory takes care of vectorization and semantic search. This makes it a zero-configuration knowledge retrieval layer — no embedding provider setup required.
**Provider Class:** `SuperMemoryProvider`\
**Config Class:** `SuperMemoryConfig`
## Install
Install the SuperMemory optional dependency group:
```bash theme={null}
uv pip install "upsonic[supermemory]"
```
## Key Differences from Traditional Vector DBs
* **No embedding provider needed.** SuperMemory embeds text internally, so you do not pass an `embedding_provider` to `KnowledgeBase`.
* **No `vector_size` to configure.** The config defaults to `0` because vectors are managed server-side.
* **No dense (raw-vector) search.** Only `full_text` and `hybrid` search modes are supported.
* **Container tags instead of collections.** The `collection_name` maps to a SuperMemory `container_tag` for organizing memories.
## Examples
### Basic Usage with KnowledgeBase
```python theme={null}
from upsonic import Agent, Task, KnowledgeBase
from upsonic.vectordb import SuperMemoryProvider, SuperMemoryConfig
# Setup SuperMemory — no embedding provider needed
config = SuperMemoryConfig(
collection_name="my_kb",
api_key="sm_your_api_key_here",
)
vectordb = SuperMemoryProvider(config)
# Create knowledge base
kb = KnowledgeBase(
sources=["document.pdf", "data/"],
vectordb=vectordb,
)
# Use with Agent
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task(
description="What are the main topics in the documents?",
context=[kb],
)
result = agent.do(task)
print(result)
```
### Using Environment Variable for API Key
Set `SUPERMEMORY_API_KEY` in your environment or `.env` file, then omit `api_key` from the config:
```python theme={null}
from upsonic.vectordb import SuperMemoryProvider, SuperMemoryConfig
config = SuperMemoryConfig(collection_name="my_kb")
vectordb = SuperMemoryProvider(config)
```
### Custom Search Settings
```python theme={null}
from upsonic import Agent, Task, KnowledgeBase
from upsonic.vectordb import SuperMemoryProvider, SuperMemoryConfig
config = SuperMemoryConfig(
collection_name="research_docs",
container_tag="research_v2",
search_mode="memories",
threshold=0.3,
rerank=True,
batch_delay=0.5,
)
vectordb = SuperMemoryProvider(config)
# Create knowledge base
kb = KnowledgeBase(
sources=["document.pdf", "data/"],
vectordb=vectordb,
)
# Use with Agent
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task(
description="What are the main topics in the documents?",
context=[kb],
)
result = agent.do(task)
print(result)
```
## Parameters
### Base Parameters (from BaseVectorDBConfig)
| Parameter | Type | Description | Default | Required |
| ------------------------------ | -------------------------------------------- | --------------------------------------------------------------- | ---------------------- | -------- |
| `collection_name` | `str` | Name of the collection (also used as default `container_tag`) | `"default_collection"` | No |
| `vector_size` | `int` | Dimension of vectors (unused, kept for interface compatibility) | `0` | No |
| `distance_metric` | `DistanceMetric` | Similarity metric (`COSINE`, `EUCLIDEAN`, `DOT_PRODUCT`) | `COSINE` | No |
| `recreate_if_exists` | `bool` | Recreate collection if it exists | `False` | No |
| `default_top_k` | `int` | Default number of results | `10` | No |
| `default_similarity_threshold` | `Optional[float]` | Minimum similarity score (0.0-1.0) | `None` | No |
| `dense_search_enabled` | `bool` | Enable dense vector search | `False` | No |
| `full_text_search_enabled` | `bool` | Enable full-text search | `True` | No |
| `hybrid_search_enabled` | `bool` | Enable hybrid search | `True` | No |
| `default_hybrid_alpha` | `float` | Default alpha for hybrid search (0.0-1.0) | `0.5` | No |
| `default_fusion_method` | `Literal['rrf', 'weighted']` | Default fusion method for hybrid search | `'weighted'` | No |
| `provider_name` | `Optional[str]` | Provider name | `None` | No |
| `provider_description` | `Optional[str]` | Provider description | `None` | No |
| `provider_id` | `Optional[str]` | Provider ID | `None` | No |
| `default_metadata` | `Optional[Dict[str, Any]]` | Default metadata for all records | `None` | No |
| `indexed_fields` | `Optional[List[Union[str, Dict[str, Any]]]]` | Fields to index for filtering | `None` | No |
### SuperMemory-Specific Parameters
| Parameter | Type | Description | Default | Required |
| --------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | -------- |
| `api_key` | `Optional[SecretStr]` | SuperMemory API key. Falls back to `SUPERMEMORY_API_KEY` env var | `None` | No |
| `container_tag` | `Optional[str]` | Tag for grouping memories. Defaults to `collection_name` | `None` | No |
| `search_mode` | `Literal['hybrid', 'memories']` | Search mode: `hybrid` combines vector + keyword, `memories` uses memory-level retrieval | `'hybrid'` | No |
| `threshold` | `float` | Minimum similarity threshold for search results (0.0-1.0) | `0.5` | No |
| `rerank` | `bool` | Enable server-side reranking of search results | `False` | No |
| `max_retries` | `int` | Maximum number of API request retries | `2` | No |
| `timeout` | `float` | API request timeout in seconds | `60.0` | No |
| `batch_delay` | `float` | Delay in seconds between individual upsert calls (rate-limit protection) | `0.1` | No |
| `index_delay` | `float` | Seconds to wait after upsert for async indexing to complete. SuperMemory indexes content asynchronously — this delay ensures content is searchable before queries run. Set to `0` to skip. | `7.0` | No |
## Search Modes
SuperMemory supports two search modes, configured via the `search_mode` parameter:
| Mode | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `hybrid` | Combines vector similarity with keyword matching for best overall relevance. **Default and recommended.** |
| `memories` | Retrieves at the memory level, suited for full-text and contextual recall. Used internally for `full_text_search`. |
Dense (raw-vector) search is **not supported** because SuperMemory manages its own embeddings. Calling `dense_search` returns an empty list.