LLM Wiki de Karpathy: uma base de conhecimento locale

#LLM Wiki: o princípio em dois minutos

Em 2 de abril de 2026, Andrej Karpathy descreve no X como usa modelos de linguagem para criar bases de conhecimento pessoais. Dois dias depois, publica um gist intitulado « LLM Wiki », que apresenta como um padrão para construir esse tipo de base com um LLM. Os dois textos são curtos e podem ser lidos em dez minutos; os links estão no final da página.

O gist parte de uma constatação: a maioria dos usos que misturam LLM e documentos se parece com RAG. Você deposita arquivos, o sistema recupera trechos no momento da pergunta e o modelo redige uma resposta. Karpathy reconhece que isso funciona, mas observa que o modelo redescobre o conhecimento a cada pergunta e que nada se acumula. Uma pergunta que exige cruzar cinco documentos pede que os mesmos trechos sejam recuperados e reunidos todas as vezes.

O LLM Wiki desloca o trabalho para a etapa anterior. Quando uma nova fonte chega, o modelo não se limita a indexá-la: ele a lê, extrai o essencial e integra o conteúdo a um conjunto de páginas Markdown interligadas. Ele atualiza as páginas existentes, revisa as sínteses e registra os pontos em que a nova fonte contradiz o que estava escrito. O gist fala de um artefato persistente que melhora com o tempo: as verificações cruzadas já foram feitas quando a pergunta chega.

A distribuição dos papéis é clara no texto. O humano escolhe as fontes, explora e faz as perguntas. O modelo faz todo o resto: resumir, relacionar, classificar, manter os registros. Karpathy diz trabalhar com o agente aberto de um lado da tela e o Obsidian do outro, e resume a instalação com uma imagem: o Obsidian é o IDE, o LLM é o programador, a wiki é a base de código.

#Três camadas: fontes, wiki, convenções

O gist descreve uma arquitetura em três camadas. Nenhuma exige uma ferramenta específica: são pastas e arquivos de texto.

As fontes brutas

Sua coleção de documentos: artigos, trabalhos de pesquisa, imagens, arquivos de dados. Eles são imutáveis: o modelo os lê e nunca os modifica. São eles, e não a wiki, que têm valor de referência.

O wiki

Uma pasta de arquivos Markdown redigidos pelo modelo: resumos de fontes, páginas de entidades, páginas de conceitos, comparações, síntese geral. Essa camada pertence ao modelo, que cria as páginas, atualiza-as e mantém os links. Você lê, ele escreve.

O arquivo de convenções

Um documento que informa ao modelo como o wiki está estruturado, quais regras seguir e como proceder para ingerir uma fonte, responder a uma pergunta ou fazer a limpeza. O gist cita CLAUDE.md para o Claude Code e AGENTS.md para o Codex. É esse arquivo que transforma um agente generalista em um mantenedor disciplinado de wiki.

Dois arquivos específicos ajudam o modelo e você a se orientarem. O primeiro, index.md, é um catálogo: cada página aparece nele com um link e um resumo de uma linha, organizada por categoria. Para responder a uma pergunta, o modelo lê primeiro o índice e depois abre as páginas úteis. O segundo, log.md, é um registro cronológico ao qual apenas adicionamos conteúdo: ingestões, perguntas e rodadas de verificação.

O gist sugere começar cada entrada do log com um prefixo regular, o que permite filtrá-lo com ferramentas Unix simples. O exemplo fornecido tem este formato:

## [2026-04-02] ingest | Article Title

#Três operações: ingerir, consultar, verificar

Ingerir (ingest)

Você coloca uma fonte na pasta de fontes brutas e pede ao modelo que a processe. De acordo com o gist, ele lê a fonte, discute os pontos principais com você, escreve uma página de resumo, atualiza o índice e as páginas de entidades e conceitos relevantes e depois adiciona uma entrada ao registro. Karpathy indica que uma única fonte pode afetar de 10 a 15 páginas do wiki.

Consultar (query)

Você faz uma pergunta. O modelo procura as páginas pertinentes, lê-as e redige uma resposta que cita suas referências. O gist insiste em um ponto: uma boa resposta pode ser armazenada no wiki como uma nova página, para que suas explorações se acumulem em vez de desaparecerem no histórico de uma conversa.

Verificar (lint)

De vez em quando, você pede ao modelo uma verificação de integridade da wiki: contradições entre páginas, afirmações superadas por fontes mais recentes, páginas órfãs sem links recebidos, conceitos citados sem uma página dedicada, referências ausentes.

Por que confiar esse trabalho a um modelo? O argumento do gist é simples: o que acaba com os wikis pessoais não é a leitura nem a reflexão, mas a manutenção dos registros. Atualizar as referências, manter os resumos atualizados, identificar contradições: a carga de manutenção cresce mais rápido que o valor do wiki, e nós desistimos. Um modelo não se cansa e pode modificar quinze arquivos de uma só vez. Karpathy relaciona a ideia ao Memex imaginado por Vannevar Bush em 1945.

#Pré-requisitos para uma wiki mantida por um modelo local

O gist não pressupõe nenhum fornecedor específico. Ele precisa de um agente capaz de ler e escrever arquivos, controlado por um modelo. Localmente, isso resulta nos seguintes componentes.

Ollama, atualizado

Ele serve o modelo em http://localhost:11434. O comando ollama launch usado mais abaixo só existe nas versões recentes. A instalação é abordada em nosso guia « Instalar Ollama ».

Um agente com acesso aos arquivos

Uma interface de conversa não basta: é preciso uma ferramenta que abra, crie e modifique arquivos no disco. O exemplo abaixo usa o OpenCode, um agente open source no terminal citado no gist, que lê um arquivo AGENTS.md colocado na raiz da pasta.

Um modelo que sabe chamar ferramentas

Ler e escrever arquivos passa por chamadas de ferramentas. Escolha um modelo que exiba a capacidade tools na biblioteca Ollama. Nosso guia « OpenCode + Ollama » lista vários, entre eles qwen3-coder:30b, devstral-small-2:24b e gpt-oss:20b.

Memória para contexto

Referências em Q4_K_M apenas para os pesos: cerca de 5 GB para 7 bilhões de parâmetros, 9 GB para 14 bilhões, 19 GB para 32 bilhões. A documentação do Ollama exige pelo menos 64 000 tokens de contexto para os agentes, que se somam a esses números.

Git

O wiki é apenas uma pasta de arquivos Markdown: o gist observa que transformá-lo em um repositório git fornece o histórico de versões sem acrescentar nada.

Obsidian (opcional)

Para ler o wiki, seguir os links e exibir o grafo das páginas. Qualquer editor Markdown serve; o Obsidian não participa da redação.

#Configuração com Ollama, passo a passo

Os comandos foram escritos para macOS e Linux; no Windows, o mais simples é usar o WSL. A estrutura de pastas e o arquivo de convenções são exemplos a serem adaptados: o gist esclarece que a estrutura das pastas, as convenções e o formato das páginas dependem do seu domínio e do seu modelo, e que tudo ali é opcional e modular.

1. 01
   Criar a pasta e o repositório

   Uma pasta para as fontes brutas, uma pasta para as páginas, um índice, um registro, tudo sob git.
2. 02
   Escrever o arquivo de convenções

   Um AGENTS.md na raiz que descreve a estrutura, as regras de escrita e os três procedimentos: ingestão, pergunta e verificação.
3. 03
   Iniciar o modelo e o agente

   Ollama serve um modelo capaz de chamar ferramentas, com 64.000 tokens de contexto; o OpenCode é aberto na pasta do wiki.
4. 04
   Ingerir uma primeira fonte

   Um único documento, processado diante dos seus olhos, revisado e depois salvo no git.
5. 05
   Consultar e organizar as respostas

   As perguntas são feitas no wiki; as sínteses úteis se tornam páginas.
6. 06
   Verificar regularmente

   Uma etapa de verificação que lista as contradições, as páginas órfãs e os links quebrados.

#1. Criar a pasta e o repositório

mkdir -p ~/wiki/raw
mkdir -p ~/wiki/wiki/sources ~/wiki/wiki/entites ~/wiki/wiki/concepts
cd ~/wiki
touch wiki/index.md wiki/log.md
git init

A pasta raw/ receberá seus documentos, e a pasta wiki/ receberá as páginas redigidas pelo modelo. Os nomes são livres, desde que a separação entre as duas permaneça visível.

#2. Escrever o arquivo de convenções

Esta é a peça que mais importa. Sem ela, o agente improvisa uma estrutura diferente a cada sessão. Crie um arquivo AGENTS.md na raiz de ~/wiki, por exemplo com base nisto:

# Conventions du wiki

Tu es le mainteneur de ce wiki. Tu écris et tu mets à jour les pages.
L'humain choisit les sources et pose les questions.

## Structure
- raw/ : sources brutes. Lecture seule : ne jamais modifier, renommer ni supprimer.
- wiki/sources/ : une page de résumé par source.
- wiki/entites/ : une page par personne, organisation, outil ou produit.
- wiki/concepts/ : une page par notion.
- wiki/index.md : catalogue de toutes les pages (lien + résumé d'une ligne), par catégorie.
- wiki/log.md : journal chronologique, ajout seul.

## Règles d'écriture
- Noms de fichiers en minuscules, avec tirets, sans accents.
- Liens internes au format [[nom-de-page]].
- Chaque affirmation renvoie au fichier de raw/ dont elle vient.
- Si deux sources se contredisent, garder les deux versions et le signaler.
- Avant de créer une page, vérifier dans l'index qu'elle n'existe pas déjà.

## Ingestion
Quand on te demande d'ingérer un fichier de raw/ :
1. Lire la source en entier.
2. Présenter les points clés et attendre la validation.
3. Écrire la page de résumé dans wiki/sources/.
4. Mettre à jour ou créer les pages d'entités et de concepts concernées.
5. Mettre à jour wiki/index.md.
6. Ajouter une entrée à wiki/log.md : ## [AAAA-MM-JJ] ingest | Titre

## Question
1. Lire wiki/index.md, puis les pages utiles.
2. Répondre en citant les pages et les sources brutes.
3. Ne rien affirmer qui ne figure pas dans le wiki ; dire ce qui manque.
4. Si la réponse apporte une synthèse nouvelle, proposer de l'enregistrer comme page.

## Vérification
Signaler sans corriger d'office : contradictions, affirmations dépassées,
pages orphelines, concepts cités sans page, liens cassés.

Este arquivo é nosso, não do Karpathy: o gist descreve o papel do arquivo de convenções sem fornecer um modelo para ele e recomenda fazê-lo evoluir junto com o modelo à medida que você descobre o que funciona no seu domínio. Mantenha-o curto. O agente o relê a cada sessão, e cada linha ocupa espaço no contexto.

#3. Iniciar o modelo e o agente

Baixe um modelo capaz de chamar ferramentas e abra o OpenCode na pasta do wiki. O comando ollama launch opencode inicia o OpenCode com um modelo servido por Ollama, a ser escolhido no seletor. A instalação do próprio OpenCode está descrita em nosso guia « OpenCode + Ollama ».

# Un modèle généraliste avec appel d'outils (à adapter à votre mémoire)
ollama pull gpt-oss:20b

# Ouvrir l'agent dans le dossier du wiki
cd ~/wiki
ollama launch opencode

Resta o contexto. Segundo a documentação do Ollama, a janela padrão depende da VRAM (4.000 tokens abaixo de 24 GB, 32.000 entre 24 e 48 GB), enquanto os agentes exigem pelo menos 64.000. A variável OLLAMA_CONTEXT_LENGTH a define na inicialização do servidor; se o Ollama já estiver funcionando como aplicativo ou serviço, ajuste o valor nas configurações dele em vez de iniciar um segundo servidor.

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

# Dans un autre terminal, une fois le modèle chargé :
ollama ps

O comando ollama ps indica se o modelo cabe inteiramente na GPU. Se transbordar para o processador, cada ingestão ficará muito lenta: use um modelo menor antes de reduzir o contexto.

#4. Ingerir uma primeira fonte

Adicione um primeiro documento em raw/, de preferência em Markdown ou texto. Para páginas da web, o gist recomenda a extensão Obsidian Web Clipper, que converte um artigo em arquivo Markdown. Em seguida, dê a instrução ao agente:

Ingère raw/mon-premier-article.md en suivant AGENTS.md.
Présente-moi d'abord les points clés et attends ma validation avant d'écrire.

O agente lê a fonte, propõe seus pontos principais e depois cria e modifica as páginas. Revise o resultado antes de avançar: a página de resumo, as páginas das entidades criadas, o índice, o registro. Em seguida, salve o estado do wiki.

git status
git add -A
git commit -m "ingest: mon-premier-article"

#5. Consultar e organizar as respostas

Depois de consultar algumas fontes, faça suas perguntas ao agente na mesma pasta. Peça explicitamente que ele cite suas páginas e fontes e diga o que o wiki não contém.

D'après le wiki, qu'est-ce qui distingue l'approche A de l'approche B ?
Cite les pages et les sources brutes utilisées, et signale ce qui manque.
Si la réponse apporte une synthèse nouvelle, enregistre-la dans wiki/concepts/
puis mets à jour l'index et le journal.

#6. Verificar regularmente

A cada poucas ingestões, execute uma rodada de verificação. Peça uma lista de problemas antes de qualquer correção: você mantém o controle sobre o que é mesclado, renomeado ou excluído.

Fais une passe de vérification du wiki en suivant AGENTS.md.
Liste les problèmes trouvés, sans rien modifier pour l'instant.

O log pode ser consultado sem agente. Com o prefixo regular das entradas, o comando fornecido no gist exibe as operações mais recentes (apenas o caminho é adaptado à nossa estrutura de diretórios):

grep "^## \[" wiki/log.md | tail -5

#LLM Wiki ou RAG: o que o chefe não substitui

O gist contrapõe o wiki ao RAG para tornar a ideia compreensível. Ele não diz que um substitui o outro, e este guia também não diz isso: as duas abordagens respondem a situações diferentes. Veja o que as diferencia, sem números, porque não temos uma medição para apresentar.

O momento do trabalho

Um RAG trabalha a partir da pergunta: ele busca trechos e depois o modelo redige. A wiki trabalha na ingestão: a síntese é escrita uma vez e depois relida a cada pergunta.

O que é preservado

Um RAG conserva trechos e seus vetores, ilegíveis como estão. O wiki conserva páginas redigidas que você pode ler, corrigir e versionar.

L'infrastructure

Um RAG exige um modelo de embeddings, um banco de dados vetorial e uma estratégia de segmentação. O wiki exige uma pasta e um agente. Segundo o gist, o índice é suficiente em uma escala moderada (da ordem de uma centena de fontes e algumas centenas de páginas) e evita configurar uma infraestrutura de RAG baseada em embeddings.

Fidelidade às fontes

Um RAG devolve ao modelo trechos originais. O wiki devolve uma reformulação escrita por um modelo, com o risco de erro que isso implica.

O volume

Um RAG é feito para grandes corpora. O wiki é limitado pelo que o modelo consegue ler de uma vez: o índice, as páginas úteis e a fonte precisam caber na janela de contexto.

Além da escala moderada, o gist reintroduz a própria pesquisa. Ele cita o qmd, um mecanismo de pesquisa local para arquivos Markdown que combina BM25, pesquisa vetorial e reclassificação por LLM, utilizável pela linha de comando ou como servidor MCP. Assim, um wiki grande acaba recorrendo aos componentes de um RAG, aplicados a páginas já sintetizadas em vez de documentos brutos. As duas abordagens se combinam mais do que se excluem.

Na prática, mantenha um RAG clássico quando o corpus for grande ou mudar constantemente (documentação empresarial, tickets, contratos), quando a resposta precisar reproduzir o trecho exato de um documento ou quando várias pessoas com direitos diferentes consultarem a mesma base. O LLM Wiki é mais adequado para um assunto que se aprofunda durante semanas: monitoramento, pesquisa, leitura de um livro, preparação de um dossiê. Esses são usos que o próprio gist cita.

#Limitações a conhecer, sobretudo localmente

Os erros também se acumulam

Um erro de resumo escrito em uma página será relido, citado e propagado para as páginas seguintes. Em um RAG, uma resposta ruim desaparece com a conversa; em um wiki, ela permanece. Essa é a razão de ser das referências sistemáticas às fontes brutas e da releitura das modificações.

Um modelo local tem menos margem

A ingestão exige seguir uma instrução longa, ler vários arquivos e modificar cerca de dez deles sem esquecer nenhum. Em geral, os modelos pequenos lidam pior com esse tipo de tarefa longa do que os modelos grandes hospedados por trás dos agentes citados no gist. Avalie com suas próprias fontes, começando pequeno.

A janela de contexto limita tudo

Uma fonte muito longa, um índice que cresceu e dez páginas para revisar nem sempre cabem em 64 000 tokens. Divida as fontes volumosas por capítulo e mantenha páginas curtas.

A ingestão leva tempo

Cada fonte desencadeia uma série de leituras e escritas. Em uma máquina modesta, conte com um processamento fonte por fonte, em vez de processar import d uma biblioteca inteira em uma noite.

A estrutura deriva

Sem regras rigorosas, o agente cria duplicatas (a mesma entidade com dois nomes) e páginas que nada conecta. As regras de nomenclatura do arquivo de convenções e a etapa de verificação existem para isso.

#Dicas e solução de problemas

O agente pula etapas da ingestão

O contexto provavelmente é curto demais: a instrução sai da janela no meio do processo. Verifique o valor de OLLAMA_CONTEXT_LENGTH, encurte AGENTS.md ou divida a fonte.

O agente descreve o que faria, sem escrever nada

O modelo lida mal com chamadas de ferramentas. Escolha um modelo que exiba a capacidade tools na biblioteca Ollama.

A mesma entidade aparece com dois nomes

Peça uma rodada de verificação direcionada para duplicatas, valide as fusões uma a uma e depois adicione a regra de nomenclatura que faltava ao arquivo de convenções.

O índice fica longo demais

Divida-o por categoria, com um índice principal que aponte para índices secundários, ou adicione uma ferramenta de busca nos arquivos Markdown, como o qmd mencionado no gist.

As respostas ignoram páginas existentes

O índice não foi atualizado durante uma ingestão. Faça-o ser reconstruído a partir do conteúdo da pasta wiki/ e depois verifique o log.

#Implementações prontas para usar

Você não precisa escrever tudo à mão. O Hermes Agent, o agente open source da Nous Research, documenta uma skill integrada chamada llm-wiki, classificada na categoria pesquisa, que reproduz esse padrão. Se você já usa esse agente com Ollama, este é um ponto de partida mais rápido; a página de documentação, no link abaixo, descreve seu funcionamento. O princípio continua o mesmo: leia as convenções antes de confiar suas fontes a elas.

#Fontes

Tudo o que é dito sobre o padrão vem do post e do gist de Andrej Karpathy. As configurações do Ollama e do OpenCode vêm da documentação deles, já citada em nosso guia “OpenCode + Ollama”. Leia novamente essas páginas antes de colar um comando: essas ferramentas evoluem rapidamente.

https://x.com/karpathy/status/2039805659525644595

https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/research/research-llm-wiki

https://docs.ollama.com/context-length

https://docs.ollama.com/integrations/opencode

#Para se aprofundar

O LLM Wiki está no cruzamento de vários assuntos já tratados no site. Cada um desses guias aborda o que este deixa deliberadamente de lado.

RAG local: introdução

Embeddings, banco de dados vetorial, divisão em partes: como funciona o RAG clássico, algo que você precisa conhecer para saber quando ele continua sendo a escolha certa. https://quelllm.fr/guide/rag-local-introduction

Obsidian + LLM local

Conectar um modelo local a um cofre do Obsidian com os plugins Copilot e Smart Connections, para conversar com notas que você mesmo escreve. https://quelllm.fr/guide/obsidian-llm-local-ollama

NotebookLM localmente

As ferramentas de código aberto que reproduzem cadernos de fontes e respostas citadas, sem uma wiki intermediária. https://quelllm.fr/guide/notebooklm-local-alternative

Fine-tuning vs RAG

Karpathy menciona em sua publicação, como possibilidade de exploração, o ajuste fino de um modelo com os dados de sua base. Este guia ajuda a decidir se o esforço vale a pena. https://quelllm.fr/guide/fine-tuning-vs-rag-choisir

OpenCode + Ollama

A instalação do agente usado aqui, a configuração do contexto e as permissões. https://quelllm.fr/guide/opencode-ollama-agent-terminal