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 valores predeterminados 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 tasa, sondas de salud, registro JSON estructurado, reindexación sin tiempo de inactividad) que ningún otro OSS centrado en RAG incluye de serie.

📊 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 de pago / parcial · ❌ no disponible · ⚠️ preocupación de licencia o predeterminado

Las 5 dimensiones donde knowledge-rag es único: sondas de salud + registro JSON + Prometheus + límite de tasa + autenticación bearer simultáneamente integrados en un servidor MCP OSS centrado en RAG. 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 sub-segundo.

Ruta 2 — Servidor HTTP / SSE (multi-usuario, aislado, 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 + payload 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)

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 cliente 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, con 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 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 o ponen detrás de un muro de pago, o 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 — Papers, Cuadernos, Datasets

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

Indexa papers de arXiv, cuadernos de laboratorio, documentación de datasets. La búsqueda semántica encuentra papers por intención, no solo por palabras clave — el reranking con cross-encoder destaca 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. 40+ usuarios autenticados mediante token bearer, con límite de tasa, monitoreados con Prometheus, sondas /health conectadas a tu balanceador de carga, logs JSON enviados a Datadog. Sin llamadas a la nube. Cumple con los requisitos de localización de datos de LGPD, GDPR e HIPAA por diseño.

Verificado a escala: reproducción en producción sobre un corpus de 5 889 documentos / 75 016 chunks 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[35 Parsers<br/>MD · PDF · DOCX · code · IaC · 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

Leyendo el 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 + reranking 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/, 35 analizadores manejan cada formato, el chunker respeta los límites de idioma, FastEmbed ONNX genera embeddings, 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, logs 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 líos de variables de entorno, sin rutas codificadas.

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

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

Cada analizador es consciente de chunks — 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. 33 formatos están habilitados por defecto; los 2 formatos MetaTrader son opt-in (agrégalos a documents.supported_formats en config.yaml).

Habilitar 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 →

⚠️ Modelo operativo — léelo una vez. Tu cliente MCP (Claude Desktop, Code, Cursor, etc.) genera y posee el proceso del servidor knowledge-rag. NO ejecutes también knowledge-rag en una terminal mientras tu cliente MCP esté abierto — dos procesos de escritura contra el mismo data_dir corrompen el segmento HNSW de ChromaDB en Windows (ver issue #216). Línea base recomendada: agrega "KNOWLEDGE_RAG_SINGLE_INSTANCE": "1" al bloque env de tu configuración MCP como red de seguridad. Explicación completa + cómo ejecutar comandos CLI de forma segura: docs/single-instance.md.

⚙️ 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 en GitHub · 70+ equipos empresariales (privados + comunidad)
• 700+ pruebas recopiladas · 1.33:1 proporción prueba-código · puerta de tendencia codecov ±0.5pp
• 35+ comprobaciones de estado en cada PR (matriz OS×Python de 9 celdas · 7 pilares de calidad)
• 35 formatos de archivo analizados nativamente · 13 herramientas MCP congeladas · 5 preajustes de dominio (cibernético · 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 una computadora portátil moderna (corpus típico de desarrollador)
• Verificado en producción en corpus de 5 889 documentos / 75 016 fragmentos

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

📚 Documentación

🤝 Comunidad y soporte

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

SLA de respuesta (mejor esfuerzo, proyecto comunitario):

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

🗺️ Versiones 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) — Corrección crítica: endurecimiento de reconstrucción nuclear + reindexación inteligente en corpus de 50k+ fragmentos
• v4.8.2 (2026-08-10) — Versión 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 — LICENCIA. 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: 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 — incrustaciones ONNX, sin inflación de PyTorch
• HuggingFace — alojamiento de modelos + cross-encoder Xenova/ms-marco-MiniLM-L-6-v2
• BAAI — el modelo de incrustación bge-small-en-v1.5

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