Configuration Reference¶

All tuning parameters for the Arandu SDK live in MemoryConfig. Every field has a sensible default - override only what you need.

from arandu.config import MemoryConfig

config = MemoryConfig(
    topk_facts=10,
    enable_reranker=False,
    min_score=0.15,
)

You can also override per-request via config_overrides:

result = await memory.retrieve(
    agent_id="user_123",
    query="...",
    config_overrides={"topk_facts": 5, "enable_reranker": False},
)

Extraction¶

Parameter	Type	Default	Description
`extraction_timeout_sec`	`float`	`30.0`	Timeout per LLM call during extraction.

Parameter	Type	Default	Description
`fuzzy_threshold`	`float`	`0.85`	Cosine similarity threshold for direct fuzzy match. Above this → auto-resolve. Below 0.50 → new entity. Between → LLM decides.
`enable_llm_resolution`	`bool`	`True`	Whether to use LLM for ambiguous entity matches. When `False`, ambiguous cases create new entities instead.

Parameter	Type	Default	Description
`topk_facts`	`int`	`20`	Maximum facts returned by `retrieve()`.
`topk_events`	`int`	`8`	Maximum events included in context.
`event_max_scan`	`int`	`200`	Maximum events scanned for relevance.
`min_similarity`	`float`	`0.20`	Minimum cosine similarity for semantic search candidates.
`min_confidence`	`float`	`0.55`	Minimum confidence for facts to be considered.
`min_score`	`float`	`0.15`	Minimum final score for facts to be included in results. Set higher (e.g., `0.20`) to filter low-relevance facts.
`recency_half_life_days`	`int`	`14`	Half-life for recency decay scoring.

Parameter	Type	Default	Description
`enable_reranker`	`bool`	`True`	Enable LLM-based reranking. When enabled, the reranker uses a multiplicative blend with the formula score - `score_weights` still matter for the base score.
`reranker_timeout_sec`	`float`	`5.0`	Timeout for the reranker LLM call. Falls back to original ranking on timeout.
`reranker_weight`	`float`	`0.70`	Weight of reranker score in the multiplicative blend: `final = formula × (floor + w × reranker)` where `floor = 1 - w`. Higher = more reranker influence. Lower = more formula score influence.
`min_reranker_score`	`float`	`0.10`	Minimum reranker score for a fact to survive. Facts below this threshold are eliminated (final_score = 0.0), giving the reranker veto power over irrelevant facts. Only applies when `enable_reranker=True`. Set `0.05` for more permissive, `0.20` for stricter.

Parameter	Type	Default	Description
`score_weights`	`dict`	`{"semantic": 0.70, "recency": 0.20, "importance": 0.10}`	Weights for hybrid ranking formula. Always affects the base formula score, which the reranker blends with multiplicatively.

Parameter	Type	Default	Description
`confidence_level_map`	`dict`	`{explicit: 0.95, strong: 0.80, weak: 0.60, speculation: 0.40}`	Confidence scores assigned during extraction.
`confidence_default`	`float`	`0.60`	Default confidence when LLM doesn't specify.

Parameter	Type	Default	Description
`spreading_activation_hops`	`int`	`2`	Maximum hops from seed facts. Set to `0` to disable.
`spreading_decay_factor`	`float`	`0.50`	Score decay per hop. Hop 1 = factor, Hop 2 = factor².
`spreading_max_related_entities`	`int`	`5`	Max KG-related entities explored per hop.
`spreading_facts_per_entity`	`int`	`3`	Max facts fetched per entity in spreading.

Parameter	Type	Default	Description
`context_max_tokens`	`int`	`2000`	Proportional token budget for context compression. Not a hard cap.
`hot_tier_ratio`	`float`	`0.5`	Fraction of budget for top-scoring facts (full detail).
`warm_tier_ratio`	`float`	`0.3`	Fraction of budget for mid-scoring facts (summarized).

Parameter	Type	Default	Description
`emotional_trend_window_days`	`int`	`30`	Lookback window for emotional trend detection.
`emotional_trend_min_events`	`int`	`5`	Minimum events to compute a trend.

Parameter	Type	Default	Description
`cluster_max_age_days`	`int`	`90`	Maximum age of facts included in clustering.
`cluster_min_facts`	`int`	`2`	Minimum facts per cluster.
`community_similarity_threshold`	`float`	`0.75`	Cosine similarity threshold for grouping clusters into communities.
`community_min_clusters`	`int`	`2`	Minimum clusters to form a community.

Parameter	Type	Default	Description
`consolidation_min_events`	`int`	`3`	Minimum events before running consolidation.
`consolidation_lookback_days`	`int`	`7`	How far back to look for patterns.

Parameter	Type	Default	Description
`importance_recency_halflife_days`	`int`	`30`	Half-life for importance score recency signal.
`summary_refresh_interval_days`	`int`	`7`	Entity summaries older than this are marked stale.

Parameter	Type	Default	Description
`vitality_stale_threshold`	`float`	`0.2`	Vitality score below which facts are considered stale.
`memify_merge_similarity_threshold`	`float`	`0.90`	Threshold for merging similar procedural memories.

Parameter	Type	Default	Description
`directive_max_tokens`	`int`	`300`	Max tokens for procedural directive generation.
`directive_cache_ttl_minutes`	`int`	`30`	TTL for directive cache.
`contradiction_similarity_threshold`	`float`	`0.80`	Threshold for detecting contradictions.

Parameter	Type	Default	Description
`timezone`	`str`	`"UTC"`	IANA timezone for temporal resolution in retrieval.

Parameter	Type	Default	Description
`extra_attribute_keys`	`set[str]`	`set()`	Additional attribute keys accepted by the system.
`attribute_aliases`	`dict[str, str]`	`{}`	Aliases for attribute keys.
`extra_namespaces`	`set[str]`	`set()`	Additional entity namespaces.
`extra_self_references`	`frozenset[str]`	`frozenset()`	Additional terms that resolve to `user:self`.
`extra_relationship_hints`	`frozenset[str]`	`frozenset()`	Additional relationship hint patterns.

Parameter	Type	Default	Description
`max_facts_per_event`	`int`	`100`	Maximum facts extracted per message (safety limit).
`embedding_dimensions`	`int`	`1536`	Embedding vector dimensions (must match your provider).