SynRAG

Busca de código nativa de AST local para agentes de codificação: definições exatas, chamadores e raio de impacto em vez de arquivos inteiros. -63,9% de tokens medidos com um agente real.

GitHub

Documentação

SyntaxRAG (SYNRAG)

Mecanismo MCP nativo de AST · Busca de código local · Grafo de Impacto de Dependências

Espanhol · English

Demo de SynRAG: indexa Flask y Hono y, al pedir SecureCookieSessionInterface open_session, devuelve ese método primero

Mecanismo local de busca de código para agentes de IA, pelo protocolo MCP. Testado com Claude Code e Google Antigravity; o instalador também o configura para Gemini CLI, Codex CLI, Cursor, Windsurf, Cline/Roo Code e Zed (não testado).

O que é SyntaxRAG (SYNRAG)

Um RAG de janelas fixas para código corta os arquivos em blocos de, por exemplo, 500 tokens que podem partir funções ao meio e não entendem hierarquias de tipos, e os agentes acabam lendo arquivos completos para se orientar. Outras ferramentas modernas também fatiam por AST; SyntaxRAG é uma opção local e aberta, e publica como cada número é medido (ver CLAIMS.md).

SyntaxRAG (SYNRAG) resolve esse problema analisando a árvore sintática abstrata (AST) do código na sua máquina local:

Tree-sitter AST Chunker: Fatia por funções, hooks, classes e objetos grandes (membro por membro, também os campos com função seta como json = () => {} e os serviços const x = { listar() {}, crear: async () => {} }), tipos e declarações completas (TypeScript, TSX/JSX, JavaScript e Python). A documentação (Markdown, MDX, reStructuredText, AsciiDoc) é fatiada em fragmentos de ~200 tokens com seu caminho de títulos; SQL por sentenças.
Localizar antes de ler: Com um nome de símbolo (ou objeto.miembro, ou Clase miembro) retorna sua definição primeiro e inteira, com uma linha de usos (sessions.py:324 open_session, :373 save_session; lo importan 3 archivo(s)) e, se for uma classe ou objeto grande, a lista de seus membros com sua linha; o restante dos resultados ocupa uma linha (ruta:líneas tipo nombre | firma). Nomes compostos também são indexados separados (esSinCupo é encontrado com "sem cupo"). Candidatos por BM25 (Tantivy sobre LanceDB) reordenados em CPU com TinyBERT (FlashRank). Mediana medida: 61-89 ms por consulta nova.
Grafo de Impacto de Dependências: Lê os imports do AST (também os de várias linhas e os re-export dos barrels) e resolve cada um para seu arquivo: caminhos relativos, paths/baseUrl do tsconfig (com extends), pacotes do próprio monorepo e módulos de Python. Assim, se dois arquivos definem useAuth, get_impact_radius diz quais arquivos dependem de cada um. Medido contra o compilador de TypeScript: mesmo arquivo em 100% dos imports locais. Não segue chamadas dinâmicas nem import().
Cache de consultas repetidas: Se você repetir a mesma consulta (sem distinguir maiúsculas nem espaços) é respondida a partir de uma tabela local (~3-4 ms). Não é um cache semântico e é esvaziado ao reindexar. A busca não usa APIs pagas; os resultados igualmente custam tokens ao modelo que os lê.
Observador de mudanças (opcional): Um serviço de systemd de usuário (lancedb-watcher.service) reindexa apenas o arquivo que você salva: ~8 ms por arquivo pequeno (mediana medida), após 0,6 s de espera para agrupar salvamentos. Usa cerca de 250-300 MB de RAM; compacta a base a cada certo número de mudanças e detecta pastas novas sem reiniciar.

Quanto economiza (medido, não prometido)

Cada número vem de um script de benchmarks/ que qualquer um pode repetir em sua máquina sobre repositórios públicos (Flask e Hono). A comparação honesta não é contra ler arquivos inteiros, mas contra o que um agente faz sem SynRAG: grep e ler o trecho.

O quê	Resultado	Script
Sistema completo com um agente real (Gemini com function calling): 10 tarefas de várias etapas (localizar, entender, planejar uma mudança, rodar testes) x 2 rodadas, contando todos os tokens que a API cobra	v1.6: -63,9% tokens (305.736 contra 110.338; intervalo de confiança 95%: -83% a -24%), qualidade 87% -> 94%. A v1.5 no mesmo dia: -4,6% (em 15-out, -29,2%). Ganha principalmente ao buscar métodos dentro de classes (`c.json` de Hono -94%, métodos de `Config` -73%) e ao planejar uma mudança (-65%); perde em testes com saída curta (+117%: as definições das ferramentas pesam mais que a tarefa) e em uma do Flask (+38%)	`benchmarks/agente/completo.py`
Agente real, apenas localizar: 16 perguntas x 2 rodadas, com e sem SynRAG	-11,5% tokens, 16/16 acertos em ambos os modos; ganha em 7 de 16 (até -79% em linguagem natural em um repo grande; perde com nomes exatos em um repo pequeno, onde `grep` retorna uma linha)	`benchmarks/agente/agente.py`
Encontrar e ler uma função pelo nome, contra grep + ler o trecho (v1.6, com a linha de usos)	Flask -36 a -38%, Hono -52% (v1.5.0 nas mesmas condições: -37 a -39% e -54%); a definição sai primeiro em 92-100%	`benchmarks/ahorro.py --indexar --semilla N`
O mesmo com perguntas em linguagem natural	Flask -37%	`benchmarks/ahorro.py --naturales`
Precisão do grafo de impacto em símbolos com nome repetido (contra TypeScript)	Por nome (v1.5.0): 15-18%. Resolvido (v1.6): 93-100%, cobertura 100%	`benchmarks/resolucion.py`
Imports que chegam ao grafo (contra o compilador de TypeScript e `ast` de Python)	v1.5.0: Hono 75%, um monorepo TS real 48%. v1.6: 100% com precisão 100%	`benchmarks/imports.py`
Documentação (fragmentos de ~200 tokens)	-22% contra grep, -91% contra o arquivo inteiro	`benchmarks/docs.py`
Empacotar um repo apenas com assinaturas (como Repomix `--compress`)	Flask -76%, Hono -84% contra o repo completo	`benchmarks/mapa.py`
Saídas longas de terminal (filtro opcional)	-87 a -99% preservando todas as linhas de erro; a saída completa fica em um arquivo	`benchmarks/filtro.py`
Custo fixo por turno (contado com a API de Gemini)	Definições: perfil completo 2.068 tokens, `esencial` (5 ferramentas) 412, `bajo_demanda` (2) 159; instrução de uso 108; bloco conciso 115 (antes do corte: 2.091, 435, 188 e 248)	`benchmarks/costo_fijo.py`

O que mais pesa em uma sessão real não é nenhuma ferramenta: é o comprimento da sessão, porque cada turno reenvia todo o histórico. context_budget_alert e session_handoff ajudam a cortar a tempo. Detalhe e limites de cada número: CLAIMS.md.

Instalação Universal em 1 Linha

Testado em Linux (CachyOS). Deve funcionar em outras distribuições, macOS e Windows com WSL, mas não são testados:

curl -sSL https://raw.githubusercontent.com/EnmanuelReynoso23/synrag/main/install.sh | bash

Ou a partir do repositório clonado:

git clone https://github.com/EnmanuelReynoso23/synrag.git
cd synrag
./install.sh

O instalador copia ou baixa o mecanismo, cria um ambiente virtual isolado em CPU, instala os lançadores SYNRAG / synrag em ~/.local/bin e configura apenas as IAs que você realmente tem instaladas. Se algo falhar, ele para e diz o que falhou. Para ver o que faria sem escrever nada: ./install.sh --dry-run (ou SYNRAG configure --dry-run).

Auto-Configuração Multi-IA

Ao instalar ou ao executar SYNRAG configure, SyntaxRAG faz duas coisas em cada IA detectada: registra o servidor MCP desktop-lancedb e adiciona às suas instruções globais um bloco curto (entre as marcas  e ) que indica usar search_desktop antes de listar pastas ou ler arquivos inteiros. Sem esse bloco a IA vê a ferramenta mas quase nunca a escolhe.

Ferramenta / Agente	MCP (servidor)	Instruções globais
Claude Code	`~/.claude.json`	`~/.claude/CLAUDE.md`
Google Antigravity	`~/.gemini/config/mcp_config.json` (se já existir `~/.gemini/antigravity/mcp_config.json`, também o mantém atualizado)	`~/.gemini/GEMINI.md`
Gemini CLI	`~/.gemini/settings.json`	`~/.gemini/GEMINI.md`
Codex CLI	`~/.codex/config.toml`	`~/.codex/AGENTS.md`
Cursor	`~/.cursor/mcp.json`	(adicionado manualmente em Settings > Rules)
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`~/.codeium/windsurf/memories/global_rules.md`
Cline / Roo Code	`cline_mcp_settings.json` do VS Code	n/a
Zed	`~/.config/zed/settings.json` (apenas se for JSON puro; com comentários mostra o que adicionar)	n/a

Garantias do instalador: não cria a pasta de uma IA que não está instalada, faz uma cópia .bak-AAAAMMDD-HHMMSS antes de modificar um arquivo existente, nunca sobrescreve um JSON que não consegue ler e é idempotente (executar duas vezes não duplica nada).

Estado de compatibilidade (6-out-2026): testado na prática com Claude Code e Google Antigravity. Gemini CLI, Codex CLI, Cursor, Windsurf, Cline/Roo Code e Zed são configurados segundo sua documentação, mas não foram testados. Se você usa algum, abra uma issue com o resultado.

Plugin de Claude Code

O repositório também é um marketplace de plugins de Claude Code. O plugin adiciona uma skill que diz ao Claude quando usar cada ferramenta do SynRAG (~140 tokens por sessão). Não instala o mecanismo: primeiro vai o instalador acima.

claude plugin marketplace add EnmanuelReynoso23/synrag
claude plugin install synrag@synrag

Desinstalar

SYNRAG uninstall            # quita la entrada MCP y el bloque de instrucciones de cada IA y los comandos
rm -rf ~/.local/opt/lancedb-hub   # opcional: borra tambien el motor y su indice

SYNRAG uninstall --dry-run mostra o que removeria sem escrever nada. Apenas remove o que o instalador adicionou.

Ferramentas MCP para Agentes de IA

Qualquer agente conectado ao SyntaxRAG tem 28 ferramentas (as duas do Gemini só aparecem se você configurar sua própria GEMINI_API_KEY; sem ela o mecanismo não usa a rede). Com SYNRAG configure --perfil esencial expõe apenas search_desktop, get_file_outline, get_impact_radius, repo_map e run_test_isolated: útil em clientes que cobram as definições em cada turno ou limitam o número de ferramentas (Claude Code as carrega sob demanda e não precisa disso). SYNRAG uninstall --perfil volta a todas.

Buscar e se orientar: search_desktop (com tipo="docs" ou "codigo"), get_file_outline (inclui os métodos de objetos e classes grandes), repo_map (assinaturas dos arquivos mais importantes por PageRank, dentro de um orçamento de tokens), list_projects, reindex_desktop.
Antes de editar: get_impact_radius (separado por definição; archivo= escolhe uma), find_related_tests, find_callers_exact, get_symbol_contract, extract_type_definition, get_import_graph, check_breaking_callsites, check_circular_imports, verify_dependency_exists (entende monorepos e workspaces), find_code_duplicates.
Editar: patch_function_body, add_import_clean, rename_symbol_scoped, remove_unused_imports (preservam quebras de linha e indentação; se o nome do arquivo for ambíguo não tocam em nada; backup fora do repo).
Executar com saída curta: run_test_isolated, lint_summary, run_typecheck_focus, tail_clean_logs.
Sessão: session_handoff, context_budget_alert, git_staged_overview, extract_todo_status, get_savings_report.
Opcional com Gemini: ask_synrag_architect, explain_blast_radius.

Comandos do CLI (`SYNRAG`)

SyntaxRAG conta com um binário autônomo para terminal:

# Panel de control y estado operativo
SYNRAG

# Búsqueda por palabras con reordenado neuronal
SYNRAG "asistenciaServicio"

# Búsqueda filtrada por proyecto
SYNRAG --project asistoya-web "useEstudiantes"

# Esquema sintáctico de un archivo (firmas y rangos de línea)
SYNRAG outline apps/web/src/modulos/asistencia/asistencia.servicio.ts

# Radio de impacto y archivos dependientes
SYNRAG impact asistenciaServicio

# Localizar tests asociados
SYNRAG tests asistenciaServicio

# Estadísticas del índice y registro de búsquedas
SYNRAG stats

# Re-escanear y auto-configurar todas las IAs instaladas
SYNRAG configure

# Qué carpetas se indexan (por defecto se detectan ~/Projects, ~/code, ~/dev...; se guardan en
# ~/.config/synrag/carpetas.txt o en la variable SYNRAG_CARPETAS)
SYNRAG carpetas
SYNRAG agregar ~/trabajo [nombre-del-proyecto]
SYNRAG quitar ~/trabajo

# Reindexar todo con Tree-sitter AST
SYNRAG index

# Mapa del repo: firmas de los archivos más importantes (PageRank) en un presupuesto de tokens
SYNRAG mapa mi-proyecto --tokens 1024 [--foco archivo.ts,funcion]

# Empaquetar un repo solo con firmas, tipos e imports (para pegarlo en un chat web)
SYNRAG empaquetar ~/mi-proyecto --salida paquete.md [--sin-comprimir]

# Opcionales (se quitan con "SYNRAG uninstall --<lo-mismo>"):
SYNRAG configure --filtro-largas   # recorta salidas largas de la terminal en Claude Code (hook PostToolUse)
SYNRAG configure --filtro          # resume salidas de instalar/compilar/probar
SYNRAG configure --conciso         # respuestas cortas (basado en Caveman de Julius Brussee, Apache-2.0)
SYNRAG configure --perfil esencial # solo 5 herramientas MCP (412 tokens de definiciones en vez de 2.068)
SYNRAG configure --perfil bajo_demanda # arranca con search_desktop; synrag_mas activa el resto (159 tokens por turno)
SYNRAG configure --pista           # Claude Code: aviso de usar SynRAG una vez por sesión, solo en mensajes de código

# Ver log en vivo del demonio reactivo (Ctrl+S)
SYNRAG watch

# Lanzar agentes directamente con el entorno MCP listo
SYNRAG claude
SYNRAG agy

Telemetria local e bases de dados existentes

SyntaxRAG registra o uso local em SQLite (~/.local/share/lancedb-hub/telemetry.db). Os dados separam as consultas medidas em tempo real de linhas que não correspondem a medições reais (coluna origen = 'medido').

Se você vem de uma base antiga com dados semeados ou de testes, pode marcá-los para que não sejam somados às métricas do relatório:

-- hacer antes una copia de seguridad de telemetry.db
UPDATE telemetry_events SET origen = 'sembrado'
WHERE tokens_retrieved = 631 AND tokens_original_file = 2500 AND results_count = 3 AND latency_ms = 6.2;

Web

A web (src/, React 19 + Tailwind 4, tema #0D1117 e ciano #00E5FF) explica o que é SynRAG, como funciona e o que foi medido. Não tem simulações nem números próprios: todos vêm de src/data/medido.ts, que copia as linhas de CLAIMS.md e vincula cada uma. Se um número mudar em CLAIMS.md, é alterado em medido.ts no mesmo dia. O exemplo de busca é uma saída real sobre Flask.

Subir a Web em Desenvolvimento

pnpm install
pnpm dev

A web estará disponível em http://localhost:5173.

Estrutura do Repositório

synrag/
├── engine/                       # Motor Central de Inteligencia Local (Python)
│   ├── chunker.py                # Tree-sitter AST Chunker (TS, TSX, JS y Python; también Markdown y SQL)
│   ├── ranker.py                 # FlashRank ONNX Cross-Encoder Reranker
│   ├── impact.py                 # Grafo de dependientes en LanceDB
│   ├── cache.py                  # Caché de consultas repetidas (LanceDB)
│   ├── telemetry.py              # Telemetría persistente en SQLite
│   ├── server_mcp.py             # Servidor MCP 2.0 (FastMCP / MCPServer)
│   ├── indexer.py                # Indexador incremental de repositorios
│   ├── installer.py              # Auto-configurador multi-IA multiplataforma
│   ├── cli.py                    # Interfaz rica de terminal (Rich + Dark Mode)
│   └── watcher.py                # Observador opcional de cambios (Watchdog)
├── src/                          # Aplicación web (React 19 + Tailwind 4)
│   ├── components/               # Hero, Problema, ComoFunciona, Resultados, Herramientas, Install, Faq
│   ├── data/medido.ts            # Cifras de la web (copiadas de CLAIMS.md, con su fila)
│   └── index.css                 # Sistema de diseño (#0D1117 + Neón Cyan)
├── public/                       # Assets públicos, logos vectoriales e install.sh
├── install.sh                    # Script universal de instalación en 1 línea
└── README.md                     # Documentación oficial

Licença

Distribuído sob a Licença MIT. Desenvolvido por Enmanuel Reynoso.