RTFM

---

O problema

Seu agente de IA está voando às cegas.

Ele faz grep em milhares de arquivos, perde o documento que responde à pergunta, inventa módulos que não existem, esquece o que você decidiu na última sessão. Quanto maior o projeto, pior fica. Você adicionou um modelo mais inteligente. Não ajudou. Porque o gargalo não é inteligência — é recuperação.

Indexadores de código (Augment, Sourcegraph, Cursor) só veem código. Mas seu projeto não é só código. São especificações, PRs, decisões de arquitetura, artigos de pesquisa, PDFs, regulamentações, notas de vault — o contexto que seu agente precisa para parar de adivinhar.

Por que construí isso

Eu estava escrevendo um artigo fiscal francês (~50 páginas de texto regulatório, referências cruzadas entre artigos de código, jurisprudência, doutrina administrativa). O Claude Code ficava fazendo grep nos mesmos diretórios em loops, ficando sem contexto e produzindo citações incorretas com confiança. Eu tinha adicionado mais memória, prompts melhores, um modelo mais inteligente. Nada disso funcionou, porque o agente não estava raciocinando mal — ele simplesmente não conseguia encontrar o parágrafo certo em um corpus jurídico de 2.000 arquivos. Então parei de tentar tornar o modelo mais inteligente e construí a camada que faltava. Isso é o RTFM.

A solução

O RTFM indexa tudo. Um comando, um arquivo SQLite, uma camada de recuperação que seu agente consulta antes de fazer grep.

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

30 segundos. O Claude Code agora pesquisa sua base de conhecimento indexada — código e documentos e PDFs e qualquer outra coisa que você adicionar — com busca de texto completo, semântica ou híbrida. O agente vê 300 tokens de metadados primeiro e expande apenas o que é relevante. Divulgação progressiva em vez de despejos de contexto.

Grátis. Roda localmente. Sem chaves de API. Sem nuvem. Seus dados continuam seus.

Como parece

$ 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

Três resultados, ~300 tokens. O agente decide o que ler a seguir com rtfm_expand(source, target_section) — não um despejo de contexto, uma conversa.

---

Início rápido

Recomendado — plugin Claude Code

No Claude Code (CLI ou aba Code do Desktop):

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

O RTFM é distribuído via marketplace roomi-fields/claude-plugins, que também inclui notebooklm-mcp para Q&A com citações. Para pegar ambos de uma vez:

/plugin install notebooklm@roomi-fields

É isso. O plugin inicializa automaticamente cada projeto no primeiro uso:

• Cria .rtfm/library.db (um arquivo SQLite)
• Injeta instruções de busca em CLAUDE.md
• Pré-concede permissão para as ferramentas MCP (sem prompt a cada busca)
• Indexa o projeto no primeiro prompt, reindexa incrementalmente a cada prompt

Sem pip install necessário. Python puro, roda em Linux / macOS / Windows / WSL com Python 3.10+ já no PATH. O plugin inclui seu próprio servidor MCP (sem dependência do SDK mcp) e resolve python3 / python / py automaticamente.

Então diga ao Claude: "Encontre o fluxo de autenticação" — ele usa rtfm_search em vez de fazer grep.

Extras opcionais (busca semântica, parsing de PDF)

O plugin principal não tem dependências. Extras opcionais mais pesados (modelo de embedding, parsers de PDF) são instalados sob demanda em um venv isolado dentro do diretório de dados do plugin — sem poluir seu Python do sistema, sem conflitos 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

A instalação do pdf-full usa o índice somente CPU do PyTorch (sem CUDA, sem GPU necessária) para ficar em torno de 1,5 GB em vez de 5 GB.

Reinicie o Claude Code após a instalação para que os extras sejam reconhecidos.

Instalação manual (Cursor, Codex, chat do Claude Desktop, outros clientes MCP)

Para clientes sem o sistema de plugins do Claude Code:

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

Em seguida, aponte seu cliente MCP para rtfm-serve (a entrada exposta pelo pacote pip). Extras opcionais via pip install rtfm-ai[embeddings,pdf].

---

Como se compara

	RTFM	Augment CE	Sourcegraph	Code-Index-MCP	MemPalace
Indexação de código	✅ (ciente de AST)	✅	✅	✅	Raso (chunks de caracteres)
Docs, especificações, markdown	✅ (parsed por cabeçalho)	Parcial	❌	Limitado	Chunks verbatim
Jurídico / regulatório	✅ (XML, BOFiP)	❌	❌	❌	❌
Pesquisa (LaTeX, PDF)	✅	❌	❌	❌	❌
Parsers personalizados	✅ (~50 linhas)	❌	❌	❌	❌
Grafo de conhecimento	✅ (links de arquivo/código)	❌	Parcial	❌	Grafo de entidades (pessoas)
Histórico de versões de arquivo	✅ (ilimitado)	❌	❌	❌	❌ (purga-e-substitui)
MCP nativo	✅	✅	✅	✅	✅
Roda localmente	✅	Nuvem	Empresarial	✅	✅
Código aberto	MIT	❌	Parcial	✅	MIT
Preço	Grátis	$20-200/mês	$$$/mês	Grátis	Grátis

O RTFM é a única opção de código aberto que indexa conteúdo multi-domínio com parsing estrutural, um grafo de conhecimento em nível de código e histórico ilimitado por arquivo. Esse é o nicho.

Diferente do MemPalace especificamente: o MemPalace é uma memória em nível de entidade para conversas (triplas quem/projeto/decisão em SQLite, além de chunks verbatim em ChromaDB). O RTFM é uma camada de recuperação para artefatos — parsed por formato, vinculados no nível de arquivo, versionados ao longo do tempo. Os dois são empilháveis, não concorrentes.

Para um detalhamento mais profundo das escolhas de design por trás de qualquer RAG (chunking, recuperação, aumento, integração, atualização, armazenamento), veja Fundamentos de RAG — os 6 eixos →

---

Memória que sobrevive às sessões

Entre sessões, a maioria dos agentes esquece. O RTFM indexa os próprios arquivos de memória do Claude Code em todos os projetos da sua máquina, com histórico completo de versões.

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

• Índice entre projetos — um único banco de dados em ~/.rtfm/memory.db vê todos os diretórios ~/.claude/projects/*/memory/ na sua máquina. Pergunte rtfm_search("OAuth auth decisions") e obtenha resultados de todos os seus 18 projetos.
• Histórico de versões ilimitado — cada alteração em um arquivo de memória é capturada (sem poda). rtfm_history <slug> retorna a evolução completa.
• Captura automática no SessionEnd — um comando instala um hook global do Claude Code. Cada sessão que você fecha captura uma nova captura.
• Curado, não verbatim — o RTFM indexa as notas que o agente já curou durante a sessão (pequenas, estruturadas, densas em sinal). Filosofia diferente do MemPalace, que indexa transcrições completas de conversas em ChromaDB (grandes, ruidosas, precisam de filtragem semântica agressiva).

---

Modo vault Obsidian

O RTFM é a camada de recuperação para o padrão Karpathy LLM Wiki. O próprio Karpathy escreveu: "em pequena escala, o arquivo de índice é suficiente, mas conforme a wiki cresce, você quer busca adequada." Isso é busca adequada.

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

• Detecta .obsidian/, propõe um mapeamento pasta → corpus
• Resolve [[wikilinks]] seguindo as regras do Obsidian → armazenado como arestas de grafo
• Gera _rtfm/ com navegação nativa do Obsidian (índice, grafo com Mermaid, hubs, órfãos, frontmatter Dataview)
• Testado em um vault de pesquisa com 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

O LLM ainda escreve sua wiki. O RTFM cuida da recuperação que index.md não consegue escalar.

Guia completo do Obsidian →

---

Integração NotebookLM

O RTFM combina naturalmente com notebooklm-mcp. O NotebookLM limita você a 50 consultas/dia por notebook; o RTFM remove esse teto indexando respostas localmente — pergunte uma vez, recupere para sempre, offline, em milissegundos.

O endpoint /batch-to-vault do notebooklm-mcp escreve Q&A com citações como {slug}.md (markdown com frontmatter) além de {slug}.json (sidecar estruturado nblm-answer-v1). Ambos são garantidos de coexistir. Dois caminhos de integração, ambos disponíveis hoje:

• Caminho A — Markdown (zero configuração): coloque o vault no RTFM e rtfm sync. O parser markdown padrão divide cada resposta em chunks de pergunta / resposta / por-citação automaticamente. Sem mapeamento, sem esquema, sem código.
• Caminho B — Sidecar JSON (metadados tipados): coloque um mapeamento nblm-answer.yaml em .rtfm/mappings/. Cada arquivo de resposta .json produz chunks tipados com notebook_id, source_name, citation_marker consultáveis via SQL, além de candidatos a arestas cites entre respostas e fontes.

Use o Caminho A, a menos que você precise especificamente filtrar ou criar grafos por campos de citação estruturados.

Receita completa do NotebookLM →

---

O que medi

Executei dois tipos de benchmarks. O quadro honesto é cheio de nuances — a recuperação ajuda mais em tarefas que são realmente solucionáveis e onde o agente está gastando tempo procurando coisas.

Tarefa com muitos documentos: geração de artigo fiscal francês (B10)

Escrever um artigo regulado de ~50 páginas a partir de um corpus de código legal, jurisprudência e doutrina administrativa. Mesmo agente (Claude Code + Sonnet 4), mesmo prompt, oito configurações testadas.

Configuração	Duração	Custo	Tokens
Linha de base (sem RTFM)	8m 16s	$22.61	8.21 M
Com RTFM (FTS padrão)	6m 58s	$11.14	3.22 M

Δ : −51 % custo, −61 % tokens, −16 % duração — com melhor precisão factual. Este é o caso de uso para o qual o RTFM foi construído: navegar em um corpus multi-domínio grande onde o grep perde o parágrafo certo.

Tarefa de código: FeatureBench (dataset LiberCoders)

11 tarefas, 3 repositórios de tamanhos variados, 4 condições (A = prompt padrão com caminhos de arquivo; B = descoberta, sem caminhos; C = RTFM FTS; D = RTFM híbrido), 3 execuções cada.

Repo	Tamanho	Onde o RTFM ajuda
metaflow	620 arquivos	Todos resolvem — RTFM não adiciona ganho mensurável
astropy	1.119 arquivos	Todas as condições 25–30 % de aprovação F2P; nenhuma resolve completamente
mlflow	8.255 arquivos	Todas as condições 0–5 % de aprovação F2P; nenhuma resolve completamente

Em uma única execução de escopo menor (test_stub_generator no metaflow), o RTFM reduziu o tempo do agente em −37 % vs. a linha de base sem caminhos. Nos repositórios maiores, as tarefas em si eram difíceis demais para o Sonnet 4 resolver dentro de um timeout de 20 minutos, independentemente da recuperação.

As ressalvas honestas

• Modelo único (Sonnet 4), agente único (Claude Code). Não é estatisticamente à prova de balas.
• Em repositórios pequenos (< 1k arquivos), grep é suficiente e o RTFM adiciona sobrecarga.
• O FeatureBench mede modificação de código, não recuperação de informações. É o benchmark errado para uma ferramenta de recuperação — estou rodando contra ele porque é o que existe. Benchmarks mais adequados (RepoQA, SWE-QA, LocAgent) estão no roadmap.

O que isso diz

RTFM vence de forma mensurável quando o gargalo é "encontrar o parágrafo certo em um corpus de 2.000 arquivos". Ele não torna tarefas insolúveis magicamente solúveis. O modelo ainda precisa fazer o trabalho — o RTFM apenas garante que ele tenha o contexto certo para fazer isso.

---

Para quem é

O RTFM funciona em qualquer lugar onde seu projeto não seja apenas código:

• LegalTech — Código + direito tributário + especificações regulatórias. Inclui parsers para XML Legifrance e BOFiP.
• Pesquisa — Código + artigos em LaTeX + conjuntos de dados. Inclui parsers para LaTeX e PDF.
• FinTech — Código + regulamentações financeiras + relatórios XBRL. Escreva um parser XBRL em 50 linhas.
• HealthTech — Código + prontuários médicos (HL7/FHIR) + diretrizes clínicas.
• Devs solo com projetos grandes — Pare de ver seu agente buscar nos mesmos 8.000 arquivos a cada sessão.
• Usuários de Obsidian / PKM — Torne seu vault realmente pesquisável pela sua IA.
• Qualquer indústria regulamentada — Se seu projeto mistura código com documentos de domínio, o RTFM é para você.

---

Lista completa de recursos

Busca e recuperação

• Busca full-text FTS5 — instantânea, zero configuração, funciona de imediato
• Busca semântica — embeddings opcionais (FastEmbed/ONNX, sem necessidade de GPU)
• Modo híbrido — combine ambos, classifique por pontuação de relevância
• Metadados primeiro — resultados retornam caminhos de arquivo + pontuações (~300 tokens), não despejos de conteúdo
• Divulgação progressiva — o agente expande apenas os chunks que realmente precisa
• Grafo de conhecimento — wikilinks + imports Python resolvidos como arestas do grafo, detecção de hubs, classificação por centralidade

Indexação 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 puro
• Extensível — adicione qualquer formato em ~50 linhas de Python
• Hooks de sincronização automática — o índice permanece atualizado a cada prompt, zero trabalho manual
• Incremental — reindexa apenas o que mudou

Integração

• Plugin nativo para Claude Code — /plugin install rtfm@roomi-fields/rtfm, auto-inicialização por projeto
• Servidor MCP em Python puro — 0 dependências externas, sem SDK mcp / pydantic / binários nativos
• Multiplataforma — Linux, macOS, Windows, WSL (requer apenas Python ≥ 3.10 no PATH)
• 13 ferramentas MCP — busca, contexto, expandir, grafo, histórico, sincronizar, tags, ...
• Fallback de instalação manual — pip install rtfm-ai para Cursor, Codex, Claude Desktop chat, qualquer outro cliente MCP
• CLI + API Python — scriptável para pipelines
• Não invasivo — não toca no seu código, não substitui seu editor

---

A arquitetura de parsers

Precisa indexar um formato que ninguém suporta? Escreva um parser em ~50 linhas.

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,
            )

Coloque-o no seu projeto, reinicie o Claude Code, e seu agente de IA médica agora entende registros FHIR.

Dois níveis de integração JSON

Para formatos baseados em JSON especificamente, o RTFM oferece um segundo caminho de extensibilidade que não requer nenhum Python:

Nível	O que você faz	O que você obtém
1. Genérico	Nada. Apenas indexe o arquivo.	Cada chave de nível superior vira um chunk. A busca full-text funciona nos valores.
2. Mapeado	Coloque um mapeamento YAML em .rtfm/mappings/ (~30 linhas).	Chunks tipados com metadados declarados, títulos personalizados, extração foreach sobre arrays, candidatos a arestas. O projeto produtor (NotebookLM, Linear, Notion, OpenAPI…) fornece o mapeamento; o RTFM permanece genérico.

Consulte mapeamentos de esquema JSON para a referência completa, e RTFM × NotebookLM para uma receita concreta.

Parsers integrados

Parser	Extensões	Estratégia
Markdown	.md	Divisão por cabeçalhos, extração de frontmatter YAML
Python	.py	Baseado em AST: cada classe/função = 1 chunk
LaTeX	.tex	Divisão por \section, \chapter, etc.
YAML	.yaml, .yml	Divisão por chaves de nível superior
JSON	.json	Divisão por chaves de nível superior ou elementos de array
TOML	.toml	Tabelas de nível superior; emite arestas depends_on (PEP 621, Cargo, Poetry)
Shell	.sh, .bash, .zsh	Chunking ciente de funções
PDF	.pdf	Baseado em páginas (pip install rtfm-ai[pdf])
Legifrance XML	.xml	Códigos legais franceses (formato LEGI)
BOFiP HTML	.html	Doutrina tributária francesa
SQLite	.sqlite, .sqlite3, .db	Esquema + linhas de amostra por tabela; arestas FK (somente leitura)
Jupyter	.ipynb	Agrupa células por cabeçalho markdown; saídas descartadas
CSV / TSV	.csv, .tsv	Cabeçalho + linhas de amostra + inferência leve de tipos
XLSX	.xlsx	Esquema por planilha + amostra (pip install rtfm-ai[xlsx])
Texto puro	.js, .ts, .rs, .go, ...	Chunks por limites de linha (~500 caracteres)

---

Ferramentas MCP

Ferramenta	O que faz
rtfm_search	Busca no índice (FTS, semântica ou híbrida)
rtfm_context	Obtém contexto relevante para um assunto (somente metadados)
rtfm_expand	Mostra todos os chunks de uma fonte com conteúdo completo
rtfm_discover	Varredura rápida da estrutura do projeto (~1s, sem necessidade de indexação)
rtfm_books	Lista documentos indexados
rtfm_stats	Estatísticas da biblioteca
rtfm_sync	Sincroniza um diretório (incremental)
rtfm_ingest	Ingere um único arquivo
rtfm_tags	Lista todas as tags
rtfm_tag_chunks	Adiciona tags a chunks específicos
rtfm_remove	Remove um arquivo do índice
rtfm_graph	Mostra o grafo de dependências de uma fonte (imports, links)
rtfm_history	Histórico de versões de arquivos e snapshots de memória

---

Referência 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 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()

---

Onde o RTFM se encaixa

O RTFM não é um gerenciador de tarefas. Não é um framework de agentes. É a camada de conhecimento que seu agente precisa por baixo do que você já está usando.

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

Sem o RTFM, seu orquestrador dirige um agente que alucina. Com o RTFM, o agente sabe sobre o que está construindo.

---

Contribuindo

Adicionar um parser é a maneira mais fácil de contribuir — e a mais impactante. Consulte CONTRIBUTING.md.

Encontrou um bug? Tem uma ideia? Abra uma issue.

Agradecimentos

@AVeryTastyRaspberry fez o RTFM rodar em Windows nativo. O RTFM é desenvolvido em Linux, e todos os comandos estavam quebrados lá — o CLI morria no import antes de conseguir analisar um argumento. O relatório (#8) apontou a linha; os testes que se seguiram, em uma máquina real com Windows 11 e verificados contra tasklist em vez das próprias afirmações do RTFM, encontraram mais cinco defeitos por trás dela e confirmaram cada correção. #9 então rastreou as janelas de console que continuavam aparecendo. Essa é uma plataforma que este projeto não poderia suportar de outra forma.

Licença

MIT — use, faça fork, estenda, publique.

Autor

Romain Peyrichou — @roomi-fields

---