own-rag

RAG local para codebases com ChromaDB + MCP, focado em setup prático e menor desperdício de tokens no uso de IA.

Idioma: Português (PT-BR) | English: README.md

Por que usar o own-rag

Sem recuperação local, a IA costuma ler muitos arquivos ou pedir grandes trechos de código, aumentando custo de tokens e tempo de resposta. Com own-rag, o repositório é indexado uma vez e exposto por ferramentas MCP, então a IA consulta primeiro os trechos mais relevantes.

Exemplo:

• Sem RAG: ao perguntar "onde MedicationController é usado?", a IA pode varrer boa parte do projeto.
• Com MCP + own-rag: a recuperação aponta rapidamente para os arquivos com maior probabilidade, reduzindo leitura desnecessária.

Os alvos imediatos por padrão são Claude Code e Cursor, mas o servidor pode ser usado por qualquer cliente compatível com MCP.

O que é instalado

• Container ChromaDB (Docker)
• Ambiente virtual Python (~/.rag_venv)
• Binário MCP (~/.local/bin/mcp-rag-server)
• Instaladores (rag-setup.run, rag-setup-macos.run)
• Comando wrapper: rag

Instalação e execução

Opção A: npm (recomendado)

npm install -g own-rag-cli
rag run /caminho/do/projeto

Se executar rag run sem caminho, o CLI pergunta se deve usar o diretório atual.

Opção B: .run direto

Linux:

chmod +x rag-setup.run
./rag-setup.run /caminho/do/projeto

macOS:

chmod +x rag-setup-macos.run
./rag-setup-macos.run /caminho/do/projeto

Comandos principais

rag run /caminho/do/projeto    # setup completo + indexação
rag monitor                    # monitor interativo do Chroma
rag monitor full               # painel completo do monitor
rag remove                     # desinstala setup local (preserva modelos baixados)
rag remove --force             # desinstala setup sem prompts de confirmação
rag clean models               # lista modelos em cache e remove um ou 'all' (dupla confirmação)

Notas:

• rag remove mantém o cache de modelos baixados.
• Use rag clean models para limpar modelos específicos ou todos (all).

Indexacao a partir de URL (HTTP/HTTPS)

Agora o rag run aceita URL remota alem de pasta local.

Como funciona:

• Se voce passar http:// ou https://, o wrapper baixa o conteudo para uma pasta temporaria.
• Se o arquivo baixado for ZIP, ele e descompactado e a pasta extraida e indexada.
• Arquivos de texto (.txt, .md e outros textos nao-binarios) podem ser indexados.
• Arquivos binarios sao ignorados pelo indexador.
• Ao terminar a indexacao, os arquivos temporarios baixados/descompactados sao removidos automaticamente.

Comportamento do downloader:

• Usa curl quando disponivel.
• Se curl nao existir, o wrapper tenta instalar automaticamente:
  • Linux: gerenciador de pacotes (apt, dnf, yum, pacman, zypper, apk)
  • macOS: Homebrew (brew)

Exemplos:

rag run https://exemplo.com/docs/guia.md
rag run https://exemplo.com/snapshots/docs-projeto.zip

Arquivos e caminhos de configuração

1) Configuração de runtime (nível CLI)

Caminho: ~/.own-rag-cli.json

Finalidade:

• Guarda endpoint do Chroma e os últimos valores de batch de indexação.
• É o arquivo mais simples para portar configuração entre máquinas.

Exemplo:

{
  "chroma": {
    "scheme": "http",
    "host": "localhost",
    "port": 8000
  },
  "indexing": {
    "embedding_batch_size": 4,
    "batch_count": 4
  }
}

Significado de cada variável:

• chroma.scheme: protocolo (http ou https).
• chroma.host: host do Chroma (localhost, IP ou DNS).
• chroma.port: porta TCP do Chroma.
• indexing.embedding_batch_size: tamanho do batch usado no encode de embeddings.
• indexing.batch_count: espelho explícito do valor de batch para leitura humana.

Se você editar esse arquivo manualmente:

1. Salve o arquivo.
2. Reinicie as ferramentas que usam MCP (Claude/Cursor).
3. Se mudou estratégia de modelo/chunk/batch, rode reindexação (rag run <projeto> ou --only-index) para manter consistência dos vetores.

2) Configuração de tuning do indexador

Caminho: ~/.cache/own-rag-cli/indexer_tuning.json

Finalidade:

• Persiste decisões de modelo/perfil/tuning (chunk_size, chunk_overlap, embedding_batch_size, etc.).
• É lido por indexador e MCP server para manter consistência entre execuções.

3) Diretórios de dados e runtime

• Dados do Chroma: ~/.rag_db
• Venv Python: ~/.rag_venv
• Binários/scripts instalados: ~/.local/bin/

4) Arquivos de configuração MCP (auto-update opcional)

• Claude Code: ~/.claude.json
• Cursor: ~/.cursor/mcp.json
• Cursor (caminhos alternativos): ~/.config/Cursor/User/mcp.json ou ~/Library/Application Support/Cursor/User/mcp.json

Escolha do modelo de embeddings (guia prático)

Valores abaixo são referência prática para CPU. O consumo real depende do tamanho do projeto e de processos concorrentes.

| Opção | Quando usar | RAM desejada (aprox.) | |---|---|---| | bge (BAAI/bge-m3) | docs + código, menor risco de memória | 8-16 GiB | | jina (jinaai/jina-embeddings-v3, padrão) | foco em qualidade para código | 32-64 GiB (ideal 48+ GiB) | | hybrid (jina v2 + bge) | duas coleções, recuperação mais ampla | 24-48 GiB |

Notas:

• Jina em CPU é pesado; com pouca RAM/swap livre pode ocorrer lentidão ou OOM (exit 137).
• Se a máquina for limitada, comece com bge.

Perfil de performance

Durante setup/indexação:

• autotune (recomendado):

  • Executa micro-benchmark local (model.encode) com métricas psutil.
  • Busca custo-benefício (nem agressivo, nem conservador).
  • Ajusta automaticamente MCP_EMBEDDING_BATCH_SIZE, MCP_CHUNK_SIZE, MCP_CHUNK_OVERLAP.

• max-performance:

  • Usa parâmetros mais agressivos para throughput.
  • Exibe aviso explícito de risco de memória.

Comportamento do endpoint Chroma

• Endpoint local padrão: http://localhost:8000.
• O setup verifica se a porta escolhida já está em uso.
• Se ~/.own-rag-cli.json apontar para host remoto, o setup não sobe Docker local.

Backup/snapshot antes de remover, formatar ou migrar máquina

Antes de executar rag remove, formatar o computador, ou migrar para outra máquina, faça snapshot:

mkdir -p "$HOME/own-rag-backup"
cp "$HOME/.own-rag-cli.json" "$HOME/own-rag-backup/" 2>/dev/null || true
cp "$HOME/.cache/own-rag-cli/indexer_tuning.json" "$HOME/own-rag-backup/" 2>/dev/null || true

tar -czf "$HOME/own-rag-backup/chromadb-ragdb-$(date +%Y%m%d-%H%M%S).tgz" -C "$HOME" .rag_db

Restauração em nova máquina:

1. Instale own-rag-cli.
2. Restaure ~/.own-rag-cli.json e, opcionalmente, o tuning.
3. Extraia o backup de .rag_db em $HOME.
4. Execute rag run /caminho/do/projeto --skip-index e valide a busca.
5. Se mudou modelo/chunks, reindexe.

Fluxos comuns

Reindexar somente (--only-index)

./rag-setup.run /caminho/do/projeto --only-index

Use quando o ambiente já está instalado e você só alterou código/documentação do projeto.

Pular indexação (--skip-index)

./rag-setup.run /caminho/do/projeto --skip-index

Use para atualizar infraestrutura/configuração primeiro (venv, Docker, MCP), deixando a indexação para depois.

Trocar modelo (--change-model)

./rag-setup.run --change-model /caminho/do/projeto

Use ao mudar estratégia de embeddings (jina, bge, hybrid). Esse fluxo pode resetar coleções e exige reindexação completa para consistência.

Environment overrides

Onde sobrescrever:

• Temporário por sessão: export VAR=valor antes do rag run.
• Persistente no runtime MCP: definir env no arquivo de configuração do MCP (~/.claude.json, mcp.json do Cursor).
• Endpoint Chroma também pode ser persistido em ~/.own-rag-cli.json.

Para que serve cada variável:

• MCP_EMBEDDING_MODEL=jina|bge|hybrid

  • Seleciona estratégia de embedding.
  • Ao alterar: reindexação obrigatória.

• MCP_JINA_QUANTIZATION=default|dynamic-int8

  • Define quantização do Jina em CPU.
  • Ao alterar: reindexação recomendada.

• MCP_PERF_PROFILE=autotune|max-performance

  • Define estratégia de tuning para chunks e batch.
  • Ao alterar: rode setup/indexador novamente para aplicar novo tuning.

• MCP_EMBEDDING_BATCH_SIZE=<int>

  • Força batch fixo (sobrescreve batch autotunado).
  • Ao alterar: reinicie MCP; reindexação recomendada para consistência operacional.

• MCP_CHUNK_SIZE=<int>

  • Define tamanho dos chunks na indexação.
  • Ao alterar: reindexação completa obrigatória.

• MCP_CHUNK_OVERLAP=<int>

  • Define sobreposição entre chunks.
  • Ao alterar: reindexação completa obrigatória.

• OWN_RAG_CLI_CONFIG_FILE=<path>

  • Muda localização do arquivo runtime (padrão ~/.own-rag-cli.json).
  • Ao alterar: reinicie setup/ferramentas MCP.

• MCP_INDEXER_CONFIG_FILE=<path>

  • Muda localização do arquivo de tuning (padrão ~/.cache/own-rag-cli/indexer_tuning.json).
  • Ao alterar: reinicie setup/ferramentas MCP.

• MCP_CHROMA_SCHEME=http|https

• MCP_CHROMA_HOST=<host>

• MCP_CHROMA_PORT=<port>

  • Sobrescrevem endpoint do Chroma.
  • Ao alterar: reinicie clientes MCP; reindexe somente se trocar para base vazia/nova.

Verificação de checksum (.run)

Verificação manual (Linux/macOS):

sha256sum rag-setup.run
sha256sum rag-setup-macos.run

No macOS sem sha256sum:

shasum -a 256 rag-setup.run
shasum -a 256 rag-setup-macos.run

Transparência de código

Lógica principal em arquivos-fonte (bin/*.py, bin/*.sh). Artefatos gerados:

• rag-setup.run
• rag-setup-macos.run

Para regenerar artefatos após mudanças no fonte:

./bin/build_run.sh
./bin/build_run_macos.sh

Validação antes de publicar

bash -n rag-setup.run
bash -n rag-setup-macos.run
python3 -m py_compile bin/indexer_full.py bin/mcp_server.py
npm pack --dry-run

Licença

MIT