CLAUDE.md, AGENTS.md and a shared team memory

CLAUDE.md, AGENTS.md, and a memory the whole team shares.

If your team codes with AI, you probably keep instruction files in the repository: CLAUDE.md for Claude Code, AGENTS.md for Codex and the other agents that read it. They are the right tool for one job. They are the wrong home for a team's evolving knowledge, and the difference starts to hurt at about three people and two tools.

What these files do well

An instruction file sits next to the code and loads when an agent starts. That makes it ideal for what changes with the repository: how to build and test, the style rules, the directories to leave alone, the commands that are safe to run. Checked into git, the file is reviewed like code and versioned with it. For one developer with one tool, that is often all the memory they need.

Where they break for a team

  • Two tools, two files. One teammate works in Claude Code and another in Codex, so the same decisions get written into CLAUDE.md and AGENTS.md, and the two copies drift within a week.
  • Decisions are not repository facts. Why the matching logic works the way it does, what the design settled on, what is left before launch: that is the team's working knowledge, and a file that loads with the code is an awkward place to keep it.
  • Nobody can see who wrote what. An agent that edits its own instruction file rewrites the team's memory in the middle of a diff. Weeks later, nobody remembers which session added the wrong assumption.
  • Local memory stays local. Whatever a tool keeps outside the repository, per person and per machine, never reaches the teammate who needs it tomorrow.

The thin file

Keep the instruction files, and keep them thin. Let them hold what belongs to the repository, and point every agent at one shared memory for everything else.

1

Repository facts stay in the file

Build and test commands, style rules, and paths to avoid stay in CLAUDE.md or AGENTS.md, reviewed like code.

2

One line points at the memory

Add a line telling the agent to read the team's shared memory before it starts and to record decisions there, not in the file.

3

Every tool reads the same place

Connect each tool to that memory over MCP, each as its own agent, so what Codex records in the morning is what Claude reads in the afternoon.

What changes for the team

The two instruction files stop competing, because neither carries the team's decisions anymore. A teammate who joins asks their own agent what changed this week and gets an answer with names. When an agent records something wrong, the history shows which one wrote it and when, and the fix is one line instead of an archaeology project.

History of deals/harborview.md
Atlas (AI) · 2 minutes ago · updated · Diff Revert
What Atlas changed: -cap rate holds at the broker number +double-counted unit moves the cap rate 40 bps ... 12 unchanged lines ...
Reverting never erases anything: it adds a new version on top.

Put what belongs to the code in the code. Put what the team knows in one memory every tool shares.

What to keep where

In CLAUDE.md or AGENTS.md

Commands, conventions, and constraints that change when the repository changes.

In the shared memory

Decisions and their reasons, who is working on what, what is left, and what each session learned.

Memava is a shared memory built for this: plain markdown every MCP tool can read and write, each tool connected as its own agent, every line attributed, and an end-of-session log skill in every new vault. The Connect AI panel in each vault has a ready line to paste into AGENTS.md or CLAUDE.md. See the setup pages.

Start free for 30 days Walk through a live vault

Keep reading: Connect Claude to a shared team memory · MCP security: what to check before you connect AI to your notes · One memory across Claude, Cursor and ChatGPT