Como escrever memórias

Uma memória é uma nota curta em Markdown que sua equipe registra para o assistente ler depois. As memórias ficam em um caminho do espaço de trabalho e só aparecem quando o assistente está trabalhando dentro desse caminho. Elas são o tipo de conteúdo mais comum no Pathrule e o mais fácil para começar.

Esta página explica quando escrever uma memória, como estruturá-la e como funcionam o escopo e o versionamento.

Quando escrever uma memória

Use uma memória quando você tiver um conhecimento que não fica óbvio pelo código e que provavelmente vai voltar a aparecer.

• Decisões. "Usamos Postgres no Supabase para tudo neste repositório. Não adicione um ORM. Use o cliente supabase-js diretamente."
• Armadilhas. "Se você alterar o enum orders.status, precisa rodar a migração de dados antes da migração de schema. A ordem é a inversa do resto do schema."
• Postmortems. "Em 2026-04-12 publicamos um handler de webhook que cobrou clientes em dobro porque não verificamos a chave de idempotência do Stripe. Agora sempre a envie."
• Convenções. "Os testes ficam ao lado do arquivo que testam, e não em um diretório __tests__ paralelo."
• Conhecimento tácito. "Só uma pessoa lembra por que esta flag existe. Ela ainda é necessária por causa de uma peculiaridade de runtime no upstream."

Não use memórias para o que o código já diz com clareza, para coisas que mudam toda semana ou para preferências puramente pessoais.

Estrutura

Toda memória tem um título e um corpo em Markdown. Mantenha os dois curtos.

• Título: curto, afirmativo, cabe numa barra lateral. "Só Postgres. Sem ORM." é melhor que "Notas sobre padrões de acesso ao banco de dados".
• Corpo: o mínimo de Markdown necessário para passar a mensagem. Listas costumam ser mais claras que parágrafos. Inclua um exemplo se ajudar.

Não há um modelo obrigatório, mas um bom ponto de partida é:

The constraint or fact in one sentence.

Why:
- The reason this matters or the incident that prompted it.

How to apply:
- The concrete thing the assistant should do when the topic comes up.

Escopo por caminho

O caminho é metade da memória. É ele que decide onde a memória aparece.

• Uma memória em /apps/api/payments aparece em qualquer trabalho dentro de apps/api/payments.
• Uma memória em /apps/api aparece para todo o diretório da api.
• Uma memória em / aparece em todo o espaço de trabalho.

Escolha o caminho mais específico que ainda cubra os casos que você quer. Uma memória sobre pagamentos no nível do espaço de trabalho vira ruído; a mesma memória na pasta de pagamentos é muito melhor.

Versionamento e edições concorrentes

Cada gravação é comparada com a versão a partir da qual você começou. Se outra pessoa gravou nesse meio-tempo, sua gravação é recusada em vez de sobrescrever a dela. Isso evita que duas pessoas, ou uma pessoa e um agente, sobrescrevam silenciosamente o trabalho uma da outra.

• No Pathrule para VS Code, uma memória é uma aba de Markdown. Uma gravação que sobrescreveria uma alteração mais recente de um colega oferece Reload, Copy My Version & Reload (seu texto vai primeiro para a área de transferência) ou Keep Mine (Overwrite).
• Via MCP, o assistente pode enviar a última versão que leu. Se houver divergência, ele recebe um conflito com a versão atual, lê de novo e mescla em vez de sobrescrever.

A exclusão também é reversível. No VS Code, uma exclusão oferece Undo na hora, e em um espaço de trabalho do Pathrule Cloud uma memória excluída fica no arquivo do espaço de trabalho até ser excluída permanentemente; nesse período, um proprietário ou administrador pode restaurá-la nas configurações do console web (Workspace, Archive) ou excluí-la de vez. Na prática, conflitos são raros porque as memórias costumam ser pequenas e focadas, mas a rede de segurança está sempre ativa.

Quem escreve as memórias

• Pessoas, escrevendo no Pathrule para VS Code (New Memory… ou Save Selection as Memory) ou com o CLI.
• O assistente, escrevendo pela ferramenta MCP pathrule_write_memory quando você pede para ele salvar algo. Durante a configuração, ele propõe memórias, regras e skills para o projeto e escreve apenas os itens que você aprovar.

No terminal, uma memória é um único comando. Sem --body, o CLI abre seu editor para você escrever o corpo; você também pode passar --body ou enviar o texto por pipe. pathrule memory list e pathrule memory read "Exact title" --print leem as memórias de volta.

pathrule memory add --path /apps/api/payments --title "Always pass the Stripe idempotency key"

As duas origens vão para o mesmo lugar. O assistente lê o que uma pessoa escreveu, e uma pessoa lê o que o assistente escreveu. Cada registro guarda quem o criou, quem o editou por último e a origem, informações que a ação Info do VS Code exibe, então é fácil identificar memórias escritas pela IA.

Como a qualidade das memórias continua revisável

O Pathrule mantém cada memória restrita e fácil de inspecionar por meio de vários controles independentes:

• A documentação geral é oferecida durante a configuração, em vez de importada automaticamente. Arquivos de instrução ativos, sua cadeia de importação, regras de ferramentas e registros de decisão têm evidência mais forte de que são conhecimento ativo.
• O agente precisa propor um conhecimento duradouro antes de salvá-lo. Tudo o que ele salva tem autoria registrada, é versionado e fica visível no espaço de trabalho como qualquer outro item, então você pode abrir, editar ou remover.
• O escopo por caminho limita onde a entrada pode aparecer, e uma entrada fora do caminho atual ainda precisa atingir o limite mínimo de relevância.
• O uso medido pode reordenar as entradas que se qualificam, mas não consegue fazer uma memória sem relação passar desse limite.
• Um agente que percebe que uma memória se desatualizou em relação ao código pode sinalizá-la como uma tarefa de atualização, que um assistente depois pega e corrige sob o seu controle. Veja Sugestões e autoauditoria. As edições são versionadas e a exclusão é reversível.
• Uma nova memória cujo título coincide com o de uma memória existente no mesmo caminho é recusada por padrão em vez de salva como segunda cópia, para que a mesma decisão não seja entregue duas vezes nem acabe divergindo. Você pode contornar isso de forma deliberada (--allow-duplicate no CLI) depois de conferir a entrada existente.

O modelo de operação resultante é um conjunto pequeno de decisões e armadilhas restritas e revisáveis, e não um grande arquivo copiado para dentro do espaço de trabalho. Veja Como o Pathrule comprova afirmações fortes para o contrato técnico completo.

Ler versus citar

As memórias mais relevantes chegam com o corpo completo, para o assistente agir diretamente com base nelas. Candidatas menos certas chegam como títulos com ids; o assistente lê uma delas por inteiro com pathrule_read_memory antes de confiar nela. Assim, o material incerto fica fora da carga padrão sem transformar correspondências fortes em idas e voltas extras.

No VS Code, Browse Knowledge Here… mostra o que uma sessão de IA em um caminho recebe, inclusive o que ela herda dos caminhos pais.

Antipadrões

• Uma memória enorme com "todas as minhas anotações". Divida por assunto e escopo. Pequena e vinculada a um caminho sempre ganha de longa e global.
• Memórias que repetem o que o código já diz. O assistente consegue ler o código. Reserve as memórias para o porquê e para as armadilhas.
• Memórias desatualizadas. Atualize ou exclua quando a decisão por trás delas mudar. Um assistente pode sinalizar uma memória desatualizada como tarefa de atualização, mas o olhar humano é mais rápido.

Criação no modo local e no Cloud

Os exemplos de add no terminal desta página são para um espaço de trabalho no Cloud. No modo local, crie e edite entradas no Local Console, no VS Code ou via MCP local; os comandos de conhecimento do CLI listam, leem e buscam essas entradas.

O que ler em seguida

• Como escrever regras, para restrições com prioridade.
• Como escrever skills, para procedimentos reutilizáveis.
• Conceitos principais, para entender a árvore do espaço de trabalho à qual tudo isso se vincula.