Practical guides to AI coding memory
CLAUDE.md vs AI memory: what belongs where?
Put rules in an instruction file when they should guide a project or your Claude sessions. Let Claude Code's auto memory keep useful repository learnings. Use Cairn when a private, sourced note should be available from supported connected tools. A user-level CLAUDE.md can carry your preferences across projects, so cross-project use alone does not require an external memory store.
Choose by scope and job
A repository instruction file is shared with the team. A personal file such as ~/.claude/CLAUDE.md applies to your Claude Code sessions across projects; organization-managed files can set broader guidance. Claude Code also reads AGENTS.md in supported repository setups, with loading details in the official documentation.
These files are written instructions. They work as context for Claude, not as a technical lock that makes an action impossible.
Claude Code already has auto memory
Auto memory adds Claude-written learnings from corrections and repeated patterns, scoped to a repository and shared across its worktrees. It can be enough for a note that only helps Claude Code in that repository.
Claude's official docs say memories and instruction files are context, not enforced configuration. Keep changeable project facts in maintained repository files, where you can review them with the code.
When a separate Cairn Memory helps
Cairn keeps private Memories with source receipts. After setup, its Claude Code plugin can recall and capture automatically; supported MCP clients can use explicit tools when connected to the intended Cairn account. Available behavior depends on the client and connection. The public local core and hosted interface are separate, so check product documentation for the tools each exposes.
Personal scope follows your Cairn account across projects. Project scope requires the same opaque project_id; Cairn does not infer that two tools share a project from a folder name. A receipt helps you check where a note came from, not whether it is still true.
A practical selection rule
1. The rule must travel with a repository
Keep it in that repository's instruction file, such as
CLAUDE.mdorAGENTS.md, and review it with the code.2. It is only your Claude Code preference
A user-level instruction such as
~/.claude/CLAUDE.mdcan carry it across your Claude Code projects.3. It is a repository-specific Claude learning
Auto memory may be enough. Check current project files before relying on remembered technical facts.
4. Another connected tool also needs the private note
Cairn may fit when each supported client uses the intended account and scope. Read the returned note and receipt before using it.
Synthetic example
Synthetic example: one developer prefers a focused test run before a broad refactor, while two fictional repositories use different runtime versions. The preference can live in the developer's user-level CLAUDE.md for Claude Code. Each runtime version belongs in its repository's package and CI files. If the preference should also be available to another connected assistant, a private Cairn Memory can carry it with a receipt; it should not replace either repository's instructions or version files.
Limits to keep in mind
- Auto memory and instruction files are Claude Code context. A preference in a user-level file can span projects, while Claude's auto memory is scoped per repository.
- Cairn requires a supported setup and the intended account. Similar repository names do not establish a shared project scope across clients.
- A remembered note or source receipt is not current project truth. Check the repository and restate any current instruction that differs.