CONFIGURATION

Everything widemem exposes through MemoryConfig. Defaults work out of the box; override only what you need.

The default config

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.

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

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

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.

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)

Uncertainty modes

How widemem behaves when retrieval confidence is LOW or NONE.

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.

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.

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.