Skip to main content

​
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:
  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

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: 
from upsonic.vectordb import SuperMemoryProvider, SuperMemoryConfig

config = SuperMemoryConfig(collection_name="my_kb")
vectordb = SuperMemoryProvider(config)

​
Custom Search Settings

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)

ParameterTypeDescriptionDefaultRequired
collection_namestrName of the collection (also used as default container_tag)"default_collection"No
vector_sizeintDimension of vectors (unused, kept for interface compatibility)0No
distance_metricDistanceMetricSimilarity metric (COSINE, EUCLIDEAN, DOT_PRODUCT)COSINENo
recreate_if_existsboolRecreate collection if it existsFalseNo
default_top_kintDefault number of results10No
default_similarity_thresholdOptional[float]Minimum similarity score (0.0-1.0)NoneNo
dense_search_enabledboolEnable dense vector searchFalseNo
full_text_search_enabledboolEnable full-text searchTrueNo
hybrid_search_enabledboolEnable hybrid searchTrueNo
default_hybrid_alphafloatDefault alpha for hybrid search (0.0-1.0)0.5No
default_fusion_methodLiteral['rrf', 'weighted']Default fusion method for hybrid search'weighted'No
provider_nameOptional[str]Provider nameNoneNo
provider_descriptionOptional[str]Provider descriptionNoneNo
provider_idOptional[str]Provider IDNoneNo
default_metadataOptional[Dict[str, Any]]Default metadata for all recordsNoneNo
auto_generate_content_idboolAuto-generate content IDsTrueNo
indexed_fieldsOptional[List[Union[str, Dict[str, Any]]]]Fields to index for filteringNoneNo

​
SuperMemory-Specific Parameters

ParameterTypeDescriptionDefaultRequired
api_keyOptional[SecretStr]SuperMemory API key. Falls back to SUPERMEMORY_API_KEY env varNoneNo
container_tagOptional[str]Tag for grouping memories. Defaults to collection_nameNoneNo
search_modeLiteral['hybrid', 'memories']Search mode: hybrid combines vector + keyword, memories uses memory-level retrieval'hybrid'No
thresholdfloatMinimum similarity threshold for search results (0.0-1.0)0.5No
rerankboolEnable server-side reranking of search resultsFalseNo
max_retriesintMaximum number of API request retries2No
timeoutfloatAPI request timeout in seconds60.0No
batch_delayfloatDelay in seconds between individual upsert calls (rate-limit protection)0.1No

​
Search Modes

SuperMemory supports two search modes, configured via the search_mode parameter:
ModeDescription
hybridCombines vector similarity with keyword matching for best overall relevance. Default and recommended.
memoriesRetrieves 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.