Alguns meses depois de começar minha prática solo de engenharia agêntica, me deparei com um problema que não havia antecipado: minha documentação estava crescendo mais rápido do que eu conseguia navegar por ela.
Eu tinha um CLAUDE.md para cada projeto, um diretório planning/ com registros de decisões e arquivos de status, um backlog de conteúdo para o blog, decisões arquiteturais entre projetos e um changelog. Tudo estava correto. Nada estava conectado. Quando precisei responder "por que escolhi pgvector em vez de Pinecone para o pipeline RAG?" tive que usar grep em quatro diretórios em dois repositórios.
A solução que construí é o que chamo de grafo de conhecimento do Company Brain — um pipeline de ingestão de documentação que lê todos os meus arquivos de planejamento, extrai entidades e relacionamentos, e os armazena em um grafo estruturado que qualquer agente do meu sistema pode consultar.
O problema com documentação plana
Arquivos Markdown planos são fáceis de escrever e armazenar. Mas não escalam bem quando as informações mais interessantes estão nas conexões entre os documentos.
Meu sistema de automação de suporte faz referência a um help-desk de clientes de-identificado. Esse mesmo sistema é o tema de vários posts do blog, um cartão de projeto no meu site de portfólio e um módulo de aprendizado sobre servidores MCP. Se estou escrevendo um novo post e quero saber em todo lugar que descrevi esse sistema publicamente, uma busca em arquivos planos me dá nomes de arquivos. Um grafo de conhecimento me dá um relacionamento tipado: (BlogPost "mcp-customer-support") -[DESCRIBES]-> (System "support-automation").
Essa distinção importa quando você está construindo agentes que raciocinam sobre o próprio trabalho. Um agente que consegue percorrer relacionamentos em vez de apenas escanear texto é um assistente fundamentalmente mais útil.
Arquitetura do pipeline de ingestão
O grafo de conhecimento do Company Brain tem três camadas:
- Ingestão de documentos — ler arquivos Markdown e JSON, extrair conteúdo estruturado
- Extração de entidades — usar Claude para identificar entidades (sistemas, decisões, posts, projetos) e seus relacionamentos
- Armazenamento em grafo — persistir arestas e nós para recuperação
Construí isso sobre o meu framework de orquestração Python, que já tinha um modelo de fila de tarefas que eu podia reutilizar. Cada arquivo no diretório de planejamento se torna uma tarefa de ingestão.
Aqui está o loop de ingestão central:
Tratando relacionamentos entre repositórios
Minha prática abrange dois repositórios: learn-ai (o site de portfólio) e python-orchestration-system (o framework agêntico). O repositório Company Brain mantém contexto entre projetos que faz referência a ambos.
O desafio é que uma decisão em python-orchestration-system/planning/decisions/ pode fazer referência a uma funcionalidade visível apenas em learn-ai/content/projects/. Meu pipeline de ingestão precisa resolver essas referências sem mesclar os repositórios.
Resolvi isso com um esquema de ID canônico: cada entidade recebe um ID prefixado que codifica seu repositório e caminho. Um sistema chamado support-automation no repositório de orquestração Python se torna python-orch:system:support-automation. O cartão de projeto do portfólio para o mesmo sistema se torna learn-ai:project:ai-chatbot-rag. O Company Brain armazena uma aresta SAME_AS conectando os dois.
Armazenamento e consulta do grafo
Armazeno o grafo em um arquivo JSON estruturado que qualquer agente pode ler. Para minha escala atual — algumas centenas de nós em dois projetos — isso é rápido o suficiente. Se o grafo crescesse significativamente, eu migraria para um banco de dados de grafo adequado, mas no momento o overhead não se justifica.
A coisa mais importante que construí foi uma função de percurso de relacionamentos que permite aos agentes fazer perguntas como "o que essa decisão afeta?" ou "quais posts do blog descrevem esse sistema?":
Como uso isso na prática
O grafo de conhecimento alimenta alguns fluxos de trabalho específicos do meu dia a dia:
Antes de escrever um post do blog, consulto o grafo para todas as entidades relacionadas ao tema do post. Isso traz à tona decisões anteriores, conteúdo existente sobre o mesmo assunto e cartões de projeto que devo referenciar — sem precisar lembrar onde cada peça está.
Ao criar um novo registro de decisão, o grafo me diz quais sistemas existentes a decisão afeta e sinaliza quaisquer conflitos com decisões anteriores sobre o mesmo tema.
Quando um agente está trabalhando em tarefas de spec, ele pode consultar o grafo para entender o contexto mais amplo do código que está tocando. Um spec para o caminho de aprendizado de MCP, por exemplo, pode automaticamente puxar o cartão de projeto do sistema de automação de suporte e as decisões anteriores sobre módulos de aprendizado.
O benefício real é que parei de perder contexto. Quando você está executando múltiplos projetos de longo prazo em paralelo, o grafo de conhecimento se torna o tecido conjuntivo que mantém tudo coerente — não apenas para mim, mas para cada agente trabalhando em meu nome.
O que eu faria diferente
O prompt de extração atual funciona bem, mas produz tipos de relacionamentos inconsistentes. "USES", "DEPENDS_ON" e "REFERENCES" acabam descrevendo coisas muito similares em documentos diferentes. Estou planejando definir uma ontologia estrita antecipadamente e passá-la como parte do system prompt para que Claude escolha de um vocabulário controlado.
Também ainda não resolvi o problema das atualizações incrementais. No momento, o pipeline reingestiona tudo a cada execução. O próximo passo é a ingestão baseada em diff: rastrear os timestamps de modificação dos arquivos e reprocessar apenas os que mudaram desde a última execução.
Se você está executando uma prática com múltiplos projetos ou um sistema agêntico com documentação de planejamento significativa, construir um grafo de conhecimento vale o tempo de configuração. O benefício composto do contexto conectado escala com cada documento que você adiciona.