Sistema de Memórias (Memories e Chronicle): Fazendo o Codex lembrar de você entre conversas
📚 Navegação da Série: Anterior [18 config.toml Configuração detalhada] explicou as chaves de comportamento — modelo, sandbox e aprovações em um único arquivo. Esta parte aborda: como fazer o Codex lembrar de você entre conversas. Não se trata apenas das regras inseridas no
AGENTS.md, mas sim das 'notas pessoais' que ele gera a partir do seu uso — identificando uma preferência sinalizada por você e lembrando dela na próxima tarefa. Também apresentamos o Chronicle, recurso experimental do Codex que utiliza o conteúdo da tela como fonte de memória.
Veja este trecho de uma conversa real que tive com um colega de trabalho.
Colega: 「Sua versão do Codex não está com as memórias ativadas? Falei para ele 'use sempre o pnpm neste projeto', mas ele tentou rodar
npm installlogo depois.」Eu: 「Você esperou que ele memorizasse logo após digitar a frase?」
Colega: 「Sim, a conversa não apresentou erros.」
Eu: 「O salvamento da memória não ocorre em tempo real; ele aguarda o terminal ficar inativo por um período antes de gerar o resumo em segundo plano. Se você testar imediatamente, ele ainda não terá processado. Além disso, regras obrigatórias como essa devem constar no
AGENTS.md, sem depender das memórias.」
Esse diálogo ilustra os dois erros mais comuns com as memórias do Codex: achar que as memórias são salvas instantaneamente e achar que elas substituem o AGENTS.md. Ambos os pensamentos são incorretos e podem causar problemas no desenvolvimento. Esta parte detalhará o funcionamento desse sistema de memórias: o tempo de salvamento, onde ficam armazenadas, como gerenciá-las e o que não deve ser delegado a elas.
Ao ler esta parte, você obterá:
- A diferença entre as duas memórias do Codex: o arquivo manual
AGENTS.mde a memória autônoma Memories, com tabela comparativa - Se a memória vem ativada, restrições regionais, ativação no
config.toml, pasta de destino e o fluxo assíncrono de atualização - Uso do comando
/memoriespara gerenciar a leitura e gravação da conversa ativa, e as chaves de controle doconfig.toml - Critérios do que deve ser memorizado ou não, e o limite de segurança de credenciais
- O funcionamento do Chronicle — recurso experimental do Codex para ler informações da tela: limitações (Pro + macOS, indisponível em UK/EU/Suíça) e as três regras de privacidade oficiais
- Um laboratório prático: ativando, testando e validando a persistência das memórias
ℹ️ Diferença em relação ao Claude Code: no Claude Code a gravação automática vem ativada, separada por diretório Git e carregando as primeiras 200 linhas ou 25KB do arquivo
MEMORY.md. No Codex o funcionamento é diferente — desativado por padrão, com bloqueios regionais, geração em segundo plano e controles próprios de caminhos e comandos.
01 Compreendendo: Duas memórias independentes
O Codex utiliza dois sistemas de memória que atuam de forma isolada: o arquivo manual (AGENTS.md) e a memória autônoma gerada pelo sistema (Memories). Muitas vezes o termo 'memória do Codex' é associado apenas ao Memories, contudo ele representa apenas uma parte desse fluxo.
Analogia: A prancheta tática de um team vs. o bloco de notas do assistente. A prancheta tática (AGENTS.md) é definida pelo treinador antes do jogo — desenhando os posicionamentos, marcações e cobranças de faltas que toda a equipe deve seguir. O bloco de notas do assistente (Memories) contém anotações informais do jogo — 'o adversário defende mal pelo lado esquerdo' ou 'o atacante chuta com a perna direita'. Ninguém pediu para ele registrar esses detalhes; ele os coleta por conta própria para sugerir no futuro. Ambas as anotações ajudam, mas uma é a diretriz obrigatória, e a outra é a observação de apoio.
Mapeamento dos sistemas de memória:
| Característica | AGENTS.md | Memories (Sistema) |
|---|---|---|
| Escrita | Desenvolvedor (manual) | Codex (automático) |
| Conteúdo | Instruções e diretrizes obrigatórias | Preferências e contextos inferidos das tarefas |
| Exemplos | Comandos de build/testes, padrões de código, restrições | Tecnologias do projeto, rotinas repetitivas, erros corrigidos anteriormente |
| Status padrão | Ativo por padrão (se o arquivo existir no projeto) | Desativado por padrão (requer ativação) |
| Garantia de leitura | Determinístico (carregado a cada tarefa) | Probabilístico (gerado e carregado em segundo plano) |
| Versionamento | Salvo no projeto e versionado no Git | Local do sistema do usuário, não versionado |
Diferença essencial: o AGENTS.md guarda o que você quer que o Codex execute sempre, enquanto o Memories reúne observações acumuladas de conversas anteriores para poupar descrições repetidas. A documentação oficial reforça essa premissa:
Salve as regras obrigatórias de sua equipe no arquivo
AGENTS.mdou documentações do repositório. Trate as memórias do sistema como um facilitador de contexto local, e não como a única fonte de regras do seu fluxo de desenvolvimento.
Regras mandatórias devem ser mantidas no AGENTS.md. Vamos detalhar o funcionamento do Memories.
💡 Resumo em uma frase: O
AGENTS.mdé versionado e lido a cada tarefa de forma obrigatória, enquanto o Memories reúne anotações locais salvas em segundo plano para apoiar o fluxo de desenvolvimento.
A imagem ilustra os fluxos de memórias do Codex: a via esquerda representa a leitura determinística do AGENTS.md do repositório (com versionamento Git); a via direita demonstra a persistência e carregamento probabilístico das memórias locais em ~/.codex/memories/ (com suporte opcional do Chronicle para capturar elementos de tela, conforme seção 05). Ambas as fontes alimentam o contexto de inicialização de novas conversas.
02 Memories: pasta de destino e fluxo assíncrono
O Memories reúne preferências, padrões de código e resoluções de erros inferidas pelo Codex para evitar descrições repetitivas no início de novas conversas.
Analogia: A sintonia com um colega de equipe de longa data. Em um novo projeto com um auxiliar desconhecido, cada etapa deve ser explicada. Com um colega de longa data, a sintonia de trabalho elimina as introduções — pois ele lembra de suas preferências. O Memories traz essa sintonia ao Codex, acumulando observações a cada tarefa.
Ativação (Desativado por padrão)
Diferente de outras ferramentas, a memória do Codex restringe o uso:
O recurso Memories vem desativado por padrão e está bloqueado para contas sob a jurisdição do Reino Unido, Suíça e Espaço Econômico Europeu (EEA).
Habilite o recurso por dois caminhos:
Caminho 1: via arquivo de configuração (adicionando no ~/.codex/config.toml):
[features]
memories = trueCaminho 2: via interface gráfica (no menu de configurações do aplicativo do Codex).
⚠️ A restrição geográfica baseia-se em regras da empresa — contas dessas jurisdições permanecem bloqueadas mesmo sob conexões seguras externas (VPN).
O fluxo de salvamento: gravação em segundo plano
A documentação detalha a persistência das memórias:
1. A gravação analisa conversas finalizadas, ignorando rotinas parciais. Conversas curtas ou incompletas são desconsideradas para evitar poluir o histórico.
2. O salvamento ocorre após um período de inatividade. O Codex aguarda a conversa ficar inativa por algumas horas para garantir que a tarefa foi concluída antes de rodar o gerador de resumos em segundo plano.
3. A gravação depende dos limites de consumo (rate-limits). Se seu consumo estiver próximo do limite da API, a gravação em segundo plano será desativada para poupar seus tokens.
4. Credenciais de API e senhas são removidas. O gerador aplica uma máscara de descaracterização em chaves, embora essa rotina sirva como proteção secundária (veja seção 04).
Pasta de armazenamento
As memórias são salvas de forma estritamente local na pasta de usuário:
~/.codex/memories/
├── (arquivos de resumos)
├── (registros permanentes)
├── (entradas recentes)
└── (evidências de conversas anteriores)A documentação orienta a visualização:
As informações salvas no diretório
~/.codex/memories/servem como relatórios de estado para depuração ou compartilhamento do diretório de trabalho do Codex. Evite alterar estes arquivos markdown manualmente; gerencie o comportamento via comandos e chaves de configuração.
A tabela abaixo resume as diferenças de comportamento de escrita e persistência:
AGENTS.md | Memories | |
|---|---|---|
| Ativação | Sempre lido se existir no projeto | Desativado por padrão, ativado manualmente |
| Persistência | Lido ao iniciar a tarefa | Gravação em segundo plano após inatividade |
| Local | Na pasta do projeto (Git) | Na pasta local ~/.codex/memories/ (local) |
| Ajustes | Edição direta do arquivo markdown | Via comando /memories e chaves de configuração |
💡 Resumo em uma frase: O Memories é um recurso local desativado por padrão, salvo em
~/.codex/memories/de forma assíncrona após a inatividade do terminal, devendo ser gerenciado por opções de configuração.
03 Comando /memories e chaves de controle
O Codex permite controlar a leitura e gravação de dados da conversa ativa, definindo se ela consome memórias antigas ou se servirá de base para memórias futuras.
Analogia: Os botões de Gravação e Reprodução de um gravador. O botão de reprodução (usar memórias) determina se a IA lerá os dados de tarefas anteriores. O botão de gravação (gerar memórias) define se o histórico ativo será compilado no futuro. As opções funcionam de forma separada — permitindo ler sem gravar novas notas ou gravar novas notas sem ler históricos antigos.
Comando de conversa: /memories
Execute na janela ou terminal do Codex para gerenciar a conversa ativa:
/memoriesO menu trará as opções para ativar ou desativar a leitura de memórias e a gravação do histórico daquela conversa específica. Modificações por esse menu aplicam-se apenas à conversa ativa, sem alterar suas regras de configuração global.
Essa opção é útil para desativar a gravação ao rodar testes rápidos ou interagir com tarefas isoladas, evitando que o Codex salve dados irrelevantes no histórico permanente.
Configurações globais: config.toml
Para gerenciar as preferências do sistema de memórias de forma permanente, edite o bloco [memories] no ~/.codex/config.toml:
| Chave de Configuração | Comportamento | Valor Padrão |
|---|---|---|
memories.use_memories | Permite ler as memórias salvas ao iniciar conversas | true |
memories.generate_memories | Permite gerar memórias a partir de conversas qualificadas | true |
memories.disable_on_external_context | Desativa a gravação se a conversa usar MCPs ou pesquisa web | false |
memories.min_rate_limit_remaining_percent | Margem de tokens para bloquear a gravação (bloqueia se abaixo de %) | 25 |
memories.extract_model | Modelo de linguagem para extrair observações da conversa | Padrão do app |
memories.consolidation_model | Modelo de linguagem para unificar os blocos de memórias | Padrão do app |
Exemplo para ler o histórico existente sem gerar novas memórias nas conversas:
[memories]
generate_memories = false
use_memories = trueA chave disable_on_external_context (antigo nome no_memories_if_mcp_or_web_search) é uma configuração de segurança recomendada, pois evita que dados obtidos de APIs externas ou buscas na internet poluem suas memórias locais de desenvolvimento.
💡 Resumo em uma frase: Mude regras da conversa ativa com o comando
/memoriese defina comportamentos do sistema com as chavesuse_memories,generate_memoriesedisable_on_external_contextnoconfig.toml.
04 O que deve ser memorizado e limites de segurança
A gravação de dados do Memories atua em segundo plano. Contudo, você deve orientar o escopo do que deve ser salvo na memória e o que deve ser mantido restrito.
Tabela de referência de conteúdos:
| ❌ Evite delegar ao Memories | ✅ Escopo recomendado para o Memories |
|---|---|
Regras de build locais, comandos obrigatórios do projeto (use AGENTS.md) | Ferramentas de desenvolvimento habituais (ex: TypeScript, pytest) |
| Configurações temporárias de testes (ex: porta local 8080) | Padrões de commits ou fluxos de submissão do desenvolvedor |
| Instruções específicas de uma tarefa (ex: ajustando tela X) | Diretrizes de tratamento de exceções ou dependências locais |
| Chaves de API, senhas ou tokens (risco de vazamento de dados) | Erros de bibliotecas locais e como foram resolvidos no passado |
Diretrizes para avaliação das memórias:
1. Requisitos obrigatórios vs Contextos: qualquer instrução que o Codex deve seguir sempre deve residir no AGENTS.md. A gravação do Memories é probabilística e não garante leitura a cada ciclo de inicialização.
2. Dados temporários vs Dados perenes: informações específicas da tarefa em andamento não devem ser guardadas na memória de longo prazo, sob risco de atrapalharem as tarefas futuras.
3. Chaves de API e Senhas (Regra Geral):
Não salve senhas ou chaves nas memórias. O Codex aplica descaracterização em chaves, mas você deve auditar as pastas antes de compartilhar diretórios de trabalho.
As memórias residem em arquivos markdown de texto plano (sem criptografia). Não confie apenas no filtro de descaracterização nativo; mantenha credenciais e tokens fora das conversas do Codex e revise a pasta ~/.codex/memories/ antes de compartilhar o diretório.
💡 Resumo em uma frase: Regras obrigatórias de desenvolvimento devem ser salvas no
AGENTS.md; evite dados temporários e nunca insira senhas ou tokens nas conversas, auditando a pasta de memórias locais regularmente.
05 O recurso Chronicle (Memória baseada na visualização da tela)
O Codex traz uma funcionalidade exclusiva não presente no Claude Code: o Chronicle.
⚠️ Recurso em fase de avaliação (research preview) sob mudanças. O Chronicle lê informações e capturas de tela para compilar memórias contextuais. Menus de ativação, permissões e comportamentos padrões dependem do estado atual da ferramenta; consulte as orientações na documentação oficial.
O que é o Chronicle
Enquanto as memórias padrão extraem informações apenas dos textos digitados nas conversas, o Chronicle analisa o conteúdo exibido na tela (janelas ativas, erros visuais no navegador, abas de terminal abertas ou páginas de PR no browser) para enriquecer o contexto de memória da IA, facilitando a resolução de tarefas sem que você tenha que descrever todo o cenário.
Benefícios apontados na documentação:
- Reconhece o erro exibido na tela ativa automaticamente;
- Complementa o contexto de desenvolvimento local com o código visualizado;
- Identifica padrões e ferramentas adotadas de forma autônoma.
Em vezes de ler o conteúdo da tela de forma contínua, o Chronicle identifica caminhos de dados ativos (ex: abas do navegador abertas com issues do GitHub ou arquivos locais no editor) para buscar informações direto de suas fontes de dados nativas.
Limitações de uso
O Chronicle possui restrições severas de ativação:
O Chronicle exige assinatura ChatGPT Pro ativa, funciona apenas no macOS e está bloqueado em contas sob a jurisdição do Reino Unido, Suíça e EEA.
Para habilitá-lo, o usuário deve possuir o app do Codex no macOS, conceder permissões de Screen Recording (gravação de tela) e Accessibility (acessibilidade) no sistema, acessar o menu Personalization nas configurações do aplicativo e ativar a opção Chronicle.
Regras de Privacidade e Segurança
A documentação detalha as precauções no uso do Chronicle:
1. Consumo de cota de chamadas elevado: o fluxo de captura e análise de tela em segundo plano consome cota de chamadas do plano com maior velocidade.
2. Injeção de instruções visual: dados mostrados na tela (como sites de terceiros abertos no navegador contendo instruções maliciosas) podem ser interpretados como comandos pelo Chronicle, gerando riscos de segurança.
3. Persistência local sem criptografia: as memórias geradas pelo Chronicle são salvas na pasta local como arquivos de texto sem criptografia.
Para mitigar riscos, use o botão de pausar no menu do Codex (Pause Chronicle) ao lidar com informações sensíveis (como senhas, dados de clientes ou dados bancários) ou em chamadas de vídeo compartilhadas. O Chronicle não grava áudio, mas captura imagens exibidas na tela.
Armazenamento de dados
- Capturas de tela: são armazenadas temporariamente no caminho de arquivos temporários do sistema (
$TMPDIR/chronicle/screen_recording/) e removidas após 6 horas. - Memórias salvas: residem em formato markdown em
~/.codex/memories_extensions/chronicle/. Você pode editar ou remover arquivos para apagar registros indesejados. - Tratamento de dados: as capturas de tela e OCRs processados nos servidores da OpenAI são descartados após a geração da memória, sem serem mantidos para treinamento de modelos.
💡 Resumo em uma frase: O Chronicle é um recurso experimental para macOS que extrai dados da tela ativa, restrito a assinaturas Pro fora de UK/EU/Suíça, devendo ser pausado (
Pause Chronicle) ao lidar com dados sensíveis.
Esta imagem apresenta a divisão dos dois sistemas de memórias: as Memories à esquerda (geradas a partir das conversas do terminal e salvas na pasta padrão de usuário) e o Chronicle à direita (extraindo informações do conteúdo visível na tela e salvando as propriedades em um diretório próprio do macOS para usuários Pro), auxiliando na contextualização das conversas.
06 Laboratório: Ativação e validação do sistema de memórias
Vamos realizar o fluxo de ativação, gravação e checagem de memórias no terminal. O laboratório funciona nos diferentes sistemas homologados.
Restrição: o laboratório requer que a conta do Codex possua acesso ao recurso (bloqueado em contas sob a jurisdição do Reino Unido, Suíça e EEA).
Passo 1: Ativar as memórias.
Edite o arquivo de configuração ~/.codex/config.toml e adicione a chave de ativação:
[features]
memories = trueSalve as alterações.
Passo 2: Iniciar a conversa no terminal.
Crie uma pasta temporária e inicie o Codex:
mkdir memory-demo
cd memory-demo
codexPasso 3: Passar uma preferência de desenvolvimento.
Diga para o Codex na conversa:
Neste projeto eu uso pytest para executar testes locais. Lembre-se desta preferência.Resultado esperado: o Codex reconhecerá a mensagem e responderá normalmente. O dado não será gravado no arquivo local na hora, pois o gerador aguarda a inatividade da conversa em segundo plano.
Passo 4: Usar o controle de conversa /memories.
Confirme o status da conversa ativa digitando:
/memoriesResultado esperado: um menu com opções de leitura e escrita será exibido. Selecione a opção para desativar a gravação de novos dados para testar o bloqueio de histórico.
Passo 5: Verificar os arquivos locais.
Após o período de inatividade da conversa (ou após simular o encerramento do terminal), verifique a pasta de memórias locais:
ls ~/.codex/memories/Resultado esperado: a pasta conterá arquivos markdown com resumos e dados inferidos a partir do uso. Caso a pasta permaneça vazia, verifique a chave memories = true nas configurações, se o consumo de cota está abaixo da margem (mínimo 25% livre) ou se a conta está sob regras regionais de restrição.
Este laboratório validou a ativação e o caminho de gravação do Memories de forma simples.
💡 Resumo em uma frase: O laboratório prático demonstra a gravação local de preferências no Memories e o papel do comando de conversa
/memoriespara gerenciar a conversa ativa de forma simples.
07 Resumo
Esta seção apresentou o funcionamento e a gestão de memórias locais no Codex.
Mapeamento dos conceitos:
| Objetivo | Mecanismo | Instrução de uso |
|---|---|---|
| Diretrizes do projeto | AGENTS.md | Regras que devem ser lidas sempre, salvas e versionadas no repositório |
| Preferências locais | Memories | Memórias geradas pelo sistema em segundo plano, desativadas por padrão |
| Controle da conversa | Comando /memories | Menu para desativar ou habilitar a memória na conversa ativa |
| Segurança de dados | Arquivo texto plano | Evite credenciais nas conversas; revise a pasta memories/ antes de compartilhar |
| Memória visual | Chronicle | Recurso experimental macOS Pro que analisa a tela; ative apenas fora de UK/EU/Suíça |
A partir de agora, você compreende: a diferença entre AGENTS.md e o Memories e quando adotar cada ferramenta, como habilitar e configurar o sistema de memórias no config.toml, as restrições regionais aplicadas e o funcionamento de triagem de tela com o Chronicle. O gerenciamento dessas memórias ajuda a personalizar a atuação do agente sem expor seus dados.
A próxima seção 20 · Conectores MCP (Model Context Protocol) — abordará o recurso de integração externa: como conectar o Codex a bancos de dados, APIs e ferramentas usando o Model Context Protocol (MCP)? Como configurar novos servidores MCP no config.toml? Mapeados os fluxos de memória locais, vejamos como o Codex interage com sistemas externos.