Vectora
Agentes de IA tradicionais operam em contextos fragmentados, gerando alucinações, desperdício de tokens e exposição acidental de segredos. O Vectora resolve isso não sendo “mais um chat”, mas sim um Sub-Agent Tier 2 projetado exclusivamente para engenharia de software: ele intercepta chamadas via Protocolo MCP, valida segurança em tempo real com o Guardian, orquestra recuperação multi-hop via Context Engine e entrega contexto estruturado ao seu agent principal (Claude Code, Gemini CLI, Cursor, etc.).
Fórmula Central:
Agente Funcional = Modelo (Gemini 3 Flash) + [Harness Runtime](/concepts/harness-runtime/) + Contexto Governado (Voyage 4 + MongoDB Atlas)
O Problema que Vectora Resolve
| Falha em Agents Genéricos | Impacto Prático | Como Vectora Mitiga |
|---|---|---|
| Contexto Raso | Busca por “autenticação” retorna 50 arquivos irrelevantes | Reranker 2.5 filtra por relevância semântica real, não por similaridade cossena bruta |
| Sem Validação Pré-Execução | Tool calls perigosos rodam antes de serem auditados | Harness Runtime intercepta, valida via Struct Validation e aplica Guardian antes da execução |
| Falta de Isolamento | Dados de projetos diferentes vazam entre sessões | Namespace Isolation via RBAC na aplicação + filtragem obrigatória no backend |
| Consumo Imprevisível | LLMs geram overfetch, gastam tokens em boilerplate | Context Engine decide escopo, aplica compaction (head/tail) e injeta só o relevante |
| Segurança Frágil | Blocklists dependem de prompts (jailbreakáveis) | Hard-Coded Guardian é compilado no binário Go, impossível de bypassar via prompt |
A Solução: Arquitetura de Sub-Agent
Vectora é exposto exclusivamente via MCP. Não há CLI de chat, TUI ou interface de conversação direta. Ele opera silenciosamente como camada de governança e contexto:
graph LR
A[Agent Principal] -->|MCP Tool Call| B[Harness Runtime]
B --> C{Guardian + Native Validation}
C -->| Aprovado| D[Context Engine]
D --> E[Embed via Voyage 4]
D --> F[Rerank via Voyage 2.5]
E --> G[MongoDB Atlas Vector Search]
F --> G
G --> H[Composed Context + Metrics]
H -->|MCP Response| A
Componentes Nucleares
| Módulo | Responsabilidade | Documentação |
|---|---|---|
| Harness Runtime | Orquestra execução, valida schemas, intercepta tool calls, persiste estado | Infraestrutura que conecta o LLM ao mundo real, não um framework de testes |
| Context Engine | Decide escopo (filesystem vs vector), aplica AST parsing, compaction multi-hop | Pipeline Embed → Search → Rerank → Compose → Validate |
| Provider Router | Roteia para stack curada, gerencia fallback BYOK, rastreia quota | Sem camadas genéricas. SDKs oficiais, parsing estável |
| Tool Executor | Valida args via Strong Typing, executa com retry exponencial, sanitiza output | Blocklist imutável aplicada antes de qualquer chamada |
Stack Curada & Infraestrutura
Vectora não é provider-agnóstico. Operamos com modelos rigorosamente calibrados para garantir consistência de métricas, estabilidade de parsing e custos previsíveis:
| Camada | Tecnologia | Por que escolhemos | Docs |
|---|---|---|---|
| LLM (Inferência) | gemini-3-flash | Latência <30ms, tool calling estável, custo 90% menor vs Pro | Gemini 3 |
| Embeddings | voyage-4 | AST-aware, captura similaridade funcional (validateToken ≈ checkJWT) | Voyage 4 |
| Reranking | voyage-rerank-2.5 | Cross-encoder otimizado para código, latência <100ms, precisão +25% vs BM25 | Reranker |
| Vector DB + Metadata | MongoDB Atlas | Backend unificado (vetores + docs + estado + audit), escalável, sem ETL | MongoDB Atlas |
Vectora Cloud Only:
O Vectora é uma solução 100% baseada em nuvem otimizada para a stack Gemini + Voyage. Não oferecemos suporte para modelos locais (Ollama, LlamaCpp, etc.) ou outros provedores genéricos para garantir a precisão do engine.
Segurança, Governança & BYOK
A segurança no Vectora é implementada na camada de aplicação, não delegada ao banco de dados:
| Camada | Implementação | Documento |
|---|---|---|
| Guardian Hard-Coded | Blocklist imutável (.env, .key, .pem, binários, lockfiles) executada antes de qualquer tool call | Guardian |
| Trust Folder | Validação de paths com fs.realpath + escopo por namespace/projeto | Trust Folder |
| RBAC Aplicativo | Roles (reader, contributor, admin, auditor) validadas em runtime | RBAC |
| BYOK ou Managed | Chaves do usuário (Free) ou créditos inclusos (Plus) | Plano Free |
| Managed (Plus) | Quota gerenciada inclusa nos planos Pro e Team | Plano Pro |
Planos & Política de Retenção
Vectora opera com modelo Digital Sovereignty First, oferecendo BYOK (Bring Your Own Key) para controle total ou Managed (Plus) para conveniência:
| Plano | Preço | Storage | API Quota | Retenção | Docs |
|---|---|---|---|---|---|
| Free | $0/mês | 512MB total | BYOK puro | 30 dias inatividade = exclusão do índice vetorial | Free |
| Pro | $29/mês | 5GB total | Unlimited (Plus) ou BYOK | 90 dias pós-cancelamento | Pro |
| Team | Custom | Custom | Unlimited (Plus) ou BYOK | Política de Compliance | Team |
| Enterprise | Custom | Ilimitado (VPC/Dedicated) | Sob contrato | Política custom | Overview |
Regras de Retenção: Contas Free inativas por 30 dias têm o índice vetorial excluído automaticamente. Metadados são preservados por +90 dias para exportação via vectora export. Downgrades notificam redução de limites e concedem 7 dias para backup. Detalhes em Política de Retenção.
Fluxo de Operação (MCP-First)
- Detecção: Agent Principal identifica necessidade de contexto profundo e dispara
context_searchvia MCP. - Interceptação: Harness Runtime captura chamada, valida namespace e aplica Guardian.
- Decisão: Context Engine escolhe escopo (filesystem, vector ou híbrido) e aplica AST parsing.
- Embed + Rerank: Query é embedada via
voyage-4, resultados brutos são refinados porvoyage-rerank-2.5. - Busca & Compaction: MongoDB Atlas retorna top-N com compaction (head/tail + pointers) para evitar context rot.
- Resposta Estruturada: Contexto validado + métricas são retornados ao agent principal, que gera a resposta final ao usuário.
Por Onde Começar?
| Categoria | Documento | Descrição |
|---|---|---|
| Início Rápido | Getting Started | winget install kaffyn.vectora, configuração via Systray, integração MCP |
| Conceitos | Sub-Agents | Por que Sub-Agent e não tools MCP passivas? Governança ativa vs funções estáticas |
| Harness Runtime | Harness Runtime | Tool Execution, Context Engineering, State Management, Verification Hooks |
| Context & RAG | Context Engine | AST parsing, compaction, multi-hop reasoning, hybrid ranking |
| Reranking | Reranker · Reranker Local | VectorDB + cross-encoder ou late binding para dados mutáveis, trade-offs de custo |
| Modelos | Gemini 3 · Voyage 4 | Stack curada, fallback BYOK, schema de configuração, custos por query |
| Backend | MongoDB Atlas | Vector Search, collections, state persistence, isolamento multi-tenant |
| Segurança | Guardian · RBAC | Blocklist hard-coded, Trust Folder, sanitização, roles por namespace |
| Planos | Overview | Free/Pro/Team, quota gerenciada, fallback automático, política de retenção |
| Integrações | MCP Protocol · VS Code · ChatGPT · Gemini API | MCP genérico, extensions, plugins, APIs |
| Referência | MCP Tools · Config YAML | Schema de tools, config.yaml validado negativamente, códigos de erro |
| Implementação | Engineering | Arquitetura em Golang, Migração de Core, CLI Engine, Systray UX |
| Contribuição | Guidelines | Golang estrito, testes de performance, PRs, roadmap público |
Frase para guardar: “Vectora não responde ao usuário. Ele entrega contexto governado ao seu agent. Backend gerenciado, API sob sua chave, segurança na aplicação, dados sempre seus.”
Guia de Navegação
- Início Rápido — Instalação, configuração BYOK e integração MCP.
- Conceitos Nucleares — Entenda Sub-Agents, Context Engine e Reranking.
- Segurança & Governança — Detalhes sobre o Guardian, Trust Folder e RBAC.
- Autenticação — Fluxos de SSO, Identidade Unificada e API Keys.
- Modelos & Providers — Stack curada com Gemini 3 e Voyage AI.
- Backend — MongoDB Atlas.
- Integrações — Como usar com Claude Code, Gemini CLI e Cursor.
- Planos & Preços — Comparativo de recursos e política de retenção.
- Referência Técnica — Schema de ferramentas MCP e Config YAML.
- Contribuição — Guidelines, padrões de código e roadmap.
- Perguntas Frequentes — Solução de problemas e dúvidas comuns.
- Protocolos — Especificações do Protocolo MCP no Vectora.
External Linking
| Concept | Resource | Link |
|---|---|---|
| MongoDB Atlas | Atlas Vector Search Documentation | www.mongodb.com/docs/atlas/atlas-vector-search/ |
| MCP | Model Context Protocol Specification | modelcontextprotocol.io/specification |
| MCP Go SDK | Go SDK for MCP (mark3labs) | github.com/mark3labs/mcp-go |
| Voyage Embeddings | Voyage Embeddings Documentation | docs.voyageai.com/docs/embeddings |
| Voyage Reranker | Voyage Reranker API | docs.voyageai.com/docs/reranker |
| Gemini API | Google AI Studio Documentation | ai.google.dev/docs |
Parte do ecossistema Vectora · Open Source (MIT) · Contribuidores