agents-project-memory

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)

1. 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.
2. Move long or fragile guidance into .claude/rules/ (one topic per file).
3. Use @imports as navigation for detailed docs instead of copying them into memory.
4. Treat memory like code: PR review, ownership, and periodic cleanup (remove dead rules).
5. For UI changes, confirm the specific values (colors, prices, text) before starting implementation to avoid rework.
6. 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

1. Keep AGENTS.md short (target 50-120 lines).
2. Move long catalogs/checklists to skill docs and reference them by path.
3. Keep one canonical policy statement per topic; link instead of repeating.
4. Prefer "read-on-demand" instructions over embedding full inventories in every session.
5. 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.