Memória para agentes de programação: Claude Code, Codex e Cursor

Use um AGENTS.md versionado e um resumo curto do ponto em que a tarefa parou como memória compartilhada entre agentes de programação, como Claude Code, Codex e Cursor. Adicione ai-memory para automatizar a captura e a transferência de contexto entre agentes, ou Beacon para inspecionar registros de sessões e aprovar aprendizados reutilizáveis. Mantenha as regras obrigatórias do projeto no repositório, qualquer que seja a opção escolhida.

Escolha o que precisa continuar disponível ao trocar de ferramenta

Guarde as decisões duradouras separadamente do estado atual da tarefa. Um novo agente pode ler seu código sem saber por que você descartou uma abordagem, qual correção fez ontem ou qual é o próximo passo do trabalho inacabado.

Três tipos de contexto resolvem problemas diferentes: instruções descrevem como trabalhar, repasses de tarefa (handoffs) indicam onde o trabalho parou, e o histórico da sessão fornece evidências para ambos. Compartilhar um deles não transfere automaticamente os demais, os processos em execução ou as permissões das ferramentas.

Abordagem	O que você preserva	Quando escolher	Quando reconsiderar
Instruções e arquivos de repasse no repositório	Regras, decisões e estado da tarefa mantidos de forma deliberada	Um pequeno conjunto de notas atende às suas necessidades e deve acompanhar o Git	Migre para um serviço se as pessoas esquecerem repetidamente de atualizar as notas
ai-memory	Observações capturadas, uma wiki em Markdown com busca e repasses entre agentes	Você troca de agente com frequência e quer automatizar a captura e a recuperação do contexto	Continue com arquivos se manter hooks, credenciais e um servidor der mais trabalho do que o benefício justifica
Beacon	Rastros de sessões em um formato comum e aprendizados do projeto aprovados explicitamente	Você precisa examinar o que aconteceu e transformar correções recorrentes em conhecimento revisado	Prefira ai-memory se os repasses automáticos forem mais importantes do que inspecionar rastros e revisar aprendizados

Em 2026-10-21, esta comparação considera ai-memory v3.1.2 e Beacon v1.3.45. A diferença está na arquitetura: ai-memory inclui servidor, hooks e MCP, além da wiki em Markdown mantida no Git; no Beacon, a captura e a aprovação de memórias são processos separados.

Comece com AGENTS.md e um repasse curto da tarefa

Faça do AGENTS.md a referência comum do projeto e verifique se cada ferramenta o carrega. As regras nativas de carregamento variam:

• Codex: lê uma cadeia de instruções desde a raiz do projeto até o diretório de trabalho. Um AGENTS.override.md tem precedência sobre AGENTS.md no mesmo diretório; consulte as regras de descoberta de instruções do Codex.
• Cursor: aceita arquivos AGENTS.md na raiz e em subdiretórios. Quando precisar de regras com escopo específico para o Cursor, mantenha-as em .cursor/rules/*.mdc; consulte a documentação de regras do Cursor.
• Claude Code: a partir de v2.1.277, pode carregar AGENTS.md diretamente, mas o comportamento padrão dá preferência aos arquivos CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md que atendam aos critérios de carregamento no diretório de trabalho ou em seus diretórios ancestrais. Se já houver instruções para o Claude ou se a sessão não oferecer suporte direto, adicione uma linha com @AGENTS.md a um CLAUDE.md na raiz, ao lado do arquivo. O guia de memória do Claude Code documenta as duas opções.

Para um pequeno teste, crie ou incorpore esta convenção ao AGENTS.md da raiz:

## Working context

- Before changing a dependency version, read its official release notes
  and run the tests for the affected component.
- When resuming work, read docs/agent-handoff.md if it exists.
- Treat handoffs as historical evidence. Check old commands, paths and
  conclusions against the current checkout before acting.

Depois de uma tarefa real, peça ao agente para produzir o repasse:

Write docs/agent-handoff.md with the goal, current branch and commit,
confirmed decisions, commands actually run and their results,
remaining uncertainty, and the next concrete action.
Distinguish failed approaches from successful ones.
Do not include credentials or copy the full conversation.

Revise esse arquivo junto com as alterações no código. Mantenha as convenções estáveis em AGENTS.md e atualize o repasse conforme a tarefa avança.

Inicie uma nova sessão em cada ferramenta e pergunte quais verificações se aplicam à atualização de uma dependência e de qual arquivo elas vieram. No Claude Code, /context também permite inspecionar os arquivos de memória carregados. Se o Codex ignorar a regra, verifique o diretório de trabalho e o arquivo que sobrescreve as instruções antes de adicionar cópias duplicadas.

A memória automática nativa continua útil dentro de seu próprio ambiente. O Claude Code armazena notas do projeto em ~/.claude/projects/<project>/memory/. As memórias locais do Codex precisam ser ativadas, ficam em ~/.codex/memories/ e têm controles em /memories. Esses armazenamentos separados não constituem um formato comum de repasse entre ferramentas.

Use ai-memory para captura automática e transferência de tarefas

Escolha ai-memory quando quiser que os agentes registrem e recuperem o contexto do projeto por meio de um serviço. Sua fonte principal de dados é uma wiki em Markdown mantida no Git, com SQLite como índice derivado. O MCP fornece ferramentas de memória aos agentes, enquanto hooks — ações disparadas por eventos — cuidam da captura e das transições de início e fim das sessões.

Instale e conecte os agentes

O exemplo a seguir considera uma instalação nova no macOS, no escopo do usuário, usando Bash, com Git e seus agentes de programação já instalados e autenticados. O guia de instalação desta versão cobre outras plataformas.

curl -fsSLo /tmp/ai-memory-install-v3.1.2.sh \
  https://github.com/akitaonrails/ai-memory/releases/download/v3.1.2/install.sh
less /tmp/ai-memory-install-v3.1.2.sh
AI_MEMORY_VERSION=3.1.2 sh /tmp/ai-memory-install-v3.1.2.sh
export PATH="$HOME/.local/bin:$PATH"
ai-memory --version
ai-memory setup --plan --agent claude-code --agent codex --agent cursor
ai-memory setup --agent claude-code --agent codex --agent cursor
ai-memory status

A versão esperada é 3.1.2. Revise o plano antes de aceitar a configuração: ela cria um serviço em segundo plano e altera as configurações de MCP, hooks e skills no escopo do usuário. Por isso, a captura também pode incluir outros projetos dos agentes selecionados.

O código que gera a configuração do Codex nesta versão também define default_tools_approval_mode = "approve" para as ferramentas do ai-memory. Revise essa permissão se quiser exigir confirmação para alterações na memória.

Para o registro nativo do Codex nesta versão, carregue o token bearer gerado no ambiente de inicialização. Com o diretório de dados padrão do macOS, estes comandos Bash fazem isso sem exibir o token:

AI_MEMORY_AUTH_TOKEN="$(cat "$HOME/Library/Application Support/ai-memory/auth-tokens/default")"
export AI_MEMORY_AUTH_TOKEN
codex

O registro faz referência a AI_MEMORY_AUTH_TOKEN; o guia de instalação do MCP explica esse requisito específico do Codex. Se o seu diretório de dados for diferente, use o caminho real informado por ai-memory status.

Dentro do Codex, execute /hooks e marque os hooks instalados do ai-memory como confiáveis. Reinicie Claude Code e Cursor depois da configuração. O código de saída do instalador, por si só, não comprova que o Codex executará hooks que ainda não foram considerados confiáveis.

Verifique separadamente o conhecimento salvo e os repasses

Use uma única cópia de trabalho e um escopo de projeto explícito na primeira verificação. A partir da raiz, execute ai-memory project init e aceite ou escolha os nomes do espaço de trabalho e do projeto. O comando grava .ai-memory.toml; mantenha os dois nomes iguais em todos os agentes.

No Claude Code, use este prompt:

Read .ai-memory.toml and use its workspace and project for ai-memory calls.
Call memory_status.
Use memory_write_page to save decisions/shared-memory-demo.md with:
"Memory trial: before a dependency upgrade, check the official release
notes and run the affected component's tests."
Read the page back with memory_read_page and report its stored path.

Abra Codex ou Cursor na mesma cópia de trabalho. Peça para chamar memory_query com Memory trial e, depois, memory_read_page no resultado correspondente. O sucesso exige que um resultado real da ferramenta retorne o caminho salvo e a decisão; uma resposta plausível sem recuperação dos dados não basta. Essas operações estão documentadas na referência de acesso programático à memória.

Depois, verifique o repasse automático com uma tarefa real e pequena: deixe uma ação claramente inacabada, encerre a sessão normalmente e abra o próximo agente no mesmo diretório. O contexto inicial dele deve identificar a ação pendente. Uma página duradoura continua disponível para busca; um repasse destina-se à sessão seguinte e só pode ser recebido uma vez.

Se a recuperação falhar, execute ai-memory doctor, inspecione o estado da conexão MCP e confira a combinação de espaço de trabalho e projeto. Uma falha de autenticação do Codex exige verificar seu ambiente de inicialização; a ausência de um repasse exige verificar a confiança nos hooks e a captura da sessão. Não trate os dois casos como a mesma falha.

Use Beacon para inspecionar rastros e aprovar aprendizados

Escolha Beacon quando quiser revisar as evidências que sustentam um aprendizado reutilizável. Ele combina métodos de coleta como OpenTelemetry, hooks e recuperação de arquivos locais de sessão, com cobertura que varia conforme a ferramenta. Capturar uma sessão não transforma automaticamente seu conteúdo em memória aprovada.

Instale um coletor local

Para uma instalação nova no macOS usando Bash e Homebrew, configure apenas os três agentes usados aqui:

brew update
brew trust asymptote-labs/tap
brew tap asymptote-labs/tap
brew install beacon
beacon version
BEACON_ONBOARDING=0 beacon endpoint install \
  --harness claude,codex,cursor --no-backfill
beacon endpoint status

Na data da verificação, a fórmula do Homebrew fornece 1.3.45. Este exemplo ignora a importação de sessões anteriores e o assistente interativo de configuração inicial. Ele instala a captura no escopo do usuário para os agentes selecionados, portanto o trabalho deles em outros repositórios também pode entrar no registro.

O assistente normal deixa Beacon Cloud pré-selecionado. Em uma instalação nova, ignorar o assistente e omitir --connect evita o cadastro no Cloud. Isso não desconecta uma instalação existente; para isso, use beacon endpoint disconnect. A documentação da configuração inicial descreve as opções de destino.

Reinicie os agentes após a configuração e use /hooks no Codex para revisar os hooks do Beacon e marcá-los como confiáveis. Faça uma sessão curta no repositório de teste, declarando explicitamente a convenção de revisão de dependências apresentada acima.

Crie, aprove e recupere um aprendizado

Inspecione a sessão registrada antes de criar um aprendizado. A partir da raiz do repositório:

beacon endpoint traces list --limit 10
read -r -p "Trace ID from the trial session: " BEACON_TRACE_ID
beacon endpoint traces show "$BEACON_TRACE_ID" --limit 150

Escolha o ID real retornado pela lista e confirme que os eventos contêm a convenção declarada. Em seguida, crie um candidato:

beacon memory candidates create \
  --trace "$BEACON_TRACE_ID" \
  --kind convention \
  --title "Dependency upgrades require release-note review" \
  --applicability "Before changing a dependency version in this repository" \
  --body "Check the dependency's official release notes and run the affected component's tests before proposing the upgrade."
read -r -p "Candidate ID returned above: " BEACON_CANDIDATE_ID
beacon memory candidates show "$BEACON_CANDIDATE_ID"

Revise o candidato e as evidências de origem. Aprove-o somente depois de aceitar o conteúdo do aprendizado:

beacon memory candidates approve "$BEACON_CANDIDATE_ID" \
  --reason "Reviewed against the source trace"

Esse caminho, no qual você fornece o texto do candidato, não chama nenhum avaliador. O avaliador opcional do Beacon atribui pontuações aos rastros; ele não fornece o texto final do aprendizado. As duas opções estão descritas na referência de comandos de memória.

Agora peça a outro agente, operando no mesmo repositório, para executar:

beacon memory list -q "dependency upgrades" --json

Peça para ele passar o ID de memória retornado para beacon memory show e explicar quando a convenção se aplica. O resultado esperado é o aprendizado aprovado associado a esse projeto. Se o resultado estiver vazio, verifique o estado de aprovação, o escopo do projeto e as palavras da consulta; a busca local do Beacon exige correspondência com todos os termos pesquisados.

Esse caminho pela CLI não exige MCP. Para recuperar dados por ferramentas do agente, o Beacon oferece um servidor MCP local separado com search_memory, get_memory e get_memory_context. Ele lê memórias locais aprovadas. Beacon Cloud usa um armazenamento separado; conectar um dispositivo não sincroniza esses dois armazenamentos de memória.

Controle aprendizados incorretos, dados privados e custos

Guarde conclusões com escopo bem definido e evidências, e trate o texto recuperado como informação histórica. Uma tentativa malsucedida pode refletir uma indisponibilidade temporária ou o uso da branch errada, em vez de uma regra permanente do projeto. Registre a situação em que o aprendizado se aplica, a tarefa ou o commit de origem, o resultado da verificação e a data da revisão; corrija ou retire a nota quando o comportamento que a sustenta mudar.

A aprovação faz parte de um processo; não comprova que uma pessoa verificou o conteúdo. Separe a pessoa que revisa um candidato do Beacon do agente que o propõe e impeça que instruções lembradas se sobreponham aos requisitos ou às permissões atuais.

A captura também muda onde os dados privados permanecem armazenados. As regras [capture] ignore_paths do ai-memory em .ai-memory.toml podem excluir eventos compatíveis baseados em caminhos, mas a documentação de uso afirma explicitamente que isso não é um filtro geral contra vazamentos em prompts e respostas. Não inclua credenciais nem dados de clientes em notas reutilizáveis; excluir a página Markdown atual pode deixar versões anteriores no Git.

No caso do Beacon Cloud, consulte a política de privacidade vigente antes de encaminhar sessões de trabalho. Em 2026-10-21, o uso para pesquisa e treinamento de modelos está ativado por padrão, com opção de desativação; o envio apenas de metadados ainda inclui informações como caminhos e linhas de comando. Armazenamento local também não torna local um modelo de programação em nuvem: o conteúdo recuperado para o contexto desse modelo passa a fazer parte de sua entrada.

Calcule os custos do processo completo. O fluxo padrão de memória do ai-memory não exige uma chave de API de modelo generativo, embora o modelo local de embeddings padrão possa ser baixado na primeira inicialização. O caminho do Beacon em que você escreve o aprendizado evita chamadas ao avaliador. O uso normal do agente de programação, o contexto adicional recuperado, o processamento opcional em nuvem, o armazenamento e o tempo de revisão ainda entram na conta; nenhuma das arquiteturas, por si só, comprova um custo total menor.

Antes de adotar uma camada de memória em todos os projetos, conclua uma troca real de ferramenta: recupere a decisão correta, identifique a ação inacabada, inspecione suas evidências e continue com base na cópia de trabalho atual. Se isso falhar, corrija o carregamento, o escopo ou a captura antes de acumular mais memória.