RTFM

---

El problema

Tu agente de IA está volando a ciegas.

Hace grep a través de miles de archivos, se pierde el documento que responde la pregunta, inventa módulos que no existen, olvida lo que decidiste en la última sesión. Cuanto más grande es el proyecto, peor se pone. Has añadido un modelo más inteligente. No ayudó. Porque el cuello de botella no es la inteligencia — es la recuperación.

Los indexadores de código (Augment, Sourcegraph, Cursor) solo ven código. Pero tu proyecto no es solo código. Son especificaciones, PRs, decisiones de arquitectura, artículos de investigación, PDFs, regulaciones, notas de vault — el contexto que tu agente necesita para dejar de adivinar.

Por qué construí esto

Estaba escribiendo un artículo fiscal francés (~50 páginas de texto regulatorio, referencias cruzadas entre artículos de código, jurisprudencia, doctrina administrativa). Claude Code seguía haciendo grep en los mismos directorios en bucles, agotando el contexto y produciendo citas incorrectas con total confianza. Había añadido más memoria, mejores prompts, un modelo más inteligente. Nada funcionó, porque el agente no razonaba mal — simplemente no podía encontrar el párrafo correcto en un corpus legal de 2,000 archivos. Así que dejé de intentar hacer el modelo más inteligente y construí la capa que le faltaba. Eso es RTFM.

La solución

RTFM indexa todo. Un comando, un archivo SQLite, una capa de recuperación que tu agente consulta antes de hacer grep.

pip install rtfm-ai && cd your-project && rtfm init

30 segundos. Claude Code ahora busca en tu base de conocimiento indexada — código y documentación y PDFs y cualquier otra cosa que agregues — con búsqueda de texto completo, semántica o híbrida. El agente ve 300 tokens de metadatos primero, luego expande solo lo relevante. Divulgación progresiva en lugar de volcados de contexto.

Gratis. Se ejecuta localmente. Sin claves API. Sin nube. Tus datos siguen siendo tuyos.

Cómo se ve

$ rtfm search "authentication flow" --limit 3
[1] src/auth/handlers.py > authenticate_user (p.2)    score 9.12
    src/auth/handlers.py:147  42 lines
[2] docs/architecture/auth.md > SSO flow (p.1)        score 7.84
    docs/architecture/auth.md:1   23 lines
[3] docs/ADR/0007-oauth.md > Decision (p.1)           score 6.90
    docs/ADR/0007-oauth.md:12  18 lines

Tres resultados, ~300 tokens. El agente decide qué leer a continuación con rtfm_expand(source, target_section) — no un volcado de contexto, una conversación.

---

Inicio rápido

Recomendado — Plugin de Claude Code

En Claude Code (CLI o pestaña Code de Desktop):

/plugin marketplace add roomi-fields/claude-plugins
/plugin install rtfm@roomi-fields

RTFM se distribuye a través del marketplace roomi-fields/claude-plugins, que también incluye notebooklm-mcp para Q&A con respaldo de citas. Para obtener ambos a la vez:

/plugin install notebooklm@roomi-fields

Eso es todo. El plugin auto-inicializa cada proyecto en el primer uso:

• Crea .rtfm/library.db (un archivo SQLite)
• Inyecta instrucciones de búsqueda en CLAUDE.md
• Pre-concede permiso para las herramientas MCP (sin prompt en cada búsqueda)
• Indexa el proyecto en el primer prompt, re-indexa incrementalmente en cada prompt

No se requiere pip install. Python puro, se ejecuta en Linux / macOS / Windows / WSL con Python 3.10+ ya en PATH. El plugin incluye su propio servidor MCP (sin dependencia del SDK de mcp) y resuelve python3 / python / py automáticamente.

Luego dile a Claude: "Encuentra el flujo de autenticación" — usa rtfm_search en lugar de hacer grep.

Extras opcionales (búsqueda semántica, análisis de PDF)

El plugin principal no tiene dependencias. Los extras opcionales más pesados (modelo de embeddings, analizadores de PDF) se instalan bajo demanda en un venv aislado dentro del directorio de datos del plugin — sin contaminar tu Python del sistema, sin conflictos de PEP 668:

/rtfm:install-embeddings    # FastEmbed ONNX (~85 MB), semantic + hybrid search
/rtfm:install-pdf           # pdftext only (~50 MB), fast text extraction
/rtfm:install-pdf-full      # + marker-pdf + CPU-only torch (~1.5 GB), complex layouts

La instalación de pdf-full usa el índice solo-CPU de PyTorch (sin CUDA, sin GPU necesaria) para mantenerse alrededor de 1.5 GB en lugar de 5 GB.

Reinicia Claude Code después de la instalación para que los extras se detecten.

Instalación manual (Cursor, Codex, chat de Claude Desktop, otros clientes MCP)

Para clientes sin el sistema de plugins de Claude Code:

pip install rtfm-ai
cd /path/to/your-project
rtfm init

Luego apunta tu cliente MCP a rtfm-serve (la entrada expuesta por el paquete pip). Extras opcionales vía pip install rtfm-ai[embeddings,pdf].

---

Cómo se compara

	RTFM	Augment CE	Sourcegraph	Code-Index-MCP	MemPalace
Indexación de código	✅ (consciente de AST)	✅	✅	✅	Superficial (fragmentos de caracteres)
Documentación, especificaciones, markdown	✅ (analizado por encabezados)	Parcial	❌	Limitado	Fragmentos verbatim
Legal / regulatorio	✅ (XML, BOFiP)	❌	❌	❌	❌
Investigación (LaTeX, PDF)	✅	❌	❌	❌	❌
Analizadores personalizados	✅ (~50 líneas)	❌	❌	❌	❌
Grafo de conocimiento	✅ (enlaces de archivo/código)	❌	Parcial	❌	Grafo de entidades (personas)
Historial de versiones de archivos	✅ (ilimitado)	❌	❌	❌	❌ (purga-y-reemplaza)
MCP nativo	✅	✅	✅	✅	✅
Se ejecuta localmente	✅	Nube	Empresarial	✅	✅
Código abierto	MIT	❌	Parcial	✅	MIT
Precio	Gratis	$20-200/mes	$$$/mes	Gratis	Gratis

RTFM es la única opción de código abierto que indexa contenido multi-dominio con análisis estructural, un grafo de conocimiento a nivel de código e historial ilimitado por archivo. Ese es el nicho.

Diferente de MemPalace específicamente: MemPalace es una memoria a nivel de entidad para conversaciones (tripletas quién/proyecto/decisión en SQLite, más fragmentos verbatim en ChromaDB). RTFM es una capa de recuperación para artefactos — analizados por formato, vinculados a nivel de archivo, versionados a lo largo del tiempo. Los dos son apilables, no competidores.

Para un desglose más profundo de las decisiones de diseño detrás de cualquier RAG (fragmentación, recuperación, aumento, integración, frescura, almacenamiento), consulta Fundamentos de RAG — los 6 ejes →

---

Memoria que sobrevive a las sesiones

Entre sesiones, la mayoría de los agentes olvidan. RTFM indexa los propios archivos de memoria de Claude Code en todos los proyectos de tu máquina, con historial de versiones completo.

rtfm memory                    # Manual snapshot
rtfm memory --install-hook     # Auto-snapshot on every SessionEnd

• Índice entre proyectos — una base de datos en ~/.rtfm/memory.db ve cada directorio ~/.claude/projects/*/memory/ en tu máquina. Pregunta rtfm_search("OAuth auth decisions") y obtén resultados de los 18 proyectos.
• Historial de versiones ilimitado — cada cambio en un archivo de memoria se captura como instantánea (sin poda). rtfm_history <slug> devuelve la evolución completa.
• Instantánea automática en SessionEnd — un comando instala un hook global de Claude Code. Cada sesión que cierras captura una nueva instantánea.
• Curado, no verbatim — RTFM indexa las notas que el agente ya curó durante la sesión (pequeñas, estructuradas, densas en señal). Filosofía diferente de MemPalace, que indexa las transcripciones completas de conversaciones en ChromaDB (grandes, ruidosas, necesitan filtrado semántico agresivo).

---

Modo vault de Obsidian

RTFM es la capa de recuperación para el patrón Karpathy LLM Wiki. El propio Karpathy escribió: "a pequeña escala el archivo de índice es suficiente, pero a medida que la wiki crece quieres una búsqueda adecuada." Esto es una búsqueda adecuada.

cd /path/to/your-obsidian-vault
rtfm vault

• Detecta .obsidian/, propone un mapeo de carpeta → corpus
• Resuelve [[wikilinks]] siguiendo las reglas de Obsidian → almacenado como aristas de grafo
• Genera _rtfm/ con navegación nativa de Obsidian (índice, grafo con Mermaid, hubs, huérfanos, frontmatter de Dataview)
• Probado en un vault de investigación de 1,700 notas

_rtfm/
├── index.md      # Hub: corpus list, top connected documents
├── graph.md      # Hub documents, orphans, broken links, Mermaid
├── recent.md     # Recently modified files
└── corpus/       # Per-corpus indexes

El LLM sigue escribiendo tu wiki. RTFM maneja la recuperación que index.md no puede escalar.

Guía completa de Obsidian →

---

Integración con NotebookLM

RTFM se combina naturalmente con notebooklm-mcp. NotebookLM te limita a 50 consultas/día por notebook; RTFM elimina ese techo indexando respuestas localmente — pregunta una vez, recupera para siempre, sin conexión, en milisegundos.

El endpoint /batch-to-vault de notebooklm-mcp escribe Q&A con respaldo de citas como {slug}.md (markdown con frontmatter) más {slug}.json (sidecar estructurado nblm-answer-v1). Ambos están garantizados a coexistir. Dos rutas de integración, ambas disponibles hoy:

• Ruta A — Markdown (configuración cero): coloca el vault en RTFM y rtfm sync. El analizador de markdown predeterminado divide cada respuesta en fragmentos de pregunta / respuesta / por-cita automáticamente. Sin mapeo, sin esquema, sin código.
• Ruta B — Sidecar JSON (metadatos tipados): coloca un mapeo nblm-answer.yaml en .rtfm/mappings/. Cada archivo de respuesta .json produce fragmentos tipados con notebook_id, source_name, citation_marker consultables vía SQL, más candidatos de arista cites entre respuestas y fuentes.

Usa la Ruta A a menos que necesites específicamente filtrar o graficar por campos de citas estructuradas.

Receta completa de NotebookLM →

---

Lo que medí

Ejecuté dos tipos de benchmarks. La imagen honesta es matizada — la recuperación ayuda más en tareas que son realmente resolubles y donde el agente está gastando tiempo buscando cosas.

Tarea con muchos documentos: generación de artículo fiscal francés (B10)

Escribir un artículo regulado de ~50 páginas a partir de un corpus de código legal, jurisprudencia y doctrina administrativa. Mismo agente (Claude Code + Sonnet 4), mismo prompt, ocho configuraciones probadas.

Configuración	Duración	Costo	Tokens
Línea base (sin RTFM)	8m 16s	$22.61	8.21 M
Con RTFM (FTS predeterminado)	6m 58s	$11.14	3.22 M

Δ : −51 % costo, −61 % tokens, −16 % duración — con mejor precisión factual. Este es el caso de uso para el que se construyó RTFM: navegar un corpus multi-dominio grande donde grep se pierde el párrafo correcto.

Tarea de código: FeatureBench (conjunto de datos LiberCoders)

11 tareas, 3 repos de tamaño variable, 4 condiciones (A = prompt estándar con rutas de archivo; B = descubrimiento, sin rutas; C = RTFM FTS; D = RTFM híbrido), 3 ejecuciones cada una.

Repo	Tamaño	Dónde ayuda RTFM
metaflow	620 archivos	Todos resuelven — RTFM no añade ganancia medible
astropy	1,119 archivos	Todas las condiciones 25–30 % de pase F2P; ninguna resuelve completamente
mlflow	8,255 archivos	Todas las condiciones 0–5 % de pase F2P; ninguna resuelve completamente

En una sola ejecución de alcance más pequeño (test_stub_generator en metaflow), RTFM redujo el tiempo del agente en −37 % frente a la línea base sin rutas. En los repos más grandes, las tareas en sí eran demasiado difíciles para que Sonnet 4 las resolviera dentro de un tiempo límite de 20 minutos, independientemente de la recuperación.

Las advertencias honestas

• Modelo único (Sonnet 4), agente único (Claude Code). No es estadísticamente a prueba de balas.
• En repos pequeños (< 1k archivos), grep es suficiente y RTFM añade sobrecarga.
• FeatureBench mide modificación de código, no recuperación de información. Es el benchmark equivocado para una herramienta de recuperación — lo estoy ejecutando porque es lo que existe. Benchmarks más adecuados (RepoQA, SWE-QA, LocAgent) están en la hoja de ruta.

Qué dice esto

RTFM gana de forma medible cuando el cuello de botella es "encontrar el párrafo correcto en un corpus de 2,000 archivos". No hace que las tareas imposibles sean resolubles mágicamente. El modelo aún tiene que hacer el trabajo — RTFM solo se asegura de que tenga el contexto correcto para hacerlo.

---

Para quién es

RTFM funciona en cualquier lugar donde tu proyecto no sea solo código:

• LegalTech — Código + leyes fiscales + especificaciones regulatorias. Incluye parsers de XML de Legifrance y BOFiP.
• Investigación — Código + artículos en LaTeX + conjuntos de datos. Incluye parsers de LaTeX y PDF.
• FinTech — Código + regulaciones financieras + informes XBRL. Escribe un parser XBRL en 50 líneas.
• HealthTech — Código + registros médicos (HL7/FHIR) + guías clínicas.
• Desarrolladores solitarios con proyectos grandes — Deja de ver a tu agente hacer grep en los mismos 8,000 archivos en cada sesión.
• Usuarios de Obsidian / PKM — Haz que tu bóveda sea realmente buscable por tu IA.
• Cualquier industria regulada — Si tu proyecto mezcla código con documentos de dominio, RTFM es para ti.

---

Lista completa de funciones

Búsqueda y recuperación

• Búsqueda de texto completo FTS5 — instantánea, sin configuración, funciona de fábrica
• Búsqueda semántica — embeddings opcionales (FastEmbed/ONNX, sin necesidad de GPU)
• Modo híbrido — combina ambos, clasifica por puntuación de relevancia
• Primero los metadatos — los resultados devuelven rutas de archivo + puntuaciones (~300 tokens), no volcados de contenido
• Divulgación progresiva — el agente expande solo los fragmentos que realmente necesita
• Grafo de conocimiento — wikilinks + imports de Python resueltos como aristas del grafo, detección de hubs, clasificación por centralidad

Indexación multi-formato

• 22 parsers integrados — Markdown, Python (AST), LaTeX, YAML, JSON, TOML, Shell, PDF, XML, HTML, SQLite, Jupyter, CSV/TSV, XLSX, EPUB, MOBI/AZW, FB2, DJVU, DOCX, ODT, RTF, texto plano
• Extensible — añade cualquier formato en ~50 líneas de Python
• Hooks de auto-sincronización — el índice se mantiene fresco en cada prompt, cero trabajo manual
• Incremental — solo re-indexa lo que cambió

Integración

• Plugin nativo de Claude Code — /plugin install rtfm@roomi-fields/rtfm, auto-inicialización por proyecto
• Servidor MCP en Python puro — 0 dependencias externas, sin SDK de mcp / pydantic / binarios nativos
• Multiplataforma — Linux, macOS, Windows, WSL (solo requiere Python ≥ 3.10 en PATH)
• 13 herramientas MCP — búsqueda, contexto, expandir, grafo, historial, sincronización, etiquetas, ...
• Respaldo de instalación manual — pip install rtfm-ai para Cursor, Codex, Claude Desktop chat, cualquier otro cliente MCP
• CLI + API de Python — programable para pipelines
• No invasivo — no toca tu código, no reemplaza tu editor

---

La arquitectura de parsers

¿Necesitas indexar un formato que nadie soporta? Escribe un parser en ~50 líneas.

from rtfm.parsers.base import BaseParser, ParserRegistry
from rtfm.core.models import Chunk
import json
from uuid import uuid4

@ParserRegistry.register
class FHIRParser(BaseParser):
    """Parse HL7 FHIR medical records."""
    extensions = ['.fhir.json']
    name = "fhir"

    def parse(self, path, metadata=None):
        data = json.loads(path.read_text())
        for entry in data.get('entry', []):
            resource = entry.get('resource', {})
            yield Chunk(
                id=resource.get('id', str(uuid4())),
                content=json.dumps(resource, indent=2),
                book_title=f"FHIR {resource.get('resourceType', 'Unknown')}",
                book_slug=resource.get('id', 'unknown'),
                page_start=1,
                page_end=1,
            )

Colócalo en tu proyecto, reinicia Claude Code, tu agente médico de IA ahora entiende registros FHIR.

Dos niveles de integración JSON

Para formatos basados en JSON específicamente, RTFM ofrece una segunda vía de extensibilidad que no necesita Python:

Nivel	Qué haces	Qué obtienes
1. Genérico	Nada. Solo indexa el archivo.	Cada clave de nivel superior se convierte en un fragmento. La búsqueda de texto completo funciona sobre los valores.
2. Mapeado	Coloca un mapeo YAML en .rtfm/mappings/ (~30 líneas).	Fragmentos tipados con metadatos declarados, títulos personalizados, extracción foreach sobre arrays, candidatos a aristas. El proyecto productor (NotebookLM, Linear, Notion, OpenAPI…) incluye el mapeo; RTFM se mantiene genérico.

Consulta mapeos de esquema JSON para la referencia completa, y RTFM × NotebookLM para una receta concreta.

Parsers integrados

Parser	Extensiones	Estrategia
Markdown	.md	Dividir por encabezados, extracción de frontmatter YAML
Python	.py	Basado en AST: cada clase/función = 1 fragmento
LaTeX	.tex	Dividir por \section, \chapter, etc.
YAML	.yaml, .yml	Dividir por claves de nivel superior
JSON	.json	Dividir por claves de nivel superior o elementos de array
TOML	.toml	Tablas de nivel superior; emite aristas depends_on (PEP 621, Cargo, Poetry)
Shell	.sh, .bash, .zsh	Fragmentación consciente de funciones
PDF	.pdf	Basado en páginas (pip install rtfm-ai[pdf])
Legifrance XML	.xml	Códigos legales franceses (formato LEGI)
BOFiP HTML	.html	Doctrina fiscal francesa
SQLite	.sqlite, .sqlite3, .db	Esquema + filas de muestra por tabla; aristas FK (solo lectura)
Jupyter	.ipynb	Agrupar celdas por encabezado de markdown; se descartan salidas
CSV / TSV	.csv, .tsv	Encabezado + filas de muestra + inferencia ligera de tipos
XLSX	.xlsx	Esquema por hoja + muestra (pip install rtfm-ai[xlsx])
Texto plano	.js, .ts, .rs, .go, ...	Fragmentos por límites de línea (~500 caracteres)

---

Herramientas MCP

Herramienta	Qué hace
rtfm_search	Buscar en el índice (FTS, semántico o híbrido)
rtfm_context	Obtener contexto relevante para un tema (solo metadatos)
rtfm_expand	Mostrar todos los fragmentos de una fuente con contenido completo
rtfm_discover	Escaneo rápido de estructura del proyecto (~1s, sin necesidad de indexación)
rtfm_books	Listar documentos indexados
rtfm_stats	Estadísticas de la biblioteca
rtfm_sync	Sincronizar un directorio (incremental)
rtfm_ingest	Ingerir un solo archivo
rtfm_tags	Listar todas las etiquetas
rtfm_tag_chunks	Añadir etiquetas a fragmentos específicos
rtfm_remove	Eliminar un archivo del índice
rtfm_graph	Mostrar grafo de dependencias para una fuente (imports, enlaces)
rtfm_history	Historial de versiones de archivos y snapshots de memoria

---

Referencia CLI

# Search
rtfm search "authentication flow"
rtfm search "article 39" --corpus cgi --limit 5

# Sync
rtfm sync                              # All registered sources
rtfm sync /path/to/docs --corpus docs  # Specific directory
rtfm sync . --force                    # Force re-index

# Source management
rtfm add /path/to/docs --corpus docs --extensions md,pdf
rtfm sources

# Obsidian vault
rtfm vault                             # Initialize for cwd vault
rtfm vault /path/to/vault              # Specific vault
rtfm vault --regenerate                # Regenerate _rtfm/ files

# Cross-project Claude memory
rtfm memory                            # Manual snapshot
rtfm memory --install-hook             # Auto-snapshot on SessionEnd

# Status & info
rtfm status
rtfm books
rtfm tags
rtfm history path/to/file.md           # Memory version history

# Semantic search
rtfm embed                             # Generate embeddings (one-time)
rtfm semantic-search "tax deductions" --hybrid

# MCP server
rtfm serve

---

API de Python

from rtfm import Library

lib = Library("my_library.db")

# Index
stats = lib.ingest("documents/article.md", corpus="docs")
result = lib.sync(".", corpus="my-project")  # SyncResult(+3 ~1 -0 =42)

# Search
results = lib.search("depreciation", limit=10, corpus="cgi")
results = lib.hybrid_search("amortissement fiscal", limit=10)

# Export for LLM
prompt_context = results.to_prompt(max_chars=8000)

lib.close()

---

Dónde encaja RTFM

RTFM no es un gestor de tareas. No es un framework de agentes. Es la capa de conocimiento que tu agente necesita debajo de lo que ya estés usando.

┌─────────────────────────────────┐
│  GSD / Taskmaster / Claude Flow │  ← Orchestration
├─────────────────────────────────┤
│              RTFM               │  ← Knowledge (you are here)
├─────────────────────────────────┤
│          Claude Code            │  ← Execution
└─────────────────────────────────┘

Sin RTFM, tu orquestador impulsa un agente que alucina. Con RTFM, el agente sabe sobre qué está construyendo.

---

Contribuciones

Añadir un parser es la forma más fácil de contribuir — y la más impactante. Consulta CONTRIBUTING.md.

¿Encontraste un error? ¿Tienes una idea? Abre un issue.

Agradecimientos

@AVeryTastyRaspberry hizo que RTFM funcionara en Windows nativo. RTFM se desarrolla en Linux, y cada comando estaba roto allí — el CLI moría en el import antes de poder analizar un argumento. El informe (#8) señaló la línea; las pruebas que siguieron, en una máquina real con Windows 11 y verificadas contra tasklist en lugar de contra las afirmaciones de RTFM, encontraron cinco defectos más detrás de ella y confirmaron cada corrección. #9 luego rastreó las ventanas de consola que seguían apareciendo. Esa es una plataforma que este proyecto no podría soportar de otra manera.

Licencia

MIT — úsalo, hazle fork, extiéndelo, publícalo.

Autor

Romain Peyrichou — @roomi-fields

---