knowledge-rag

knowledge-rag

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

⭐ Historial de estrellas

_{Gráfico actualizado diariamente por GitHub Action}

🎯 Por qué knowledge-rag

La mayoría de los frameworks RAG caen en una de tres trampas: (1) requieren que envíes tus datos a una API en la nube, (2) te dan 300 bloques de construcción y 0 configuraciones predeterminadas con opinión, o (3) incluyen RAG como una característica del 5% de una plataforma mucho más grande que no pediste.

knowledge-rag hace una cosa bien: es el servidor RAG local nativo de MCP que Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini CLI y Zed pueden buscar de inmediato — con infraestructura empresarial (autenticación bearer, métricas Prometheus, limitación de velocidad, sondas de salud, registro JSON estructurado, reindexación sin tiempo de inactividad) que ningún otro OSS centrado en RAG incluye integrado.

📊 Cómo se compara knowledge-rag con otros frameworks RAG

Auditamos 16 frameworks y plataformas RAG populares (LlamaIndex, LangChain, ChromaDB, Weaviate, Qdrant, RAGFlow, LightRAG, DSPy, GraphRAG, Haystack, RAG-Anything, kotaemon, txtai, llmware, Dify, open-webui, FastGPT) para que puedas elegir con honestidad.

Leyenda: ✅ integrado · 🟡 plugin / nivel pago / parcial · ❌ no disponible · ⚠️ problema de licencia o configuración predeterminada

Las 5 dimensiones donde knowledge-rag es único: sondas de salud + registro JSON + Prometheus + limitación de velocidad + autenticación bearer simultáneamente integrados en un servidor MCP OSS centrado en RAG. La reindexación sin tiempo de inactividad + reindexación asíncrona en segundo plano + caos/resistencia/mutación nocturnos están documentados en el README de nadie más.

🚀 Inicio rápido (3 minutos, de cero a tu primera consulta)

Elige tu ruta de integración — knowledge-rag envía el mismo servidor a través de cada canal.

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

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

Coloca tus PDFs, markdown, archivos de código en documents/. Reinicia tu cliente MCP. Pregúntale:

search_knowledge("your query")

Eso es todo. La primera consulta carga el modelo de embeddings ONNX (~200MB, descarga única). Las consultas posteriores se almacenan en caché y alcanzan latencia de menos de un segundo.

Ruta 2 — Servidor HTTP / SSE (multi-usuario, aislado de red, con balanceo 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

• Sonda de salud: curl http://your-host:8179/health → 200 + carga JSON
• Recolección Prometheus: http://your-host:9179/metrics
• Despachador MCP: autenticado mediante Authorization: Bearer your-secret-token

Ruta 3 — Docker (modelos pre-descargados, listo para aislamiento de red)

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

Guía de instalación completa con los 5 métodos, 8 configuraciones de clientes MCP y configuración de GPU: docs/INSTALLATION.md →

🤖 Habilidades listas para usar para agentes de IA

Instalar knowledge-rag le da a tu agente 13 herramientas MCP. No le dice al agente cuándo usarlas. Eso es lo que resuelve la carpeta skills/ — habilidades de comportamiento listas para usar para Claude Code, Cursor, Windsurf, Cline, Zed, VS Code Copilot que convierten "IA con acceso a RAG" en "IA que realmente usa RAG primero".

10 habilidades, licencia MIT, organizadas por tipo:

Instalación — elige la ruta más corta para tu 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

Ambas reinician Claude Code y listo. La opción 2 admite --project, --only rag-check-first,rag-cite-sources, --dry-run, --help.

Para Cursor, Windsurf, Cline e instrucciones manuales completas → skills/README.md · Catálogo completo con cadenas de habilidades → skills/CATALOG.md

🛠️ Las 13 herramientas MCP que recibe tu agente

Una vez instalado, tu agente de IA recibe estas 13 herramientas automáticamente:

Referencia completa de la API con detalles de parámetros, esquemas de retorno, ejemplos: docs/API.md →

🏢 Características empresariales (integradas, cero configuración)

Cada framework RAG afirma ser "listo para producción". Esto es lo que knowledge-rag incluye en el núcleo OSS, verificado por pruebas de regresión, que los competidores ponen detrás de un muro de pago, convierten en plugin, o simplemente no tienen.

💼 Casos de uso (corpus reales, equipos reales)

Equipos de seguridad — Red / Blue / CTF

Preajuste: cybersecurity.yaml · 8 categorías · 200+ palabras clave de enrutamiento · 69 expansiones de consulta

Ingiere MITRE ATT&CK, informes de amenazas, writeups de exploits, informes de incidentes. Busca desde Claude Code con search_knowledge("privilege escalation windows") y obtén recuperación instantánea en todo tu corpus. Aislado — nada sale del portátil.

Equipos de desarrollo — Documentos de diseño, Runbooks, Código

Preajuste: developer.yaml · 9 categorías · 150+ palabras clave de enrutamiento · 50+ expansiones

Reemplaza la búsqueda en Confluence. Ingiere documentos de arquitectura, ADRs, runbooks, código, especificaciones de API. Los desarrolladores preguntan a su agente de IA "cómo autenticamos el servicio de pagos" y obtienen el ADR exacto + la cita del archivo de implementación.

Laboratorios de investigación — Artículos, Cuadernos, Conjuntos de datos

Preajuste: research.yaml · 9 categorías · 100+ palabras clave de enrutamiento · 40+ expansiones

Indexa artículos de arXiv, cuadernos de laboratorio, documentación de conjuntos de datos. La búsqueda semántica encuentra artículos por intención, no solo por palabras clave — el reranking con cross-encoder saca a la luz el realmente relevante en lugar de cinco que comparten un término.

Base de conocimiento empresarial — Aislada, auditable

Preajuste: general.yaml · pizarra en blanco, búsqueda semántica pura

Despliega vía SSE en una sola VM. Más de 40 usuarios autenticados mediante token bearer, con límite de tasa, monitoreados con Prometheus, sondas /health conectadas a tu balanceador de carga, registros JSON enviados a Datadog. Sin llamadas a la nube. Cumple los requisitos de localización de datos de LGPD, GDPR e HIPAA por diseño.

Verificado a escala: reproducción en producción en un corpus de 5 889 documentos / 75 016 fragmentos con consultas concurrentes durante una reconstrucción nuclear — cero tiempo de inactividad, cero errores (ver CHANGELOG v4.8.3).

🏗️ Arquitectura de un vistazo

Vista de extremo a extremo de cómo se conectan los clientes MCP, el pipeline de recuperación, el almacenamiento y la infraestructura empresarial. Cada flecha es una ruta de código real — nada de lo que se muestra aquí es 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

Lectura del diagrama (de arriba a abajo):

1. Cualquier cliente MCP — Claude Code, Cursor, Windsurf y otros 5 — se conecta mediante el transporte de tu elección (stdio para uso personal, SSE/streamable-http para equipos).
2. El modo HTTP encadena 3 middlewares ASGI en orden: primero las sondas de salud (siempre respondidas), luego la autenticación bearer (protegida con WWW-Authenticate), y luego el limitador de tasa (ventana deslizante).
3. Las 13 herramientas MCP están decoradas con @rate_limited + @instrument — Prometheus cuenta cada llamada, el limitador de tasa aplica RPM+burst, ambos con costo cero cuando están deshabilitados.
4. search_knowledge verifica primero la caché de consultas; un fallo de caché se enruta a través del Query Router (clasificador regex) ya sea a la ruta rápida FTS5 (léxica) o al pipeline híbrido (BM25 + semántico + RRF + rerank con cross-encoder).
5. El almacenamiento es 100% local: ChromaDB (modo WAL) para vectores + metadatos, SQLite FTS5 (WAL + busy-timeout) para la ruta rápida léxica, index_metadata.json para estado duradero.
6. La ingesta de documentos se ejecuta continuamente: el watchdog observa documents/, 20 analizadores manejan cada formato, el fragmentador respeta los límites de idioma, FastEmbed ONNX genera incrustaciones, SHA256 deduplica, y un intercambio de staging realiza reconstrucciones sin tiempo de inactividad con reversión ante fallos.
7. Observabilidad empresarial (opt-in) — /metrics de Prometheus, registros JSON estructurados, payload /health — se conecta a los mismos puntos de instrumentación, sin necesidad de cambios de código.
8. config.yaml (con 5 preajustes de dominio) controla cada subsistema — sin espaguetis de variables de entorno, sin rutas codificadas.

Arquitectura completa — 4 diagramas Mermaid detallados (Visión general del sistema · Flujo de consultas · Ingesta de documentos · efecto hybrid_alpha): docs/ARCHITECTURE.md

📄 20 formatos de archivo — analizados de forma nativa, sin necesidad de plugins

Cada analizador es consciente de fragmentos — Markdown se divide en encabezados ##, el código se divide en límites de función/clase, los cuadernos omiten salidas base64, los PDF usan PyMuPDF, las hojas de cálculo se extraen hoja por hoja. 18 formatos están habilitados por defecto; los 2 formatos MetaTrader son opt-in (agrégalos a documents.supported_formats en config.yaml).

Habilita un formato opt-in — agrega la extensión a documents.supported_formats en tu config.yaml:

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

Referencia completa del analizador con notas por formato: docs/CONFIGURATION.md

🔌 Elige tu integración MCP

Guía completa de configuración de clientes con esquemas JSON por cliente: docs/INSTALLATION.md#use-with-other-mcp-clients →

⚙️ Configuración en 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"

Preajustes preconstruidos: cybersecurity.yaml · developer.yaml · research.yaml · general.yaml · multilingual.yaml

Referencia completa de configuración — cada campo, cada valor predeterminado, guía de ajuste: docs/CONFIGURATION.md →

🔒 Seguridad y cumplimiento

knowledge-rag está diseñado para equipos que no pueden permitir que sus documentos salgan del perímetro.

Insignia de OpenSSF Best Practices: aprobada · ID de proyecto #13864

📈 Números que importan

• 26 000+ descargas totales en PyPI · 250+ estrellas de GitHub · 70+ equipos empresariales (privados + comunitarios)
• 700+ pruebas recopiladas · 1.33:1 proporción prueba-código · puerta de tendencia codecov ±0.5pp
• 35+ verificaciones de estado en cada PR (matriz de 9 celdas OS×Python · 7 pilares de calidad)
• 20 formatos de archivo analizados de forma nativa · 13 herramientas MCP congeladas · 5 preajustes de dominio (ciberseguridad · desarrollo · investigación · multilingüe · general)
• BM25 128× más rápido que la línea base · cross-encoder +1.88pp Recall@10 (p<0.001) · caché −40% latencia p95
• 1 800+ archivos / 39 K fragmentos indexados en < 3 min en un portátil moderno (corpus típico de desarrollador)
• Verificado en producción en corpus de 5 889 documentos / 75 016 fragmentos

Panel de referencia público: https://lyonzin.github.io/knowledge-rag/

📚 Documentación

🤝 Comunidad y soporte

• Reportar un error → Abrir un issue
• Hacer una pregunta → Discusiones de GitHub
• Reportar una vulnerabilidad → Aviso de seguridad (privado)
• Contribuir → CONTRIBUTING.md

SLA de respuesta (mejor esfuerzo, proyecto comunitario):

• Reportes de seguridad: dentro de 48 h
• Reportes de errores con reproducción: dentro de 5 días hábiles
• Solicitudes de funciones: clasificadas en el próximo ciclo de lanzamiento

🗺️ Lanzamientos recientes

• v4.8.5 (2026-08-13) — Observabilidad empresarial: endpoint /health + registro estructurado JSON opcional
• v4.8.4 (2026-08-13) — Parche: correcciones de seguridad + durabilidad + defensivas
• v4.8.3 (2026-08-10) — Hotfix crítico: endurecimiento de nuclear-rebuild + smart-reindex en corpus de 50k+ chunks
• v4.8.2 (2026-08-10) — Lanzamiento opcional de ruta rápida léxica FTS5
• v4.8.0 (2026-08-06) — Base multilingüe + reindexación sin tiempo de inactividad

Historial completo: CHANGELOG.md →

📜 Licencia

Licencia MIT — LICENSE. Para siempre. Sin ventas adicionales en la nube, sin doble licencia, sin cláusulas restrictivas. Haz un fork, vende derivados, intégralo en productos comerciales — a la licencia no le importa.

🙏 Agradecimientos

Construido sobre los hombros de increíbles proyectos de código abierto:

• Anthropic MCP — Especificación del Protocolo de Contexto de Modelo + SDK de Python
• ChromaDB — base de datos vectorial que simplemente funciona
• FastEmbed — embeddings ONNX, sin el peso de PyTorch
• HuggingFace — alojamiento de modelos + cross-encoder Xenova/ms-marco-MiniLM-L-6-v2
• BAAI — el modelo de embeddings bge-small-en-v1.5

Contribuidores de la comunidad: @Hohlas · @eeshsaxena · Sergey Khokhlov · y todos los que presentaron issues o PRs.