knowledge-rag

knowledge-rag

pip install knowledge-rag   →   restart Claude Code   →   search_knowledge("your query")

⭐ Star History

_{Gráfico atualizado diariamente por GitHub Action}

🎯 Por que knowledge-rag

A maioria dos frameworks de RAG cai em uma de três armadilhas: (1) exigem que você envie seus dados para uma API em nuvem, (2) entregam 300 blocos de construção e zero padrões opinativos, ou (3) empacotam RAG como um recurso de 5% de uma plataforma muito maior que você não pediu.

knowledge-rag faz uma coisa bem: é o servidor RAG local nativo de MCP que Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini CLI e Zed podem pesquisar de pronta entrega — com infraestrutura empresarial (autenticação bearer, métricas Prometheus, limitação de taxa, health probes, log JSON estruturado, reindexação sem downtime) que nenhum outro OSS focado em RAG inclui nativamente.

📊 Como knowledge-rag se compara a outros frameworks de RAG

Auditamos 16 frameworks e plataformas populares de RAG (LlamaIndex, LangChain, ChromaDB, Weaviate, Qdrant, RAGFlow, LightRAG, DSPy, GraphRAG, Haystack, RAG-Anything, kotaemon, txtai, llmware, Dify, open-webui, FastGPT) para que você possa escolher com honestidade.

Legenda: ✅ integrado · 🟡 plugin / camada paga / parcial · ❌ indisponível · ⚠️ preocupação com licença ou padrão

As 5 dimensões em que knowledge-rag é único: health probes + log JSON + Prometheus + limitação de taxa + autenticação bearer simultaneamente integrados em um servidor MCP OSS focado em RAG. Reindexação sem downtime + reindexação assíncrona em segundo plano + chaos/soak/mutation noturnos estão documentados no README de nenhum outro projeto.

🚀 Quick Start (3 minutos, do zero à sua primeira consulta)

Escolha seu caminho de integração — knowledge-rag entrega o mesmo servidor em todos os canais.

Caminho 1 — Claude Code, Cursor, Windsurf, Cline, VS Code, Gemini CLI, Zed (MCP)

pip install knowledge-rag
knowledge-rag init                    # scaffolds config.yaml + documents/

Coloque seus PDFs, markdown e arquivos de código em documents/. Reinicie seu cliente MCP. Pergunte a ele:

search_knowledge("your query")

Pronto. A primeira consulta carrega o modelo de embedding ONNX (~200MB, download único). Consultas subsequentes são armazenadas em cache e atingem latência abaixo de 1 segundo.

Caminho 2 — Servidor HTTP / SSE (multi-usuário, air-gapped, com balanceamento de carga)

# config.yaml
server:
  transport: "sse"                    # or "streamable-http"
  host: "0.0.0.0"
  port: 8179
  auth:
    bearer_token: "your-secret-token"
  rate_limit:
    enabled: true
    requests_per_minute: 60
  metrics:
    enabled: true
    port: 9179
  logging:
    format: "json"                    # ELK / Loki / Datadog / CloudWatch ready

knowledge-rag --transport sse

• Health probe: curl http://your-host:8179/health → 200 + payload JSON
• Coleta Prometheus: http://your-host:9179/metrics
• Dispatcher MCP: autenticado via Authorization: Bearer your-secret-token

Caminho 3 — Docker (modelos pré-baixados, pronto para air-gapped)

docker pull ghcr.io/lyonzin/knowledge-rag:latest
docker run -v $(pwd)/documents:/app/documents -p 8179:8179 ghcr.io/lyonzin/knowledge-rag:latest

Guia completo de instalação com todos os 5 métodos, 8 configurações de clientes MCP e setup de GPU: docs/INSTALLATION.md →

🤖 Habilidades prontas para agentes de IA

Instalar o knowledge-rag dá ao seu agente 13 ferramentas MCP. Mas não diz ao agente quando usá-las. É isso que a pasta skills/ resolve — habilidades comportamentais prontas para Claude Code, Cursor, Windsurf, Cline, Zed, VS Code Copilot que transformam "IA com acesso a RAG" em "IA que realmente usa RAG primeiro".

10 habilidades, licença MIT, organizadas por tipo:

Instalação — escolha o caminho mais curto para sua máquina:

# Option 1 — Via skills.sh (needs Node — one command, zero clone)
npx skills add lyonzin/knowledge-rag

# Option 2 — Via our install.sh (no Node needed; works on Linux/macOS/WSL/Git Bash)
curl -fsSL https://raw.githubusercontent.com/lyonzin/knowledge-rag/master/skills/install.sh | bash

Ambos reiniciam o Claude Code e você está pronto. A opção 2 suporta --project, --only rag-check-first,rag-cite-sources, --dry-run, --help.

Para Cursor, Windsurf, Cline e instruções manuais completas → skills/README.md · Catálogo completo com cadeias de habilidades → skills/CATALOG.md

🛠️ As 13 ferramentas MCP que seu agente recebe

Depois de instalado, seu agente de IA recebe automaticamente estas 13 ferramentas:

Referência completa da API com detalhes de parâmetros, schemas de retorno e exemplos: docs/API.md →

🏢 Recursos Empresariais (integrados, zero configuração)

Todo framework de RAG afirma ser "pronto para produção." Aqui está o que knowledge-rag entrega no núcleo OSS, verificado por testes de regressão, que concorrentes ou colocam atrás de paywall, ou viram plugin, ou simplesmente não têm.

💼 Casos de Uso (corpora reais, equipes reais)

Equipes de Segurança — Red / Blue / CTF

Predefinição: cybersecurity.yaml · 8 categorias · 200+ palavras-chave de roteamento · 69 expansões de consulta

Ingerir MITRE ATT&CK, relatórios de ameaças, writeups de exploits, relatórios de incidentes. Pesquise a partir do Claude Code com search_knowledge("privilege escalation windows") e obtenha recall instantâneo em todo o seu corpus. Isolado (air-gapped) — nada sai do laptop.

Equipes de Desenvolvimento — Documentos de Design, Runbooks, Código

Predefinição: developer.yaml · 9 categorias · 150+ palavras-chave de roteamento · 50+ expansões

Substitua a busca no Confluence. Ingerir documentos de arquitetura, ADRs, runbooks, código, especificações de API. Devs perguntam ao seu agente de IA "como autenticamos o serviço de pagamento" e obtêm o ADR exato + citação do arquivo de implementação.

Laboratórios de Pesquisa — Artigos, Notebooks, Datasets

Predefinição: research.yaml · 9 categorias · 100+ palavras-chave de roteamento · 40+ expansões

Indexe artigos do arXiv, notebooks de laboratório, documentação de datasets. A busca semântica encontra artigos por intenção, não apenas por palavras-chave — o reranking com cross-encoder traz o realmente relevante em vez de cinco que compartilham um termo.

Base de Conhecimento Empresarial — Isolada, Auditável

Predefinição: general.yaml · tela em branco, busca semântica pura

Implante via SSE em uma única VM. 40+ usuários autenticados via token bearer, com limite de taxa, monitorados por Prometheus, sondas /health conectadas ao seu balanceador de carga, logs JSON enviados ao Datadog. Sem chamadas em nuvem. Atende aos requisitos de localidade de dados da LGPD, GDPR e HIPAA por design.

Verificado em escala: reprodução em produção em um corpus de 5 889 documentos / 75 016 chunks com consultas concorrentes durante uma reconstrução nuclear — zero downtime, zero erros (veja CHANGELOG v4.8.3).

🏗️ Arquitetura em resumo

Visão de ponta a ponta de como clientes MCP, o pipeline de recuperação, armazenamento e a infraestrutura empresarial se conectam. Cada seta é um caminho de código real — nada aqui é aspiracional.

flowchart TB
    subgraph CLIENTS["MCP Clients (any of these)"]
        C1[Claude Code]
        C2[Claude Desktop]
        C3[Cursor]
        C4[Windsurf]
        C5[VS Code · Cline · Gemini CLI · Zed]
    end

    subgraph TRANSPORT["Transport Layer"]
        T1[stdio<br/>1 process per client]
        T2[SSE / streamable-http<br/>1 server serves N clients]
    end

    subgraph MIDDLEWARE["ASGI Middleware Chain (HTTP mode)"]
        M1[HealthMiddleware<br/>/health · /healthz]
        M2[BearerAuthMiddleware<br/>constant-time compare]
        M3[Rate Limiter<br/>sliding window]
    end

    subgraph MCP["13 MCP Tools (frozen contract)"]
        MT1[search_knowledge]
        MT2[get_document · search_similar]
        MT3[add_document · add_from_url · update · remove]
        MT4[reindex_documents · get_reindex_status]
        MT5[list_documents · list_categories · get_index_stats · evaluate_retrieval]
    end

    subgraph SEARCH["Retrieval Pipeline"]
        R[Query Router<br/>lexical vs semantic]
        F[FTS5 Fast-Path<br/>opt-in · lt 10ms]
        BM[BM25 Inverted Index<br/>128x faster than baseline]
        SE[Semantic Search<br/>FastEmbed ONNX lazy-loaded]
        RRF[Reciprocal Rank Fusion]
        CE[Cross-Encoder Rerank<br/>MiniLM-L-6-v2]
        QC[Query Cache<br/>LRU + 5-min TTL]
    end

    subgraph STORAGE["Storage (100% local)"]
        CH[ChromaDB<br/>vectors + metadata<br/>WAL mode]
        FT[SQLite FTS5<br/>lexical index<br/>WAL + busy-timeout]
        MD[index_metadata.json<br/>durable state]
    end

    subgraph INGEST["Document Ingestion"]
        FS[documents/ folder]
        WD[Watchdog<br/>10s debounce]
        PA[20 Parsers<br/>MD · PDF · DOCX · code · IPYNB]
        CK[Chunker<br/>markdown-aware · code-aware]
        EM[FastEmbed ONNX<br/>384D bge-small-en-v1.5]
        DD[SHA256 Dedup]
        SW[Zero-downtime Staging Swap<br/>rollback on validation fail]
    end

    subgraph OBS["Enterprise Observability (opt-in)"]
        PM[Prometheus /metrics<br/>7 canonical + histograms]
        LG[Structured JSON logs<br/>ELK · Loki · Datadog · CloudWatch]
        HC[Health payload<br/>version · uptime · cache stats]
    end

    subgraph CFG["Configuration"]
        YM[config.yaml<br/>+ 5 domain presets]
    end

    C1 & C2 & C3 & C4 & C5 -->|MCP protocol| T1
    C1 & C2 & C3 & C4 & C5 -.->|remote deploy| T2
    T1 --> MCP
    T2 --> M1 --> M2 --> M3 --> MCP

    MT1 --> QC
    QC -->|cache miss| R
    R -->|lexical| F
    R -->|semantic| SE
    R -->|hybrid| BM
    F --> CH
    F --> FT
    BM --> CH
    SE --> CH
    BM --> RRF
    SE --> RRF
    RRF --> CE
    CE --> QC

    MT2 --> CH
    MT3 --> INGEST
    MT4 --> SW
    MT5 --> CH

    FS --> WD --> PA
    PA --> CK --> EM --> DD --> CH
    SW -.->|atomic swap| CH
    SW -.-> FT
    CH -.-> MD

    MCP -.->|instrumented| PM
    MCP -.->|logs| LG
    M1 --> HC

    YM -.-> SEARCH
    YM -.-> STORAGE
    YM -.-> OBS
    YM -.-> MIDDLEWARE

    classDef client fill:#3776AB,stroke:#1e5a8a,color:#fff
    classDef transport fill:#00A67E,stroke:#006e54,color:#fff
    classDef middleware fill:#6b46c1,stroke:#4c1d95,color:#fff
    classDef storage fill:#4b5563,stroke:#1f2937,color:#fff
    classDef obs fill:#dc2626,stroke:#7f1d1d,color:#fff
    classDef ingest fill:#f59e0b,stroke:#78350f,color:#fff

    class C1,C2,C3,C4,C5 client
    class T1,T2 transport
    class M1,M2,M3 middleware
    class CH,FT,MD storage
    class PM,LG,HC obs
    class FS,WD,PA,CK,EM,DD,SW ingest

Lendo o diagrama (de cima para baixo):

1. Qualquer cliente MCP — Claude Code, Cursor, Windsurf e outros 5 — conecta-se via o transporte de sua escolha (stdio para uso pessoal, SSE/streamable-http para equipes).
2. O modo HTTP encadeia 3 middlewares ASGI em ordem: primeiro as sondas de saúde (sempre respondidas), depois a autenticação bearer (cercada com WWW-Authenticate), depois o limitador de taxa (janela deslizante).
3. Todas as 13 ferramentas MCP são decoradas com @rate_limited + @instrument — Prometheus conta cada chamada, o limitador de taxa aplica RPM+burst, ambos com custo zero quando desativados.
4. search_knowledge verifica o cache de consultas primeiro; em caso de cache miss, roteia pelo Query Router (classificador regex) para o fast-path FTS5 (léxico) ou o pipeline híbrido (BM25 + semântico + RRF + rerank com cross-encoder).
5. O armazenamento é 100% local: ChromaDB (modo WAL) para vetores + metadados, SQLite FTS5 (WAL + busy-timeout) para o fast-path léxico, index_metadata.json para estado durável.
6. A ingestão de documentos é contínua: o watchdog observa documents/, 20 parsers lidam com cada formato, o chunker respeita limites de idioma, FastEmbed ONNX gera embeddings, SHA256 deduplica, e um swap de staging realiza reconstruções sem downtime com rollback em caso de falha.
7. Observabilidade empresarial (opt-in) — Prometheus /metrics, logs JSON estruturados, payload /health — conecta-se aos mesmos pontos de instrumentação, sem necessidade de alterações de código.
8. config.yaml (com 5 predefinições de domínio) controla todos os subsistemas — sem espaguete de variáveis de ambiente, sem caminhos hardcoded.

Arquitetura completa — 4 diagramas Mermaid detalhados (Visão Geral do Sistema · Fluxo de Consulta · Ingestão de Documentos · efeito hybrid_alpha): docs/ARCHITECTURE.md

📄 20 Formatos de Arquivo — analisados nativamente, sem necessidade de plugins

Cada parser é ciente de chunks — Markdown divide em cabeçalhos ##, código divide em limites de função/classe, notebooks pulam saídas base64, PDFs usam PyMuPDF, planilhas extraem folha por folha. 18 formatos são habilitados por padrão; os 2 formatos MetaTrader são opt-in (adicione a documents.supported_formats em config.yaml).

Habilite um formato opt-in — adicione a extensão a documents.supported_formats no seu config.yaml:

documents:
  supported_formats: [".md", ".pdf", ".mq4", ".mqh"]

Referência completa do parser com notas por formato: docs/CONFIGURATION.md

🔌 Escolha sua integração MCP

Guia completo de configuração de clientes com schemas JSON por cliente: docs/INSTALLATION.md#use-with-other-mcp-clients →

⚙️ Configuração em 30 segundos

# config.yaml — everything is optional; defaults just work

paths:
  documents_dir: "./documents"
  data_dir: "./data"

models:
  embedding:
    profile: "compact"                  # "compact" | "quality" | "multilingual" | "custom"
    gpu: "auto"                         # "auto" | "true" | "false"
  reranker:
    enabled: true                       # cross-encoder rerank

search:
  default_results: 5
  max_results: 100

server:                                 # optional — SSE / HTTP mode
  transport: "stdio"                    # or "sse" / "streamable-http"
  auth:
    bearer_token: ""                    # set a secret to enable auth
  rate_limit:
    enabled: false
  metrics:
    enabled: false
  logging:
    format: "text"                      # or "json"

Predefinições prontas: cybersecurity.yaml · developer.yaml · research.yaml · general.yaml · multilingual.yaml

Referência completa de configuração — todos os campos, todos os padrões, guia de ajuste: docs/CONFIGURATION.md →

🔒 Segurança e Conformidade

knowledge-rag é projetado para equipes que não podem permitir que seus documentos saiam do perímetro.

OpenSSF Best Practices badge: aprovado · ID do projeto #13864

📈 Números que importam

• 26 000+ downloads totais no PyPI · 250+ estrelas no GitHub · 70+ equipes empresariais (privadas + comunidade)
• 700+ testes coletados · 1.33:1 proporção teste-código · gate de tendência codecov ±0.5pp
• 35+ verificações de status em cada PR (matriz 9 células OS×Python · 7 pilares de qualidade)
• 20 formatos de arquivo analisados nativamente · 13 ferramentas MCP congeladas · 5 predefinições de domínio (cyber · dev · research · multilingual · general)
• BM25 128× mais rápido que a linha de base · cross-encoder +1.88pp Recall@10 (p<0.001) · cache −40% latência p95
• 1 800+ arquivos / 39 K chunks indexados em < 3 min em um laptop moderno (corpus típico de desenvolvedor)
• Verificado em produção em corpora de 5 889 documentos / 75 016 chunks

Painel público de benchmarks: https://lyonzin.github.io/knowledge-rag/

📚 Documentação

🤝 Comunidade e Suporte

• Reportar um bug → Abrir uma issue
• Fazer uma pergunta → Discussões do GitHub
• Reportar uma vulnerabilidade → Aviso de segurança (privado)
• Contribuir → CONTRIBUTING.md

SLA de resposta (melhor esforço, projeto comunitário):

• Relatórios de segurança: em até 48 h
• Relatórios de bug com reprodução: em até 5 dias úteis
• Solicitações de recursos: triadas no próximo ciclo de lançamento

🗺️ Lançamentos recentes

• v4.8.5 (2026-08-13) — Observabilidade empresarial: endpoint /health + registro estruturado JSON opcional
• v4.8.4 (2026-08-13) — Patch: correções de segurança, durabilidade e defensivas
• v4.8.3 (2026-08-10) — Hotfix crítico: endurecimento de nuclear-rebuild e smart-reindex em corpora com 50 mil+ chunks
• v4.8.2 (2026-08-10) — Lançamento opcional do fast-path lexical FTS5
• v4.8.0 (2026-08-06) — Base multilíngue + reindexação com zero indisponibilidade

Histórico completo: CHANGELOG.md →

📜 Licença

Licença MIT — LICENSE. Para sempre. Sem upsell de nuvem, sem dual-licenciamento, sem cláusulas restritivas. Faça fork, venda derivados, incorpore em produtos comerciais — a licença não se importa.

🙏 Agradecimentos

Construído sobre os ombros de projetos open-source incríveis:

• Anthropic MCP — especificação do Model Context Protocol + SDK Python
• ChromaDB — banco de dados vetorial que simplesmente funciona
• FastEmbed — embeddings ONNX, sem o inchaço do PyTorch
• HuggingFace — hospedagem de modelos + cross-encoder Xenova/ms-marco-MiniLM-L-6-v2
• BAAI — o modelo de embeddings bge-small-en-v1.5

Contribuidores da comunidade: @Hohlas · @eeshsaxena · Sergey Khokhlov · e todos que abriram issues ou PRs.