agenticluke/knowledge-sync-plus

Operações de Conhecimento

Gerencie conhecimento em vários armazenamentos.

Dê a cada fato um lar principal. Outros armazenamentos podem conter uma nota curta e um link para esse lar.

Use Este Skill Quando

Use este skill quando o usuário quiser:

• Salvar fatos ou notas em uma base de conhecimento.
• Importar um arquivo, chat ou conjunto de dados.
• Sincronizar conhecimento entre armazenamentos.
• Encontrar ou mesclar notas duplicadas.
• Pesquisar fatos conhecidos sobre um tópico.
• Atualizar uma fonte compartilhada de verdade.
• Fazer mais do que uma simples consulta de memória.

Regras Principais

• Mantenha o trabalho de código no repositório clonado real.
• Coloque planos ativos e estado de trabalho no GitHub, Linear ou no repositório.
• Coloque notas longas fora do repositório de código quando não pertencerem ao código.
• Coloque notas de longo prazo e entre dispositivos na base de conhecimento.
• Pesquise antes de criar.
• Não faça duas cópias principais do mesmo fato.
• Não faça chamadas externas a menos que o usuário peça e a ferramenta necessária já esteja configurada.
• Nunca salve chaves, senhas, tokens, cookies ou dados de login privados.
• Não faça commit ou push a menos que o usuário peça ou já tenha aprovado essa etapa.
• Não substitua fatos mais novos por notas mais antigas.

Camadas de Armazenamento

1. Fonte de Trabalho Ativa

Exemplos:

• Issues, pull requests, discussões e notas de release do GitHub
• Issues, projetos e documentos do Linear
• Arquivos no repositório do projeto real

Use para:

• Planos atuais
• Roadmaps
• Estado de release
• Estado de rollout
• Trabalho de build e código

Se um fato mudar o trabalho ativo, atualize esta camada primeiro.

2. Memória do Claude Code

Caminho:

~/.claude/projects/*/memory/

Use arquivos Markdown curtos com frontmatter YAML.

Use para:

• Escolhas do usuário
• Feedback do usuário
• Pequenos fatos do projeto
• Notas curtas de referência
• Fatos necessários em chats futuros

Não presuma que este caminho existe ou pode ser alterado. Verifique primeiro.

3. Memória MCP

Ferramentas comuns:

• create_entities
• create_relations
• add_observations
• search_nodes

Use para:

• Pessoas, equipes, ferramentas e projetos nomeados
• Links entre esses itens
• Fatos que devem ser fáceis de pesquisar depois

Use os nomes exatos das ferramentas do servidor MCP atual. Se nenhum servidor de memória estiver configurado, pule esta camada e informe.

4. Repositório da Base de Conhecimento

Use para:

• Notas de longo prazo
• Exportações de sessão
• Pesquisas conjuntas
• Run books
• Documentos longos

Este é o principal armazenamento entre dispositivos para conteúdo que não é código do projeto.

5. Banco de Dados

Exemplos:

• Supabase
• PostgreSQL

Use para:

• Grandes conjuntos de linhas
• Grandes conjuntos de documentos
• Pesquisa de texto completo
• Dados que precisam de SQL

Mantenha apenas um resumo curto e um ID de registro na memória.

6. Notas e Arquivo Local

Use para:

• Notas para pessoas lerem
• Planos antigos
• Listas de mídia local
• Arquivos não-código de curto prazo

Não use como um segundo repositório de código ou como lar principal para planos ativos.

Escolha o Lar Principal

Use este guia:

Tipo de conhecimento	Lar principal	Cópia opcional
Plano atual, release ou estado de código	GitHub, Linear ou repositório do projeto	Nota curta na memória
Decisão de negócio	Memória do projeto ou base de conhecimento	Memória MCP
Escolha ou feedback do usuário	Memória do Claude Code	Memória MCP
Pequeno fato de referência	Memória do Claude Code	Memória MCP
Grande conjunto de documentos	Banco de dados ou base de conhecimento	Resumo curto na memória
Exportação de chat ou sessão	Repositório da base de conhecimento	Resumo curto na memória
Nota local de curto prazo	Arquivo local	Nenhum

Se duas opções se encaixarem, escolha o armazenamento que possui o trabalho. Adicione um link do outro armazenamento em vez de copiar o texto completo.

Etapas de Importação

1. Leia e Classifique

Encontre:

• A fonte
• O tópico
• A data
• O proprietário
• Se os fatos estão atualizados
• Se o texto contém segredos
• O melhor lar principal

Não importe texto que você não pode ler ou confiar. Marque fatos incertos como incertos.

2. Pesquise por Correspondência

Antes de escrever:

• Pesquise arquivos de memória.
• Pesquise na memória MCP quando estiver configurada.
• Pesquise na base de conhecimento.
• Verifique GitHub ou Linear quando possam ser os proprietários do fato.
• Verifique o banco de dados de destino quando usado.

Corresponda por tópico, nomes, datas, IDs e links de fonte.

3. Lide com Cópias e Conflitos

Se o mesmo fato existir:

• Atualize o registro principal.
• Adicione novos links de fonte ou datas.
• Mantenha histórico útil.
• Remova ou marque cópias antigas apenas quando seguro.

Se duas fontes discordarem:

• Não adivinhe.
• Mantenha ambas as alegações com suas datas e fontes.
• Prefira a fonte mais recente apenas quando ela claramente possui o fato.
• Pergunte ao usuário quando a escolha alterar trabalho ou remover dados.

4. Salve

Escreva apenas em armazenamentos que estão no escopo e prontos para uso.

• Atualize a fonte de trabalho ativa primeiro quando o trabalho ativo mudar.
• Mantenha a memória do Claude Code curta.
• Use a memória MCP para fatos e links.
• Coloque texto longo na base de conhecimento.
• Coloque conjuntos grandes em um banco de dados.
• Adicione uma fonte, data e proprietário quando conhecidos.

Se um armazenamento estiver faltando ou for somente leitura, não salve nada lá. Relate o que não pôde ser feito.

5. Atualize Índices

Atualize qualquer lista de tópicos, lista de sessões ou arquivo de resumo usado para encontrar o novo item.

Use nomes de arquivo em kebab-case minúsculo, como:

release-plan-2026-05.md

6. Verifique o Resultado

Leia de volta cada registro alterado. Certifique-se de que links, datas e nomes estão corretos.

Trabalho de Sincronização

Sincronize Chats

Para exportações de chat do Claude, Codex ou outros:

1. Remova segredos e dados de login privados.
2. Mantenha o nome da fonte e a data.
3. Salve a exportação completa na base de conhecimento.
4. Adicione um resumo curto na memória.
5. Atualize o índice de sessão.
6. Faça commit e push apenas com aprovação do usuário.

Sincronize Estado do Workspace

Para arquivos e configurações importantes:

1. Faça um mapa da pasta.
2. Copie apenas fatos úteis e não secretos.
3. Remova chaves, tokens, senhas, cookies e caminhos privados.
4. Anote a fonte e a data.
5. Acompanhe mudanças ao longo do tempo.

Não copie uma pasta de código ativa inteira em um arquivo.

Sincronize GitHub ou Linear

Quando um fato alterar o trabalho ativo:

1. Encontre o item que possui o trabalho.
2. Atualize esse item primeiro.
3. Adicione documentos de suporte quando necessário.
4. Adicione uma nota local apenas se der valor extra.
5. Vincule a nota de volta ao item principal.

Sincronize Muitas Fontes

Para chats, favoritos, eventos do GitHub ou outras fontes:

1. Agrupe itens por tópico.
2. Remova cópias exatas e próximas.
3. Mantenha links de fonte e datas.
4. Escreva uma nota de status clara.
5. Salve no lar principal.
6. Faça commit e push apenas com aprovação do usuário.

Padrão de Memória

Curto prazo:
Use a lista de tarefas atual para o trabalho neste chat.

Médio prazo:
Use arquivos curtos em ~/.claude/projects/*/memory/.

Longo prazo:
Use GitHub ou Linear para trabalho ativo.
Use a base de conhecimento para notas longas.

Fatos vinculados:
Use a memória MCP para itens, fatos e links.

Formulário de Arquivo de Conhecimento

---
title: Plano de release
type: project
topics:
  - release
  - mobile-app
source: https://example.com/item/123
updated: 2026-05-12
status: current
---

# Plano de Release

Fatos curtos vão aqui.

## Links

- Item de trabalho principal: URL ou caminho de arquivo

Use apenas campos que ajudem. Use uma data ISO no formato YYYY-MM-DD. Defina status como current, stale, archived ou unclear.

Exemplo Concreto

Solicitação do usuário:

Salve isto: O lançamento do aplicativo móvel foi adiado de 1º de junho para 15 de junho. A issue 42 do GitHub é a proprietária do plano de lançamento.

Etapas:

1. Pesquise o plano de lançamento no GitHub, memória, memória MCP e base de conhecimento.
2. Abra a issue 42 e verifique se é o item de trabalho principal.
3. Se permitido, atualize a issue 42 para 15 de junho.
4. Atualize a nota de memória antiga em vez de criar uma nova.
5. Adicione um fato MCP de que a data de lançamento é 15 de junho e vincule-o à issue 42.
6. Marque qualquer nota de 1º de junho como desatualizada. Mantenha-a apenas se a data antiga for histórico útil.
7. Leia de volta a data e os links salvos.
8. Relate cada armazenamento alterado e qualquer armazenamento pulado.

Não atualize o GitHub se o usuário apenas pediu uma revisão ou pesquisa.

Casos Extremos

• Se a fonte não tiver data, diga que a data é desconhecida.
• Se o proprietário não estiver claro, pergunte antes de alterar um plano ativo.
• Se um arquivo for muito grande, armazene-o na base de conhecimento ou banco de dados e mantenha uma nota curta na memória.
• Se dois itens compartilharem um nome, use IDs, links, proprietários e datas para distingui-los.
• Se o conteúdo puder ser privado, salve o mínimo necessário.
• Se um segredo for encontrado, omita-o. Não copie ou imprima.
• Se uma gravação falhar parcialmente, não afirme que a sincronização está concluída. Liste o que funcionou e o que falhou.
• Se um salvamento excluiria histórico útil, arquive-o ou pergunte primeiro.
• Se não houver um lar principal seguro, pergunte ao usuário onde deve ir.
• Se o mesmo fato deve aparecer em dois armazenamentos, mantenha o texto completo em um armazenamento. Coloque uma nota curta e link no outro.

Verificação Final

Antes de terminar, confirme:

• Nenhuma nova duplicata foi criada.
• Cada fato tem um lar principal.
• Fatos antigos foram atualizados ou marcados como desatualizados.
• Nenhum segredo foi salvo ou impresso.
• Datas, nomes, IDs e links estão corretos.
• Índices e resumos estão atualizados.
• Links cruzados foram adicionados quando úteis.
• Todos os registros alterados foram lidos de volta.
• Nenhum commit, push ou gravação externa foi feita sem aprovação.
• O usuário é informado sobre o que mudou, o que foi pulado e por quê.