Project Memory for Claude Code + Codex (Jan 2026)

Configure project memory so Claude Code and Codex get stable, scoped instructions across sessions while keeping token cost low. Use a single source of truth: keep AGENTS.md as primary and symlink CLAUDE.md to it.

Quick Reference

Memory Type Typical Location Purpose

Managed policy OS-dependent (see official docs) Organization-wide standards (security, compliance)

Project memory ./AGENTS.md (primary) + ./CLAUDE.md (symlink → AGENTS.md) Shared project context and conventions

Project rules ./.claude/rules/*.md

Modular, topic-focused rules (testing, security, style)

User memory ~/.claude/CLAUDE.md

Personal preferences across projects

Project memory (local) ./CLAUDE.local.md (git-ignored) Local-only, project-specific preferences

How Loading Works (High Level)

Claude Code (CLAUDE.md symlink):

• Recursive loading: from the current working directory up to (but not including) filesystem root (/ ).

• On-demand loading: nested CLAUDE.md files under the cwd are loaded only when Claude reads files in those subtrees.

• Imports: @path/to/file pulls in additional context (max depth: 5; ~ supported).

Codex (AGENTS.md primary):

• Reads AGENTS.md in the repo root or working directory.

• Keep it concise; mirror the same content as CLAUDE.md when supporting both tools.

Workflow (Best Practice)

• Start with a minimal primary memory file (AGENTS.md, 50–120 lines): what the project is, how it's shaped, and the "must not break" rules.

• Move long or fragile guidance into .claude/rules/ (one topic per file).

• Use @imports as navigation for detailed docs instead of copying them into memory.

• Treat memory like code: PR review, ownership, and periodic cleanup (remove dead rules).

• For UI changes, confirm the specific values (colors, prices, text) before starting implementation to avoid rework.

• For feature delivery, prefer one worktree per feature, run project quality gates, then open one focused PR.

Execution Workflow (Worktree + Gate + PR)

When repositories include a workflow script (for example scripts/git/feature-workflow.sh ), prefer this sequence for AI coding sessions:

1) Create isolated branch/worktree

./scripts/git/feature-workflow.sh start <feature-slug> cd .worktrees/<feature-slug>

2) Implement + commit

git add -A git commit -m "feat: <summary>"

3) Run project quality gate (example)

../../scripts/git/feature-workflow.sh gate

4) Open PR (gate may run again)

../../scripts/git/feature-workflow.sh pr --title "feat: <summary>"

If no helper script exists, use native git worktrees and apply the same policy:

• one feature per worktree

• one focused PR per feature

• run repo-specific gate(s) before PR creation

Rules With Optional Path Scope

Create .claude/rules/testing.md , .claude/rules/security.md , etc. If a rule only applies to a slice of the repo, scope it:

paths:

• "src/api/**/*.ts"

Commands (Claude Code)

• /memory to view and directly edit memories.

• /init to bootstrap project memory (see official docs for current behavior).

Commands (Codex)

• Edit AGENTS.md directly; no special memory command is required.

Cross-Platform Strategy (AGENTS.md + CLAUDE.md)

If you support multiple coding assistants, keep one canonical file and mirror it:

• macOS/Linux: CLAUDE.md should be a symlink to AGENTS.md .

• Windows: prefer copying (or a small sync script) over symlinks unless Developer Mode is enabled.

Avoid tool-specific claims in the memory file; keep it portable and strictly project-focused.

Token-Budget Profile for Project Memory

When sessions repeatedly include very large memory payloads, apply this compact profile.

Compact Profile Rules

• Keep AGENTS.md short (target 50-120 lines).

• Move long catalogs/checklists to skill docs and reference them by path.

• Keep one canonical policy statement per topic; link instead of repeating.

• Prefer "read-on-demand" instructions over embedding full inventories in every session.

• Maintain a short runtime memory and a fuller reference doc when needed.

Suggested Split

• AGENTS.md (runtime): project goal, hard constraints, workflow rules, critical safety constraints.

• docs/* or skill references: long lists, examples, optional playbooks, large inventories.

Quality Gate

If startup memory exceeds practical context budgets, trim before adding new rules.

Validation (Fast Checks)

• Run the bundled linter: bash frameworks/shared-skills/skills/agents-project-memory/scripts/lint_claude_memory.sh .

• Manually scan for unresolved @imports and secrets before merging memory changes.

Resources

Resource Purpose

references/memory-patterns.md Patterns and anti-patterns

references/memory-examples.md Full examples by stack

references/large-codebase-strategy.md 100K–1M LOC strategy

data/sources.json Official links

Related Skills

Skill Purpose

agents-skills Skill creation patterns

agents-subagents Agent/subagent setup

docs-codebase Repo documentation patterns

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.

• Prefer primary sources; report source links and dates for volatile information.

• If web access is unavailable, state the limitation and mark guidance as unverified.