[ADR-0009] Armazenamento Vetorial Analítico (DuckDB + Parquet)

• *Status:* Proposto
• *Data:* 16 de Maio, 2026

*Contexto:*

A busca de código por similaridade exige um motor de banco de dados local veloz e sem dependências externas (daemon-less). Para o MVP, a persistência de vetores precisa ser simples. No entanto, o planejamento da Fase BETA (Rede P2P M2M) exige que os dados semânticos de um projeto possam ser sincronizados através de uma rede descentralizada (Merkle DAG / Kademlia DHT). Bancos de dados monolíticos fechados impedem a sincronização eficiente de deltas (diferenças).

*Decisão:*

Adotaremos o *DuckDB (via extensão nativa Rustler)* como motor analítico híbrido:

1. *MVP (Armazenamento Nativo):* Na Fase 1 e 2, os vetores de 384 dimensões (FLOAT[384]) serão armazenados nativamente nas tabelas do arquivo local .duckdb usando a extensão vss (Vector Similarity Search) para cálculo de similaridade de cosseno via SQL puro. A "falsa quantização" via números aleatórios será removida da camada Rust.
2. *Ponte para P2P (Exportação Parquet):* A arquitetura será desenhada de forma desacoplada. No futuro, o gbr_graph exportará namespaces periodicamente para pequenos arquivos .parquet. O motor DuckDB consultará esses arquivos diretamente. Na Fase BETA, a rede P2P sincronizará apenas os arquivos .parquet que sofrerem mutações, resolvendo o problema do "Data Lake Descentralizado".

*Consequências:*

• *Positivas:* Resolução imediata para a busca semântica local com altíssima performance; prepara a base de dados para a sincronização fragmentada do futuro (Web3) sem precisar trocar o SGBD.
• *Negativas:* Exigirá a compilação do Rustler linkado estaticamente com as bibliotecas do DuckDB, o que aumentará o tamanho do binário final da CLI distribuída.

Melhoria v2

• *Decisão:* A persistência vetorial usará *DuckDB + vss* localmente (FLOAT[384]), eliminando a "falsa quantização". Devido ao aumento do tamanho do binário (linkagem estática do DuckDB e Candle ML), o motor semântico operará em uma *Arquitetura Sidecar*: será um processo completamente separado (gbr_semantic_mcp) do agente principal (gleambr_ai). Isso garante que o agente "magrinho" permaneça leve e portátil, acionando o motor semântico (quando existente) exclusivamente via o protocolo MCP. Para a futura rede P2P (BETA), os dados migrarão para exportações fragmentadas em *Apache Parquet*.