Configuração¶

Todos os parâmetros do sistema de memória são configurados através de uma única dataclass MemoryConfig. Todo parâmetro tem um default sensato - sobrescreva apenas o que importa para o seu caso de uso.

from arandu import MemoryClient, MemoryConfig

config = MemoryConfig(
    extraction_timeout_sec=15.0,
    topk_facts=30,
    enable_reranker=True,
)

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

Extraction¶

Parâmetros que controlam como fatos, entidades e relacionamentos são extraídos de mensagens.

Parâmetro	Tipo	Default	Descrição
`extraction_timeout_sec`	`float`	`30.0`	Timeout por chamada LLM durante extração. No timeout, a extração retorna resultado vazio (fail-safe) - sem exceção
`enable_informed_extraction`	`bool`	`True`	Habilita extração informada por memória (v0.9.0+). Quando habilitado, o pipeline usa uma única chamada LLM informada pelo conhecimento existente em vez de 4 chamadas separadas. Cai pro fallback (extração cega) em caso de falha. `False` para usar a extração multi-pass legada
`informed_extraction_topk`	`int`	`10`	Máximo de fatos existentes a recuperar por entidade como contexto da extração informada. Só usado quando a entidade não tem profile_text
`informed_extraction_context_budget_tokens`	`int`	`800`	Budget de tokens para o contexto de conhecimento existente injetado no prompt de extração informada. Distribuído entre as entidades encontradas

Dicas:

O modelo de extração é determinado pelo LLMProvider injetado no MemoryClient. Para usar um modelo mais barato na extração, injete um provider configurado com esse modelo
Reduza extraction_timeout_sec se precisa de respostas mais rápidas ao custo de extrações potencialmente perdidas
Use enable_informed_extraction=False se seu provider LLM tiver dificuldade com o prompt unificado (ex: modelos menores). O sistema cai automaticamente pra extração legada de 4 chamadas + reconciliação

Entity Resolution¶

Parâmetros que controlam como menções de entidades extraídas são resolvidas para registros canônicos.

Parâmetro	Tipo	Default	Descrição
`fuzzy_threshold`	`float`	`0.85`	Threshold de similaridade de cosseno para fuzzy match direto. Score ≥ esse valor resolve diretamente; score entre 0.50 e esse valor encaminha para LLM; score < 0.50 cria nova entidade. Reduzir esse valor expande a faixa de fuzzy-resolve e reduz chamadas LLM
`enable_llm_resolution`	`bool`	`True`	Se deve usar um LLM para fuzzy matches ambíguos (faixa 0.50 - `fuzzy_threshold`). Quando `False`, candidatos ambíguos criam nova entidade

Dicas:

Reduza fuzzy_threshold (ex: 0.75) para ser mais agressivo no matching - isso encolhe a faixa "ambígua" que requer chamadas LLM
Defina enable_llm_resolution=False para pular o fallback LLM em matches ambíguos (mais rápido, mas pode criar mais entidades duplicadas)
O modelo LLM para entity resolution e reconciliação é determinado pelo LLMProvider injetado no MemoryClient

Retrieval¶

Parâmetros que controlam como fatos são recuperados em resposta a queries.

Parâmetro	Tipo	Default	Descrição
`topk_facts`	`int`	`20`	Número máximo de fatos a retornar
`topk_events`	`int`	`8`	Número máximo de eventos a considerar para contexto
`event_max_scan`	`int`	`200`	Máximo de eventos a escanear durante retrieval
`min_similarity`	`float`	`0.20`	Similaridade de cosseno mínima para resultados de busca semântica
`min_confidence`	`float`	`0.55`	Confiança mínima do fato para incluir nos resultados de retrieval

min_confidence é um filtro apenas de read-time

Todos os fatos são persistidos durante o write independente do score de confidence. A filtragem acontece durante memory.retrieve(). Isso é por design: a confidence pode ser ajustada ao longo do tempo via reforço (confirmações NOOP), e descartar fatos no write-time seria irreversível.

Dicas:

Aumente topk_facts (ex: 50) para contexto mais amplo ao custo de mais ruído
Reduza min_similarity (ex: 0.10) para capturar matches semânticos mais distantes
Aumente recency_half_life_days (ex: 30) se fatos mais antigos devem permanecer relevantes por mais tempo
Defina enable_reranker=False para retrieval mais rápido quando precisão é menos crítica

Score Weights¶

Pesos para a fórmula de ranking híbrido que combina múltiplos sinais de retrieval.

Parâmetro	Tipo	Default	Descrição
`score_weights`	`dict`	`{"semantic": 0.70, "recency": 0.20, "importance": 0.10}`	Pesos para cada sinal de scoring (devem somar ~1.0)

config = MemoryConfig(
    score_weights={
        "semantic": 0.60,   # reduzir semântico, aumentar outros sinais
        "recency": 0.25,
        "importance": 0.15,
    },
)

Dicas:

Aumente o peso de "recency" para aplicações onde frescor importa mais que relevância semântica
Aumente o peso de "importance" para favorecer entidades bem estabelecidas e fatos frequentemente mencionados

Confidence¶

Parâmetros que controlam os níveis de confiança atribuídos a fatos extraídos.

Parâmetro	Tipo	Default	Descrição
`confidence_level_map`	`dict`	`{"explicit_statement": 0.95, "strong_inference": 0.80, "weak_inference": 0.60, "speculation": 0.40}`	Mapeamento de nomes de nível de confiança para scores numéricos
`confidence_default`	`float`	`0.60`	Confiança padrão quando o LLM não especifica um nível

Spreading Activation¶

Parâmetros que controlam como o contexto se expande a partir de fatos semente ao longo de relacionamentos de entidades.

Parâmetro	Tipo	Default	Descrição
`spreading_activation_hops`	`int`	`2`	Número máximo de hops de relacionamento a partir de fatos semente
`spreading_decay_factor`	`float`	`0.50`	Multiplicador de decay de score por hop (0.5 = dividido pela metade a cada hop)
`spreading_max_related_entities`	`int`	`5`	Máximo de entidades relacionadas a seguir por semente
`spreading_facts_per_entity`	`int`	`3`	Máximo de fatos a puxar de cada entidade relacionada

Compressão de Contexto¶

Parâmetros que controlam como fatos recuperados são comprimidos na string de contexto final.

Parâmetro	Tipo	Default	Descrição
`context_max_tokens`	`int`	`2000`	Máximo de tokens no output de contexto formatado
`hot_tier_ratio`	`float`	`0.50`	Parcela do orçamento de tokens para fatos com scores mais altos
`warm_tier_ratio`	`float`	`0.30`	Parcela do orçamento de tokens para fatos de suporte

O orçamento restante (1 - hot - warm = 0.20) vai para o cold tier (contexto de background).

Tendências Emocionais¶

Parâmetros para detectar padrões emocionais em mensagens do usuário.

Parâmetro	Tipo	Default	Descrição
`emotional_trend_window_days`	`int`	`30`	Janela para análise de tendências emocionais
`emotional_trend_min_events`	`int`	`5`	Mínimo de eventos necessários para detectar uma tendência

Clustering¶

Parâmetros para o background job de fact clustering.

Parâmetro	Tipo	Default	Descrição
`cluster_max_age_days`	`int`	`90`	Idade máxima dos fatos a incluir no clustering
`cluster_min_facts`	`int`	`2`	Mínimo de fatos por cluster
`community_similarity_threshold`	`float`	`0.75`	Threshold de similaridade de cosseno para agrupar clusters em comunidades
`community_min_clusters`	`int`	`2`	Mínimo de clusters para formar uma comunidade

Consolidation¶

Parâmetros para o background job de consolidation.

Parâmetro	Tipo	Default	Descrição
`consolidation_min_events`	`int`	`3`	Mínimo de eventos antes de rodar consolidation
`consolidation_lookback_days`	`int`	`7`	Quantos dias olhar para trás (em dias) em busca de padrões

Sleep-Time Compute¶

Parâmetros para importance scoring e summary refresh em background.

Parâmetro	Tipo	Default	Descrição
`importance_recency_halflife_days`	`int`	`30`	Half-life para sinal de recência no importance scoring
`summary_refresh_interval_days`	`int`	`7`	Dias antes de um resumo de entidade ser considerado obsoleto

Memify¶

Parâmetros para o background job de memify (conhecimento episódico → procedural).

Parâmetro	Tipo	Default	Descrição
`vitality_stale_threshold`	`float`	`0.2`	Score de vitalidade abaixo do qual um fato é considerado obsoleto
`memify_merge_similarity_threshold`	`float`	`0.90`	Threshold de similaridade para mesclar procedimentos similares

Memória Procedural¶

Parâmetros para retrieval de memória diretiva/procedural.

Parâmetro	Tipo	Default	Descrição
`directive_max_tokens`	`int`	`300`	Máximo de tokens para diretivas procedurais
`directive_cache_ttl_minutes`	`int`	`30`	Cache TTL para lookups de diretivas
`contradiction_similarity_threshold`	`float`	`0.80`	Threshold para detectar diretivas contraditórias

Locale / Deploy¶

Parametro	Tipo	Default	Descricao
`timezone`	`str`	`"UTC"`	Timezone IANA para interpretar referencias temporais relativas

O parametro timezone afeta como referencias temporais relativas ("ontem", "semana passada", "hoje de manha") sao interpretadas durante a extracao de fatos e retrieval. Todos os timestamps no banco sao armazenados em UTC independente desta configuracao.

Por exemplo: se timezone="Asia/Tokyo" e o usuario diz "ontem", o SDK interpreta "ontem" relativo ao horario de Tokyo (JST), nao UTC.

Parametros de `write()`¶

Alem do MemoryConfig, o metodo write() aceita parametros por chamada:

Parametro	Tipo	Default	Descricao
`occurred_at`	`datetime \\| None`	`None` (usa `now`)	Timestamp de quando a mensagem foi enviada. Usado para imports historicos -- o LLM resolve referencias temporais relativas ("yesterday", "last week") baseado nessa data, nao na data atual
`dry_run`	`bool`	`False`	Roda extracao sem persistir nada no banco
`recent_messages`	`list[str] \\| None`	`None`	Contexto de conversa recente para resolver pronomes
`verbose`	`bool`	`False`	Inclui pipeline trace com dados intermediarios
`config_overrides`	`dict \\| None`	`None`	Sobrescreve campos do `MemoryConfig` para esta chamada

Catálogo Aberto (Extensões do Deployer)¶

Parâmetros para estender o catálogo de atributos built-in com entradas customizadas.

Parâmetro	Tipo	Default	Descrição
`extra_attribute_keys`	`set[str]`	`set()`	Attribute keys adicionais reconhecidas durante extração
`attribute_aliases`	`dict[str, str]`	`{}`	Aliases para attribute keys (ex: `{"hometown": "city"}`)
`extra_namespaces`	`set[str]`	`set()`	Namespaces de entidade adicionais além dos tipos built-in
`extra_self_references`	`frozenset[str]`	`frozenset()`	Palavras adicionais tratadas como auto-referências (ex: `{"yo"}` para espanhol)
`extra_relationship_hints`	`frozenset[str]`	`frozenset()`	Palavras adicionais de dica de relacionamento para entity resolution

Limites¶

Parâmetro	Tipo	Default	Descrição
`max_facts_per_event`	`int`	`100`	Máximo de fatos extraídos de uma única mensagem
`embedding_dimensions`	`int`	`1536`	Dimensionalidade dos vetores de embedding (deve corresponder ao seu provider)

Configuração¶

Extraction¶

Entity Resolution¶

Retrieval¶

Score Weights¶

Confidence¶

Spreading Activation¶

Compressão de Contexto¶

Tendências Emocionais¶

Clustering¶

Consolidation¶

Sleep-Time Compute¶

Memify¶

Memória Procedural¶

Locale / Deploy¶

Parametros de write()¶

Catálogo Aberto (Extensões do Deployer)¶

Limites¶

Parametros de `write()`¶