MemoryCustodian

1) Instale o MemoryCustodian (escolha o caminho que corresponde ao seu agente/fluxo de trabalho): Escolha um método de instalação: - Peça ao seu agente de codificação para instalar a habilidade do repositório: https://github.com/waittim/MemoryCustodian - Codex (marketplace local): execute `codex plugin marketplace add .` a partir de um checkout, depois `codex plugin add memory-custodian@memory-custodian-dev`. - Claude Code (plugin): para testes locais, execute `claude --plugin-dir .`, ou instale em habilidades pessoais com `./install.sh claude`. - Agentes estilo Gemini: instale com `./install.sh gemini` ou `gemini skills link ./skills/memory-custodian`. - CLI/checkout de origem: execute do repositório via `scripts/memory-custodian ...` ou instale editável com `python3 -m pip install -e .` para obter o comando `memory-custodian`.

2) Inicialize o MemoryCustodian em um projeto (uma vez por repositório): Execute a inicialização uma vez para cada projeto de destino: - Se instalado como um script de console: `memory-custodian init --project-root /path/to/project --agent all` - A partir de um checkout de origem: `scripts/memory-custodian init --project-root /path/to/project --agent all` Use `--agent codex`, `--agent claude`, `--agent gemini` ou `--agent all` para gerar o(s) arquivo(s) de bootstrap fino(s) que seu agente lê.

3) Entenda o que a inicialização cria (onde a memória reside): A inicialização cria o conjunto de memória durável padrão em `docs/memory/`: - `manifest.md` (direciona o que carregar) - `brief.md` (forma atual do projeto) - `decisions.md` (decisões chave) - `constraints.md` (requisitos rígidos) - `do-not-use.md` (caminhos rejeitados / lápides) - `inbox.md` (área de preparação) Os arquivos de bootstrap da plataforma (por exemplo, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`) permanecem finos e apontam os agentes para `docs/memory/`.

4) Curate o resumo gerado antes de confiar nele: Após `init`, `brief.md` começa como um andaime com TODOs. Preencha-o a partir de fontes autoritativas do projeto (README, código, docs) antes de tratar a memória como pronta. Use `memory-custodian status --project-root /path/to/project` (ou `scripts/memory-custodian status ...`) para ver se o resumo ainda não foi curado; `status` e `check` relatam um resumo não curado.

5) Carregue a memória certa para uma tarefa (leitura manifest-first): O fluxo de trabalho pretendido para os agentes é: 1) Leia `docs/memory/manifest.md`. 2) Leia `docs/memory/brief.md`. 3) Carregue apenas os arquivos relevantes para a tarefa nomeados pelo manifesto. Para inspeção manual, gere um pacote de contexto com: - `memory-custodian read --project-root /path/to/project --task planning` - `memory-custodian read --project-root /path/to/project --task implementation` - `memory-custodian read --project-root /path/to/project --task artifact`

6) Adicione memória durável quando algo deve sobreviver ao bate-papo atual: Registre decisões/restrições/preferências/abordagens rejeitadas usando a CLI: - `memory-custodian add "Escolhemos o carregamento manifest-first." --type decision` - `memory-custodian add "Persistir backoff de nova tentativa de sincronização." --type decision --area sync --reason "Manter as novas tentativas limitadas entre os lançamentos."` Mantenha as entradas de decisão curtas (a ferramenta impõe um guia de tokens e rejeita gravações excessivamente longas, a menos que você explicitamente permita entradas longas).

7) Habilite módulos de memória opcionais apenas quando se tornarem relevantes: Módulos opcionais (por exemplo, regras, perfis, áreas) são opcionais e não são carregados a menos que sejam habilitados e roteados pelo manifesto. Habilite-os conforme necessário: - `memory-custodian enable preferences` - `memory-custodian enable rules/output` - `memory-custodian enable profile/git` - `memory-custodian enable area/frontend` Habilitar nunca sobrescreve um arquivo de módulo existente.

8) Use 'do-not-use' para preservar abordagens rejeitadas e evitar regressões: Quando você rejeita intencionalmente uma abordagem (por exemplo, um backend de armazenamento ou arquitetura), registre-a em `docs/memory/do-not-use.md` (via edições ou o fluxo de trabalho apropriado de adicionar/esquecer) para que sessões futuras não a reproponham.

9) Verifique a saúde e a compatibilidade do protocolo regularmente: Execute a validação determinística para garantir que a estrutura, os orçamentos e os metadados do protocolo estejam corretos: - `memory-custodian check --project-root /path/to/project` Use `memory-custodian status` para uma visão geral rápida e para detectar um resumo não curado.

10) Compacte e mantenha a memória (preview-first, mutações seguras): Use comandos de manutenção para manter a memória pequena e atualizada: - `memory-custodian compact --project-root /path/to/project` A compactação é protegida e preview-first; aplique as alterações somente após revisar o plano. A compactação da caixa de entrada é conservadora (por exemplo, remoção exata de unidades de marcadores de nível superior duplicadas e filtragem de lápides) e espera que um agente/humano faça a promoção semântica para decisões/restrições.

11) Esqueça informações desatualizadas com segurança (preview-first): Remova ou redija tópicos desatualizados com o esquecimento preview-first: - Visualizar: `memory-custodian forget "nota de implantação antiga" --mode soft --project-root /path/to/project` - Aplicar após revisão: `memory-custodian forget "nota de implantação antiga" --mode soft --apply --project-root /path/to/project` Correspondências amplas exigem confirmação explícita (por exemplo, `--allow-broad-match`). Alguns casos exigem reescrita manual; a ferramenta recusará exclusões em massa inseguras.

12) Repare ou substitua uma configuração existente quando necessário: Se arquivos estiverem faltando ou metadados precisarem ser atualizados sem sobrescrever conteúdo curado: - Reparar: `memory-custodian init --project-root /path/to/project --repair` Se você intencionalmente deseja uma substituição completa, use a substituição preview-first e aplique somente quando estiver correto: - `memory-custodian init --project-root /path/to/project --replace-existing` - então adicione `--apply` somente se os arquivos listados devem ser substituídos.

13) Migre as versões do protocolo/memória do projeto quando a ferramenta for atualizada: Quando `check` relata metadados de protocolo antigos ou ausentes, migre o manifesto do projeto offline: - Visualizar: `memory-custodian migrate --project-root /path/to/project` - Aplicar após revisão: `memory-custodian migrate --apply --project-root /path/to/project`

14) Use a invocação correta no Windows vs. checkout de origem: No Windows, instale o comando do console e use `memory-custodian ...`. A partir de um checkout de repositório em qualquer plataforma, você pode executar `scripts/memory-custodian ...` como o wrapper.