sqlite-graphrag 1.0.91

---
name: sqlite-graphrag
description: Esta skill DEVE ativar para operações da CLI sqlite-graphrag incluindo memória persistente, GraphRAG, grafo de entidades, busca híbrida, recall, remember, ingest, enrich, deep-research, embedding LLM, seleção de backend (codex claude opencode), enforço OAuth-only, validação preflight, FTS5, similaridade cosine BLOB-backed, isolamento de CWD, gestão de namespace, migração, manutenção. Ativa em palavras-chave memória RAG GraphRAG SQLite one-shot OAuth offline persistente grafo entidade embedding codex claude opencode remember recall hybrid-search ingest enrich forget purge link
---


## Quando Esta Skill Ativa
- ATIVE quando o usuário pede para lembrar, salvar, recordar, recuperar, buscar ou persistir algo entre sessões
- ATIVE para contexto de longo prazo, grafo de conhecimento, GraphRAG, RAG, ligação de entidades, gestão de memória
- ATIVE quando sqlite, sqlite-graphrag, embedding, FTS5, hybrid-search ou memória LLM for mencionado
- NUNCA ATIVE para dados efêmeros pontuais, I/O simples de arquivo ou tarefas sem relação a contexto persistente


## Regras de Instrução para LLMs (Prompt Rules)
- QUANDO "lembre disso", "salve isso" → EXECUTE `remember --force-merge` com `--graph-stdin` incluindo entidades curadas e relações canônicas
- QUANDO "o que sabe sobre X", "recall X" → EXECUTE `hybrid-search "X" --k 10 --json` PRIMEIRO, EXPANDA top com `read --name <nome> --json`
- QUANDO "como X se relaciona com Y" → EXECUTE `graph traverse --from X --depth 2 --json` ou `related X --hops 2 --json`
- QUANDO "pesquise profundamente sobre X" → EXECUTE `deep-research "X" --k 20 --max-hops 3 --json`
- ANTES de criar memória → EXECUTE `hybrid-search "<nome>" --k 5 --json` para VERIFICAR duplicatas; se encontrar, USE `--force-merge`
- APÓS criar/atualizar memória → VERIFIQUE com `read --name <nome> --json | jaq '{name, description, body_length}'`
- APÓS CADA turno com achados novos → AVALIE persistência via `remember --force-merge`; se nada novo, DECLARE "Nenhum achado novo"
- QUANDO exit code não-zero → LEIA envelope JSON via `jaq '{code, message, error_class}'`, REPORTE remediação
- QUANDO exit 9 (duplicada) → RETENTE com `--force-merge`
- QUANDO exit 19 (SHUTDOWN) → RETRY OBRIGATÓRIO; trabalho parcial descartado
- QUANDO exit 75 (singleton) → AGUARDE e retente; NUNCA aumente concorrência
- QUANDO exit 16 (preflight) → CORRIJA config MCP; NUNCA bypass com `SKIP_PREFLIGHT`
- SEMPRE parseie saída JSON com `jaq` (NUNCA `jq`)
- SEMPRE passe flag `--json` em toda invocação de `sqlite-graphrag`
- SEMPRE use `--llm-backend codex --llm-model gpt-5.4-mini` OU `--llm-backend claude --llm-model claude-sonnet-4-6` OU `--llm-backend opencode --llm-model opencode/big-pickle` para comandos de embedding
- SEMPRE use APENAS relações canônicas: `applies-to`, `uses`, `depends-on`, `causes`, `fixes`, `contradicts`, `supports`, `follows`, `related`, `mentions`, `replaces`, `tracked-in`
- SEMPRE mapeie não-canônicas: `adds|creates → causes`, `implements → supports`, `blocks → contradicts`, `tested-by → related`, `part-of → applies-to`
- SEMPRE normalize nomes de entidade para kebab-case ASCII lowercase ANTES de passar à CLI
- NUNCA use MCP Serena ou `.md` para persistência; NUNCA escreva MEMORY.md
- NUNCA inicie daemon (REMOVIDO); NUNCA passe `ANTHROPIC_API_KEY` ou `OPENAI_API_KEY`
- PREFIRA `remember --force-merge` sobre `edit`; PREFIRA `--graph-stdin` sobre `--enable-ner`
- LIMITE entidades a conceitos de domínio; REJEITE palavras genéricas, pronomes, UUIDs, timestamps


## Arquitetura e Princípios
- INVOKE sempre como subprocesso; READ stdout para JSON/NDJSON; READ stderr para logs; CHECK exit code ANTES de parsear
- SAIBA que BUILD é LLM-only one-shot; binário NÃO tem daemon, NÃO tem ONNX runtime, NÃO tem cache de modelo
- SAIBA que similaridade COSINE é pure Rust sobre BLOB-backed `memory_embeddings`, `entity_embeddings`, `chunk_embeddings`
- SAIBA que SCHEMA é v15 após `init` ou `migrate` em banco fresco
- ENFORCE OAUTH-ONLY: spawn ABORTA exit 1 se `ANTHROPIC_API_KEY` ou `OPENAI_API_KEY` estiver definida
- SAIBA que `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL` são PRESERVADAS para providers customizados (OpenRouter, Bedrock)
- SAIBA que flags de endurecimento são SEMPRE passadas para subprocessos `claude -p` e `codex exec`
- SAIBA que CWD do subprocesso é ISOLADO via `apply_cwd_isolation`; `CLAUDE_CONFIG_DIR` definido para dir de isolamento; órfãos limpos via `cleanup_isolation_dirs`
- SAIBA que 7 guards preflight rodam ANTES de cada fork LLM: `check_argv_size`, `check_binary_exists`, `check_mcp_config_inline`, `check_mcp_config_path`, `check_walkup_mcp_json`, `check_output_buffer`, `check_claude_config_dir`
- SAIBA que exit 16 (`EX_CONFIG`) é falha preflight universal; LEIA envelope para remediação por variante
- DEFINA `SQLITE_GRAPHRAG_SKIP_PREFLIGHT=1` APENAS em emergências
- ISOLE NAMESPACE por projeto via `--namespace <ns>` ou env; default é `global`
- NUNCA exponha o binário como servidor MCP ou serviço HTTP
- NUNCA escreva arquivo `.sqlite` em paralelo ao binário ou de outra ferramenta
- USE MOCK LLM CLI para CI: prefixe `tests/mock-llm` ao PATH


## Seleção de Backend LLM
- PASSE `--llm-backend codex` para spawnar Codex CLI headless (backend DEFAULT)
- PASSE `--llm-backend claude` para spawnar Claude Code headless via `embed_via_claude_local` (zero-token, compatível com OAuth)
- PASSE `--llm-backend opencode` para spawnar OpenCode CLI headless (sistema de auth próprio, NÃO OAuth)
- PASSE `--llm-backend codex,claude` para codex-primeiro com fallback claude
- PASSE `--llm-backend codex,claude,opencode,none` para cadeia completa de fallback com embedding null como último recurso
- PASSE `--llm-model <MODEL>` para selecionar modelo de embedding para o backend ativo
- SAIBA modelos DEFAULT: codex=`gpt-5.5`, claude=`claude-sonnet-4-6`, opencode=`opencode/big-pickle`
- PASSE `--llm-fallback-mode <claude|codex|opencode>` para trocar backend mid-job em rate-limit
- PASSE `--skip-embedding-on-failure` APENAS quando `--llm-backend …,none` está ativo
- PASSE `--dry-run-backend` para planejar operação de backend sem executar (preview idempotente)
- PARSEE campo `backend_invoked` em todo envelope de embedding para CONFIRMAR qual backend rodou
- PASSE `--codex-binary <PATH>`, `--claude-binary <PATH>`, `--opencode-binary <PATH>` para sobrescrever localização dos binários
- PASSE `--opencode-model <MODEL>` e `--opencode-timeout <SECONDS>` para ajustes específicos do opencode
- PASSE `--mode codex|claude-code|opencode` para pipelines de extração em ingest e enrich
- SAIBA que output NDJSON do opencode tem 3 tipos de evento: `step_start`, `text`, `step_finish`
- SAIBA modelos gratuitos opencode: `opencode/big-pickle`, `opencode/deepseek-v4-flash-free`, `opencode/mimo-v2.5-free`, `opencode/nemotron-3-ultra-free`, `opencode/north-mini-code-free`
- EXECUTE `codex login` para refrescar OAuth do codex; refresque OAuth do claude quando stale
- NUNCA passe API keys com qualquer backend; spawn ABORTA exit 1


## Referência de Flags Globais
- `--db <PATH>` — sobrescrever localização do banco (NÃO é global; cada subcomando aceita independentemente)
- `--namespace <ns>` — escopar operações para um namespace
- `--lang en|pt` — forçar idioma do stderr
- `--tz <TIMEZONE>` — localizar timestamps
- `--json` — saída JSON estruturada (SEMPRE passe)
- `--low-memory` — paralelismo unitário para containers restritos
- `--max-concurrency N` — cap de invocações CLI pesadas concorrentes
- `--wait-lock SECS` — ampliar janela de aquisição de lock
- `--llm-parallelism N` — cap de fan-out de subprocessos de embedding (default 4, clamp [1, 32])
- `--llm-backend <chain>` — seleção de backend com fallback separado por vírgula
- `--llm-model <MODEL>` — modelo de embedding para backend ativo
- `--dry-run-backend` — planejar operação de backend sem executar
- `--llm-fallback-mode <backend>` — trocar backend mid-job em rate-limit
- `--llm-fallback <chain>` — cadeia de fallback comma-separated tentada quando primário falha (default `codex,claude,none`)
- `--llm-slot-no-wait` — falhar imediatamente exit 75 quando nenhum slot LLM livre (em vez de esperar)
- `--embedding-dim N` — override de dimensionalidade de embedding [8, 4096] (default 64 MRL)
- `--graceful-shutdown-secs N` — orçamento de cleanup antes de SIGKILL
- `--skip-embedding-on-failure` — exit 0 em falha de embedding (APENAS com fallback terminando em `none`)
- `--strict-env-clear` — preservar apenas `PATH` em subprocesso para compliance
- `--codex-binary`, `--claude-binary`, `--opencode-binary` — sobrescrever paths dos binários
- `--opencode-model`, `--opencode-timeout` — overrides específicos do opencode
- `-v`/`-vv`/`-vvv` — logging info/debug/trace no stderr


## CRUD Escrita (remember, remember-batch, ingest)
- INVOKE `remember --name <kebab> --type <kind> --description <text>` com `--body <text>` ou `--body-file <path>` ou `--body-stdin`
- INVOKE `remember --graph-stdin` para anexar `{body, entities, relationships}` em único JSON
- PASSE entities como `[{name, entity_type}]` em kebab-case ASCII
- PASSE relationships como `[{source, target, relation, strength}]` onde `strength em [0.0, 1.0]`
- PASSE `--force-merge` para updates idempotentes e restauração de soft-deleted
- PASSE `--clear-body` para limpar corpo durante update com `--force-merge`
- PASSE `--dry-run` para validar inputs sem persistir
- PASSE `--max-rss-mb <MiB>` para abortar quando RSS exceder threshold (default 8192)
- RESPEITE limite de 512000 bytes e 512 chunks por corpo
- VALORES válidos de `--type`: `user`, `feedback`, `project`, `reference`, `decision`, `incident`, `skill`, `document`, `note`
- USE `--enable-ner` para extração de entidades URL-regex (APENAS URL-regex desde remoção do NER)
- INVOKE `remember-batch` para 10+ memórias via NDJSON stdin; ESPERE status por item e linha de sumário
- INVOKE `ingest <DIR> --recursive --pattern "*.md"` para importar diretório
- PASSE `--type <kind>` para aplicar mesmo tipo a todos arquivos ingeridos
- PASSE `--mode codex|claude-code|opencode` para extração de entidades curada por LLM
- USE `--auto-describe` (default true) para extrair descrição da primeira linha do corpo; opt out via `--no-auto-describe`
- USE `--resume` para continuar da fila após interrupção; `--retry-failed` para apenas falhados
- USE `--fail-fast` para parar na primeira falha por arquivo
- USE `--max-name-length N` para sobrescrever truncamento padrão de nomes em 60 chars
- USE `--llm-parallelism N` em `ingest` (default 2); `--ingest-parallelism N` para paralelismo per-file
- PASSE `--claude-model <MODEL>` e `--claude-timeout <secs>` (default 300) para `--mode claude-code`
- PASSE `--codex-model <MODEL>` e `--codex-timeout <secs>` (default 300) para `--mode codex`
- PASSE `--rate-limit-wait <secs>` (default 60) para espera inicial em rate-limit com `--mode claude-code`
- PASSE `--queue-db <path>` para BD de fila customizado; `--keep-queue` para preservar após conclusão
- PASSE `--low-memory` em `ingest` para modo single-threaded (3-4x mais lento, <4 GB RAM)
- PASSE `--dry-run` em `ingest` para preview de mapeamento arquivo-para-nome sem persistir
- RESPEITE cap `--max-files 10000` como validação all-or-nothing
- NUNCA misture `--body`, `--body-file`, `--body-stdin`, `--graph-stdin` em única invocação
- NUNCA passe corpo vazio sem entities via `--graph-stdin`
- NUNCA use `fd | xargs remember`; INVOKE `ingest` em vez disso
- NUNCA use `--force-merge` em `ingest` (exclusivo de `remember`)


## CRUD Leitura, Atualização, Deleção
- INVOKE `read --name <kebab> --json` para fetch O(1); `read --id <N>` por memory_id; `--with-graph` para entidades vinculadas
- INVOKE `list --type <kind> --limit N --offset N --json`; `--include-deleted` para soft-deleted
- INVOKE `history --name <n> --diff --json` para versões com diff de caracteres
- INVOKE `edit --name <n> --body-file <path>` para atualizar corpo (re-embeda); `--description` para só descrição; `--force-reembed` sem mudar corpo
- USE `--expected-updated-at <ts>` para optimistic locking; TRATE exit 3 como conflito
- INVOKE `rename --from <old> --to <new>`; `restore --name <n> --version <N>`; `forget --name <n>` (soft-delete, exit 4 se ausente)
- INVOKE `purge --retention-days <N> --yes --dry-run` para preview; `unlink --from <a> --to <b> --relation <type>`; `--entity <name> --all` para massa
- INVOKE `prune-relations --relation <type> --yes --show-entities --dry-run`; `cleanup-orphans --yes` após bulk forget; `vacuum --json`
- NUNCA pule optimistic locking; NUNCA delete via shell `sqlite3`


## Operações de Grafo de Entidades
- INVOKE `link --from <a> --to <b> --relation <type> --create-missing --weight <float>` para criar aresta
- PASSE `--entity-type <kind>` para entidades auto-criadas (default `concept`)
- PASSE `--max-entity-degree N` para avisar quando entidade exceder N conexões
- USE `--strict-relations` para falhar em tipos de relação não-canônicos
- INVOKE `graph entities --json` para listar entidades; ACESSE via `.entities[]` (NÃO `.items[]`)
- ORDENE via `--sort-by degree|name|created_at`; PAGINE via `--limit N --offset N`
- INVOKE `graph stats --json` para inspecionar `node_count`, `edge_count`, `avg_degree`, `max_degree`
- SAIBA que grau de entidade é calculado via query COUNT precisa (`recalculate_degree`)
- INVOKE `graph traverse --from <root> --depth <N> --json` para travessia de subgrafo
- USE `--format json|dot|mermaid` com `--output <path>` para exportar grafo
- INVOKE `memory-entities --name <memory>` para lookup forward; `--entity <name>` para reverso
- INVOKE `rename-entity`, `delete-entity --cascade`, `merge-entities --names "a,b,c" --into <target>`
- INVOKE `reclassify --name <n> --new-type <kind>` ou `--from-type <old> --to-type <new> --batch`
- INVOKE `reclassify-relation --from-relation <old> --to-relation <new> --batch` para migração em massa de tipos de relação
- INVOKE `normalize-entities --yes` para normalizar todos nomes para kebab-case ASCII
- INVOKE `prune-ner --entity <n>` para remover bindings NER; `prune-ner --all --yes` para todos no namespace
- VALIDE nomes de entidade: mínimo 2 chars, sem newlines, sem ALL_CAPS curtos (4 chars ou menos REJEITADOS)
- RELAÇÕES canônicas: `applies-to`, `uses`, `depends-on`, `causes`, `fixes`, `contradicts`, `supports`, `follows`, `related`, `mentions`, `replaces`, `tracked-in`
- TIPOS canônicos de entidade: `project`, `tool`, `person`, `file`, `concept`, `incident`, `decision`, `memory`, `dashboard`, `issue_tracker`, `organization`, `location`, `date`
- NUNCA use `mentions` como relação padrão


## Busca GraphRAG (recall, hybrid-search, related, deep-research, enrich)
- USE padrão canônico de três camadas: `hybrid-search` depois `read --name` depois `related|graph traverse`
- INVOKE `recall <query> --k N` para busca semântica pura KNN; PASSE `--no-graph` para desabilitar expansão de grafo
- INTERPRETE `distance` crescente como similaridade decrescente; `score` = `1.0 - distance` clamped [0.0, 1.0]
- INVOKE `hybrid-search <query> --k N` para fusão FTS5+KNN via RRF
- PASSE `--rrf-k 60` para fusão padrão; `--weight-vec 1.0 --weight-fts 1.0` para balanceada
- PASSE `--type <kind>` para filtrar resultados por tipo de memória
- PASSE `--fallback-fts-only` para pular embedding ao vivo e servir apenas FTS5 BM25 (modo offline)
- USE `--with-graph --max-hops 2 --min-weight 0.3` para expansão de grafo; LEIA TANTO `results[]` QUANTO `graph_matches[]`
- INVOKE `related <name> --hops N` para travessia multi-hop a partir de memória
- INVOKE `deep-research "<query>" --k 20 --max-hops 3 --max-sub-queries 7 --max-results 50` para pesquisa paralela multi-hop
- PASSE `--graph-decay <float>` (default 0.7) para decaimento de score por hop; `--graph-min-score <float>` (default 0.05) para threshold mínimo
- PASSE `--max-neighbors-per-hop N` para limitar vizinhos por entidade por hop
- PASSE `--timeout <secs>` (default 30) para timeout por sub-query
- PASSE `--with-bodies` para incluir corpos completos de memórias nos resultados
- INVOKE `enrich --operation <op>` para qualidade de grafo via LLM: `memory-bindings`, `entity-descriptions`, `body-enrich`, `re-embed --limit N --resume`
- PASSE `--llm-parallelism N` para controlar subprocessos LLM concorrentes
- PASSE `--max-cost-usd N` para limitar custo acumulado de LLM (ignorado para usuários OAuth)
- USE `--dry-run` para preview sem spawnar LLM
- PARSEE top campos: `recall` retorna `results[].{name, snippet, distance, score, source}`; `hybrid-search` retorna `results[].{name, combined_score, vec_rank, fts_rank}`
- PARSEE `deep-research` retorna `sub_queries[]`, `results[]`, `evidence_chains[]`, `graph_context`, `stats`
- NUNCA confunda `distance` com `combined_score` em ranking
- NUNCA aumente `--hops` sem inspecionar `graph stats` antes


## Códigos de Saída e Estratégia de Retry
- EXIT 0: sucesso; EXIT 1: erro de validação; EXIT 2: parsing de argumento; EXIT 3: conflito de lock otimista (recarregue e retente)
- EXIT 4: não encontrado; EXIT 5: erro de namespace; EXIT 6: payload grande demais; EXIT 9: duplicada (use `--force-merge`)
- EXIT 10: erro de banco (execute `vacuum` + `health`); EXIT 11: falha de embedding (verifique backend + OAuth)
- EXIT 13: falha parcial de batch (reprocesse apenas falhados); EXIT 14: erro de I/O; EXIT 15: banco ocupado (amplie `--wait-lock`)
- EXIT 16: falha preflight (corrija config MCP, NUNCA trate como transitório)
- EXIT 19: SHUTDOWN (RETRY OBRIGATÓRIO, trabalho parcial descartado); PARSEE envelope `{error, code, signal, graceful, message}`
- EXIT 20: erro interno; EXIT 75: slots esgotados ou job singleton locked (respeite cooldown, NUNCA retente imediatamente)
- EXIT 77: pressão de RAM (aguarde memória livre)
- NUNCA ignore exit não-zero; NUNCA reprocesse batch inteiro após exit 13; NUNCA confunda exit 1 com exit 9


## Concorrência e Paralelismo
- RESPEITE teto rígido `2 x nCPUs` para comandos pesados: `init`, `remember`, `ingest`, `recall`, `hybrid-search`
- DEFINA `--llm-parallelism N` default 4 em `remember`/`edit`, default 2 em `ingest` (clamp [1, 32])
- USE `--llm-max-host-concurrency N` para cap de subprocessos LLM cross-process
- USE `--llm-slot-wait-secs N` para esperar slot ou `--llm-slot-no-wait` para abortar
- SAIBA que JOB SINGLETON: `enrich`, `ingest --mode claude-code|codex|opencode` adquirem singleton por namespace
- USE `--wait-job-singleton SECS` ou `--force-job-singleton` para quebrar lock stale
- ATIVE `SQLITE_GRAPHRAG_LOW_MEMORY=1` para paralelismo unitário (3-4x mais lento)
- NUNCA rode `enrich` em paralelo contra mesmo banco


## Pipeline de Manutenção e Subcomandos de Diagnóstico
- EXECUTE `sqlite-graphrag init --namespace <ns>` no primeiro uso
- EXECUTE `health --json` para verificar `integrity_ok`, `schema_ok`, `schema_version >= 15`
- EXECUTE `migrate --dry-run --json` para preview; depois `migrate --json` após upgrade do binário
- EXECUTE `optimize --json` para refrescar estatísticas do planner; inclui `fts_rebuilt`
- EXECUTE `fts rebuild --json` quando `health.fts_degraded` for true; `fts check --json` para integridade; `fts stats --json` para contagens
- INVOKE `backup --output <path> --json` para backup online; `sync-safe-copy --dest <path>` para snapshot atômico
- INVOKE `export --namespace <ns> --type <kind> --json` para exportar como NDJSON
- INVOKE `vacuum --json` após purge grande; INSPECIONE `wal_size_mb` em health para fragmentação
- INVOKE `vec orphan-list --json` depois `vec purge-orphan --yes` para limpar vetores órfãos; `vec stats --json` para saúde
- INVOKE `debug-schema --json` para troubleshooting de drift de schema
- INVOKE `completions <bash|zsh|fish|elvish|powershell>` para completions de shell
- INVOKE `codex-models --json` para inspecionar whitelist de modelos codex
- INVOKE `stats --json` para estatísticas do banco (contagens, tamanhos, breakdown por namespace)
- INVOKE `namespace-detect --json` para resolver precedência de namespace da invocação atual
- INVOKE `cache list --json` para listar arquivos de modelo em cache; `cache clear-models --yes` para forçar re-download
- INVOKE `pending list --filter-status queued --json` para fila de checkpoint; `pending show <id>`; `pending cleanup --yes`
- INVOKE `pending-embeddings list --json` para fila de retry; `pending-embeddings process --json` para reprocessar
- INVOKE `slots status --json` para semáforo host-wide; `slots release --slot-id <N> --yes` para órfãos
- INVOKE `embedding status --json` para contagens; `embedding list --json` para inspeção por entrada
- AGENDE semanal: `purge` depois `cleanup-orphans` depois `prune-relations --relation mentions` depois `vacuum` depois `optimize` depois `sync-safe-copy`
- SAIBA que toda escrita executa `PRAGMA wal_checkpoint(TRUNCATE)` após commit
- SE corrupção: `sqlite3 broken.sqlite ".recover" | sqlite3 repaired.sqlite`


## Referência de Variáveis de Ambiente
- `SQLITE_GRAPHRAG_DB_PATH` — path persistente do banco
- `SQLITE_GRAPHRAG_NAMESPACE` — namespace persistente
- `SQLITE_GRAPHRAG_LLM_BACKEND` — backend persistente (codex|claude|opencode|none|auto)
- `SQLITE_GRAPHRAG_LLM_MODEL` — override persistente de modelo
- `SQLITE_GRAPHRAG_CODEX_BINARY` / `SQLITE_GRAPHRAG_CODEX_EMBED_MODEL` — binário e modelo de embed codex
- `SQLITE_GRAPHRAG_CLAUDE_BINARY` — override de path do binário claude
- `SQLITE_GRAPHRAG_OPENCODE_BINARY` / `SQLITE_GRAPHRAG_OPENCODE_MODEL` / `SQLITE_GRAPHRAG_OPENCODE_EMBED_MODEL` / `SQLITE_GRAPHRAG_OPENCODE_TIMEOUT` — overrides opencode
- `SQLITE_GRAPHRAG_EMBEDDING_DIM` — dimensão de embedding [8, 4096] (default 64 MRL)
- `SQLITE_GRAPHRAG_LOW_MEMORY` — habilitar paralelismo unitário
- `SQLITE_GRAPHRAG_STRICT_ENV_CLEAR` — modo compliance
- `SQLITE_GRAPHRAG_DISPLAY_TZ` — timezone persistente
- `SQLITE_GRAPHRAG_LOG_FORMAT` — `json` para agregadores de log
- `SQLITE_GRAPHRAG_SKIP_PREFLIGHT` — bypass preflight (APENAS EMERGÊNCIAS)
- `SQLITE_GRAPHRAG_IGNORE_SHUTDOWN` — APENAS para harnesses de teste CI


## Fórmulas CLI Prontas para Uso
- INIT namespace: `sqlite-graphrag init --namespace <ns>`
- VERIFICAR saúde: `sqlite-graphrag health --namespace <ns> --json | jaq '{integrity_ok, schema_version}'`
- MIGRATE preview: `sqlite-graphrag migrate --dry-run --json`
- MIGRATE aplicar: `sqlite-graphrag migrate --json`
- REMEMBER codex todas flags: `sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini --codex-binary <path> --llm-parallelism 4 remember --name <n> --type decision --description "desc" --body-file doc.md --force-merge --max-rss-mb 4096 --json`
- REMEMBER claude todas flags: `sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 --claude-binary <path> --llm-parallelism 4 remember --name <n> --type decision --description "desc" --body "conteudo" --force-merge --json`
- REMEMBER opencode todas flags: `sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle --opencode-binary <path> --opencode-timeout 300 --llm-parallelism 4 remember --name <n> --type note --description "desc" --body-stdin --json`
- REMEMBER graph-stdin: pipe JSON `{body, entities, relationships}` para `sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini remember --name <n> --type decision --description "desc" --graph-stdin --force-merge --json`
- REMEMBER-BATCH: pipe NDJSON para `sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini remember-batch --json`
- DRY-RUN backend: `sqlite-graphrag --llm-backend codex --dry-run-backend recall "query" --k 5 --json`
- RECALL codex: `sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini recall "query" --k 5 --no-graph --json`
- RECALL claude: `sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 recall "query" --k 5 --json`
- RECALL opencode: `sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle recall "query" --k 5 --json`
- HYBRID-SEARCH codex todas flags: `sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini hybrid-search "query" --k 10 --with-graph --max-hops 2 --min-weight 0.3 --rrf-k 60 --weight-vec 1.0 --weight-fts 1.0 --type decision --json`
- HYBRID-SEARCH claude: `sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 hybrid-search "query" --k 10 --json`
- HYBRID-SEARCH opencode: `sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle hybrid-search "query" --k 10 --with-graph --json`
- HYBRID-SEARCH fts-only: `sqlite-graphrag hybrid-search "query" --k 10 --fallback-fts-only --json`
- DEEP-RESEARCH todas flags: `sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 deep-research "pergunta" --k 20 --max-hops 3 --max-sub-queries 7 --max-results 50 --with-bodies --graph-decay 0.7 --graph-min-score 0.05 --timeout 30 --max-neighbors-per-hop 10 --json`
- RELATED: `sqlite-graphrag related <nome> --hops 2 --relation uses --json`
- INGEST codex todas flags: `sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini ingest ./docs --mode codex --recursive --pattern "*.md" --type document --auto-describe --resume --max-files 1000 --max-name-length 80 --llm-parallelism 2 --codex-model gpt-5.4-mini --codex-timeout 300 --fail-fast --low-memory --json`
- INGEST claude todas flags: `sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 ingest ./docs --mode claude-code --recursive --pattern "*.md" --type document --auto-describe --resume --claude-model claude-sonnet-4-6 --claude-timeout 600 --rate-limit-wait 60 --max-cost-usd 5 --queue-db .ingest-queue.sqlite --keep-queue --json`
- INGEST opencode todas flags: `sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle ingest ./docs --mode opencode --recursive --pattern "*.md" --type document --auto-describe --opencode-model opencode/big-pickle --opencode-timeout 600 --json`
- INGEST dry-run: `sqlite-graphrag ingest ./docs --dry-run --pattern "*.md" --recursive --json`
- ENRICH re-embed codex: `sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini enrich --operation re-embed --limit 100 --resume --llm-parallelism 4 --json`
- ENRICH memory-bindings claude: `sqlite-graphrag --llm-backend claude --llm-model claude-sonnet-4-6 enrich --operation memory-bindings --mode claude-code --max-cost-usd 5 --json`
- ENRICH opencode: `sqlite-graphrag --llm-backend opencode --llm-model opencode/big-pickle enrich --operation entity-descriptions --mode opencode --dry-run --json`
- READ com grafo: `sqlite-graphrag read --name <n> --with-graph --json`
- READ por id: `sqlite-graphrag read --id 42 --json`
- LIST: `sqlite-graphrag list --type decision --limit 50 --offset 0 --include-deleted --json`
- HISTORY: `sqlite-graphrag history --name <n> --diff --json`
- EDIT corpo codex: `sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini edit --name <n> --body-file novo.md --expected-updated-at "2026-01-01T00:00:00Z" --json`
- EDIT descrição: `sqlite-graphrag edit --name <n> --description "nova desc" --json`
- EDIT force-reembed: `sqlite-graphrag --llm-backend codex --llm-model gpt-5.4-mini edit --name <n> --force-reembed --json`
- RENAME: `sqlite-graphrag rename --from <antigo> --to <novo> --json`
- RESTORE: `sqlite-graphrag restore --name <n> --version 2 --json`
- FORGET: `sqlite-graphrag forget --name <n> --json`
- PURGE preview: `sqlite-graphrag purge --retention-days 30 --yes --dry-run --json`
- LINK todas flags: `sqlite-graphrag link --from <a> --to <b> --relation uses --weight 0.8 --create-missing --entity-type tool --strict-relations --max-entity-degree 50 --json`
- UNLINK: `sqlite-graphrag unlink --from <a> --to <b> --relation uses --json`
- UNLINK massa: `sqlite-graphrag unlink --entity <nome> --all --json`
- GRAPH stats: `sqlite-graphrag graph stats --json | jaq '{node_count, edge_count, avg_degree}'`
- GRAPH entities: `sqlite-graphrag graph entities --sort-by degree --order desc --limit 20 --json`
- GRAPH traverse: `sqlite-graphrag graph traverse --from <entidade> --depth 2 --json`
- GRAPH exportar: `sqlite-graphrag graph --format <json|dot|mermaid> --output <path>`
- MERGE entidades: `sqlite-graphrag merge-entities --names "a,b,c" --into alvo --json`
- NORMALIZE entidades: `sqlite-graphrag normalize-entities --yes --json`
- RECLASSIFY entidade: `sqlite-graphrag reclassify --name <n> --new-type concept --json`
- RECLASSIFY massa: `sqlite-graphrag reclassify --from-type tool --to-type concept --batch --json`
- RECLASSIFY-RELATION: `sqlite-graphrag reclassify-relation --from-relation <antiga> --to-relation <nova> --batch --json`
- PRUNE-NER: `sqlite-graphrag prune-ner --entity <n>` ou `prune-ner --all --yes`
- PRUNE-RELATIONS preview: `sqlite-graphrag prune-relations --relation mentions --yes --show-entities --dry-run`
- CLEANUP pipeline: INVOKE `forget --name <n>` depois `cleanup-orphans --yes --json` depois `vacuum --json`
- PENDING lista: `sqlite-graphrag pending list --filter-status queued --json`
- PENDING-EMBEDDINGS: `sqlite-graphrag pending-embeddings list --json` depois `pending-embeddings process --json`
- SLOTS: `sqlite-graphrag slots status --json` e `slots release --slot-id <N> --yes --json`
- EMBEDDING status: `sqlite-graphrag embedding status --json` e `embedding list --json`
- FTS: `sqlite-graphrag fts rebuild --json` e `fts check --json` e `fts stats --json`
- VEC: `sqlite-graphrag vec stats --json` e `vec orphan-list --json` depois `vec purge-orphan --yes --json`
- BACKUP: `sqlite-graphrag backup --output backup.sqlite --json`
- SYNC-SAFE-COPY: `sqlite-graphrag sync-safe-copy --dest snapshot.sqlite`
- EXPORT: `sqlite-graphrag export --namespace <ns> --type decision --json`
- OPTIMIZE: `sqlite-graphrag optimize --json`
- VACUUM: `sqlite-graphrag vacuum --json`
- DEBUG-SCHEMA: `sqlite-graphrag debug-schema --json`
- CODEX-MODELS: `sqlite-graphrag codex-models --json`
- COMPLETIONS: `sqlite-graphrag completions <bash|zsh|fish|elvish|powershell>`
- STATS: `sqlite-graphrag stats --json`
- NAMESPACE-DETECT: `sqlite-graphrag namespace-detect --json`
- CACHE listar: `sqlite-graphrag cache list --json`
- CACHE limpar: `sqlite-graphrag cache clear-models --yes`
- FALLBACK CHAIN: `sqlite-graphrag --llm-backend codex --llm-fallback codex,claude,opencode,none --skip-embedding-on-failure remember --name <n> --type note --description "desc" --body-file nota.md --json`
- Manutenção semanal: INVOKE `purge --retention-days 90 --yes` depois `cleanup-orphans --yes` depois `prune-relations --relation mentions --yes` depois `vacuum` depois `optimize` depois `sync-safe-copy --dest backup.sqlite`
- Roteamento de exit code: ROTEAR `$?` — 0 sucesso, 9 use `--force-merge`, 11 verifique backend OAuth, 16 corrija preflight MCP, 19 RETRY OBRIGATÓRIO, 75 aguarde cooldown


## Regras Ativas
- SEMPRE passe `--llm-backend` e `--llm-model` em comandos de embedding
- SEMPRE parsee `backend_invoked` para confirmar qual backend rodou
- SEMPRE execute `codex login` ou refresque OAuth do claude quando stale
- NUNCA passe API keys (OAuth-only, exit 1); NUNCA use daemon, `--bare`, `--gliner-variant` (REMOVIDOS)
- NUNCA instale com `--features embedding-legacy` ou `--features ner-legacy`
- NUNCA rode `enrich` em paralelo contra mesmo banco; NUNCA escreva `.sqlite` fora do binário
- NUNCA ignore exit 19 (RETRY OBRIGATÓRIO) ou exit 16 (corrija config MCP)
- NUNCA chame `migrate --to-llm-only` sem guarda `--drop-vec-tables`