# Shared memory for AI coding agents: a project brain

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

Shared memory for AI coding agents: how a project brain keeps decisions, handoff notes and corrections so every new Claude Code or Codex session starts informed.

**In short:**

- Each new agent session starts blank. A shared project memory keeps decisions, corrections and handoff notes, so the next agent does not repeat old mistakes or reopen settled questions.
- AgentVera’s Brain builds that memory from your docs, commits, PRs, issues and past agent conversations, and marks each decision as current, stale or superseded.
- Agents read and write it over MCP: brain_recall searches the memory, brain_remember keeps a correction or decision, and short handoff notes are left after turns and on compaction.

**Shared memory for AI coding agents is a project-level store of decisions, corrections and handoff notes that every agent reads at the start and adds to while it works, so a new session does not start from zero.** Without it, each Claude Code or Codex session knows only what is in the repo and its instruction files. With it, the next agent knows why you picked JWT, that the user already said "no new dependencies", and that the last agent left the refund flow half done.

This post explains why agents forget, what belongs in a shared memory, and how AgentVera’s Brain builds one from your project history and lets agents read and write it over MCP.

## Why coding agents forget

A coding agent’s memory is its context window. When the session ends, or when the conversation is compacted, most of what happened is gone. The next session gets:

- The system prompt and tool definitions
- Your instruction files, such as `CLAUDE.md` or `AGENTS.md`
- Whatever it reads from the repo during the task

That works for code, because the code is in the repo. It fails for reasons. The commit says *what* changed; the reason often lives in a PR comment, an issue or a conversation with an agent that no longer exists. So agents ask the same questions, propose the approach you rejected last week and redo work another agent already finished. When you [run several agents in parallel](/en/blog/run-multiple-claude-code-agents/ "Run multiple Claude Code agents"), this gets worse: each one learns something the others never see.

## What belongs in a shared memory

Instruction files and a shared memory do different jobs.

| | Instruction file (CLAUDE.md, AGENTS.md) | Shared memory |
| --- | --- | --- |
| Written by | You, by hand | Built from history, plus agents as they work |
| Content | Rules, commands, conventions | Decisions with reasons, corrections, handoff notes |
| Changes | Rarely | Every day |
| Loaded | Whole file, every session | Searched when needed, short summary at start |
| Knows when it is out of date | No | Can mark decisions stale or superseded |

Keep your instruction file short and stable ([how to write one](/en/blog/claude-md-agents-md/ "CLAUDE.md and AGENTS.md")). Put the moving parts in memory. A useful shared memory holds four kinds of things:

1. **Decisions.** "We use JWT for the API because sessions broke the mobile app", with the date and the source.
2. **Corrections.** Things the user told an agent it got wrong. These are the most expensive to lose.
3. **Handoff notes.** What an agent did, and what it left open.
4. **Facts.** Small truths about the project that are not obvious from the code.

## How AgentVera’s Brain builds the memory

In AgentVera, each project has a **Brain** tab on its Details page. Click **Build memory** (later **Refresh memory**) and it reads the project’s history:

- Git-tracked docs and decision records: README, ARCHITECTURE, CONTRIBUTING, CLAUDE, AGENTS, CHANGELOG, `docs/`, `adr/` and `decisions/` (up to 250 files)
- The newest 1,500 non-merge commits
- Up to 200 pull requests and 200 issues, if the project is on GitHub and you are signed in
- Up to 120 past agent conversations

Claude Haiku pulls the decisions out of that material. Each one gets a title, the reason, a date, its sources and the code terms it is about. Duplicates are merged.

Decisions are not true forever, so each one has a status: **current**, **stale** or **superseded**. **Compare with code** checks a decision’s code terms against the repo with `git grep`. **Verify with Claude** runs a read-only Sonnet check for a closer look. That way the memory can tell an agent "we decided this, but the code moved on".

The Brain tab has four views: **Decisions**, **Knowledge graph**, **Context pack** and **Memory**. There is also an **Ask** box. Ask "Why do we use JWT?" and Sonnet answers from the memory, read-only, with citations to the sources.

## How agents read and write the memory

Building the memory is half the job. The other half is getting agents to use it. AgentVera adds an MCP server named `agentvera-brain` to every agent whose CLI takes MCP servers. If MCP is new to you, start with [what an MCP server is](/en/blog/what-is-mcp-server/ "What is an MCP server?").

The server has two tools:

| Tool | What it does |
| --- | --- |
| `brain_recall` | Searches decisions (with their status), docs, commits, PRs, issues, past conversations, handoff notes and remembered facts. Returns up to 8 hits, each with an `[id]` to cite. Called without a query, it returns the kept memories and open threads. |
| `brain_remember` | Keeps one self-contained sentence as a `fact`, `correction` or `decision`. Not meant for progress updates. Identical text is not stored twice. |

The server also tells the agent when to use them: call `brain_recall` before a task that touches earlier work, call `brain_remember` when the user corrects it, states a rule or preference, or a decision is made, and cite items by `[id]`.

A typical exchange in a Claude Code session looks like this:

```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)
```

The next agent that touches auth finds both, without you repeating yourself.

## Handoff notes: memory between sessions

The **Agents write the memory** switch on the Brain tab is on unless you turn it off. With it on:

- After turns (at most every 15 minutes per agent), and always when an agent compacts its conversation, the agent leaves a short handoff note. Haiku writes it: a summary of one to four sentences and up to six open threads, shown as **Left open**.
- Corrections and decisions the agent keeps with `brain_remember` go into the same memory.
- New agents of the project get the recent ones.
- Between 03:00 and 06:00 the brain is compiled again, but only if it was built before, there are new notes since, and at most once every 12 hours.

Notes and memories are listed in the **Memory** view, labeled Fact, Correction, Decision or Session note. **Forget** removes one.

When a new agent starts, its instructions get a short intro of up to 2,500 characters: the kept memories (corrections first, up to 15), plus the newest note from up to six other agents of the last seven days that still have open threads. This is what makes compaction less painful: the summary Claude Code writes is gone after the session, but the handoff note stays. For more on what compaction keeps and drops, see [Claude Code context window](/en/blog/claude-code-context-window/ "Claude Code context window").

## The context pack

Separately, the **Context pack** view holds a summary of the project of up to 2,500 characters. Turn on **Give new agents a context pack** and new agents get the pack plus the list of stale decisions in their instructions. It is off by default, because it adds to every new agent’s starting context. Turn it on if your agents keep missing the same background.

## Setting it up in five steps

1. Open the project in AgentVera and go to **Details → Brain**.
2. Click **Build memory**. Sign in to GitHub first if you want PRs and issues included.
3. Look through **Decisions**. Run **Compare with code** on the ones you doubt.
4. Leave **Agents write the memory** on, and decide whether you want the context pack.
5. Start a new Claude Code or Codex agent and give it a task that touches earlier work. Watch it call `brain_recall`.

## Shared memory and coordination

Memory answers "what do we know?". Coordination answers "who is doing what right now?". For live work, AgentVera also gives agents a notice board over MCP (`agentvera-board`) where they post notes, decisions, todos and findings, and it warns when two agents edit the same file. The two fit together: the board is for today, the Brain is for next month.

Memory also pairs well with the [project map](/en/features/project-map/ "Project map"). The map tells an agent *where* code is; the Brain tells it *why* the code is that way.

## Limits to know

- The Brain is added to agents that take MCP servers. Plain terminals and agents on a remote SSH host do not get it.
- Session notes and memories each keep up to 200 entries.
- Everything is stored locally, one file per project in the app’s data folder. Decision extraction, handoff notes and answers use Claude through your Claude Code login, so those requests go to Anthropic.
- A memory is only as good as what it keeps. Review the Memory view now and then and forget notes that are wrong.

## Summary

Shared memory for AI coding agents fills the gap between static instruction files and a context window that resets. AgentVera’s Brain builds it from your docs, commits, PRs, issues and conversations, tracks which decisions still hold, and lets every MCP-capable agent recall and remember over `agentvera-brain`, with handoff notes after turns and on compaction. The Brain is part of the free plan. Read the [Brain feature page](/en/features/brain/ "Brain") or [download AgentVera](/en/download/) and build your first project memory.

## Frequently asked questions

**What is shared memory for AI coding agents?** A store of project knowledge that every agent can read and add to: why decisions were made, what the user corrected, what a previous agent left open. It outlives a single session, so a new agent starts with the context the last one had.

**Is CLAUDE.md not enough?** CLAUDE.md and AGENTS.md hold rules you write by hand and that rarely change. A shared memory also holds what happens while you work: decisions from commits and PRs, corrections, handoff notes and which decisions the code no longer follows.

**How do agents use the Brain in AgentVera?** Through an MCP server named agentvera-brain. brain_recall searches decisions, docs, commits, PRs, issues, past conversations and notes; brain_remember keeps one sentence as a fact, correction or decision. Agents are told to cite what they use by its [id].

**Which agents get the shared memory?** Agents whose CLI takes MCP servers, such as Claude Code and Codex. Plain terminals and agents on a remote SSH host do not get it.

**Where is the memory stored?** On your computer, one file per project in the app’s data folder. Extracting decisions and answering questions uses Claude through your Claude Code login, so those requests go to Anthropic.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/