Por que RAG apenas com vetores é fraco para agentes de codificação

Construindo Droste: um motor de memória de código estrutural + semântico local para agentes MCP

Agentes de codificação AI estão melhorando, mas sua camada de memória ainda é frequentemente muito rasa.

A maioria dos fluxos de trabalho dos agentes ainda depende de uma das duas coisas:

1. leituras de arquivos cegas;
2. busca vetorial sobre pedaços.

Ambos são úteis, mas ambos perdem algo importante em bases de código: estrutura causal.

Uma função pode ser relevante para um bug mesmo que não compartilhe palavras com a consulta do usuário. Uma função SQL pode ser chamada através de uma string RPC de TypeScript ou Dart. Um arquivo pode
importar porque é um chamador, chamado, manipulador, migração ou dependência, não porque seu texto pareça semelhante.

Essa é a razão pela qual comecei a construir o Droste.

GitHub:
https://github.com/lorismascio17/droste-memory

PyPI:
https://pypi.org/project/droste-memory/

## O que é Droste

Droste é um motor de memória de código local para agentes de codificação AI.

Ele indexa um repositório em um gráfico híbrido estrutural + semântico:

• pastas;
• arquivos;
• símbolos;
• funções;
• classes;
• métodos;
• links chamador/chamado;
• arestas de importação/dependência;
• links entre linguagens;
• embeddings locais.

Então, ele expõe essa memória através de:

• um CLI;
• um servidor MCP;
• um visualizador de gráfico visual.

O objetivo é simples: dar a um agente a fatia causal de código que ele precisa, em vez de forçá-lo a escanear arquivos repetidamente ou depender apenas da similaridade semântica.

## Por que a busca vetorial sozinha não é suficiente

A busca vetorial é boa para encontrar código que soa semelhante a uma consulta.

Mas o código muitas vezes importa por causa de relacionamentos, não de redação.

Por exemplo:

• um controlador chama um serviço;
• um serviço chama um repositório;
• um frontend invoca uma função RPC;
• uma função de borda toca uma tabela de banco de dados;
• uma migração define algo usado indiretamente a partir do código do aplicativo;
• um teste revela um comportamento não óbvio na implementação.

Um índice vetorial pode perder esses links se as palavras forem diferentes.

Um gráfico pode preservá-los.

Essa é a ideia principal de design por trás do Droste: combinar recuperação semântica com recuperação estrutural.

## Local-first por design

Droste é local-first.

Nenhum banco de dados em nuvem é necessário. Nenhuma conta é necessária. Nenhuma chave de API é necessária.

Instalar:

python -m pip install --upgrade droste-memory

  Indexe um repositório:

  droste index .

  Pergunte por contexto:

  droste context "fluxo de checkout" --budget 1500

Execute como um servidor MCP:

droste mcp

Um agente AI pode então chamar o Droste como um backend de memória de código local em vez de fazer leituras de arquivos cegas.

## Uso do MCP

Para clientes MCP, a configuração básica é:

{
"mcpServers": {
"droste": {
"command": "droste",
"args": ["mcp"]
}
}
}

Para trabalho sério em múltiplos repositórios, o Droste também suporta o uso de um banco de dados por projeto:

{
"mcpServers": {
"droste": {
"command": "droste",
"args": [
"--db",
"/caminho/absoluto/para/droste_memory_db.json",
"mcp"
]
}
}
}

Isso evita misturar contexto de diferentes repositórios.

## O que acontece internamente

Droste constrói um gráfico local do projeto.

Em um nível alto:

1. Extrai símbolos de arquivos de origem.
2. Mapeia funções, classes, métodos, arquivos e pastas.
3. Constrói arestas de dependência onde possível.
4. Calcula embeddings locais.
5. Armazena o gráfico em arquivos JSON locais fragmentados.
6. Recupera contexto usando tanto similaridade semântica quanto relacionamentos de gráfico.
7. Empacota o resultado em um orçamento de tokens para um LLM.

A parte importante é que a recuperação não é apenas "quais pedaços são semelhantes?"

Ela também pergunta:

• o que chama isso?
• o que isso chama?
• qual arquivo possui este símbolo?
• quais nós relacionados estão conectados pelo gráfico?
• quais links entre linguagens existem?

## Armazenamento local fragmentado

Droste não armazena o gráfico inteiro como um único arquivo JSON gigante.

Ele usa armazenamento local fragmentado, com um fragmento por caminho de origem. Isso mantém as salvaguardas incrementais mais rápidas e evita reescrever todo o banco de dados após cada alteração.

Ele também usa um modelo de consistência leve estilo seqlock para que um leitor não monte uma captura rasgada enquanto outro processo está escrevendo fragmentos.

Isso é importante porque o fluxo de trabalho pretendido é ao vivo:

• o motor indexa;
• o visualizador lê;
• o servidor MCP responde a solicitações de agentes;
• o desenvolvedor continua codificando.

## Gráfico visual

Droste também inclui um visualizador.

A ideia é representar a base de código como um gráfico ampliável: projeto, pastas, arquivos, símbolos e arestas causais.

Não é destinado a substituir o CLI ou o servidor MCP. É destinado a tornar o acoplamento e o raio de explosão visíveis.

Na prática, eu queria algo mais próximo de um "universo de código" do que uma árvore de arquivos plana.

## Status atual

Droste ainda está em fase inicial, mas utilizável.

Os recursos atuais incluem:

• CLI Python;
• servidor MCP;
• indexação local;
• extração de símbolos baseada em Tree-sitter;
• embeddings semânticos através de modelos locais;
• armazenamento fragmentado;
• isolamento de raiz de projeto;
• classificação consciente de consulta;
• empacotamento de contexto orçado em tokens;
• visualizador de gráfico visual.

Última versão:

python -m pip install --upgrade droste-memory

## Exemplos de comandos

droste index .
droste status
droste context "fluxo de autenticação" --budget 2000
droste zoom "AlgumaFunção"
droste view
droste mcp

## O que estou buscando feedback

Eu apreciaria especialmente feedback de pessoas que estão construindo ou usando agentes de codificação AI.

Feedback útil seria:

• O interface MCP faz sentido?
• O fluxo de instalação é limpo?
• A recuperação parece melhor do que a busca de arquivos normal em projetos reais?
• As fatias de contexto retornadas são úteis para um LLM?
• Quais relacionamentos de gráfico seriam mais importantes em sua pilha?
• O que tornaria isso mais útil no dia a dia da codificação?

## Links

GitHub:
https://github.com/lorismascio17/droste-memory

PyPI:
https://pypi.org/project/droste-memory/

Instalar:

python -m pip install --upgrade droste-memory

Droste é open source e licenciado sob MIT.