# Configuration

All memory system parameters are configured through a single `MemoryConfig` dataclass. Every parameter has a sensible default — override only what matters for your use case.

```python
from arandu import MemoryClient, MemoryConfig

config = MemoryConfig(
    extraction_mode="single_pass",
    topk_facts=30,
    enable_reranker=True,
)

memory = MemoryClient(
    database_url="postgresql+psycopg://...",
    llm=provider,
    embeddings=provider,
    config=config,
)
```

---

## Extraction

Parameters controlling how facts, entities, and relationships are extracted from messages.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `extraction_model` | `str` | `"gpt-4o"` | LLM model used for fact extraction |
| `extraction_mode` | `str` | `"multi_pass"` | Extraction strategy: `"multi_pass"` (3 LLM calls, higher accuracy) or `"single_pass"` (1 call, faster) |
| `extraction_timeout_sec` | `float` | `30.0` | Timeout per LLM call during extraction |
| `multi_pass_entity_threshold` | `int` | `3` | Entity count at or below which multi-pass falls back to single-pass |
| `entity_batch_size` | `int` | `5` | Number of entities per fact-extraction batch in multi-pass mode |
| `reflexion_timeout_sec` | `float` | `10.0` | Timeout for the optional reflexion (quality review) pass in single-pass mode |

**Tips:**

- Use `"single_pass"` for simple messages with 1-2 entities — it's faster and cheaper
- Increase `entity_batch_size` if your messages mention many entities at once
- Lower `extraction_timeout_sec` if you need faster responses at the cost of potentially missed extractions

---

## Entity Resolution

Parameters controlling how extracted entity mentions are resolved to canonical entity records.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `fuzzy_threshold` | `float` | `0.85` | Cosine similarity threshold for direct fuzzy match (above this = automatic match) |
| `enable_llm_resolution` | `bool` | `True` | Whether to use an LLM for ambiguous fuzzy matches (0.50–0.85 range) |
| `entity_resolution_model` | `str` | `"gpt-4o-mini"` | LLM model for entity disambiguation |
| `entity_resolution_timeout_sec` | `float` | `10.0` | Timeout for LLM entity resolution calls |

**Tips:**

- Lower `fuzzy_threshold` (e.g., 0.75) to be more aggressive in matching similar entity names
- Set `enable_llm_resolution=False` to skip the LLM fallback for ambiguous matches (faster, but may create more duplicate entities)

---

## Reconciliation

Parameters controlling how new facts are compared against existing knowledge.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `reconciliation_model` | `str` | `"gpt-4o-mini"` | LLM model for reconciliation decisions (ADD/UPDATE/NOOP/DELETE) |
| `reconciliation_timeout_sec` | `float` | `10.0` | Timeout for reconciliation LLM calls |

---

## Retrieval

Parameters controlling how facts are retrieved in response to queries.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `topk_facts` | `int` | `20` | Maximum number of facts to return |
| `topk_events` | `int` | `8` | Maximum number of events to consider for context |
| `event_max_scan` | `int` | `200` | Maximum events to scan during retrieval |
| `min_similarity` | `float` | `0.20` | Minimum cosine similarity for semantic search results |
| `min_confidence` | `float` | `0.55` | Minimum fact confidence to include in results |
| `recency_half_life_days` | `int` | `14` | Half-life (in days) for exponential recency decay |
| `context_budget_tokens` | `int` | `3000` | Total token budget for the retrieval pipeline |
| `enable_reranker` | `bool` | `True` | Whether to use LLM reranking on retrieval results |
| `reranker_model` | `str` | `"gpt-4o-mini"` | LLM model for reranking |
| `reranker_timeout_sec` | `float` | `5.0` | Timeout for reranker LLM calls |

**Tips:**

- Increase `topk_facts` (e.g., 50) for broader context at the cost of more noise
- Lower `min_similarity` (e.g., 0.10) to catch more distant semantic matches
- Increase `recency_half_life_days` (e.g., 30) if older facts should remain relevant longer
- Set `enable_reranker=False` for faster retrieval when precision is less critical

---

## Score Weights

Weights for the hybrid ranking formula that combines multiple retrieval signals.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `score_weights` | `dict` | `{"semantic": 0.70, "recency": 0.20, "importance": 0.10}` | Weights for each scoring signal (must sum to ~1.0) |

```python
config = MemoryConfig(
    score_weights={
        "semantic": 0.60,   # reduce semantic, boost other signals
        "recency": 0.25,
        "importance": 0.15,
    },
)
```

**Tips:**

- Increase `"recency"` weight for applications where freshness matters more than semantic relevance
- Increase `"importance"` weight to favor well-established entities and frequently mentioned facts

---

## Confidence

Parameters controlling confidence levels assigned to extracted facts.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `confidence_level_map` | `dict` | `{"explicit_statement": 0.95, "strong_inference": 0.80, "weak_inference": 0.60, "speculation": 0.40}` | Mapping from confidence level names to numeric scores |
| `confidence_default` | `float` | `0.60` | Default confidence when the LLM doesn't specify a level |

---

## Spreading Activation

Parameters controlling how context expands from seed facts along entity relationships.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `spreading_activation_hops` | `int` | `2` | Maximum number of relationship hops from seed facts |
| `spreading_decay_factor` | `float` | `0.50` | Score decay multiplier per hop (0.5 = halved each hop) |
| `spreading_max_related_entities` | `int` | `5` | Maximum related entities to follow per seed |
| `spreading_facts_per_entity` | `int` | `3` | Maximum facts to pull from each related entity |

---

## Context Compression

Parameters controlling how retrieved facts are compressed into the final context string.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `context_max_tokens` | `int` | `2000` | Maximum tokens in the formatted context output |
| `hot_tier_ratio` | `float` | `0.50` | Share of token budget for highest-scored facts |
| `warm_tier_ratio` | `float` | `0.30` | Share of token budget for supporting facts |

The remaining budget (1 - hot - warm = 0.20) goes to the cold tier (background context).

---

## Emotional Trends

Parameters for detecting emotional patterns in user messages.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `emotional_trend_window_days` | `int` | `30` | Window for analyzing emotional trends |
| `emotional_trend_min_events` | `int` | `5` | Minimum events required to detect a trend |

---

## Clustering

Parameters for the fact clustering background job.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `cluster_max_age_days` | `int` | `90` | Maximum age of facts to include 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

Parameters for the consolidation background job.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `consolidation_min_events` | `int` | `3` | Minimum events before running consolidation |
| `consolidation_lookback_days` | `int` | `7` | How far back (in days) to look for patterns |

---

## Sleep-Time Compute

Parameters for background importance scoring and summary refresh.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `importance_recency_halflife_days` | `int` | `30` | Half-life for recency signal in importance scoring |
| `summary_refresh_interval_days` | `int` | `7` | Days before an entity summary is considered stale |

---

## Memify

Parameters for the memify (episodic → procedural knowledge) background job.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `vitality_stale_threshold` | `float` | `0.2` | Vitality score below which a fact is considered stale |
| `memify_merge_similarity_threshold` | `float` | `0.90` | Similarity threshold for merging similar procedures |

---

## Procedural Memory

Parameters for directive/procedural memory retrieval.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `directive_max_tokens` | `int` | `300` | Maximum tokens for procedural directives |
| `directive_cache_ttl_minutes` | `int` | `30` | Cache TTL for directive lookups |
| `contradiction_similarity_threshold` | `float` | `0.80` | Threshold for detecting contradictory directives |

---

## Locale / Deployment

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `timezone` | `str` | `"UTC"` | IANA timezone for temporal resolution in retrieval (e.g., `"America/Sao_Paulo"`) |

---

## Open Catalog (Deployer Extensions)

Parameters for extending the built-in attribute catalog with custom entries.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `extra_attribute_keys` | `set[str]` | `set()` | Additional attribute keys recognized during extraction |
| `attribute_aliases` | `dict[str, str]` | `{}` | Aliases for attribute keys (e.g., `{"hometown": "city"}`) |
| `extra_namespaces` | `set[str]` | `set()` | Additional entity namespaces beyond built-in types |
| `extra_self_references` | `frozenset[str]` | `frozenset()` | Additional words treated as self-references (e.g., `{"yo"}` for Spanish) |
| `extra_relationship_hints` | `frozenset[str]` | `frozenset()` | Additional relationship hint words for entity resolution |

---

## Limits

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `max_facts_per_event` | `int` | `100` | Maximum facts extracted from a single message |
| `embedding_dimensions` | `int` | `1536` | Dimensionality of embedding vectors (must match your provider) |
