Vetores não são memória: como o DecisionsSearch governa conhecimento que muda

Renzo Tognella — Tue, 18 Aug 2026 20:20:45 +0000

Uma análise metodológica de grafos, RAG híbrido, evidência e versionamento para agentes de IA.

Uma regra antiga pode continuar sendo o resultado mais parecido com uma pergunta, mesmo depois de ter sido substituída.

Esse é o problema que o DecisionsSearch tenta investigar: para um agente de IA, lembrar não é apenas encontrar texto semelhante. É saber qual decisão existe, por que ela foi aceita, a qual projeto pertence, o que mudou e qual versão ainda pode ser considerada válida.

O DecisionsSearch é um projeto experimental de engenharia. Ele ainda não é uma autoridade histórica validada em produção. O objetivo é testar, com código e regressões locais, uma hipótese:

Memória para agentes precisa combinar contexto, evidência, histórico temporal, relações e recuperação — não apenas incorporações vetoriais.

O problema: similaridade não é validade

Uma incorporação vetorial transforma um texto em uma representação numérica. Isso permite encontrar textos próximos por significado aproximado.

É útil quando alguém pergunta:

“Como o sistema costuma tratar esse tipo de erro?”

e a memória registrada usa palavras diferentes:

“A correção adotada no PR alterou o fluxo de validação para evitar a duplicidade.”

Mas a similaridade não responde sozinha:

Pergunta	O vetor ajuda?	O que ainda é necessário
Encontrar algo parecido	Sim	Similaridade semântica
Saber se a regra ainda vale	Parcialmente	Estado, validade e versão atual
Saber o que mudou	Não por si só	Revisões, diferenças e linhagem
Saber por que acreditar	Não	Evidência e origem
Saber a qual projeto pertence	Não necessariamente	Contexto e escopo
Impedir uma sobrescrita concorrente	Não	Proposta, aprovação e CAS

O ponto central é este: recuperação encontra candidatos; governança decide o que pode virar conhecimento compartilhado.

A escolha arquitetural central: ledger para governar, índice para recuperar

O DecisionsSearch separa duas responsabilidades:

o ledger mantém identidade, histórico, estado, validade, evidências e decisões de mudança;
o Qdrant mantém uma projeção derivada para tornar a recuperação rápida.

No caminho persistente projetado, o Neo4j é o adaptador canônico. O Qdrant não é a autoridade da memória; ele materializa os heads publicados para busca.

Essa separação resolve um problema comum de arquiteturas RAG: o índice de busca pode atrasar, falhar ou precisar ser reconstruído. Se a história estiver no índice, uma falha de materialização pode parecer perda de conhecimento. Se a história estiver no ledger, a projeção pode ser refeita.

A ideia é parecida com a diferença entre um arquivo histórico e um catálogo: o catálogo acelera a localização; ele não substitui o arquivo original.

O contrato mínimo de uma memória

Para explicar o modelo sem transformar o artigo em um catálogo de classes, quatro conceitos são suficientes.

Família: a identidade contínua

Uma família representa a entidade lógica da memória.

Se o texto de uma decisão muda, isso não deveria criar automaticamente outra decisão sem relação com a anterior. A família mantém essa identidade estável.

Revisão: um instantâneo imutável

Cada publicação cria uma revisão com conteúdo, hash, autor, motivo, revisões-pai, evidências e janela de validade.

A revisão é imutável. Uma correção não reescreve o instantâneo anterior; cria outro instantâneo ligado a ele.

Head: o que está publicado agora

O head, ou ponteiro atual, aponta para a revisão atualmente publicada dentro de um escopo e uma ramificação.

Isso permite separar duas perguntas diferentes:

qual versão vale agora?
quais versões já valeram antes?

Evidência: a origem de uma afirmação

A evidência guarda informações como fonte, localizador, hash, autor, modelo de extração, confiabilidade e estado de verificação.

Ela não prova automaticamente que a afirmação é verdadeira. Ela torna a origem inspecionável e permite distinguir uma informação sustentada, contradita, não verificada ou indisponível.

O grafo não é decoração

Podemos representar o conhecimento como um grafo G = (V, E):

V são os vértices: projetos, famílias, revisões, evidências e outros objetos do domínio;
E são as arestas: relações tipadas entre esses objetos.

Uma distância vetorial pode dizer que duas memórias são parecidas. Uma aresta pode dizer algo muito mais específico:

RELATED_TO: existe relação, mas sem uma direção semântica forte;
DEPENDS_ON: uma memória depende de outra;
REFINES: uma decisão refina outra;
DEPRECATES: uma versão substitui uma anterior;
CONFLICTS_WITH: duas afirmações entram em conflito;
EVOLVES_FROM: uma memória evoluiu de outra.

Essa tipagem é importante. Tratar todas as relações como “parecido com” elimina direção, intenção e semântica.

Esses tipos fazem parte do modelo que o projeto suporta; eles não significam que todos já tenham sido exercitados no benchmark. Na execução v10, o ledger registrou apenas duas relações, ambas do tipo REFINES.

O diagrama abaixo é um modelo conceitual. No ledger, o projeto também funciona como escopo estruturado do conteúdo, e algumas relações são representadas por asserções reificadas. Nem toda seta do desenho corresponde a uma aresta direta no Neo4j.

Três usos diferentes do grafo

No DecisionsSearch, o grafo cumpre três papéis.

1. Modelar contexto e linhagem

As evidências ligadas à revisão identificam o PR ou documento de origem. As relações tipadas preservam como uma decisão se conecta a outra, o que foi refinado, substituído, desenvolvido ou colocado em conflito.

Esse é o papel mais importante para perguntas históricas:

“Qual decisão levou a esta regra?”

“O que essa alteração substituiu?”

2. Recuperar vizinhança estrutural

Depois que a busca densa encontra algumas sementes, o sistema pode expandir relações elegíveis por ativação espalhada.

A implementação atual limita a profundidade e aplica decaimento. Uma memória diretamente relacionada recebe mais ativação; memórias mais distantes recebem menos. Esse recurso é opcional e estava desligado no benchmark v10.

A escolha é deliberadamente conservadora. Relações de linhagem e governança, como DEPRECATES e CONFLICTS_WITH, não devem simplesmente reintroduzir conhecimento obsoleto na recuperação semântica. A expansão usa um conjunto menor de relações, como RELATED_TO, DEPENDS_ON, REFINES e EVOLVES_FROM.

Isso não é PageRank, Leiden nem um GraphRAG completo. É uma expansão estrutural limitada, usada como sinal complementar.

3. Incorporar importância e contexto

O sistema também trabalha com peso efetivo, significância, recência e relações. Esses sinais podem ajudar a ordenar resultados, mas não substituem a relevância da pergunta.

Por isso, o ramo estrutural recebe menos peso na fusão quando é mais cego ao texto da consulta. Uma memória importante no projeto não deve aparecer no topo apenas porque tem peso alto, ignorando completamente a pergunta.

O que não estamos afirmando

O projeto possui serviços e ideias relacionados a agrupamento, propagação de peso e análise de grafo. Porém, o benchmark apresentado neste artigo não valida uma implementação completa de GraphRAG, PageRank personalizado ou detecção de comunidades.

A formulação correta é:

O grafo fornece relações tipadas, linhagem, contexto e expansão estrutural limitada para complementar a recuperação semântica.

Como uma memória entra no sistema

O caminho de escrita é mais longo do que “extrair texto e salvar” porque cada etapa evita um tipo de falha.

1. Sanitização e extração

O evento pode conter segredo, PII, detalhe efêmero, informação incompleta ou apenas uma hipótese do modelo.

A sanitização reduz o risco de propagar conteúdo indevido. A extração estruturada transforma a fonte em candidatos com campos definidos, como título, resumo, categoria, projeto, evidências, arquivos, regras e objetivo.

Uma decisão importante é aceitar explicitamente o resultado NO_MEMORY: nem toda observação merece virar memória durável.

Problema evitado: transformar logs, conversas e hipóteses em conhecimento permanente.

Compromisso: o sistema pode descartar algo que seria útil, além de depender da qualidade do extrator.

2. Gates de admissão

A admissão é organizada como uma cadeia de validações:

projeto;
evidência;
duplicidade ou identidade;
contexto da categoria;
peso mínimo.

A validação contextual muda de acordo com o tipo. Uma regra de negócio precisa de domínio; um padrão de código precisa de exemplos; uma decisão arquitetural precisa de justificativa e alternativas consideradas.

A deduplicação usa similaridade para distinguir três situações:

uma memória nova;
uma atualização da mesma identidade;
um possível refinamento de uma memória parecida, mas diferente.

Problema evitado: lixo semântico, duplicidade e memórias sem contexto.

Compromisso: os limiares são heurísticos. Um limite alto pode rejeitar variações legítimas; um limite baixo pode misturar identidades diferentes.

3. Proposta antes da mutação

No caminho canônico, o agente não publica diretamente uma memória ativa. Ele cria uma proposta com:

estado anterior;
estado posterior;
diferença por campo;
evidências;
heads observados;
motivo da mudança;
hash da prévia.

A proposta permite revisar o que será alterado sem contaminar o ledger.

Problema evitado: transformar uma sugestão de agente em conhecimento compartilhado sem revisão.

Compromisso: existe mais latência e uma etapa de governança, mas a mudança fica contestável antes da publicação.

4. Aprovação e `preview_hash`

A aprovação está vinculada ao conteúdo exato da prévia. Se o conteúdo, as evidências ou os heads esperados mudarem, o hash não corresponde mais.

Além disso, a barreira local impede que um agente aprove a própria proposta. A regra de separação entre quem propõe e quem aprova depende desse limite local; ela não deve ser lida como uma política universal de identidade ou como autenticação corporativa.

Essa é uma barreira local de governança. Ela ainda não equivale a autenticação corporativa, autorização externa ou política de múltiplos aprovadores.

5. CAS em vez de “a última escrita vence”

Uma proposta carrega os heads esperados.

Se outro escritor publicar uma revisão entre a prévia e a aplicação, a comparação falha. A proposta fica obsoleta e precisa ser revista.

Problema evitado: uma alteração antiga sobrescrever silenciosamente uma decisão mais nova.

Compromisso: conflitos não desaparecem. Eles voltam para revisão, rebase ou mesclagem explícita.

6. Outbox e projeção derivada

O ledger grava a revisão, o head, as transições, as relações e o evento de outbox na mesma operação canônica.

Depois, um materializador processa o evento e atualiza o Qdrant. Esse materializador é idempotente, pode tentar novamente falhas e possui caminho de reconstrução.

Problema evitado: uma escrita direta e frágil em duas bases independentes.

Compromisso: a busca pode ficar temporariamente atrasada. A consistência entre ledger e índice é eventual, mas o estado do outbox torna o atraso observável e reprocessável.

Projeto antes da recuperação

Memórias sem contexto podem ser semanticamente parecidas e ainda assim pertencer a sistemas diferentes.

Por exemplo, “regra de faturamento” pode ter significados, exceções e nomes de módulos completamente distintos em dois repositórios.

Por isso, o projeto é carregado como campo estruturado da memória e recebido como contexto da consulta. O filtro é aplicado nos ramos de recuperação antes da fusão:

Qdrant recebe o projeto no filtro dos pontos;
o ramo estrutural consulta apenas revisões do projeto;
no caminho baseado no ledger, a ativação espalhada verifica o projeto dos vizinhos.

É importante ser preciso: o código não cria necessariamente um único subgrafo temporário antes de todas as buscas. Ele envia o contexto do projeto para cada fonte e só depois combina os resultados.

Essa garantia ainda não deve ser tratada como isolamento universal: o caminho legado baseado em nós do Neo4j exige filtros e testes explícitos para assegurar o mesmo comportamento. Além disso, a ativação espalhada não foi habilitada na execução v10.

Também não é correto tratar isso como autorização ou isolamento de segurança. É escopo de recuperação.

No hook de pós-commit, o projeto pode ser informado explicitamente; quando não há valor configurado, o script usa o nome da pasta raiz local (repo.name), que pode não coincidir com o nome do repositório remoto. Nas outras interfaces, o chamador fornece o projeto. Isso significa que a descoberta automática não é universal em todos os caminhos.

Como o RAG combina sinais diferentes

O DecisionsSearch não trata RAG como “vetor mais instrução”. A recuperação é uma sequência de decisões, em que cada mecanismo cobre um tipo de falha.

Busca densa: intenção e paráfrase

A busca densa representa o conteúdo da memória em um espaço vetorial. Ela ajuda quando a consulta e a memória usam vocabulário diferente.

Em algumas rotas de persistência, o texto enviado ao modelo de incorporação vetorial combina título, resumo, objetivo, gatilho, justificativa, regras, detalhes e módulos. Já o materializador canônico usado no benchmark v10 constrói a representação com título, resumo e detalhes. Essa diferença entre caminhos é importante: a composição da representação vetorial é uma decisão de implementação, não uma propriedade universal de toda memória.

Escolha: usar significado aproximado para recuperar paráfrases.

Limitação: o vetor não sabe se a memória é atual, se foi substituída ou se tem evidência suficiente.

Busca esparsa: termos que não podem virar sinônimos

A busca esparsa, baseada em sinais lexicais, protege identificadores, caminhos de arquivo, nomes de módulos, códigos de erro, siglas e classes.

Escolha: manter uma rota para correspondência exata.

Compromisso: exige índice e configuração adicionais. No benchmark v10, o ramo esparso estava desabilitado; portanto, os números apresentados não medem ganho de busca densa combinada com busca esparsa.

Busca estrutural: estado e relações

O ramo estrutural adiciona informações que não aparecem apenas no texto:

projeto;
categoria;
escopo e ramificação;
estado ativo;
peso efetivo;
metadados de estado e, quando habilitada, vizinhança de relações;
revisões e heads.

No caminho canônico, essa etapa é principalmente uma enumeração de revisões ativas filtradas por projeto, categoria, escopo e ramificação. A travessia da vizinhança acontece separadamente, quando a ativação espalhada está habilitada. O ramo estrutural pode ser pouco sensível ao texto da consulta, porque ordenar por peso não significa entender a pergunta. Por esse motivo, ele entra com peso menor na fusão, em vez de dominar a busca.

RRF: combinar listas ordenadas, não escalas incompatíveis

Scores de cosseno, BM25, peso e ativação não têm necessariamente a mesma escala. Somá-los diretamente produziria uma combinação difícil de interpretar.

O Reciprocal Rank Fusion usa a posição de cada candidato em cada lista:

RRF(d) = soma de wᵢ / (k + posiçãoᵢ(d))

No projeto, k começa em 60 e os pesos padrão são ajustáveis. A intenção é premiar memórias que aparecem bem em mais de uma visão, sem fingir que as pontuações brutas são comparáveis.

O RRF organiza relevância. Ele não decide verdade.

Score composto: relevância, recência e importância

Depois da fusão, o score composto combina:

relevância;
recência;
importância.

Quando não são substituídos por configuração, os valores padrão dão 50% para relevância, 25% para recência e 25% para importância. A recência usa meia-vida de 90 dias.

Essa escolha permite que uma memória relevante e recente tenha prioridade, sem tornar a recência o único critério.

O peso composto é uma política de ordenação, não uma prova causal de que a resposta é correta. Ainda são necessárias ablações para medir quanto cada componente contribui.

Reordenação: uma segunda opinião cara

O reordenador recebe os candidatos da primeira etapa e pode melhorar a ordenação usando uma comparação mais profunda entre consulta e documento.

Na execução v10, foi usado o Qwen via OpenRouter: 78 chamadas de reordenação tiveram sucesso em 79 tentativas.

Isso mostra que o componente foi exercitado. Não mostra, sozinho, que ele melhorou as métricas, porque não houve uma ablação controlada com a reordenação desligada.

Reconciliação: o resultado precisa poder voltar à origem

O Qdrant carrega identificadores da família e da revisão, o hash, o projeto e a validade. A busca também aplica filtros de estado e escopo. Isso fornece os elementos para uma verificação posterior, mas o caminho atual não hidrata universalmente cada resultado com o ledger nem verifica, antes de retornar, o head e todas as evidências associadas.

Portanto, a reconciliação completa é uma camada parcial/planejada, não uma garantia automática da consulta atual. O resultado deveria corresponder a um head canônico ativo e manter ligação com:

família;
revisão;
hash;
projeto;
validade;
evidência.

Se a base não sustenta a resposta, uma política de abstenção ainda precisa ser definida e validada como comportamento formal do agente.

Correção não é apagamento

Considere uma regra de negócio registrada a partir de um pull request.

O fluxo é:

o primeiro PR sustenta v1;
uma nova mudança gera evidência;
uma proposta compara v1 com a possível v2;
após aprovação, v2 é publicada como filha de v1;
o head passa a apontar para v2;
v1 continua disponível para auditoria, reversão ou pergunta temporal.

A versão antiga deixa de ser a atual, mas não precisa desaparecer.

Isso também vale para invalidação, supersessão, reversão, mesclagem e conflitos. Um conflito não deve ser resolvido silenciosamente escolhendo a frase mais convincente; ele precisa permanecer explícito ou seguir para uma decisão de domínio.

O que a avaliação local mostra

A avaliação mais recente usa a execução local:

100 pull requests públicos do ERPNext;
1.485 arquivos únicos no corpus;
87 registros brutos de extração;
79 candidatos únicos persistidos;
8 registros classificados como inválidos pelo validador da extração;
79 consultas de recuperação.

Os oito inválidos não são “oito memórias rejeitadas pelas barreiras de admissão”. Eles foram classificados antes da persistência por problemas como falta de conhecimento durável, atribuição incorreta ou uma mudança específica demais para ser uma memória reutilizável.

Métricas da execução

Métrica	Resultado	Como interpretar
MRR	0,9451	Posição média do primeiro resultado esperado
NDCG@10	0,9593	Qualidade de ordenação com relevância binária
Precision@1	0,8987	Resultado esperado em primeiro em 71 de 79 consultas
Recall@5	1,0	Resultado esperado apareceu até a quinta posição
Recall@10	1,0	Resultado esperado apareceu até a décima posição
Latência p50	924,53 ms	Mediana observada na execução
Latência p95	1.611,47 ms	Percentil observado na execução
Reordenação	78/79 sucessos	Chamadas do reordenador

Perfil metodológico

A execução usou:

LLM de extração OpenAI GPT 5.6 Luna via Codex;
modelo vetorial text-embedding-3-small com 512 dimensões;
Qwen via OpenRouter para reordenação;
busca esparsa desligada;
ativação espalhada e HyDE desligados;
reescritor de consulta local, sem chamada externa;
InMemoryMemoryLedger;
Qdrant local em disco;
aprovação por uma barreira local do benchmark;
nenhum conjunto independente de teste.

As consultas foram associadas a memórias do próprio conjunto persistido. O conjunto de avaliação excluiu consultas que expunham identificadores óbvios, como número de PR, URL e título exato, mas isso não cria um conjunto de teste independente.

Portanto, Recall@5 e Recall@10 iguais a 1,0 significam que os alvos apareceram nesses cortes deste corpus controlado. Não significam que o sistema encontrará qualquer memória em qualquer repositório.

O benchmark mede a ordenação da recuperação. Ele não mede:

verdade factual;
qualidade de toda extração;
qualidade da resposta final do agente;
generalização para outros repositórios;
segurança de aprovação;
durabilidade em produção;
isolamento entre projetos;
qualidade dos relacionamentos;
efeito causal da busca esparsa, da reordenação ou do ramo estrutural.

Decisões e compromissos em uma tabela

Escolha	Benefício	Custo ou limite
Ledger versionado	Preserva histórico, estado e linhagem	Mais complexidade de escrita
Aprovação antes da publicação	Evita mutação sem revisão	Menos autonomia e mais latência
CAS	Protege contra propostas obsoletas	Conflitos voltam para revisão
Qdrant como projeção	Busca rápida e reconstruível	Consistência eventual
Busca densa	Recupera intenção e paráfrases	Pode perder termos exatos
Busca esparsa opcional	Protege identificadores	Índice adicional; não medido no v10
Grafo tipado	Preserva direção, dependência e conflito	Relações precisam de qualidade e governança
RRF	Combina listas sem normalizar pontuações incompatíveis	Pesos ainda são ajustáveis
Reordenação	Melhora a ordenação final	Custo, latência e dependência externa
Filtro por projeto	Reduz mistura de contextos	Não é autorização nem isolamento de segurança entre clientes

O que está implementado, testado e ainda é hipótese

Implementado e parcialmente coberto por regressões locais

famílias, revisões, heads e validade;
evidências ligadas às revisões;
propostas, diferenças, aprovação local e CAS;
barreiras de projeto, evidência, duplicidade, contexto e peso;
outbox, novas tentativas e reconstrução local;
busca densa, ramo estrutural e RRF;
busca esparsa e reordenação como capacidades opcionais;
relações tipadas e ativação limitada;
testes de atualização, reversão, conflitos, temporalidade e falhas do materializador.

Ainda parcial ou planejado

reconciliação distribuída, fencing e injeção de falhas;
políticas de evidência por domínio;
conjunto de avaliação histórico independente e avaliação entre projetos;
reconciliação final automática de cada resultado com head e evidências;
política formal de abstenção do agente;
teste com projetos maiores;
teste com projetos desde o início dele.

Conclusão

O DecisionsSearch não tenta resolver memória para agentes adicionando apenas mais um vetor.

A proposta é separar duas coisas que normalmente são misturadas:

recuperar algo que parece relevante;
decidir o que pode continuar sendo conhecimento compartilhado.

Tudo isso ainda é uma hipótese em consolidação, não uma promessa de produção, e nem de reprodutibilidade

A pergunta que continua guiando o projeto é:

Antes de um agente usar uma memória para tomar uma decisão, quais evidências ele deveria ser obrigado a mostrar?

O código e a documentação estão disponíveis no repositório:

https://github.com/Renzo-Tognella/DecisionsSearch

DEV Community: Renzo Tognella