# sqlite-graphrag
> Memória persistente para 27 agentes de IA em um único binário Rust de 25 MB
27 agentes de IA. Um binário de 25 MB. Zero chamadas em nuvem. sqlite-graphrag entrega a qualquer assistente de programação IA uma camada de memória local, rápida e privada, baseada em um único arquivo SQLite, sem conta no Pinecone, sem fatura de embeddings da OpenAI, sem cluster Docker para manter. Recall em menos de 50 ms. Recuperação nativa em grafo. Saída JSON determinística pronta para orquestração em pipelines.
- Leia este documento em [inglês (EN)](llms.txt).
## Documentação Principal
### Fontes canônicas em inglês para ingestão por LLMs
- [README](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/README.md): instalação completa, referência de comandos, tabela de integrações e FAQ
- [HOW_TO_USE](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/docs/HOW_TO_USE.md): passo a passo da instalação até o primeiro hybrid search em 60 segundos
- [COOKBOOK](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/docs/COOKBOOK.md): trinta receitas cobrindo ingestão, recuperação, travessia de grafo, backup e auditoria
- [AGENTS](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/docs/AGENTS.md): guia persuasivo para autores de agentes IA: economia, contrato JSON, roteamento por exit codes
- [INTEGRATIONS](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/INTEGRATIONS.md): configuração específica por fornecedor para todos os 27 agentes e IDEs suportados
- [CHANGELOG](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/CHANGELOG.md): histórico completo de versões com notas de migração
- [CONTRIBUTING](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/CONTRIBUTING.md): fluxo de pull request e padrões de código
- [SECURITY](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/SECURITY.md): política de divulgação responsável e canal de contato
- [CODE_OF_CONDUCT](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/CODE_OF_CONDUCT.md): padrões da comunidade
## Comandos Principais
### Subcomandos agrupados por ciclo de vida
- `init` inicializa o banco SQLite e baixa o modelo de embeddings uma única vez
- `remember` salva uma memória com nome, tipo, descrição, corpo e grafo de entidades opcional; use `--max-rss-mb` para limitar o RSS do processo durante embedding (padrão 8192 MiB)
- `recall` realiza busca por similaridade vetorial KNN sobre as memórias armazenadas
- `hybrid-search` funde FTS5 full-text e KNN vetorial via Reciprocal Rank Fusion
- `deep-research` decompõe uma query em até 7 sub-queries, computa embedding separado por sub-query, executa busca híbrida vetorial+FTS paralela fundida via RRF mais travessia de grafo de 3 hops por sub-query, deduplica e monta cadeias de evidência direcionadas; flags: `--k` (padrão 20), `--max-sub-queries` (padrão 7), `--max-hops` (padrão 3), `--min-weight`, `--max-concurrency`, `--timeout`, `--with-bodies`, `--max-results` (padrão 50), `--rrf-k` (padrão 60), `--graph-decay` (padrão 0.7), `--graph-min-score` (padrão 0.05), `--max-neighbors-per-hop`
- `read` `list` `forget` `rename` `edit` `history` `restore` gerenciam o ciclo de vida da memória; `read --id <id>` busca pelo ID numérico da memória como alternativa ao `--name`; `edit --type` muda o tipo da memória
- `remember-batch` ingere múltiplas memórias a partir de um stream NDJSON em uma única invocação
- `completions` gera scripts de autocompletar para bash, zsh, fish, elvish e powershell
- `link` `unlink` `related` gerenciam relacionamentos tipados entre entidades para travessia multi-hop
- `health` `stats` `migrate` `vacuum` `optimize` `sync-safe-copy` gerenciam o banco de dados; `health` reporta `vec_memories_missing` e `vec_memories_orphaned` para diagnósticos do índice vetorial; `health` também reporta `relation_concentration_warning` e detecção de super-hub quando qualquer entidade ou tipo de relação domina o grafo
- `backup` cria backup consistente do banco usando a API SQLite Online Backup, seguro com WAL
- `fts rebuild` `fts check` `fts stats` reparam, verificam e inspecionam o índice FTS5 full-text
- `memory-entities` lista todas as entidades vinculadas a uma memória pelo nome
- `delete-entity` remove uma entidade e opcionalmente propaga a exclusão para seus relacionamentos
- `rename-entity` renomeia uma entidade do grafo preservando todos os relacionamentos baseados em FK e re-gera embedding para busca vetorial
- `reclassify` muda o `entity_type` de uma entidade ou de uma categoria inteira via `--batch`
- `merge-entities` mescla nós de entidade duplicados em um único nó canônico
- `prune-ner` remove vínculos gerados por NER de uma entidade (`--entity`) ou de todas (`--all --yes`)
- `remember --dry-run` faz preview do parsing e extração do grafo sem gravar no banco
- `cleanup-orphans` `prune-relations` removem entidades órfãs e relações fracas ou não utilizadas do grafo
- `purge` `namespace-detect` cuidam de manutenção e resolução de namespace
- `reclassify-relation` renomeia tipos de relacionamento no grafo; modo individual: `--source A --target B --from-relation antigo --to-relation novo`; modo batch: `--from-relation antigo --to-relation novo --batch`; filtros opcionais: `--filter-source-type`, `--filter-target-type`; `--dry-run` faz preview; trata colisões UNIQUE via `UPDATE OR IGNORE` + `DELETE`
- `normalize-entities` normaliza todos os nomes de entidade no namespace para kebab-case ASCII minúsculo; mescla colisões automaticamente (ex.: `Claude Code` e `claude-code` viram um nó com relacionamentos combinados); `--dry-run` faz preview, `--yes` aplica
- `enrich` pipeline de qualidade do grafo aumentada por LLM via `--mode claude-code` ou `--mode codex`; padrão scan-judge-persist com queue DB para resume/retry; 3 operações implementadas: `--operation memory-bindings` (extrai entidades de memórias órfãs), `--operation entity-descriptions` (gera descrições para entidades sem descrição), `--operation body-enrich` (expande corpos curtos de memória); `--dry-run` faz preview sem spawnar LLM; `--max-cost-usd` limita orçamento; `--llm-parallelism <N>` controla subprocessos LLM simultâneos (padrão 1); saída é NDJSON (eventos de fase, eventos por item, resumo)
## Variáveis de Ambiente
### Superfície de configuração em tempo de execução
- `SQLITE_GRAPHRAG_DB_PATH` override explícito para o caminho do banco SQLite
- O comportamento padrão cria ou abre `graphrag.sqlite` no diretório atual
- `SQLITE_GRAPHRAG_CACHE_DIR` diretório para os arquivos de cache do modelo de embeddings
- `SQLITE_GRAPHRAG_LOG_LEVEL` nível de filtro de rastreamento com valores de `error` a `trace`
- `SQLITE_GRAPHRAG_LANG` idioma de saída da CLI com valores `en` ou `pt`
- `SQLITE_GRAPHRAG_NAMESPACE` override de namespace respeitado por todos os comandos (corrigido em v1.0.51)
## Entrada do Grafo
### Contrato mínimo de payload para `remember`
- `--entities-file` espera um array JSON de objetos de entidade
- Cada entidade deve incluir `name` mais `entity_type` ou alias `type`
- Valores válidos de `entity_type`: `project`, `tool`, `person`, `file`, `concept`, `incident`, `decision`, `memory`, `dashboard`, `issue_tracker`, `organization`, `location`, `date`
- `--relationships-file` espera um array JSON de objetos de relacionamento
- Cada relacionamento deve incluir `source`/`from`, `target`/`to`, `relation` e `strength`
- `strength` deve ser float em `[0.0, 1.0]` e é mapeado para `weight` nas saídas do grafo
- Payloads de arquivo usam relações com underscore como `applies_to`, `depends_on` e `tracked_in`; aliases com hífen são normalizados antes da gravação
- As flags CLI de `link` e `unlink` usam relações com hífen como `applies-to`, `depends-on` e `tracked-in`
## Extração NER
### Extração de entidades zero-shot com GLiNER
- Passe `--enable-ner` ou defina `SQLITE_GRAPHRAG_ENABLE_NER=1` para ativar no `remember` e no `ingest`
- Funciona com `--graph-stdin`: passe `"entities": []` no JSON e o GLiNER extrai automaticamente
- Variantes do modelo via `--gliner-variant`: `fp32` (1,1 GB), `fp16` (580 MB), `int8` (349 MB), `q4` (894 MB), `q4f16` (472 MB)
- Sobrescreva o modelo com `SQLITE_GRAPHRAG_GLINER_MODEL`; ajuste o limiar com `SQLITE_GRAPHRAG_GLINER_THRESHOLD` (padrão `0.5`)
- Campo de resposta `extraction_method`: `gliner-<variant>+regex`, `regex-only` ou `none:extraction-failed`
- `--skip-extraction` está depreciado desde v1.0.45; use `--enable-ner` em vez disso
- `--max-rss-mb <MiB>` em `remember` e `ingest` aborta embedding quando o RSS do processo excede o limite (padrão 8192 MiB)
## Modos de Ingestão (v1.0.62)
### Três modos de extração para ingestão em massa
- `--mode none` (padrão): ingestão apenas do body, sem extração de entidades/relações
- `--mode gliner`: extração NER com GLiNER (requer `--enable-ner`, modelo ONNX local)
- `--mode claude-code`: extração curada por LLM via binário Claude Code instalado localmente
- Modo Claude Code spawna `claude -p` headless com `--json-schema` para saída estruturada
- Requer Claude Code >= 2.1.0 instalado na máquina com assinatura Pro/Max ativa
- Resumível via flag `--resume` com queue DB SQLite rastreando progresso por arquivo
- Timeout por arquivo via `--claude-timeout <S>` (padrão 300s); mata processos `claude -p` travados
- Controle de orçamento via `--max-cost-usd <N>` para limitar gasto acumulado
- Rate limit com backoff exponencial automático (60s → 120s → 300s → 900s)
- `--mode codex` spawna `codex exec --json` por arquivo para extração curada por LLM via OpenAI Codex CLI
- Requer Codex CLI instalado localmente; usa `--output-schema` para saída JSON estruturada
- Flags específicas do Codex: `--codex-binary <PATH>`, `--codex-model <MODEL>`, `--codex-timeout <S>` (padrão 300)
- Variável de ambiente `SQLITE_GRAPHRAG_CODEX_BINARY` substitui a busca no PATH
- Rastreamento de uso de tokens via campos `input_tokens` e `output_tokens` (cost_usd não disponível no Codex CLI)
- Pipeline completo de embeddings aplicado às memórias ingeridas via Codex para recall e hybrid-search
Autenticação: OAuth funciona automaticamente em ambos os modos — nenhuma chave de API necessária.
--mode claude-code lê OAuth de ~/.claude/.credentials.json (Claude Pro/Max/Team).
--mode codex lê autenticação de dispositivo via codex auth login (OpenAI).
Chaves de API (ANTHROPIC_API_KEY, OPENAI_API_KEY) ABORTAM o spawn com AppError::Validation. OAuth é o ÚNICO fluxo de credencial aceito.
## Exit Codes
### Status determinístico para roteamento em pipelines
- `0` sucesso: continue o loop do agente
- `1` falha de validação ou runtime: registre e informe o operador
- `2` argumento CLI inválido: corrija o uso e tente novamente
- `9` memória duplicata detectada: ignore ou use `--force-merge`
- `3` conflito de atualização otimista: releia `updated_at` e tente novamente
- `4` memória ou entidade não encontrada: trate o recurso ausente com elegância
- `5` namespace não pôde ser resolvido: passe `--namespace` explicitamente
- `6` payload excedeu os limites configurados: divida o corpo em partes menores
- `10` erro no banco de dados SQLite: execute `health` para inspecionar integridade
- `11` geração de embedding falhou: verifique os arquivos do modelo e tente novamente
- `12` extensão sqlite-vec falhou ao carregar: reinstale com a extensão bundled
- `13` falha parcial em batch: respeite o backoff e tente novamente
- `14` erro de I/O no sistema de arquivos: diretório de cache não gravável, diretório de ingestão inexistente
- `15` banco de dados ocupado após tentativas: aguarde e tente novamente
- `20` erro interno ou de serialização JSON
- `75` EX_TEMPFAIL: todos os slots de concorrência ocupados OU singleton de job travado, tente com backoff
- `77` RAM disponível abaixo do mínimo necessário para carregar o modelo de embeddings
## O Que Mudou na v1.0.68
### Correções críticas (G28 + G29)
- v1.0.68 é o primeiro release desde v1.0.65 que compila no Windows via `cargo install`. v1.0.66 e v1.0.67 quebravam com `error[E0308]` em `src/terminal.rs:29` porque `HANDLE` em `windows-sys >= 0.59` é `*mut c_void` (era `isize` em 0.48/0.52). Correção: `!handle.is_null() && handle != INVALID_HANDLE_VALUE` mais `windows-sys` fixado em `=0.59.0` exato, mais job de CI `windows-build-check`.
- `enrich`, `ingest --mode claude-code` e `ingest --mode codex` agora adquirem um singleton por namespace via `lock::acquire_job_singleton(job_type, namespace, wait_seconds)`. Uma segunda invocação concorrente no mesmo banco retorna `AppError::JobSingletonLocked { job_type, namespace }` (exit 75, retryable) em vez de empilhar 4 × N workers × 10 servidores MCP.
- `claude_runner::build_claude_command` agora respeita `SQLITE_GRAPHRAG_CLAUDE_EMPTY_CONFIG_DIR` (opt-in). Quando definida para um diretório vazio, o subprocesso é iniciado com `CLAUDE_CONFIG_DIR=<esse dir>`, suprimindo servidores MCP do escopo user. Este é o único mecanismo que o Claude Code realmente honra — `--strict-mcp-config` e `--mcp-config '{}'` são silenciosamente ignorados conforme [anthropics/claude-code#10787].
- `enrich` emite `tracing::warn!` quando `--llm-parallelism > 4`, recomendando a combinação com o override `CLAUDE_CONFIG_DIR`.
- Helper `retry::CircuitBreaker` adicionado com `AttemptOutcome::{Success, Transient, HardFailure}`. Erros rate-limited e timeout são explicitamente excluídos da contagem de falhas.
- 3 falhas de teste pré-existentes em `src/commands/{history,list,read}.rs` corrigidas (asserções timezone-agnostic).
## Referências Opcionais
### Materiais complementares para contexto mais profundo
- [Guia CLAUDE](https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/docs/CLAUDE.md): padrões de invocação específicos para Claude Code e estratégias de memória de sessão
- [Definições de SKILL](https://github.com/daniloaguiarbr/sqlite-graphrag/tree/main/skill/sqlite-graphrag-en): skills de slash-command pré-construídas para o harness Claude Code
- [Pacote crates.io](https://crates.io/crates/sqlite-graphrag): binário publicado com semver e metadados de MSRV
- [Referência API docs.rs](https://docs.rs/sqlite-graphrag): rustdoc para consumidores da biblioteca
## Fatos Estáveis
### Identidade e metadados de versão
- Nome do pacote `sqlite-graphrag` publicado no crates.io sob MIT OR Apache-2.0
- Versão atual 1.0.68 com MSRV Rust 1.88 declarado no `Cargo.toml`
- Repositório `https://github.com/daniloaguiarbr/sqlite-graphrag` com CI em push e tag
- Modelo de embeddings `multilingual-e5-small` quantizado via `fastembed` com aproximadamente 750 MB de RAM
- Camada de armazenamento `rusqlite` com SQLite bundled mais extensão `sqlite-vec` e módulo FTS5
- Até quatro instâncias simultâneas suportadas via semáforo de contagem com locks advisory `fs4`