How Claude Code Manages Memory Across Multiple Projects: Team Practices for CLAUDE.md, Memory, and Hooks

After a team starts using Claude Code seriously, memory becomes a practical problem. One repository uses pnpm, another uses Poetry; one project requires tests before edits, another asks for documentation first. Deployment commands, branch rules, coding style, and files that should not be touched are easy to mix up.

The fix is not to put every rule into one giant prompt. The better pattern is layered memory: use CLAUDE.md for stable repository rules, Memory for cross-project preferences, and Hooks for repeatable checks. Then Claude Code can enter each project with the right context instead of carrying habits from the wrong repository.

Why multi-project memory gets messy

Real engineering teams usually have multiple stacks, multiple repositories, and several types of work: frontend, backend, scripts, operations, and documentation. Some rules are team-wide; others belong to exactly one repository. If those rules are only explained in chat, every new session repeats the same setup.

The goal is not to make Claude Code remember more. The goal is to make it remember the right things in the right place.

A three-layer memory model

In short: CLAUDE.md answers “how this project works”, Memory answers “how this person or team usually collaborates”, and Hooks answer “which checks should always run”.

CLAUDE.md: a project manual for the agent

Place CLAUDE.md in the repository root and keep it concrete, stable, and actionable. It is not a replacement for README; it is a working guide for the coding agent.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# Project Guide

## Tech Stack

- Runtime: Node.js 22
- Package manager: pnpm
- Framework: Next.js
- Tests: Vitest and Playwright

## Common Commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Run unit tests: `pnpm test`
- Run lint: `pnpm lint`
- Run e2e tests: `pnpm test:e2e`

## Working Rules

- Before editing shared UI components, inspect existing usage first.
- Prefer existing helpers in `src/lib` before adding new utilities.
- Do not change database migrations unless the task explicitly asks for it.
- Keep unrelated refactors out of feature fixes.

## Verification

- For UI changes, run `pnpm lint` and the nearest relevant test.
- For API changes, add or update request-level tests.
- For database changes, include migration notes in the final summary.

The point is to reduce guessing. If a project has fixed commands, unusual directories, or historical traps, write them down.

Do not turn CLAUDE.md into a junk drawer

A common failure mode is making CLAUDE.md thousands of lines long. Claude Code can read it, but the important rules become buried and sometimes contradictory.

Keep these constraints:

• Every rule should affect real behavior.
• Delete outdated commands and architecture notes.
• Do not store temporary tasks in CLAUDE.md.
• Avoid emotional reminders or repeated wording.
• If a rule only applies to one directory, scope it clearly.

Memory: cross-project preferences

Memory is better for durable preferences that apply across repositories:

• The team prefers Chinese commit messages.
• Production configuration changes require a risk explanation first.
• Never reset uncommitted user changes automatically.
• Frontend pages must be checked for mobile overflow.
• Code reviews should list findings before summaries.

These do not belong to one repository. They shape collaboration everywhere. Repository paths, deployment scripts, and table names should stay in project files, not long-term memory.

Hooks: automate the checks

CLAUDE.md and Memory are text. Hooks are for actions that should happen repeatedly:

• Run formatting after edits.
• Check for secrets before commits.
• Remind the agent to run tests when key directories change.
• Block .env, tokens, or production config from accidental commits.
• Summarize changed files and verification results at the end.

Hooks should automate clear checks, not replace human judgment. Decisions such as whether a product change is correct still belong to the team.

Suggested team layout

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

workspace/
├── app-web/
│   ├── CLAUDE.md
│   └── package.json
├── app-api/
│   ├── CLAUDE.md
│   └── pyproject.toml
├── infra/
│   ├── CLAUDE.md
│   └── deploy.ps1
└── docs/
    └── ai-working-rules.md

Each repository keeps its own CLAUDE.md. Shared rules can live in team documentation, while stable cross-project preferences can be promoted into Memory.

Examples for different projects

Frontend repository:

1
2
3
4
5
6

## Frontend Rules

- Use existing components in `src/components` before creating new ones.
- Keep layout stable on mobile and desktop.
- Use `pnpm lint` for quick validation.
- For visual changes, mention what viewport was checked.

Backend repository:

1
2
3
4
5
6

## Backend Rules

- API handlers live in `src/routes`.
- Database migrations must be reviewed manually.
- Do not change authentication middleware without explicit approval.
- Run `pytest tests/api` after endpoint changes.

Operations repository:

1
2
3
4
5
6

## Operations Rules

- Treat deployment scripts as production-sensitive.
- Do not print secrets or tokens in logs.
- Prefer dry-run mode before changing remote state.
- Summarize changed commands before final handoff.

The files do not need to use the same template. They should make the most important local constraints obvious.

When to update memory

Update memory when Claude Code repeats the same mistake, when team members keep reminding it of the same rule, when verification changes, when directory structure changes, or when an old rule no longer applies.

Do not save every conversation. Save rules that will still matter next month, for the next teammate, or in the next repository.

Code review workflow

A useful review flow is:

1. Read the current repository’s CLAUDE.md.
2. Inspect the directories touched by the change.
3. Run the smallest relevant verification.
4. Prioritize bugs, regressions, and missing tests.
5. End with a short change summary.

This keeps Claude Code grounded in the real project instead of starting from a generic review checklist.

Common mistakes

The first mistake is putting everything in Memory, which causes cross-project pollution. The second is turning CLAUDE.md into a complete development handbook. The third is writing rules but not automating obvious checks. The fourth is never cleaning outdated instructions.

A practical rollout

1. Add a short CLAUDE.md to each active repository.
2. Include stack, commands, protected files, and verification.
3. Move cross-project preferences into Memory.
4. Automate repeat checks with Hooks.
5. Review outdated rules every two weeks.

Start with the mistakes Claude Code makes most often. Improve the system after real use.

Summary

Claude Code works better across projects when memory is layered. Put repository facts in CLAUDE.md, long-term preferences in Memory, and repeat checks in Hooks. A good memory system is not the longest one; it is the one that helps Claude Code do the right thing in the right repository.