loletranga/Personal-Knowledge-Graph

Base de Conhecimento Pessoal × Grafo de Conhecimento (Baseado em Arquivos, Iterável)

Transforme um conjunto de documentos Markdown em uma rede de conhecimento "lembrável e rastreável": cada documento ganha uma camada de metadados frontmatter, conectados em um grafo usando três tipos de relação, e scripts geram camadas de destilação (registro de decisões + lista de adjacência do grafo) para que o Agente possa consultar ideias e contextos passados antes de analisar e decidir.

Conceitos Centrais (Leia e Entenda Antes de Agir)

1. O documento em si é a única fonte da verdade. O grafo não é um sistema independente; o frontmatter e os links bidirecionais residem nos arquivos .md do usuário; o diretório graph/ é puramente gerado, podendo ser deletado e recriado a qualquer momento. Qualquer modificação ocorre apenas nos documentos de origem.
2. Escrever exige confirmação. O frontmatter é rascunhado por você, mas antes de escrever em lote, mostre uma amostra ao usuário e obtenha confirmação; relações de julgamento como supersedes (quem substituiu quem) devem ser listadas e confirmadas — não é permitido escrever silenciosamente.
3. É melhor rebaixar do que forçar uma conclusão. Documentos cuja conclusão não pôde ser extraída devem receber status: reference. Nunca invente uma "conclusão em uma frase". Uma conclusão errada pode enganar o usuário em uma decisão, sendo muito mais prejudicial do que sua ausência.

Este diretório de skill contém dois arquivos acompanhantes (localizados no mesmo diretório deste SKILL.md):

• scripts/gen_kb_graph.py — Script de geração do grafo (biblioteca padrão pura, utilizável offline)
• references/schema.md — Especificação completa do frontmatter, semântica dos três tipos de aresta, modelos de saída, formato de saída para recall. Leia-o primeiro ao criar a base ou se estiver em dúvida sobre os campos.

---

Fluxo de Execução

Passo 0: Determinar o Escopo e Explicar ao Usuário o Que Acontecerá

• O usuário fornece uma pasta → Essa pasta é a raiz da base de conhecimento.
• O usuário fornece um ou alguns arquivos → Pergunte: usar a pasta onde esses arquivos estão como raiz (recomendado, pois documentos históricos poderão se conectar em um grafo) ou criar uma nova pasta de base de conhecimento independente para armazená-los.
• O usuário não tem nenhum arquivo e quer começar uma base → Vá para o Passo 2 "Esqueleto de Base Vazia".
• Antes de começar, confirme com o usuário em duas ou três frases: qual é o diretório raiz, quais arquivos serão modificados (frontmatter dos documentos de origem + novo diretório graph/), e que o corpo do documento não será alterado.

Passo 1: Detectar o Estado da Base de Conhecimento

Leia o diretório raiz:

• Se já existir <raiz>/gen_kb_graph.py ou <raiz>/graph/INDEX.md → Modo Iteração (base existente)
• Caso contrário → Modo Construção (base nova)

Passo 2 A: Modo Construção (Incluindo Esqueleto de Base Vazia)

1. Esqueleto de Base Vazia (quando o usuário não tem arquivos históricos): Crie os seguintes arquivos e vá para o Passo 3 para informar:
   • <raiz>/Guia_Rápido_da_Base_de_Conhecimento.md: Extraia de references/schema.md o template de frontmatter e as três regras principais, para referência do usuário ao escrever no dia a dia (com status: reference)
   • <raiz>/Template-Documento_de_Análise.md: Um template em branco com frontmatter completo (também com o frontmatter padrão)
2. Instalar o Script: Copie scripts/gen_kb_graph.py do diretório da skill para <raiz>/gen_kb_graph.py (pule se já existir). Colocar o script na base a torna autocontida — o usuário ou outro agente pode reconstruir o grafo sem depender desta skill.
3. Execução de Teste: python3 <raiz>/gen_kb_graph.py <raiz>. Leia a visão geral em <raiz>/graph/report.md e informe ao usuário o tamanho (quantos documentos, quantos sem frontmatter).
4. Rascunhar Metadados (trabalho principal): Leia references/schema.md primeiro, depois processe por subdiretório ou domínio em lotes:
   • Leia cada documento e rascunhe o frontmatter: date (data da conclusão), domain, status (active/superseded/reference), conclusion (conclusão em uma frase, apenas "o que este documento defende ao final", não um resumo do conteúdo)
   • Mostre uma amostra primeiro: Escolha 2-3 documentos representativos (um de decisão, um de referência), mostre o frontmatter que será escrito, obtenha confirmação do usuário sobre o formato antes de processar em lote
   • Identifique relações de substituição: pares de documentos com nomes contendo v2/novo/cópia/revisão, ou que se contradizem no conteúdo, sugira apontamentos de supersedes e liste para confirmação do usuário antes de escrever
   • Relate o progresso após cada lote; não mexa em uma palavra do corpo do documento, apenas adicione o frontmatter
5. Reconstrução e Entrega: Reexecute o script (que gera automaticamente a página graph/kb-graph.html), mostre ao usuário as primeiras linhas do INDEX.md e as lacunas restantes no report.md, e informe que ele pode abrir kb-graph.html no navegador para ver o grafo interativo.

Passo 2 B: Modo Iteração (Base Existente)

1. Execute o <raiz>/gen_kb_graph.py existente (se não existir, copie novamente do diretório da skill)
2. Leia graph/report.md e processe apenas o incremental: novos documentos sem frontmatter, documentos sem date/conclusion, links quebrados. Rascunhe → Confirme → Escreva
3. Complemento de Arestas Semânticas: Para novos documentos, leia-os e proponha relações related ("duas facetas da mesma coisa") e supersedes ("este documento corrige aquele") com documentos existentes, acompanhadas de uma frase de justificativa. Escreva após confirmação.
4. Reconstrua (incluindo a atualização da página de visualização kb-graph.html) e informe ao usuário as mudanças (número de novos nós/arestas, lacunas restantes)

Passo 3: Informar o Usuário Como Usar

Ao final de cada construção/iteração, lembre o usuário de usar assim (pode usar o texto original abaixo):

Da próxima vez que for analisar ou decidir, diga diretamente: "Me lembre das minhas ideias e conclusões anteriores sobre [assunto]". Então, consultarei o grafo, verificarei a cadeia de substituições e a atualidade, e fornecerei um relatório de referência. Se quiser ver o grafo visualmente, abra graph/kb-graph.html no navegador (pode pesquisar, filtrar, clicar nos nós para ver detalhes). Continue escrevendo seus documentos como antes; quando terminar, diga "atualize a base de conhecimento" e eu adicionarei metadados e relacionarei os novos documentos automaticamente.

---

Modo de Recall (Consulta Pré-decisão)

Quando o usuário pedir para lembrar de ideias passadas e o diretório alvo já tiver artefatos graph/, execute este fluxo, apenas leitura:

1. Leia graph/INDEX.md, combine palavras-chave do tópico com títulos e conclusões dos documentos, filtre itens relevantes (é melhor incluir demais do que deixar faltar)
2. Se precisar expandir, leia graph/GRAPH.md: siga as cadeias de supersedes e os vizinhos related dos documentos filtrados inicialmente para completar o contexto
3. Leia o frontmatter e a seção de conclusão dos documentos relevantes (não precisa ler o texto completo)
4. Produza a saída em um formato fixo (exemplo completo em references/schema.md):
   • Lista de Ideias Relacionadas: Cada item = Data | Conclusão em uma frase | Status | Link do documento
   • Cadeia de Substituições: Trajetória de mudança de ideias sobre o assunto, indicando quando e o que foi substituído/corrigido
   • Pontos de Referência para o Problema Atual: Quais conclusões podem ser reutilizadas diretamente, quais estão desatualizadas e exigem cuidado
   • Declaração de Ausência de Precedentes: Se o grafo não contiver nenhum registro de decisão histórica sobre o problema, diga explicitamente "Esta é uma decisão totalmente nova, sem precedentes anteriores disponíveis" — esta também é uma saída valiosa

---

Pontos de Verificação com o Usuário (Obrigatório Parar)

1. Antes de construir: Escopo do diretório raiz, regras de ignorar (pode usar <raiz>/.kbignore para excluir diretórios, um padrão por linha)
2. Antes de escrever frontmatter em lote: Confirmação de amostra de 2-3 documentos
3. Antes de escrever relações supersedes: Confirmação de pares listados
4. Qualquer modificação no corpo do texto: Proibida por padrão, só faça se o usuário solicitar explicitamente

Uso do Script

python3 gen_kb_graph.py <diretório_raiz_da_base> [--output graph] [--ignore "books,old,*_old"] [--no-html]

Ignorados por padrão: diretórios ocultos, .venv, venv, node_modules, pycache, .git, o próprio diretório de saída. Idempotente, pode ser reexecutado a qualquer momento; gera 5 arquivos (INDEX.md / GRAPH.md / kb-graph.json / report.md / kb-graph.html), cujo formato está em references/schema.md. kb-graph.html é uma página de visualização de arquivo único, sem dependências (grafo de força + tabela de registro de decisões, com suporte a pesquisa, filtro, clique em detalhes, duplo clique para abrir o arquivo fonte). Se o ambiente permitir, pode ser aberta diretamente no navegador para exibição ao usuário.

Limite de Escalabilidade

Quando os documentos ultrapassarem cerca de 500, o GRAPH.md não puder ser lido de uma vez, ou consultas de múltiplos saltos forem frequentes, o grafo baseado em arquivos atinge seu limite. Recomende ao usuário migrar para um sistema LightRAG (grafo + busca vetorial híbrida) — o frontmatter e os links bidirecionais são o melhor corpus de migração, sem perdas. Até lá, não introduza bancos de dados ou serviços externos.