Everything widemem exposes through MemoryConfig. Defaults work out of the box; override only what you need.
The default config
$python
from widemem import WideMemory, MemoryConfig
# These are the defaults. Calling WideMemory() with no args is equivalent.
memory = WideMemory(config=MemoryConfig(
# LLM: OpenAI gpt-4o-mini
# Embedding: text-embedding-3-small
# Vector store: FAISS local
# Retrieval: balanced mode
# Uncertainty: helpful mode
# Decay: exponential, rate 0.01
# Scoring: similarity 0.5, importance 0.3, recency 0.2
# Hierarchy: disabled
# Active retrieval: disabled
# TTL: none
))
LLM providers
Extraction and conflict resolution both run through the configured LLM. Three providers are supported out of the box.
$python
from widemem.core.types import LLMConfig
# OpenAI (default)
llm = LLMConfig(provider="openai", model="gpt-4o-mini")
# Anthropic
llm = LLMConfig(provider="anthropic", model="claude-haiku-4-5")
# Ollama (local, no API key)
llm = LLMConfig(provider="ollama", model="llama3.2", base_url="http://localhost:11434")
memory = WideMemory(config=MemoryConfig(llm=llm))
API keys come from OPENAI_API_KEY or ANTHROPIC_API_KEY environment variables, or can be passed explicitly via LLMConfig(api_key=...). widemem does not log, cache, or transmit keys beyond what the provider SDKs do.
Embedding providers
$python
from widemem.core.types import EmbeddingConfig
# OpenAI (default)
emb = EmbeddingConfig(provider="openai", model="text-embedding-3-small")
# Local, no API key
emb = EmbeddingConfig(
provider="sentence-transformers",
model="all-MiniLM-L6-v2",
)
memory = WideMemory(config=MemoryConfig(embedding=emb))
For air-gapped deployments, combine Ollama (LLM) with sentence-transformers (embeddings) and the whole stack runs locally.
Vector stores
$python
from widemem.core.types import VectorStoreConfig
# FAISS local (default)
vs = VectorStoreConfig(provider="faiss", path="~/.widemem/faiss_index")
# Qdrant local or remote
vs = VectorStoreConfig(
provider="qdrant",
host="qdrant.internal",
port=6333,
collection_name="widemem",
)
FAISS handles roughly 100k to 1M memories per process on commodity hardware. Above that, switch to Qdrant. See /docs/self-hosting for scaling guidance.
Retrieval modes
Three presets controlling retrieval depth, candidate pool size, and similarity boost. Override at init or per query.
$python
from widemem import WideMemory, MemoryConfig
from widemem.core.types import RetrievalMode
# Default: balanced
config = MemoryConfig(retrieval_mode=RetrievalMode.BALANCED)
# Fast: lower latency, smaller top_k
config = MemoryConfig(retrieval_mode=RetrievalMode.FAST)
# Deep: highest accuracy, larger top_k
config = MemoryConfig(retrieval_mode=RetrievalMode.DEEP)
# Or override per query
results = memory.search("query", mode=RetrievalMode.DEEP)
Balanced is the default
As of v1.4, balanced mode enables hierarchy and uses top_k=25. Earlier defaults were equivalent to fast. If you are upgrading from v1.3 and see higher latency, this is why; switch to fast to restore the old behavior.
Uncertainty modes
How widemem behaves when retrieval confidence is LOW or NONE.
$python
from widemem.core.types import UncertaintyMode
# strict: refuse to answer when unsure
config = MemoryConfig(uncertainty_mode=UncertaintyMode.STRICT)
# helpful (default): hedge with related context
config = MemoryConfig(uncertainty_mode=UncertaintyMode.HELPFUL)
# creative: offer to guess with a warning
config = MemoryConfig(uncertainty_mode=UncertaintyMode.CREATIVE)
Scoring weights
The final score for a retrieved memory combines three signals. Defaults: similarity 0.5, importance 0.3, recency 0.2.
$python
from widemem.core.types import ScoringConfig, DecayFunction
scoring = ScoringConfig(
similarity_weight=0.5,
importance_weight=0.3,
recency_weight=0.2,
decay_function=DecayFunction.EXPONENTIAL,
decay_rate=0.01,
)
memory = WideMemory(config=MemoryConfig(scoring=scoring))
Decay functions: EXPONENTIAL (default, smooth), LINEAR, STEP, or NONE (disable recency weighting entirely).
YMYL and topic weights
YMYL (Your Money or Your Life) classification automatically boosts importance and disables decay for health, financial, and legal facts. It is on by default and uses a two-tier pattern system to avoid false positives. Topic weights let you manually bias retrieval for your own categories.
See the YMYL.md doc for the full pattern list, classifier flow, and limitations.
TTL (time-to-live)
Auto-expire memories older than N days at search time. No background jobs needed.
$python
memory = WideMemory(config=MemoryConfig(ttl_days=30))
Useful for ephemeral session context that should not leak into long-term memory. YMYL-classified facts bypass TTL.
Full reference
Every config field, provider option, and default value is in the README. The source of truth for MemoryConfig is widemem/core/types.py.