Filosofia de Design¶

O arandu é projetado em torno de duas bases: princípios de engenharia de software que o tornam confiável e extensível, e modelos de ciência cognitiva que informam sua arquitetura. Esta página cobre ambos - as decisões de engenharia e os paralelos com neurociência que as inspiraram.

Princípios de Engenharia¶

Injeção de Dependência Baseada em Protocol¶

O SDK usa typing.Protocol do Python para todas as dependências externas (LLM, embeddings). Sem herança necessária - apenas implemente as assinaturas dos métodos:

@runtime_checkable
class LLMProvider(Protocol):
    async def complete(
        self,
        messages: list[dict],
        temperature: float = 0,
        response_format: dict | None = None,
        max_tokens: int | None = None,
    ) -> LLMResult: ...

Por quê: Vendor lock-in mata adoção. Ao usar tipagem estrutural (duck typing), qualquer LLM provider funciona sem herdar de uma classe base. O provider OpenAI está incluído por conveniência, mas você pode trocar por Anthropic, modelos locais ou endpoints customizados sem nenhuma mudança no SDK.

Conteudo Gerado em Ingles¶

Todo conteudo gerado por LLM -- perfis de entidade, summaries, resumos de cluster, meta-observations e diretivas procedurais -- e produzido em ingles, independente da lingua da conversa do usuario.

Por que: Consistencia no retrieval. Quando perfis e summaries estao numa lingua unica, a comparacao semantica via embeddings e mais precisa (sem mistura de idiomas no mesmo embedding space). Alem disso, LLMs tendem a produzir output mais consistente e preciso em ingles.

Fatos permanecem na lingua original: Os fatos (fact_text) sao extraidos na lingua em que o usuario escreveu. Se a conversa e em portugues, os fatos ficam em portugues. Apenas o conteudo sintetizado (perfis, summaries, padroes) e normalizado para ingles.

Fail-Safe por Padrao¶

Todo estagio do pipeline tem comportamento de fallback:

Estágio	Falha	Fallback
Extraction	Timeout/erro do LLM	Retorna extração vazia; evento ainda é registrado
Entity Resolution	Fallback LLM falha	Cria nova entidade (prefere duplicatas a dados perdidos)
Reconciliation	Erro do LLM	Default para ADD
Reranking	Reranker falha	Mantém ranking original
Background jobs	Qualquer job falha	Outros jobs continuam independentemente

Por quê: Em um agente de IA em produção, a memória é um sistema de suporte - nunca deve crashar o fluxo principal. Uma resposta degradada (faltando algum contexto) é sempre melhor que um erro.

Composição Sobre Herança¶

O SDK não tem classes base abstratas, nem hierarquias profundas de classes. É construído com módulos pequenos e focados compostos em pipelines:

write/extract.py → write/entity_resolution.py → write/reconcile.py → write/upsert.py
read/retrieval_agent.py → read/retrieval.py → read/reranker.py

Por quê: Cada módulo tem uma única responsabilidade com inputs e outputs claros. Você pode entender, testar e substituir qualquer módulo independentemente. Segue a filosofia Unix: faça uma coisa bem feita.

Segurança Transacional com Savepoints¶

Operações de escrita usam savepoints do banco de dados (session.begin_nested()) para que uma falha em um fato não aborte o batch inteiro:

async with session.begin_nested():
    # Se isso falhar, apenas este savepoint faz rollback
    session.add(new_fact)
    await session.flush()

Por quê: Em um pipeline que processa múltiplos fatos por mensagem, transações atômicas tudo-ou-nada são frágeis demais. Savepoints dão atomicidade por fato mantendo a transação externa viva.

Paralelos com Neurociência¶

A arquitetura do arandu se inspira em modelos estabelecidos de neurociência cognitiva. Cada paralelo abaixo mapeia um componente do sistema para seu correspondente biológico.

Codificação: O Write Pipeline¶

Sistema: Message → Alias Lookup → Pré-retrieval → Extração Informada → Resolve → Upsert

Cérebro: Input sensorial → Resposta de orientação → Ativação de esquemas → Codificação orientada por esquema → Associação → Armazenamento

Quando você vivencia algo, seu cérebro não grava um vídeo bruto. Ele codifica uma representação seletiva - extraindo características salientes, vinculando-as ao conhecimento existente, e armazenando o resultado de forma que possa ser recuperado depois. O write pipeline faz o mesmo:

Alias lookup + Pré-retrieval é a resposta de orientação: antes de codificar informação nova, o cérebro primeiro verifica "eu já sei algo sobre isso?" -- ativando esquemas existentes que vão guiar a codificação. Da mesma forma, o pipeline carrega perfis e fatos existentes antes de chamar o LLM.
Extração informada é a codificação orientada por esquema: o cérebro humano não codifica informação no vácuo -- novos estímulos são processados no contexto de esquemas mentais existentes (Bartlett, 1932). O LLM recebe contexto existente e decide na fonte o que é genuinamente novo (NEW) vs. o que atualiza conhecimento existente (UPDATE). Isso reduz drasticamente a redundância.
Entity resolution é a associação: vincular novas menções a traços de memória existentes
Upsert é o armazenamento: comprometer o traço processado na memória de longo prazo

Da extração cega para a extração informada

Na versão anterior, o pipeline usava extração cega (sem contexto) seguida de reconciliação separada. Isso espelhava um modelo onde codificação e reconsolidação são processos separados. A extração informada unifica esses dois processos, assim como a neurociência moderna reconhece que codificação e reconsolidação compartilham circuitos hipocampais -- a codificação de nova informação é inerentemente influenciada por memórias existentes.

Memória Associativa: Entity Resolution¶

Sistema: Resolução em 3 fases (exact → fuzzy → LLM)

Cérebro: Pattern completion em circuitos hipocampais-neocorticais

O cérebro não armazena memórias como registros isolados - armazena como padrões de ativação em redes neurais. Quando você encontra uma pista parcial ("Carol"), seu cérebro completa o padrão para recuperar a representação completa ("Carolina, minha colega do trabalho").

A entity resolution espelha esse processo:

Exact match = recuperação direta (associações fortes e bem estabelecidas)
Fuzzy match = pattern completion (pista parcial ativa o padrão existente mais similar)
LLM fallback = recall deliberado (esforço consciente para desambiguar quando a recuperação automática falha)

O fuzzy threshold (0.85) e a faixa de fallback LLM (0.50-0.85) modelam o gradiente de confiança do cérebro: matches fortes são automáticos, matches ambíguos requerem deliberação.

Reconsolidação: Reconciliação de Fatos¶

Sistema: Decisões ADD / UPDATE / NOOP / DELETE

Cérebro: Reconsolidação de memória (Nader, Schiller, & LeDoux, 2000)

Quando uma memória é recuperada, ela entra em um estado lábil onde pode ser modificada. Isso é a reconsolidação - o mecanismo do cérebro para atualizar memórias com nova informação preservando o traço original.

O estágio de reconciliação modela esse processo:

NOOP = recuperação sem modificação (memória confirmada, last_confirmed_at atualizado)
UPDATE = reconsolidação (memória antiga substituída, nova versão criada com link de proveniência via supersedes_fact_id)
ADD = nova codificação (sem memória existente para reconsolidar)
DELETE = esquecimento ativo (retração explícita, modelado definindo invalidated_at)

O sistema de versionamento de fatos (valid_from, valid_to, supersedes_fact_id) preserva o histórico completo - assim como o cérebro retém traços de memórias originais mesmo após a reconsolidação.

Spreading Activation: Graph Retrieval¶

Sistema: Traversal BFS 2-hop com fator de decay

Cérebro: Spreading activation em redes semânticas (Collins & Loftus, 1975)

No modelo de Collins e Loftus, quando um conceito é ativado (ex: "caminhão de bombeiros"), a ativação se espalha ao longo de links associativos para conceitos relacionados ("vermelho", "caminhão", "emergência"), com a força diminuindo conforme a distância aumenta.

O graph retrieval implementa isso diretamente:

Entidades semente da query ativam os nós iniciais
Hop 1 ativa vizinhos diretos (sem pruning - todas as conexões disparam)
Hop 2 ativa conexões de segundo grau (com pruning por min_edge_strength)
Fator de decay (0.50 por hop) modela a atenuação da ativação ao longo da distância
Edge strength modela a força associativa entre conceitos (reforçada por co-menção repetida)

O query_bonus (1.5x) para entidades cujos nomes aparecem na query modela priming top-down - quando você menciona explicitamente uma entidade, suas conexões são mais fortemente ativadas.

Sleep-Time Compute: Processamento em Background¶

Sistema: Clustering, consolidation, importance scoring, summary refresh

Cérebro: Consolidação de memória durante o sono (Diekelmann & Born, 2010)

Durante o sono, o cérebro realiza manutenção crítica:

Replay hipocampal - Experiências recentes são reexecutadas em forma comprimida, transferindo-as do armazenamento de curto prazo (hipocampal) para longo prazo (neocortical)
Homeostase sináptica - Sinapses fortemente ativadas são mantidas enquanto fracamente ativadas são podadas (Tononi & Cirelli)
Detecção de padrões - O neocórtex detecta regularidades estatísticas entre episódios
Extração de essência - Memórias episódicas detalhadas são comprimidas em conhecimento semântico

Os background jobs mapeiam para esses processos:

Processo cerebral	Job do sistema	Mecanismo
Replay hipocampal	Consolidation	Revisa eventos recentes, detecta padrões e contradições
Homeostase sináptica	Importance scoring	Pontua entidades por densidade + recência + frequência de retrieval + conectividade
Detecção de padrões	Community detection	Encontra grupos de entidades relacionadas via análise de grafos
Extração de essência	Summary refresh + Memify	Gera resumos comprimidos a partir de fatos detalhados

Curva de Esquecimento: Vitalidade e Recência¶

Sistema: Decay de recência, scoring de vitalidade, pruning baseado em importância

Cérebro: Curva de esquecimento de Ebbinghaus (1885)

Hermann Ebbinghaus demonstrou que a retenção de memória decai exponencialmente ao longo do tempo, mas cada recuperação (prática) reseta a curva e desacelera o decay futuro. Este é o efeito de espaçamento - o achado mais robusto na pesquisa sobre memória.

O arandu modela isso com:

Decay de recência - Decay exponencial com half-life configurável (recency_half_life_days). Fatos recentes pontuam mais alto. Isso modela a curva básica de esquecimento.
Reforço por retrieval - Cada decisão NOOP (fato confirmado durante write) atualiza last_confirmed_at, efetivamente "praticando" o fato e resetando sua curva de decay.
Scoring de vitalidade - Combina recência, recência de confirmação (last_confirmed_at) e importância para determinar quão "vivo" um fato está. Fatos de baixa vitalidade são candidatos a consolidation ou pruning.

Atenção Seletiva: Reranking¶

Sistema: LLM reranker em candidatos de retrieval

Cérebro: Atenção seletiva (Broadbent, 1958; Treisman, 1964)

O cérebro não processa todo input sensorial igualmente - a atenção seletiva filtra e prioriza informações com base nos objetivos atuais. O efeito cocktail party demonstra isso: você consegue focar em uma conversa em um ambiente barulhento filtrando sinais irrelevantes.

O reranker age como o filtro de atenção:

Sinais brutos de retrieval (semantic, keyword, graph) produzem um conjunto amplo de candidatos - como o input sensorial completo
O reranker avalia cada candidato contra a intenção da query - como a seleção atencional
Apenas os fatos mais relevantes passam para o contexto - como o sinal atendido

É por isso que o reranker usa um LLM (não apenas heurísticas de scoring): a atenção é direcionada a objetivos e requer compreender o significado tanto da query quanto dos candidatos.

Working Memory: Orçamento de Contexto¶

Sistema: Orçamento de tokens com tiers hot/warm/cold

Cérebro: Working memory (Baddeley & Hitch, 1974; Cowan, 2001)

A working memory tem um limite de capacidade estrito -- Cowan estima que 4 mais ou menos 1 itens podem ser mantidos no foco de atencao simultaneamente. O orcamento de contexto modela essa restricao:

Orcamento de tokens = limite de capacidade (voce nao pode enviar contexto infinito para um LLM)
Known facts = foco de atencao (fatos mais relevantes, ordenados por score)
Observed patterns = conhecimento de alto nivel (padroes, tendencias, insights)
Relevant conversations = contexto episodico de suporte (eventos recentes)

Essa abordagem garante que o LLM receba um contexto focado e priorizado, em vez de um despejo ruidoso de tudo que o sistema sabe.

Tabela Resumo¶

Componente do Sistema	Modelo de Neurociencia	Referencia
Write Pipeline	Codificacao orientada por esquema	Bartlett (1932)
Extracao Informada	Resposta de orientacao + codificacao contextual	--
Perfis de Entidade	Esquemas mentais / representacoes consolidadas	--
Entity Resolution	Memória associativa / Pattern completion	--
Reconciliation	Reconsolidação	Nader, Schiller, & LeDoux (2000)
Graph Retrieval	Spreading activation	Collins & Loftus (1975)
Decay de Recência	Curva de esquecimento	Ebbinghaus (1885)
Background Jobs	Consolidação durante o sono	Diekelmann & Born (2010)
Importance Scoring	Homeostase sináptica	Tononi & Cirelli (SHY)
Summary Refresh	Formação de memória de essência	--
Reranking	Atenção seletiva	Broadbent (1958)
Orçamento de Contexto	Capacidade da working memory	Baddeley & Hitch (1974); Cowan (2001)
Vitalidade/Reforço	Efeito de espaçamento	Ebbinghaus (1885)

Estes são analogias, não afirmações

Os paralelos acima são inspirações arquiteturais, não afirmações científicas. O arandu é um sistema de engenharia, não um modelo cognitivo. O cérebro é vastamente mais complexo - esses paralelos destacam as intuições de design, não os mecanismos biológicos.