# Configuration Reference

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

```python
from arandu.config import MemoryConfig

config = MemoryConfig(
    topk_facts=10,
    enable_reranker=False,
    min_score=0.1,
)
```

You can also override per-request via `config_overrides`:

```python
result = await memory.retrieve(
    user_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. |

## Entity Resolution

| 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. |

## Retrieval

| 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.10` | Minimum final score for facts to be included in results. Set higher (e.g., `0.1`) to filter low-relevance facts. |
| `recency_half_life_days` | `int` | `14` | Half-life for recency decay scoring. |

## Reranker

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `enable_reranker` | `bool` | `True` | Enable LLM-based reranking. When enabled, the reranker determines final scores — `score_weights` only affect pre-reranking order. |
| `reranker_timeout_sec` | `float` | `5.0` | Timeout for the reranker LLM call. Falls back to original ranking on timeout. |

## Score Weights

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `score_weights` | `dict` | `{"semantic": 0.70, "recency": 0.20, "importance": 0.10}` | Weights for hybrid ranking formula. Only affects ranking when `enable_reranker=False`. |

## Confidence

| 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. |

## Spreading Activation

| 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. |

## Context Compression

| 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). |

## Emotional Trends

| 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. |

## Clustering

| 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. |

## Consolidation

| 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. |

## Sleep-Time Compute

| 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. |

## Memify

| 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. |

## Procedural Memory

| 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. |

## Locale

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

## Open Catalog (Extensions)

| 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. |

## Limits

| 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). |
