Claude Code Cross-Project Memory Setup: 3 Layers (2026)

A new Claude Code session keeps asking for the same repository rules, while a rule from one project appears in another.

The winning setup is a three-layer model: use CLAUDE.md for stable facts, Claude Code Skills for reusable workflows, and external Agent Memory for changing preferences and task state. Do not merge every past conversation into one global prompt.

This guide is for:

• Developers maintaining several repositories who want to stop repeating architecture and tooling rules.
• Engineering leads who need to separate shared team standards from personal preferences.
• Teams running coding agents continuously and requiring persistence, isolation, backups, and recovery tests.

Last updated August 10, 2026. Configuration details were checked against the official Claude Code memory documentation, Skills documentation, and settings reference.

Start by separating the information layers

The most common configuration mistake is treating every useful instruction as “memory.” That creates a large prompt containing project facts, deployment procedures, personal habits, old decisions, and sensitive context. The model may then apply a correct rule in the wrong repository.

A safer design begins with three questions:

1. Will this remain true for most future sessions?
   Put it in CLAUDE.md or a scoped rule file.

2. Is this a repeatable procedure that should load only when needed?
   Put it in a Skill, normally inside a SKILL.md file.

3. Does it change over time and describe a person, task, or previous decision?
   Store it in an Agent Memory system with project and user boundaries.

Keep stable facts separate from operating procedures

Stable facts include:

• Repository layout.
• Build, test, and lint commands.
• Naming conventions.
• Architectural boundaries.
• Required review rules.
• Supported runtime versions.
• Non-negotiable security practices.

A deployment procedure, incident response flow, or pull request review sequence is different. It may be stable enough to reuse, but it does not need to occupy the context of every coding task. That is a better fit for a Skill.

Dynamic memory includes:

• A developer’s preferred explanation style.
• A previous decision and the reason behind it.
• The current migration status.
• A task that was paused before completion.
• A recurring debugging pattern discovered during work.

Do not place secrets, customer records, private access tokens, production URLs, or repository-specific incident details in a global memory file. A configuration file being reloaded does not mean Claude Code has a permanent human-like memory. It means that selected files are inserted into the current session context.

Important: Instructions shape model behavior, but they are not an enforcement boundary. Use permissions, hooks, sandboxing, or infrastructure controls when an action must be blocked rather than merely discouraged. The Claude Code security guidance describes this distinction.

Build the first project layer with CLAUDE.md

The first implementation step should be deliberately boring: create one project-level CLAUDE.md, keep it short, and test whether a fresh session reads it correctly.

For a fictional repository named Northstar-API, a suitable file might look like this:

# Northstar API

## Project facts
- The service runs from `services/api`.
- Database migrations are stored in `db/migrations`.
- API handlers must not access the database directly.
- New endpoints require request validation and integration tests.

## Commands
- Install: `pnpm install`
- Unit tests: `pnpm test`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`

## Required behavior
- Do not edit generated files directly.
- Before proposing a commit, run the relevant tests.
- Ask for confirmation before changing deployment configuration.

This file records facts and constraints that a new contributor would need. It does not contain a complete deployment manual, a long troubleshooting history, or a transcript of previous conversations.

The official documentation recommends concise instructions and gives a target of under 200 lines per CLAUDE.md file. That is not a hard parser limit. It is a maintenance and context-management target. Longer files consume more context and can reduce adherence. (docs.anthropic.com)

What belongs in CLAUDE.md and what belongs elsewhere?

Use the following rule:

• If Claude should know it at the start of nearly every session, use CLAUDE.md.
• If Claude needs it only for a particular file type or directory, use .claude/rules/.
• If Claude needs it for a repeatable task, use a Skill.
• If it describes changing history or personal preference, use Agent Memory.
• If it must be enforced technically, use settings, permissions, hooks, or an external control.

Claude Code loads project instructions from locations such as ./CLAUDE.md and ./.claude/CLAUDE.md. User-level instructions can live under ~/.claude/CLAUDE.md, while managed policies can be deployed by an organization. The official memory and instruction hierarchy should be checked before standardizing a team layout.

To verify a new project file:

1. Open the repository root.
2. Start a new Claude Code session.
3. Run /context.
4. Confirm that the expected memory files are listed.
5. Ask Claude to state the build command and one architectural rule.
6. Compare the answer with the file rather than assuming it loaded correctly.

A reload test matters because a successful file write does not prove that the intended working directory, scope, or import path is active.

Use Skills for repeatable workflows

Once project facts are stable, move repeated procedures into Claude Code Skills. A Skill should answer a workflow question such as:

• How should a pull request be reviewed?
• How should a release candidate be tested?
• How should a database migration be prepared?
• How should a deployment dry run be performed?

A simplified Skill directory might be:

Northstar-API/
└── .claude/
    └── skills/
        └── review-api/
            └── SKILL.md

The SKILL.md file should include a clear description, the conditions under which the workflow applies, and the sequence Claude should follow. For example:

---
name: review-api
description: Review API changes for validation, authorization, database access, tests, and migration safety.
---

# API review workflow

1. Read the changed files and related tests.
2. Check request validation and authorization boundaries.
3. Check for direct database access from handlers.
4. Run the targeted test suite.
5. Report findings by severity.
6. Do not modify files unless the user asks for fixes.

The description is not decorative. It helps Claude decide when a Skill is relevant. A vague description such as “helps with code” gives the router little useful information. A specific description identifies the task, scope, and expected output.

The current Claude Code Skills documentation explains how Skills extend the agent with instructions and supporting files. Skills are better than a giant CLAUDE.md when the workflow is conditional or multi-step.

How should project, personal, and plugin Skills be separated?

Use scope as an ownership decision:

• Project Skills: committed with the repository and shared by the team.
• Personal Skills: private workflows that apply across repositories, such as a preferred changelog format.
• Plugin Skills: packaged capabilities distributed with an extension or organization-wide toolset.

A project Skill may safely assume the repository’s own commands and directory structure. A personal Skill should avoid assumptions about a specific customer, repository, or deployment account. A plugin Skill should document its required tools and permissions clearly, because another project may activate it without knowing its internal dependencies.

Avoid creating two Skills with nearly identical descriptions. If both appear relevant, Claude may choose inconsistently. Use distinct names and descriptions such as review-api, release-mobile, and debug-queue, rather than three generic “development helper” Skills.

A useful acceptance test is to create three prompts:

• One that should activate the Skill.
• One that should not activate it.
• One that resembles the task but belongs to another repository.

The Skill passes only if the first prompt uses it, the second does not unnecessarily load it, and the third does not apply repository-specific instructions by accident.

Configure shared settings without sharing private context

Multiple projects can share a small set of personal preferences through user-level instructions or user-level Skills. Team standards should normally remain in version-controlled project files. Sensitive configuration should remain local or managed through a secure deployment layer.

For example, a developer may keep this preference at user scope:

# Personal coding preferences

- Prefer explicit error handling over silent fallback behavior.
- Explain risky changes before editing files.
- Use concise commit messages with an imperative verb.

That preference can apply across repositories without exposing a customer name or a project-specific service URL.

A team, by contrast, may commit:

# Team rules

- Never commit credentials.
- Add tests for authorization changes.
- Do not push directly to the protected branch.

The distinction is important because “shared configuration” is not the same as “shared memory.” Shared configuration is intentional and reviewable. Memory may contain incidental history that was useful in one repository but harmful in another.

When external files are imported into a project instruction file, review the trust boundary before accepting them. Imports can make a shared repository load files from a developer’s home directory, so the source and approval behavior should be understood before deployment.

Does Claude Code automatically remember old projects?

Not in the way most people mean by permanent cross-project memory.

Each session begins with a fresh context window. Claude Code can load persistent instructions from CLAUDE.md, and current versions also provide native auto memory. However, the official documentation describes auto memory as project-oriented and machine-local. It is stored under a project-specific directory and is not automatically shared across machines or cloud environments.

That means a developer should not assume:

• A decision made in Repository A will be recalled in Repository B.
• A local memory directory will follow the project to a new workstation.
• A resumed session is equivalent to a permanent knowledge base.
• Reloading CLAUDE.md gives Claude access to every previous conversation.
• A team member will see another person’s private notes.

Claude Code can continue or resume sessions through CLI options such as --continue and --resume, but session recovery is different from a durable, queryable Agent Memory layer. The CLI reference documents these session operations and their scope.

This distinction prevents a common design error: storing a dynamic task journal in CLAUDE.md and expecting it to behave like a database. The file will be loaded repeatedly, even when the old task is irrelevant.

Add external Agent Memory only when the use case requires it

External Agent Memory becomes justified when the team needs dynamic state beyond a single repository or machine. Typical examples include a developer preference profile, a cross-repository task tracker, a decision history, or a long-running coding agent that must recover after a restart.

The external layer should not be a bucket that receives every prompt. It needs an explicit data model.

At minimum, store:

• user_id: isolates personal preferences and permissions.
• project_id: prevents one repository’s context from being recalled in another.
• memory_type: distinguishes preference, decision, task state, and technical fact.
• source: records the file, issue, commit, or conversation that supports the memory.
• created_at and updated_at: make stale entries visible.
• retention_policy: defines when the entry expires or is reviewed.
• deletion_status: supports removal requests and cleanup.

A retrieval request should include a project identifier and a purpose. For example:

Retrieve only:
- user preferences for user-042
- decisions tagged northstar-api
- task state for migration-118

Exclude:
- customer data
- credentials
- unrelated repositories
- unverified assumptions

The memory component should return evidence with each result. “The team prefers PostgreSQL” is weaker than “Decision recorded in docs/architecture/adr-014.md, approved in commit abc123.” Evidence makes stale or incorrect recall easier to challenge.

Operational warning: If a memory record cannot identify its owner, project, source, and deletion path, it should not be treated as production memory.

For teams that need shared tools or data sources, MCP can provide access to external systems, but MCP is not automatically a memory store. The official MCP documentation describes the protocol as a way to connect applications and models to tools and data sources. Storage, identity, retention, and authorization still need to be designed separately.

Test isolation, hot loading, and restart recovery

A three-layer setup is incomplete until it passes regression tests. The following sequence can be run with fictional repositories such as Northstar-API, Harbor-Web, and Atlas-Worker.

1. Create a clean test account or user identity.
   Do not use production customer records or real secrets.

2. Add one distinct project fact to each repository.
   For example, use different test commands and fictional service names.

3. Start a new session in each repository.
   Run /context and confirm that only the intended project files are loaded.

4. Test Skill activation.
   Send one prompt that should trigger the Skill and one similar prompt that should not.

5. Test conflict handling.
   Give two repositories different rules for formatting, deployment, or test commands. Confirm that the rule from one repository is not applied to the other.

6. Write one dynamic memory record.
   Tag it with the test user and the correct project identifier.

7. Restart the coding environment.
   Confirm that the record is recoverable only when the correct identity and project scope are supplied.

8. Delete the record.
   Verify that retrieval no longer returns it and that backups follow the same deletion policy.

9. Upgrade the Claude Code installation or memory component in a staging environment.
   Re-run the fixed test prompts before changing the production setup.

10. Back up configuration before migration.
    Preserve CLAUDE.md, Skills, settings, schemas, and memory export procedures separately.

Claude Code Skills are designed to load when invoked or when Claude determines that they are relevant. This makes a hot-load test important: adding a Skill file is not enough; the agent must recognize the description and use the workflow at the right time.

Use this three-layer decision table

Place the following table beside the repository configuration documentation so maintainers can decide where new information belongs.

Information or requirement	Recommended layer	Loading behavior	Sharing scope	Main risk
Project architecture and commands	Project CLAUDE.md	Loaded at session start	Repository team	File becomes too long
Personal coding preferences	User-level CLAUDE.md or user rules	Loaded across projects	One developer	Personal habits affect unrelated work
File-type-specific rules	.claude/rules/	Loaded by scope or matching paths	Repository team	Conflicting rules
Deployment or review procedure	Project or personal Skill	Loaded when relevant	Team or individual	Poor descriptions cause wrong activation
Previous decision or task status	External Agent Memory	Retrieved by query	User and project boundaries	Stale or incorrect recall
Secrets and credentials	Secret manager or environment	Access-controlled at runtime	Authorized identity only	Accidental exposure
Mandatory command restrictions	Permissions, hooks, or managed settings	Enforced by tooling	Organization or project	Misconfiguration blocks work

The practical allocation is simple:

• Facts go into CLAUDE.md.
• Procedures go into Skills.
• Changing state goes into Agent Memory.
• Sensitive data goes into a protected secret system.
• Hard restrictions go into enforcement controls.

This model also answers how to avoid leaking code information across projects: do not use a global memory namespace, require a project identifier for retrieval, keep personal and team identities separate, attach evidence to records, and define deletion before storing the first entry.

For a continuously running coding agent, the environment itself becomes part of the design. A disposable laptop setup often loses local state, depends on one developer’s machine, and makes restart testing inconsistent. A persistent remote coding workspace can be easier to back up, isolate, and audit, especially when several repositories must share controlled tooling. Teams evaluating that operating model can review the Zutcloud Mac rental options and the Zutcloud Help Center before choosing a deployment pattern.

The local alternative still makes sense for long-term heavy workloads, physical device access, offline development, or strict control over hardware. Remote access is less attractive when the network path is unreliable, repository policy forbids hosted environments, or the team cannot define who owns the persistent workspace.

For temporary experiments, multi-repository testing, or a team that needs a repeatable Mac-based coding environment without purchasing and maintaining another machine, renting a Mac through Zutcloud can remove several operational disadvantages of the current setup: local state may disappear after a workstation change, shared configuration may drift between developers, and restart recovery may never be tested consistently. The better choice is not always rental, but when the goal is a short-lived or continuously managed Claude Code environment with controlled isolation, a persistent remote Mac is often easier to reproduce than a collection of personal laptops. Further questions about access and delivery can be handled through Zutcloud contact support.

Use the three-layer template before adding any new memory entry:

Project facts:
  CLAUDE.md

Reusable procedures:
  .claude/skills/<workflow>/SKILL.md

Dynamic state:
  External Agent Memory
  Keyed by user_id + project_id
  Includes source, timestamps, retention, and deletion status

If a new instruction does not clearly belong to one of those locations, stop and classify it before storing it. That small pause prevents the most expensive failure mode: a coding agent that remembers enough to sound confident, but not enough to know which project the information belongs to.

Further reading

• Self-Hosted vs. SaaS Agent Memory: Choosing a Cost-Effective Architecture
• AI Agent File System Design: Sandboxes, Layered Storage, and Isolation