Graphify para documentação e papers: dá para mapear uma pasta sem código?

Sim. Segundo a documentação oficial, o Graphify aceita pastas com docs, papers, imagens e vídeos, não só código. Markdown, HTML, .rst, .txt, YAML e PDF entram direto, .docx e .xlsx exigem o extra office e vídeo/áudio exigem o extra video. Esses formatos passam por uma etapa semântica feita pelo modelo do assistente, então o conteúdo sai da sua máquina, e o resultado fica em graphify-out/ (graph.html, GRAPH_REPORT.md e graph.json).
Este guia é para quem tem uma pasta cheia de anotações técnicas em markdown, PDFs de papers ou documentação de projeto e quer ver como os conceitos se conectam. Se o objetivo for mapear um repositório de código, o fluxo é parecido, mas sem a etapa semântica que este guia detalha.
O que você precisa antes de mapear uma pasta de documentação
Você precisa de três coisas: o pacote oficial instalado, os extras certos para os formatos da sua pasta e um assistente que rode a skill /graphify, como o Claude Code.
Se liga no nome do pacote, porque é aí que muita gente erra. No PyPI, o oficial é o graphifyy, com DOIS y. Existem outros pacotes chamados graphify por lá, mas eles não têm relação com o projeto.
A instalação recomendada usa uv tool install graphifyy, que cria um ambiente isolado. A alternativa é o pipx. Para conferir se deu certo, rode graphify --version:

Black Week do Nexus
A formação de IA mais completa do Brasil
- 7 formações · 112 cursos · 26 mil alunos
uv tool install graphifyy
# ou
pipx install graphifyy
graphify --version
Segundo a visão geral da documentação, o pacote instala o comando graphify e o servidor MCP graphify-mcp. O projeto é publicado sob a licença Apache-2.0.
Os extras dependem do que tem na sua pasta:
- O extra office adiciona suporte a
.docxe.xlsx - O extra video adiciona vídeo e áudio, com faster-whisper e yt-dlp
Os dois são instalados com uv tool install, colocando o nome do extra entre colchetes logo depois de graphifyy, com tudo entre aspas.
O código-fonte fica no repositório oficial Graphify-Labs/graphify. O endereço antigo safishamsi/graphify redireciona para lá.
Quais formatos o Graphify aceita fora do código e o que acontece com cada um
A página Supported inputs lista documentos, Office e PDF, e o README completa com imagens, vídeo e áudio. Cada categoria tem um tratamento diferente:
- Documentos (
.md,.mdx,.qmd,.html,.txt,.rst,.yaml,.yml): passam pelo Claude para extrair conceitos, relações e justificativas de design - Office (
.docx,.xlsx): são convertidos para markdown e depois extraídos, desde que o extra office esteja instalado - PDF (
.pdf): passa por mineração de citações e extração de conceitos - Imagens (
.png,.jpg,.webp,.gif): entram na extração semântica, segundo o README da branch v8 - Vídeo e áudio (
.mp4,.mov,.mp3,.wave outros): são transcritos localmente com faster-whisper, e as transcrições ficam em cache emgraphify-out/transcripts/
No vídeo e no áudio, transcrição e processamento semântico são etapas separadas. Novas execuções pulam os arquivos que já foram transcritos.
Por que documentos não ficam só na sua máquina
Aqui está a maior diferença em relação ao uso com código, e vale entender o PORQUÊ.
O código é analisado localmente com gramáticas tree-sitter, de forma determinística e sem chave de API. Docs, PDFs, imagens e transcrições não têm uma "gramática" assim, então passam por uma etapa semântica.
Que etapa semântica? É o momento em que um modelo de IA lê o texto e decide quais conceitos existem e como se relacionam. Segundo o README, isso é feito pela skill /graphify com o modelo que a sessão da IDE estiver usando (por exemplo, Claude no Claude Code).

VPS Hostinger para seu sistema
10% OFF extraVPS com SSD NVMe e backups semanais. O cupom MATHEUSHORADECODAR é aplicado automaticamente pelo link.
Ver planos com 10% OFF →Ou seja, o conteúdo é enviado ao assistente de IA. Tome cuidado se a pasta tiver contrato, dado de cliente ou anotação interna.
Como a etapa semântica funciona por dentro
O documento how-it-works.md chama essa etapa de Pass 3. Em um corpus só de código, ela é pulada. Ela só roda quando há docs, papers, imagens ou transcrições.
O trabalho roda em paralelo com os subagentes do assistente. Cada subagente lê um lote de arquivos e devolve um fragmento JSON com nós, arestas e grupos.
Também dá para usar modelos configurados no lugar do assistente, como Gemini, Kimi, OpenAI, DeepSeek ou Ollama local. Para material sensível, o Ollama local é a opção da lista que roda na sua própria máquina.
Como mapear uma pasta de papers e anotações com o Graphify, passo a passo
O fluxo abaixo segue os comandos citados no README e na documentação.
- Instale e verifique o pacote. Rode
uv tool install graphifyye depoisgraphify --version. Se o comando responder com a versão, a instalação está ok.O erro comum deste passo: instalar o pacote
graphify(com um y só). Ele não tem relação com o projeto. O certo égraphifyy. - Instale o extra office se a pasta tiver Word ou Excel.
Use
uv tool installcom o extra office, no formato descrito na seção de requisitos.O erro comum deste passo: esperar que
.docxe.xlsxentrem no grafo sem o extra. Sem ele, esses arquivos não são tratados. Se a pasta tiver gravações, o raciocínio é o mesmo com o extra video. - Abra a pasta no Claude Code e gere o mapa. Com o Graphify instalado, digite no Claude Code:
/graphify - Adicione um paper por URL, se quiser. O README mostra este exemplo com um paper do arXiv:
/graphify add https://arxiv.org/abs/1706.03762O comando busca o paper e o adiciona ao grafo. Só o exemplo do arXiv aparece no README da branch main, então outros tipos de URL não estão confirmados.
- Consulte o grafo. O README cita três comandos:
/graphify query "quais anotações falam de autenticação?" /graphify path "Conceito A" "Conceito B" /graphify explain "Nome do Nó"As perguntas e os nomes acima são só exemplos, troque pelos conceitos da sua pasta. Os comandos percorrem o
graph.jsone mostram detalhes das arestas: tipo de relação, confiança e localização na fonte. - Atualize quando editar os documentos. Mudou uma anotação ou trocou um PDF? Rode:
/graphify --update
Isso atualiza os nós semânticos de forma incremental. Cada arquivo recebe uma impressão digital por hash de conteúdo, guardada em graphify-out/cache/, e arquivos inalterados são pulados.

Crie sistemas com IA para vender
Prompts, modelos e checklists para criar e publicar seu sistema com IA e preparar a oferta para o primeiro cliente.
Quero o e-book gratuito Receba o livro e os bônus no seu e-mail.O erro comum deste passo está documentado na issue #4814: um .graphify_partial.txt deixado por um --update pode segurar um doc em cache numa build completa posterior. Se um documento editado não refletir no grafo depois de uma build completa, vale olhar essa issue.
O que aparece em graphify-out/ depois de mapear documentação e papers
É em graphify-out/ que você confere se o mapa faz sentido. Segundo o README, a saída principal tem três arquivos:
graph.html: abre no navegador, com nós clicáveis, filtro e busca. Cada nó é um conceito e as cores representam as comunidades detectadasGRAPH_REPORT.md: traz conceitos-chave, conexões surpreendentes e perguntas sugeridasgraph.json: o grafo completo, que pode ser consultado sem reler os arquivos
Além deles, podem aparecer cache/ (impressões digitais dos arquivos extraídos) e transcripts/ (quando a pasta tem vídeo ou áudio).
Como ler EXTRACTED, INFERRED e AMBIGUOUS
Em papers, essa é a parte que mais importa revisar. O blog do Graphify explica as três marcas que cada relação recebe:
- EXTRACTED: lida diretamente da fonte
- INFERRED: inferência razoável, com pontuação de confiança
- AMBIGUOUS: marcada para revisão
Na prática, uma relação EXTRACTED tem respaldo no texto. Já INFERRED e AMBIGUOUS são onde o modelo interpretou, e aí cabe a você conferir no paper antes de citar a conexão em algum lugar.
Sem embeddings e sem banco vetorial
Se você conhece RAG, talvez espere um banco vetorial por trás. Não é o caso: o Graphify não guarda embeddings nem usa vector store. As perguntas são respondidas percorrendo o grafo.
Quando faz sentido usar o Graphify em documentação e pesquisa (e o que não foi testado)
Pelo que a documentação descreve, os cenários compatíveis são estes:
- Base de anotações técnicas em markdown:
.mde.mdxestão na lista de documentos suportados - Coleção de papers: PDFs passam por mineração de citações, e papers do arXiv entram com
/graphify add - Docs de projeto:
.rste.htmlestão entre os formatos aceitos - Gravações de reunião ou palestra: com o extra video, são transcritas localmente e entram na etapa semântica
Agora os limites, sem enfeite. A documentação diz que a pasta sem código é aceita e que o Pass 3 roda para docs, mas não há exemplo oficial de corpus só de documentação com o resultado mostrado.
Também não estão documentados a qualidade da extração em PDFs escaneados (sem camada de texto) ou cheios de fórmulas e tabelas, o tempo de processamento e o custo em tokens para uma pasta grande. Formatos como .ipynb, .pptx, .epub ou exports de Notion e Obsidian não aparecem na página Supported inputs.
Próximo passo: comece por uma pasta pequena de markdown
Escolha uma pasta pequena de notas que você conhece bem e rode /graphify nela. Como você sabe o que está escrito ali, fica fácil julgar se o mapa acertou.
Abra o graph.html, compare os conceitos-chave do GRAPH_REPORT.md com o conteúdo real e revise as arestas AMBIGUOUS. Se o resultado fizer sentido, aí vale crescer para os PDFs e as gravações 🙂.
E se você também quer mapear o repositório do projeto, rode o mesmo /graphify nele: o código é analisado localmente com tree-sitter, sem chave de API.
Perguntas frequentes
Dá pra consultar o grafo do Graphify sem abrir o Claude Code?
Sim. Segundo a documentação oficial, o grafo pode ser consultado pelo terminal, por um agente de código ou por um cliente MCP, usando o servidor graphify-mcp que é instalado junto com o pacote graphifyy.
O Graphify é gratuito para mapear papers e documentação?
O projeto é open source, publicado sob a licença Apache-2.0, e a instalação do pacote graphifyy via uv tool install ou pipx não tem custo. O que a documentação não detalha é o custo de tokens do modelo de IA usado na etapa semântica, que varia conforme o provedor escolhido.
Fontes consultadas
Consulta em .
Encontre outros guias no YouTube da Hora de Codar. Se quiser aprofundar o contexto, veja Como está o mercado de trabalho para PHP, dentro e fora do Brasil? #php.
Formações
Formação Vibe Coding
Do Prompt ao Produto: Crie Software Real com IA
- 474 aulas
- 20 projetos
- 39h 30min
Blog | Mais populares
O que é o Graphify e como ele muda a forma como o Claude Code entende seu projeto?
O Graphify transforma seu projeto em um grafo de conhecimento consultável pelo Claude Code, Cursor, Codex e Gemini CLI. Entenda como funciona.
Graphify funciona no Cursor, Codex e Gemini CLI ou só no Claude Code?
O Graphify funciona no Cursor, Codex, Gemini CLI e mais 14 assistentes: veja como a integração muda de ferramenta pra ferramenta antes de instalar.
O que é o graphify e como ele transforma seu projeto em um grafo de conhecimento?
O graphify transforma seu projeto em um grafo de conhecimento que a IA consulta direto, sem grep. Leitura do código é local, via tree-sitter, sem LLM.
