Implementing a Three‑Layer Memory Model for Claude Code

Why separate CLAUDE.md and claude-mem

Claude Code reads CLAUDE.md first and uses its content to shape behavior. Over time users tend to append bug fixes, investigation notes, failed designs, and ad‑hoc decisions, causing the file to grow indefinitely. Longer files increase context noise, mixing stable rules with outdated details, which makes it harder for Claude Code to focus on the most important information. Therefore CLAUDE.md should remain concise, stable, and long‑term valid—more like a project constitution.

What belongs in CLAUDE.md

Only information needed in almost every Claude Code session should be stored here. Typical categories:

Project facts – long‑term stable (e.g., tech stack, directory structure).

Work commands – high‑frequency use (e.g., test, build, lint commands).

Strong constraints – always enforced (e.g., do not modify generated files, do not commit secrets).

General conventions – influence implementation style (e.g., code style, testing requirements, dependency management).

Example layout:

# Project Guide
## Tech Stack
- Node.js
- TypeScript
- PostgreSQL
- pnpm

## Common Commands
- pnpm install
- pnpm lint
- pnpm test

## Code Style
- Use TypeScript strict mode.
- Prefer explicit return types for exported functions.
- Do not introduce new dependencies without approval.
- Keep business logic out of controllers.

## Do Not
- Do not modify files under generated/.
- Do not commit secrets or credentials.
- Do not call real payment gateway in tests.
- Do not use npm or yarn in this repo.

## Important Paths
- src/modules/order: order domain logic
- src/modules/payment: payment and callback handling
- tests/e2e: end‑to‑end tests
- scripts/db: database migration scripts

What belongs in claude-mem

claude-mem

stores dynamic experience—information that is not needed for every task but is crucial for specific scenarios. Typical entries:

Historical bugs (e.g., inventory double‑release due to missing idempotency).

Failed attempts (e.g., timestamp‑based deduplication that broke because of gateway retry delays).

Test strategies (e.g., regression suites for coupons, discounts, refunds, activity stacking).

Module design history (e.g., permission module avoids remote calls to keep the permission check path local).

Investigation conclusions and temporary state needed to continue a long task.

These entries are retrieved only when the relevant task arises, preventing unnecessary context pollution.

Three‑layer context model

CLAUDE.md

– Project rule layer. Answers “What long‑term rules does the project follow?”

claude‑mem – Project experience layer. Answers “What past events or decisions affect the current judgment?”

Current session – Task‑specific layer. Answers “What am I doing right now? Which files, logs, or test results are relevant?”

Each layer has distinct responsibilities and should not be mixed.

Practical template for CLAUDE.md

# Project Guide
## Tech Stack
- Runtime: ...
- Language: ...
- Framework: ...
- Database: ...
- Package manager: ...

## Common Commands
- Install: ...
- Lint: ...
- Unit test: ...
- E2E test: ...
- Build: ...

## Code Style
- ...

## Testing Rules
- ...

## Do Not
- ...

## Important Paths
- ...

Do not overload this file with historical bugs or extensive retrospectives; those belong in claude-mem. When a current session yields a stable conclusion, promote that knowledge to claude-mem instead of CLAUDE.md.

Example of current session data

Task: fix intermittent inventory inconsistency after order cancellation.

Read files: order.service.ts, inventory.service.ts, cancel-order.spec.ts.

Finding: duplicate cancellation requests enter inventory release logic without idempotent guard.

Next step: add concurrent‑cancellation test and verify inventory release occurs only once.

If the investigation leads to a stable rule (e.g., always apply idempotent guard on cancellation), move that rule to CLAUDE.md. If it remains a one‑off insight, store it in claude-mem.

Key take‑away

CLAUDE.md

stores stable, long‑term rules; claude-mem records dynamic experience; the current session holds transient task data. Keeping the three layers separate prevents context pollution and lets Claude Code follow project rules while recalling relevant experience when needed.