own-rag-cli 0.0.3-snapshot → 0.0.4-snapshot

package/README.md

@@ -1,15 +1,18 @@
 # own-rag
 
-Local RAG for codebases with ChromaDB + MCP, focused on simple setup and local control.
+Local RAG for codebases with ChromaDB + MCP, focused on practical setup and lower LLM token waste.
 
 Language: English (default) | Portuguese: `README.pt-br.md`
 
 ## Why use own-rag
 
-- Search your codebase semantically from MCP clients (Claude/Cursor).
-- Keep data local by default.
-- Run on CPU (no GPU required).
-- Choose between safer memory usage (`autotune`) or higher throughput (`max-performance`).
+Without local retrieval, an AI assistant often scans many files or asks you to paste large chunks of code, which increases token usage and slows iteration. With `own-rag`, your repository is indexed once and exposed via MCP tools, so the assistant can fetch only the most relevant files/chunks.
+
+Example:
+- Without RAG: asking "where is `MedicationController` used?" may trigger broad project reads.
+- With MCP + own-rag: retrieval points directly to likely files first, so the assistant reads less and answers faster.
+
+Immediate MCP targets are Claude Code and Cursor, but the server can be used by any MCP-capable client.
 
 ## What gets installed
 
@@ -63,8 +66,8 @@ rag remove --force              # uninstall without confirmation prompts
 Path: `~/.own-rag-cli.json`
 
 Purpose:
-- Stores Chroma endpoint (`scheme`, `host`, `port`).
-- Stores latest indexing batch fields (`indexing.embedding_batch_size`, `indexing.batch_count`).
+- Stores Chroma endpoint and last known indexing batch values.
+- Used as the simplest user-facing config to move between machines or switch endpoint.
 
 Example:
 
@@ -82,6 +85,18 @@ Example:
 }
 ```
 
+Field meaning:
+- `chroma.scheme`: `http` or `https`.
+- `chroma.host`: Chroma host (`localhost`, IP, or DNS).
+- `chroma.port`: Chroma TCP port.
+- `indexing.embedding_batch_size`: batch size used by embedding encode.
+- `indexing.batch_count`: mirrored batch value for explicit readability.
+
+If you edit this file manually:
+1. Save the file.
+2. Restart tools that consume MCP (Claude/Cursor).
+3. If you changed model/chunk/batch strategy, run reindex (`rag run <project>` or `--only-index`) so stored vectors match new settings.
+
 ### 2) Indexer tuning config
 
 Path: `~/.cache/own-rag-cli/indexer_tuning.json`
@@ -100,11 +115,11 @@ Purpose:
 
 - Claude Code: `~/.claude.json`
 - Cursor: `~/.cursor/mcp.json`
-- Cursor (alt, Linux/macOS variants): `~/.config/Cursor/User/mcp.json` or `~/Library/Application Support/Cursor/User/mcp.json`
+- Cursor (alt paths): `~/.config/Cursor/User/mcp.json` or `~/Library/Application Support/Cursor/User/mcp.json`
 
 ## Choosing the embedding model (practical guidance)
 
-These are practical memory guidelines for CPU usage. Real usage depends on project size, file size, and other running processes.
+These are practical CPU-memory guidelines. Real usage depends on project size and concurrent processes.
 
 | Choice | Use case | Approx RAM target |
 |---|---|---|
@@ -113,70 +128,122 @@ These are practical memory guidelines for CPU usage. Real usage depends on proje
 | `hybrid` (`jina v2 + bge`) | two collections, broader retrieval strategy | 24-48 GiB |
 
 Notes:
-- Jina on CPU is heavy; with low free RAM/swap, you can see slowdowns or OOM (`exit 137`).
-- If your machine has limited memory, start with `bge`.
+- Jina on CPU is heavy; with low free RAM/swap, slowdowns or OOM (`exit 137`) can happen.
+- If your machine is memory-limited, start with `bge`.
 
 ## Performance profile
 
-During setup/indexing, choose one profile:
+During setup/indexing:
 
 - `autotune` (recommended):
   - Runs a short local benchmark (`model.encode`) with `psutil` metrics.
-  - Tries to keep memory in a safer range (roughly cost-benefit target).
+  - Targets cost-benefit (not too aggressive, not too conservative).
   - Automatically adjusts `MCP_EMBEDDING_BATCH_SIZE`, `MCP_CHUNK_SIZE`, `MCP_CHUNK_OVERLAP`.
 
 - `max-performance`:
   - Uses more aggressive throughput-oriented parameters.
-  - Explicit warning is shown because memory can increase considerably.
+  - Shows explicit memory-risk warning.
 
 ## Chroma endpoint behavior
 
 - Default local endpoint is `http://localhost:8000`.
-- Setup checks if the selected port is already in use.
-- If `host` in `~/.own-rag-cli.json` is remote (not localhost/127.0.0.1/::1), local Docker startup is skipped.
+- Setup checks if selected port is already in use.
+- If `~/.own-rag-cli.json` points to a remote host, local Docker startup is skipped.
+
+## Backup/snapshot before reinstall or machine migration
+
+Before running `rag remove`, formatting your machine, or moving to another machine, snapshot these files:
+
+```bash
+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
+```
+
+Restore on a new machine:
+1. Install `own-rag-cli`.
+2. Restore `~/.own-rag-cli.json` and optional tuning file.
+3. Extract `.rag_db` backup into `$HOME`.
+4. Start with `rag run /path/to/project --skip-index` and validate search.
+5. If model/chunk settings changed, reindex.
 
 ## Common flows
 
-### Reindex only
+### Reindex only (`--only-index`)
 
 ```bash
 ./rag-setup.run /path/to/project --only-index
 ```
 
-### Skip index step
+Use when environment is already installed and you only changed project code/docs.
+
+### Skip index step (`--skip-index`)
 
 ```bash
 ./rag-setup.run /path/to/project --skip-index
 ```
 
-### Change model later
+Use when you want to refresh infra/config first (venv, Docker, MCP wiring), and index later.
+
+### Change model (`--change-model`)
 
 ```bash
 ./rag-setup.run --change-model /path/to/project
 ```
 
-This flow warns about resetting Chroma collections and requiring full reindex.
+Use when switching embedding strategy (`jina`, `bge`, `hybrid`). This may reset collections and requires full reindex so embeddings remain consistent.
 
 ## Environment overrides
 
-Main overrides:
+Where to override:
+- Temporary for one shell/session: `export VAR=value` before `rag run`.
+- Persistent for MCP runtime: set env in your MCP client config (`~/.claude.json`, Cursor `mcp.json`).
+- Chroma endpoint can also be persisted in `~/.own-rag-cli.json`.
+
+What each variable does:
 
 - `MCP_EMBEDDING_MODEL=jina|bge|hybrid`
+  - Selects embedding strategy.
+  - After changing: reindex required.
+
 - `MCP_JINA_QUANTIZATION=default|dynamic-int8`
+  - Jina CPU quantization mode.
+  - After changing: reindex recommended.
+
 - `MCP_PERF_PROFILE=autotune|max-performance`
+  - Chooses tuning strategy for chunk and batch decisions.
+  - After changing: rerun index setup to apply new tuning.
+
 - `MCP_EMBEDDING_BATCH_SIZE=<int>`
+  - Forces fixed embedding batch size (overrides autotune batch).
+  - After changing: restart MCP; reindex recommended for consistent throughput assumptions.
+
 - `MCP_CHUNK_SIZE=<int>`
+  - Sets chunk length for indexing.
+  - After changing: full reindex required.
+
 - `MCP_CHUNK_OVERLAP=<int>`
+  - Sets overlap between chunks.
+  - After changing: full reindex required.
+
 - `OWN_RAG_CLI_CONFIG_FILE=<path>`
+  - Moves runtime config location from default `~/.own-rag-cli.json`.
+  - After changing: restart setup/MCP tools.
+
 - `MCP_INDEXER_CONFIG_FILE=<path>`
+  - Moves tuning config location from default `~/.cache/own-rag-cli/indexer_tuning.json`.
+  - After changing: restart setup/MCP tools.
+
 - `MCP_CHROMA_SCHEME=http|https`
 - `MCP_CHROMA_HOST=<host>`
 - `MCP_CHROMA_PORT=<port>`
+  - Overrides Chroma endpoint.
+  - After changing: restart MCP clients; reindex only if switching to a fresh/empty database.
 
 ## Checksum verification (`.run`)
 
-Current checksum (documented in this repo) refers to payload hash.
-
 Manual verification (Linux/macOS):
 
 ```bash

package/README.pt-br.md

@@ -1,15 +1,18 @@
 # own-rag
 
-RAG local para codebases com ChromaDB + MCP, focado em instalação simples e controle local.
+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
 
-- Busca semântica no seu código via clientes MCP (Claude/Cursor).
-- Dados locais por padrão.
-- Execução em CPU (sem GPU obrigatória).
-- Escolha entre perfil mais seguro de memória (`autotune`) ou maior throughput (`max-performance`).
+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
 
@@ -63,8 +66,8 @@ rag remove --force             # desinstala sem prompts de confirmação
 Caminho: `~/.own-rag-cli.json`
 
 Finalidade:
-- Armazena endpoint do Chroma (`scheme`, `host`, `port`).
-- Armazena campos de batch da indexação (`indexing.embedding_batch_size`, `indexing.batch_count`).
+- 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:
 
@@ -82,6 +85,18 @@ Exemplo:
 }
 ```
 
+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`
@@ -100,11 +115,11 @@ Finalidade:
 
 - Claude Code: `~/.claude.json`
 - Cursor: `~/.cursor/mcp.json`
-- Cursor (variações Linux/macOS): `~/.config/Cursor/User/mcp.json` ou `~/Library/Application Support/Cursor/User/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, arquivos e processos concorrentes.
+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.) |
 |---|---|---|
@@ -118,60 +133,114 @@ Notas:
 
 ## Perfil de performance
 
-Durante setup/indexação, escolha:
+Durante setup/indexação:
 
 - `autotune` (recomendado):
   - Executa micro-benchmark local (`model.encode`) com métricas `psutil`.
-  - Busca faixa mais estável de memória (custo-benefício).
+  - 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 maior consumo de memória.
+  - 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 `host` em `~/.own-rag-cli.json` for remoto (não localhost/127.0.0.1/::1), o setup não sobe Docker local.
+- 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:
+
+```bash
+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
+### Reindexar somente (`--only-index`)
 
 ```bash
 ./rag-setup.run /caminho/do/projeto --only-index
 ```
 
-### Pular indexação
+Use quando o ambiente já está instalado e você só alterou código/documentação do projeto.
+
+### Pular indexação (`--skip-index`)
 
 ```bash
 ./rag-setup.run /caminho/do/projeto --skip-index
 ```
 
-### Trocar modelo depois
+Use para atualizar infraestrutura/configuração primeiro (venv, Docker, MCP), deixando a indexação para depois.
+
+### Trocar modelo (`--change-model`)
 
 ```bash
 ./rag-setup.run --change-model /caminho/do/projeto
 ```
 
-Esse fluxo alerta sobre reset das coleções Chroma e reindexação completa.
+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
 
-## Variáveis de ambiente (override)
+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`.
 
-Principais variáveis:
+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`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "own-rag-cli",
-  "version": "0.0.3-snapshot",
+  "version": "0.0.4-snapshot",
   "description": "Local RAG setup with ChromaDB + MCP server (Jina/BGE hybrid support).",
   "license": "MIT",
   "private": false,