# Memória compartilhada para agentes de código com IA

URL: https://agentvera.dev/pt/blog/shared-memory-for-ai-coding-agents/ · Publicado: 2026-10-24

Memória compartilhada para agentes de código: como um cérebro do projeto guarda decisões, notas de passagem e correções para cada nova sessão começar informada.

**Resumo:**

- Cada nova sessão de agente começa em branco. Uma memória compartilhada do projeto guarda decisões, correções e notas de passagem, para que o próximo agente não repita erros antigos nem reabra questões resolvidas.
- O Brain do AgentVera monta essa memória a partir dos seus docs, commits, PRs, issues e conversas antigas de agentes, e marca cada decisão como atual, desatualizada ou substituída.
- Os agentes a leem e escrevem via MCP: brain_recall busca na memória, brain_remember guarda uma correção ou decisão, e notas de passagem curtas ficam registradas após os turnos e na compactação.

**Memória compartilhada para agentes de código com IA é um repositório, no nível do projeto, de decisões, correções e notas de passagem que todo agente lê no início e amplia enquanto trabalha, para que uma nova sessão não comece do zero.** Sem ela, cada sessão do Claude Code ou do Codex só sabe o que está no repositório e nos arquivos de instruções. Com ela, o próximo agente sabe por que você escolheu JWT, que o usuário já disse “nada de dependências novas” e que o último agente deixou o fluxo de reembolso pela metade.

Este post explica por que os agentes esquecem, o que deve ficar numa memória compartilhada e como o Brain do AgentVera monta uma a partir do histórico do projeto e deixa os agentes lerem e escreverem nela via MCP.

## Por que os agentes de código esquecem

A memória de um agente de código é a janela de contexto dele. Quando a sessão termina, ou quando a conversa é compactada, a maior parte do que aconteceu some. A próxima sessão recebe:

- O system prompt e as definições de ferramentas
- Seus arquivos de instruções, como `CLAUDE.md` ou `AGENTS.md`
- O que ela ler do repositório durante a tarefa

Isso funciona para o código, porque o código está no repositório. Falha para os motivos. O commit diz *o que* mudou; o motivo muitas vezes está num comentário de PR, numa issue ou numa conversa com um agente que já não existe. Então os agentes fazem as mesmas perguntas, propõem a abordagem que você rejeitou na semana passada e refazem trabalho que outro agente já terminou. Quando você [roda vários agentes em paralelo](/pt/blog/run-multiple-claude-code-agents/ "Rodar vários agentes do Claude Code"), fica pior: cada um aprende algo que os outros nunca veem.

## O que deve ficar numa memória compartilhada

Arquivos de instruções e uma memória compartilhada fazem trabalhos diferentes.

| | Arquivo de instruções (CLAUDE.md, AGENTS.md) | Memória compartilhada |
| --- | --- | --- |
| Escrito por | Você, à mão | Montada a partir do histórico, mais os agentes enquanto trabalham |
| Conteúdo | Regras, comandos, convenções | Decisões com motivos, correções, notas de passagem |
| Muda | Raramente | Todo dia |
| Carregado | O arquivo inteiro, em toda sessão | Buscada quando preciso, com um resumo curto no início |
| Sabe quando está desatualizado | Não | Pode marcar decisões como desatualizadas ou substituídas |

Mantenha seu arquivo de instruções curto e estável ([como escrever um](/pt/blog/claude-md-agents-md/ "CLAUDE.md e AGENTS.md")). Coloque as partes que mudam na memória. Uma memória compartilhada útil guarda quatro tipos de coisa:

1. **Decisões.** “Usamos JWT na API porque sessões quebraram o app de celular”, com a data e a fonte.
2. **Correções.** Coisas que o usuário disse a um agente que ele errou. São as mais caras de perder.
3. **Notas de passagem.** O que um agente fez e o que deixou em aberto.
4. **Fatos.** Pequenas verdades sobre o projeto que não são óbvias pelo código.

## Como o Brain do AgentVera monta a memória

No AgentVera, cada projeto tem uma aba **Brain** na página de detalhes. Clique em **Build memory** (depois **Refresh memory**) e ele lê o histórico do projeto:

- Docs rastreados pelo git e registros de decisão: README, ARCHITECTURE, CONTRIBUTING, CLAUDE, AGENTS, CHANGELOG, `docs/`, `adr/` e `decisions/` (até 250 arquivos)
- Os 1.500 commits mais recentes que não são de merge
- Até 200 pull requests e 200 issues, se o projeto está no GitHub e você fez login
- Até 120 conversas antigas de agentes

O Claude Haiku extrai as decisões desse material. Cada uma recebe um título, o motivo, uma data, as fontes e os termos de código a que se refere. Duplicatas são mescladas.

Decisões não valem para sempre, então cada uma tem um status: **current**, **stale** ou **superseded** (atual, desatualizada ou substituída). **Compare with code** confere os termos de código de uma decisão contra o repositório com `git grep`. **Verify with Claude** roda uma checagem somente leitura com o Sonnet para um olhar mais atento. Assim a memória pode dizer a um agente “decidimos isso, mas o código seguiu outro caminho”.

A aba Brain tem quatro visões: **Decisions**, **Knowledge graph**, **Context pack** e **Memory**. Há também uma caixa **Ask**. Pergunte “Por que usamos JWT?” e o Sonnet responde a partir da memória, somente leitura, citando as fontes.

## Como os agentes leem e escrevem a memória

Montar a memória é metade do trabalho. A outra metade é fazer os agentes a usarem. O AgentVera adiciona um servidor MCP chamado `agentvera-brain` a todo agente cuja CLI aceita servidores MCP. Se MCP é novidade para você, comece por [o que é um servidor MCP](/pt/blog/what-is-mcp-server/ "O que é um servidor MCP?").

O servidor tem duas ferramentas:

| Ferramenta | O que faz |
| --- | --- |
| `brain_recall` | Busca decisões (com o status), docs, commits, PRs, issues, conversas antigas, notas de passagem e fatos guardados. Retorna até 8 resultados, cada um com um `[id]` para citar. Chamada sem consulta, retorna as memórias guardadas e as pendências abertas. |
| `brain_remember` | Guarda uma frase autossuficiente como `fact`, `correction` ou `decision`. Não serve para atualizações de progresso. Texto idêntico não é guardado duas vezes. |

O servidor também diz ao agente quando usá-las: chamar `brain_recall` antes de uma tarefa que toca trabalho anterior, chamar `brain_remember` quando o usuário o corrige, declara uma regra ou preferência, ou quando uma decisão é tomada, e citar os itens pelo `[id]`.

Uma troca típica numa sessão do Claude Code fica assim:

```text
You: Add refresh tokens to the API.
Agent: (calls brain_recall "auth tokens JWT")
       Found [d12] "Use JWT for the API, sessions broke the mobile app" (current)
       and a correction [m4] "Never store tokens in localStorage".
       I will keep JWT and put the refresh token in an httpOnly cookie.
You: Good. And refresh tokens expire after 30 days.
Agent: (calls brain_remember, kind: decision)
```

O próximo agente que mexer em autenticação encontra as duas coisas, sem você precisar se repetir.

## Notas de passagem: memória entre sessões

O interruptor **Agents write the memory** na aba Brain fica ligado a menos que você o desligue. Com ele ligado:

- Depois dos turnos (no máximo a cada 15 minutos por agente), e sempre que um agente compacta a conversa, o agente deixa uma nota de passagem curta. Quem escreve é o Haiku: um resumo de uma a quatro frases e até seis pendências abertas, mostradas como **Left open**.
- Correções e decisões que o agente guarda com `brain_remember` vão para a mesma memória.
- Novos agentes do projeto recebem as mais recentes.
- Entre 03:00 e 06:00 o brain é compilado de novo, mas só se já tiver sido montado antes, houver notas novas desde então, e no máximo uma vez a cada 12 horas.

Notas e memórias aparecem na visão **Memory**, marcadas como Fact, Correction, Decision ou Session note. **Forget** remove uma.

Quando um novo agente começa, as instruções dele recebem uma introdução curta de até 2.500 caracteres: as memórias guardadas (correções primeiro, até 15), mais a nota mais recente de até seis outros agentes dos últimos sete dias que ainda têm pendências abertas. É isso que torna a compactação menos dolorosa: o resumo que o Claude Code escreve some depois da sessão, mas a nota de passagem fica. Para saber mais sobre o que a compactação mantém e descarta, veja [janela de contexto do Claude Code](/pt/blog/claude-code-context-window/ "Janela de contexto do Claude Code").

## O context pack

À parte, a visão **Context pack** guarda um resumo do projeto de até 2.500 caracteres. Ative **Give new agents a context pack** e os novos agentes recebem o pack mais a lista de decisões desatualizadas nas instruções. Fica desligado por padrão, porque aumenta o contexto inicial de todo novo agente. Ligue se seus agentes vivem perdendo o mesmo contexto de fundo.

## Configurando em cinco passos

1. Abra o projeto no AgentVera e vá em **Details → Brain**.
2. Clique em **Build memory**. Faça login no GitHub antes se quiser incluir PRs e issues.
3. Revise as **Decisions**. Rode **Compare with code** nas que te deixam em dúvida.
4. Deixe **Agents write the memory** ligado e decida se quer o context pack.
5. Inicie um novo agente do Claude Code ou do Codex e dê a ele uma tarefa que toque trabalho anterior. Veja-o chamar `brain_recall`.

## Memória compartilhada e coordenação

A memória responde “o que sabemos?”. A coordenação responde “quem está fazendo o quê agora?”. Para o trabalho ao vivo, o AgentVera também dá aos agentes um quadro de avisos via MCP (`agentvera-board`), onde eles publicam notas, decisões, tarefas e descobertas, e avisa quando dois agentes editam o mesmo arquivo. Os dois se completam: o quadro é para hoje, o Brain é para o mês que vem.

A memória também combina bem com o [mapa do projeto](/pt/features/project-map/ "Mapa do projeto"). O mapa diz a um agente *onde* o código está; o Brain diz *por que* o código é assim.

## Limites que vale saber

- O Brain é adicionado a agentes que aceitam servidores MCP. Terminais simples e agentes num host SSH remoto não o recebem.
- Notas de sessão e memórias guardam até 200 entradas cada.
- Tudo fica armazenado localmente, um arquivo por projeto na pasta de dados do app. A extração de decisões, as notas de passagem e as respostas usam o Claude pelo seu login do Claude Code, então essas requisições vão para a Anthropic.
- Uma memória só é tão boa quanto o que ela guarda. Revise a visão Memory de vez em quando e esqueça as notas que estiverem erradas.

## Resumo

Memória compartilhada para agentes de código com IA preenche o vão entre arquivos de instruções estáticos e uma janela de contexto que reinicia. O Brain do AgentVera a monta a partir dos seus docs, commits, PRs, issues e conversas, acompanha quais decisões ainda valem e deixa todo agente com suporte a MCP lembrar e guardar via `agentvera-brain`, com notas de passagem após os turnos e na compactação. O Brain faz parte do plano gratuito. Leia a [página do recurso Brain](/pt/features/brain/ "Brain") ou [baixe o AgentVera](/pt/download/) e monte a primeira memória do seu projeto.

## Perguntas frequentes

**O que é memória compartilhada para agentes de código com IA?** Um repositório de conhecimento do projeto que todo agente pode ler e ampliar: por que decisões foram tomadas, o que o usuário corrigiu, o que um agente anterior deixou em aberto. Ela sobrevive a uma única sessão, então um novo agente começa com o contexto que o último tinha.

**O CLAUDE.md não basta?** CLAUDE.md e AGENTS.md guardam regras que você escreve à mão e que raramente mudam. Uma memória compartilhada também guarda o que acontece enquanto você trabalha: decisões vindas de commits e PRs, correções, notas de passagem e quais decisões o código já não segue.

**Como os agentes usam o Brain no AgentVera?** Por um servidor MCP chamado agentvera-brain. brain_recall busca decisões, docs, commits, PRs, issues, conversas antigas e notas; brain_remember guarda uma frase como fato, correção ou decisão. Os agentes são orientados a citar o que usam pelo [id].

**Quais agentes recebem a memória compartilhada?** Agentes cuja CLI aceita servidores MCP, como o Claude Code e o Codex. Terminais simples e agentes num host SSH remoto não a recebem.

**Onde a memória fica armazenada?** No seu computador, um arquivo por projeto na pasta de dados do app. Extrair decisões e responder perguntas usa o Claude pelo seu login do Claude Code, então essas requisições vão para a Anthropic.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/