One Repository. One Shared Brain.

A practical guide to shared AI memory for development teams.

The problem: your team's knowledge is trapped in chat logs

Git synchronizes source code. It does not synchronize what your AI learned while writing it.

Most development teams now work with AI coding assistants, and most teams use more than one. One developer prefers Claude Code, another works in Cursor, a third runs Codex. Each assistant builds a private model of the project inside its own conversation history: which approaches were already rejected, why a flow is locked to one specific mode, which innocent-looking refactor causes an incident. The code lands in the repository. The understanding never does.

The symptoms are familiar to anyone working this way: the same requirements re-explained in every new session, different assistants proposing conflicting architectures, decisions re-litigated because the reasoning behind them evaporated, and the same landmines rediscovered by each person. On my own team, reviewing our history, one class of authorization bug shipped six separate times in four months. Each time, the developer and agent who fixed it learned the lesson. The knowledge then disappeared into a chat log, and the next feature reintroduced the bug.

The root cause is simple to state. Teams version their source code, documentation, and infrastructure. They do not version engineering decisions, rejected alternatives, implementation rationale, or the knowledge their AI assistants accumulate. This guide fixes that with plain files and the version control you already have.

The principle: commit the contract, not the machinery

Docker did not unify runtime environments by running a synchronization service. It unified them with a committed text file. docker-compose.yml travels with the repository, and every machine interprets it identically. The environment problem became a file-contract problem, and git solved distribution for free.

Shared AI memory has exactly the same shape. The missing piece is a file contract that every agent reads at session start and writes back to before session end. Git is already the bus, and no new infrastructure is required.

Everything below follows from that one idea.

What already exists (as of July 2026)

You do not need to invent conventions. Four building blocks matter:

The three-layer architecture

Layer 1: rules. One canonical AGENTS.md per repository. Architecture overview, build and test commands, conventions, review criteria, and the session contract from this guide. Stable content that changes rarely.

Layer 2: evolving knowledge. A committed .ai/ directory holding the state of play: current work, decisions, known issues, lessons. Changes weekly or daily, versioned and reviewed like code.

Layer 3: personal. Machine paths, private preferences, credentials, each assistant's own local memory. Gitignored, never committed, never shared.

The separation matters because the three layers have different change rates and different trust levels. Mixing them is how instruction files grow stale and how secrets end up in git history.

One more thing before the implementation: the shared memory serves humans as much as agents. A new developer inherits the project's accumulated intelligence by reading one small directory, instead of assembling tribal knowledge one conversation at a time.

                        repository
   +--------------------------------------------------+
   |                                                  |
   |   AGENTS.md   rules + the session contract       |
   |       ^                                          |
   |       |  one-line shims (CLAUDE.md, ...)         |
   |                                                  |
   |   .ai/        evolving shared memory             |
   |               STATE.md, decisions/, lessons...   |
   |                                                  |
   |   src/        the code itself                    |
   |                                                  |
   +--------------------------------------------------+
        ^                 ^                 ^
        |                 |                 |
   Claude Code         Cursor            Codex
        |                 |                 |
   every agent reads at session start,
   writes back before session end

Implementation, step by step

Step 1: create AGENTS.md

Move your existing agent instructions, whatever file they live in today, into a root AGENTS.md. Keep it under a few hundred lines: what the project is, how to build and test it, the conventions that are non-negotiable, and the session contract from step 5. In a monorepo, the standard supports nested AGENTS.md files; the nearest file wins, so subprojects can carry their own specifics.

Step 2: bridge every tool to it

Tools that read AGENTS.md natively need nothing. For the rest, create a shim rather than a copy:

# CLAUDE.md (entire file)
@AGENTS.md

All project instructions live in AGENTS.md, the cross-tool
canonical file. Do not add instructions here.

The rule is one source of truth with thin pointers, never parallel files. Two instruction files that drift apart are worse than one imperfect file.

Step 3: scaffold the .ai/ directory

.ai/
  STATE.md         <- THE handoff. Current state, in-flight work,
                      next steps, open questions. Rewritten at the
                      end of every session, never appended.
                      Capped at ~100 lines.
  INDEX.md         <- one line per file below
  architecture.md  <- how the system hangs together, and WHY
  conventions.md   <- evolving patterns not yet stable enough
                      for AGENTS.md
  known-issues.md  <- live landmines, each entry dated
  lessons.md       <- failures already paid for
  decisions/
    ADR-001-....md <- one decision per file: context, decision,
    ADR-002-....md    consequences, rejected alternatives.
                      Immutable once accepted; superseded,
                      never edited.

Resist the urge to add more files. Overlapping files holding the same fact in two places is guaranteed drift. If two files could hold a fact, you have one file too many.

Step 4: seed it, never launch it empty

An empty knowledge base teaches the team to ignore it. Spend the first half day promoting knowledge that already exists: the architecture explanation you keep re-typing, the decision you have defended three times, the incident postmortems, the landmines everyone tiptoes around. Ask your AI assistant to draft the seed content from your conversation history, then edit it down by hand. Sanitize as you go; step 7 of the checklist covers what must never be included.

Step 5: write the session contract into AGENTS.md

Three imperative bullets. Long policy documents get ignored by every agent; short contracts get followed.

1. Session start: read .ai/STATE.md, then .ai/INDEX.md. Open other files only when relevant. Never bulk-load the whole directory into context.
2. During work: when you make a decision or hit a landmine, update the matching .ai/ file in the same branch as the code change. Decisions become a new ADR.
3. Session end: rewrite STATE.md: done, in flight, next, risks, open questions. Five minutes, never an essay.

Automate the start where your tooling allows it. Claude Code, for example, supports session hooks, so STATE.md can be injected into every session automatically:

#!/bin/bash
# session-start hook: surface the shared memory
STATE="$PROJECT_DIR/.ai/STATE.md"
if [ -f "$STATE" ]; then
  echo "-- Shared project memory: .ai/STATE.md --"
  cat "$STATE"
  echo "-- Full index: .ai/INDEX.md. Rewrite STATE.md before finishing. --"
fi

Tools without hooks rely on the instruction inside AGENTS.md itself, which they load on every session anyway.

Step 6: make review enforce it

Add one checkbox to your pull request template:

- [ ] .ai/ updated (STATE.md / ADR / known-issues) or N/A

Reviewers treat a stale STATE.md like a failing test. If you run an automated PR reviewer, add AGENTS.md and .ai/** to the paths it watches, and check what file it reads for project context. During my own migration, the automated reviewer flagged that it had been reading the old instruction file, which the new shim had just reduced to seven lines. One overlooked line would have quietly degraded every future review. The shared memory is a first-class artifact; wrong memory deserves the same scrutiny as wrong code.

The operating rules that keep it trustworthy

• Every claim is dated. Anything that cites code carries an implicit warning: point-in-time observation, re-verify before relying on it.
• Delete beats update beats append. Resolved issues are removed, not marked fixed and kept. STATE.md is rewritten, never grown.
• Memory changes ride the code PR. They get the same review as code, because a wrong memory entry is a bug that infects every future session of every developer.
• Size caps force pruning: STATE.md under ~100 lines, topic files under ~150, the whole directory under ~15 files. Hitting a cap is the system working, not failing.
• One topic per file. Merge conflicts stay rare and trivial, even with several people working in parallel.

What never goes in shared memory

• Secrets, keys, tokens, credentials. No exceptions, including "just this once" examples. Add a key-shaped-string check to CI if you can.
• Personal data of users or customers, in any form, including anonymized-looking examples.
• Anything derivable from code or git history. Implementation history belongs in commits and PR descriptions. The memory holds the why, never a duplicate of the what.
• Personal preferences and machine-specific paths. Layer 3, gitignored.
• Raw chat transcripts. Summaries only. Logs rot, and nobody prunes them.

Common failure modes and their countermeasures

When to graduate to a memory service

Write the upgrade trigger down in advance so the decision is never made in frustration: more than roughly five developers, or the day grep across fifteen markdown files stops finding things. At that point an MCP memory service with embeddings and semantic recall earns its infrastructure, and your committed files become its seed corpus rather than wasted work.

Until that day, the shared brain is a directory of markdown, reviewed like code, distributed by git. The same boring trick that fixed environments a decade ago: commit the contract, not the machinery.

Quick-start checklist

1. Create root AGENTS.md: project overview, build and test commands, conventions, session contract.
2. Bridge non-native tools with one-line import shims. One source of truth, thin pointers.
3. Scaffold .ai/: STATE.md, INDEX.md, architecture.md, conventions.md, known-issues.md, lessons.md, decisions/.
4. Seed it from existing knowledge. Never launch empty.
5. Add the three-bullet session contract to AGENTS.md; automate session start where your tool supports hooks.
6. Add the .ai/ updated or N/A checkbox to the PR template; point any automated reviewer at AGENTS.md and .ai/**.
7. Scan for secrets and personal data before the first commit, and on every memory change after.
8. Write down the scale-up trigger, then stop thinking about memory services until it fires.

Git taught us to version code.
AI may teach us to version engineering knowledge.

Useful references: the AGENTS.md specification and supported-tool list, the memory-bank methodology, and the Claude Code AGENTS.md discussion where the import bridge is documented.