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: Ollama llama3.1:8b (local, no API key)
# Embedding: sentence-transformers all-MiniLM-L6-v2, 384 dims (local)
# Vector store: FAISS, in RAM unless you set a path
# History: SQLite at ~/.widemem/history.db
# Retrieval: balanced mode
# Uncertainty: helpful mode
# Decay: exponential, rate 0.01
# Scoring: similarity 0.5, importance 0.3, recency 0.2
# Hierarchy: disabled
# YMYL: disabled (opt in)
# Active retrieval: disabled
# TTL: none
))
The defaults need pip install "widemem-ai[local]" and a running Ollama with llama3.1:8b pulled. No API key. Cloud providers are optional extras: [openai] and [anthropic].
LLM providers
Extraction and conflict resolution both run through the configured LLM. Three providers are supported. Leave model unset and each provider picks its own default.
$python
from widemem.core.types import LLMConfig
# Ollama (default, local, no API key): llama3.1:8b
llm = LLMConfig(provider="ollama", base_url="http://localhost:11434")
# OpenAI: gpt-4o-mini. Needs pip install "widemem-ai[openai]"
llm = LLMConfig(provider="openai")
# Anthropic: claude-haiku-4-5-20251001. Needs pip install "widemem-ai[anthropic]"
llm = LLMConfig(provider="anthropic")
memory = WideMemory(config=MemoryConfig(llm=llm))
The local default is llama3.1:8b because llama3.2 (3B) kept the stale fact and split one fact into one per word in every one of our test runs. Any other Ollama model works through model=.
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
# sentence-transformers (default, local): all-MiniLM-L6-v2, 384 dims
emb = EmbeddingConfig(provider="sentence-transformers")
# Ollama: nomic-embed-text, 768 dims
emb = EmbeddingConfig(provider="ollama")
# OpenAI: text-embedding-3-small, 1536 dims. Needs the [openai] extra
emb = EmbeddingConfig(provider="openai")
memory = WideMemory(config=MemoryConfig(embedding=emb))
The default stack already runs fully local. After the first run has downloaded MiniLM (about 90 MB), set HF_HUB_OFFLINE=1 for air-gapped deployments.
Embedding dimensions are fixed per index
A vector index keeps the dimension it was built with. A 1536-dim FAISS index or Qdrant collection from widemem 1.x (OpenAI embeddings) will not open under the 384-dim default. To keep a 1.x store, set provider="openai" on both LLMConfig and EmbeddingConfig.
Vector stores
$python
from widemem.core.types import VectorStoreConfig
# FAISS (default). Without a path, vectors live in RAM and vanish on exit
vs = VectorStoreConfig(provider="faiss", path="~/.widemem/faiss")
# Qdrant: embedded with a path, or a server on localhost:6333 without one
vs = VectorStoreConfig(provider="qdrant", path="/var/lib/widemem/qdrant") # absolute: ~ is not expanded
# pgvector: any Postgres you can reach
vs = VectorStoreConfig(
provider="pgvector",
url="postgresql://user:pass@db.internal:5432/widemem?sslmode=require",
)
A FAISS path is a directory; widemem writes the index and its state file inside it. FAISS handles roughly 100k to 1M memories per process on commodity hardware. Above that, switch to Qdrant or pgvector. 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
Search reports a confidence level; your app decides what to say. Pass the confidence and a mode to the helper to get an action and a message. MemoryConfig.uncertainty_mode is not read by search.
$python
from widemem import UncertaintyMode
from widemem.retrieval.uncertainty import build_uncertainty_guidance
response = memory.search("what's their blood type?", user_id="alice")
# strict: refuse when unsure
# helpful: hedge with related context
# creative: offer to guess with a warning
guidance = build_uncertainty_guidance(response.confidence, UncertaintyMode.STRICT, list(response))
if guidance: # None means HIGH confidence: answer normally
print(guidance["action"], guidance["message"]) # e.g. "refuse"
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 opt-in (YMYLConfig(enabled=True)) 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.