Project Memory for Claude Code + Codex

Configure project memory so Claude Code and Codex get stable, scoped instructions across sessions without bloating every prompt. For shared teams, keep the portable project rules in AGENTS.md, mirror that into CLAUDE.md when needed, and keep tool-specific behavior in the tool's native layer.

Scope. This skill owns the instruction files themselves (AGENTS.md, CLAUDE.md, .claude/rules/, AGENTS.override.md, auto-memory): what goes in them, how each runtime loads them, and the instruction budget. Long-term memory systems for users, agents, or knowledge (extraction, consolidation, temporal facts, vector/graph stores, memory vendors) belong to ai-context-layer. Context architecture beyond those files (hot/warm/cold layers, compiled knowledge bases, context graphs, maturity models) belongs to dev-context-engineering, which links here for the baseline.

Treat repo memory as a living exception file. If an agent can reliably infer something by reading the code, config, or README, keep it out of the always-loaded layer. Put only the durable, non-inferable guidance here.

Quick Reference

Layer	Typical Location	Purpose
Shared project memory	./AGENTS.md	Portable repo instructions for Codex and other AGENTS.md-aware tools
Claude project memory	./CLAUDE.md	Claude Code project instructions. Whether Claude Code also reads AGENTS.md natively depends on version, provider, and whether a CLAUDE.md-family file exists — look it up before dropping the @AGENTS.md import or symlink (loading-and-layers.md)
Claude scoped rules	./.claude/rules/*.md	Modular Claude-only rules, optionally path-scoped
Personal instructions (Codex + Claude Code)	~/.codex/AGENTS.md; ~/.claude/CLAUDE.md imports it with @~/.codex/AGENTS.md	One personal file for both runtimes; repo files hold project facts only (loading-and-layers.md)
Codex directory override	./AGENTS.override.md	Higher-precedence guidance for one directory; it may be local or checked in
Codex runtime permissions	~/.codex/config.toml, trusted .codex/config.toml, permission profiles, .rules	Configure sandbox boundaries, approval policy/reviewer, and executable command policy
Codex auto-memory	~/.codex/memories/ (feature flag in config.toml)	Machine-local accumulated recall; may be off for teammates; keep must-always rules in AGENTS.md, not here
Claude auto memory	~/.claude/projects/<project>/memory/ — MEMORY.md index + topic files	Machine-local, accumulated notes; a capped prefix of MEMORY.md loads each session (look up the cap); topic files load on demand
Instruction budget	One shared pool across all loaded tiers; ≤200 lines per always-loaded file	HumanLayer's informal estimate (~150–200 instructions) is directional, not measured; the runtime's own prompt uses part of it. Owner: claude-md-instruction-budget.md
Layered memory model	references/memory-patterns.md	Keep the hot memory small; push history and reusable procedures into the right layers

When To Use Which Layer

Need	Best Place
Stable repo rules shared by every tool	AGENTS.md
Claude Code-specific modular rules	.claude/rules/*.md
Personal behavioral instructions across repos, both runtimes	~/.codex/AGENTS.md, imported by ~/.claude/CLAUDE.md; never copied into repos
How the agent writes replies to you (answer first, one decision per question)	the personal file; template in reply-clarity-ste.md
Codex runtime defaults and approval behavior	~/.codex/config.toml or trusted .codex/config.toml
Local-only Claude settings	.claude/settings.local.json
Machine-local scratch guidance that evolves over time	Claude auto memory
Task-specific playbooks or workflows	skills, not project memory
Searchable corpus memory across many docs/repos	vector brain or docs retrieval layer, not hot project memory

Full per-runtime loading semantics and the config.toml vs AGENTS.md split: references/loading-and-layers.md.

Workflow

Use the AGENTS.md inclusion checklist before adding or retaining a line in project memory.

1. Start with a short root AGENTS.md or CLAUDE.md: project purpose, hard constraints, key commands, and "must not break" rules.
2. Inline only the highest-value shared rules so Codex does not depend on Claude-specific features.
3. Prioritize exact commands, weird setup steps, deployment quirks, hard boundaries, and verification rules over philosophy or summary prose.
4. Move Claude-only detail into .claude/rules/ when it would otherwise bloat the shared file.
5. For monorepos, add nested AGENTS.md files in packages or services that truly need local context.
6. For repos with many skills, make AGENTS.md point to a compact router/discovery map first, then to the full catalog (for example a generated <catalog>/discovery.md, then <catalog>/graph.json only after the router is chosen).
7. In AGENTS.md, name the primary routers explicitly when they are the intended entry points. Keep one-line scopes in hot memory; keep skill lists, scenario detail, and per-router Mermaid in generated graph artifacts.
8. Treat memory like code: review it, delete stale guidance, keep hot memory small and stable, and keep examples aligned with actual workflows.
9. Define conflict resolution before adding another layer. Loaded files concatenate, so no file mechanically overrides another; the precedence below is a policy you write down, not runtime behavior: current task instructions beat standing memory; narrower repo rules beat broader personal guidance within their documented scope; runtime permission policy remains authoritative for capability. When two durable files disagree without a declared precedence, surface the conflict instead of silently choosing the newest text.

Standing rules

• Retrospective updates: when Codex or Claude Code repeats a mistake, or when the model takes a line more literally than intended, ask it to analyze the failure and propose an AGENTS.md update. Add rules reactively (after repeated mistakes), not preemptively. Format: rule + why + example of the mistake.
• Worktree lifecycle rules: if a repo uses agent worktrees, make the closeout explicit in AGENTS.md: merge the branch into dev, run the repo gate, remove the worktree, verify git worktree list --porcelain, and delete stale session metadata. Do not let worktrees become long-lived storage for abandoned branches or dirty experiments.
• Progression: prompts → AGENTS.md → skills → automations. If a workflow in AGENTS.md becomes repeatable, extract it into a skill. If a skill runs on a cadence, wrap it in an automation. Skills define the method; automations define the schedule.
• Stabilize the session prefix when the runtime benefits from it: pick the session model and toolset at start and document the default in AGENTS.md (see references/claude-md-fragments.md §3). Model, tool-schema, or MCP changes can reduce prompt-cache reuse, but invalidation and billing are provider- and runtime-specific. Confirm with usage telemetry before calling a change the dominant token cost.
• Paste-ready blocks: for the high-leverage sections (Task Delegation, Preferred Tools, Session Model), use the fragments in references/claude-md-fragments.md and adapt to the repo. Each block carries its rationale so the next reader knows why it's in hot memory.
• Memory health checks: for file-based memory folders, schedule review of contradictions, stale facts, unsupported claims, and missing source links. Keep a dated archive outside the agent-write path before allowing agents to update memory files automatically.

Docs Boundary

Project memory is an operational router, not a documentation dumping ground.

• Put exact recurring commands, verification gates, workflow authorization rules (for example, "ask before production deploy"), and "never do" constraints in AGENTS.md. Put runtime approval/reviewer policy in Codex configuration.
• Link to canonical docs for architecture, onboarding, API behavior, product decisions, and long procedures.
• Put operational runbooks in docs/operations/ or docs/runbooks/ when they need owners, steps, and evidence.
• Put generated LLM context in docs/context/ or context/ with a rebuild command; do not paste generated catalogs into hot memory.
• Do not create a new Markdown file for every session, audit, or answer. Update a canonical doc, file a lifecycle-managed report, or keep the content in chat.
• If a memory update would make AGENTS.md a catalog, report index, or plan archive, move that detail to docs and leave only the pointer and rule.

For larger knowledge bases, keep a three-zone file structure instead of dumping everything into hot memory:

• raw/: imported source material and unprocessed notes
• compiled/ or wiki/: reviewed, source-linked canonical pages
• outputs/: generated answers and reports waiting for review

Only promote generated outputs into compiled/ after source review. If the corpus needs semantic search or cross-repo retrieval, route to ai-vector-brain.

Router Catalog Pattern

For repos with many skills or agent workflows, use AGENTS.md as the router pointer, not the skill catalog. Keep the root file to a short generated index and a small set of entry points:

## Start Here (load on demand)

- `<catalog>/discovery.md` — compact router map when the full skills list exceeds the runtime's discovery budget
- `<catalog>/graph.json` — full generated skill catalog after choosing a router

## Primary Routers

- `$router-main` — choose the correct domain router
- `$router-<domain-a>` — one-line scope
- `$router-<domain-b>` — one-line scope

Do not paste the full skill list into AGENTS.md. The generated discovery file is the hot-context map; router SKILL.md files, graph.json, and per-router Mermaid files are the detail layer.

Memory Discipline

Keep the hot memory small and intentional. The four load-bearing rules:

• Intent-first: put strategic context in memory; per-task intent stays in each prompt turn.
• Exception-file test: only add lines that are hard to infer, matter most sessions, and prevent repeated mistakes.
• Instruction budget: adherence drops as always-loaded instructions pile up — prune ruthlessly. The figure and its source live in claude-md-instruction-budget.md.
• Feedback loops: explicit verification steps let the agent catch its own mistakes, so fewer correction rounds reach you.

Full detail (intent-first model, promoting auto-memory notes into instruction files, working-if metric, verification templates): references/memory-discipline.md.

Structure Patterns

For the three durable patterns — Hooks vs Project Memory (when to enforce instead of suggest), Three-Tier Boundaries (Always / Ask / Never), and Progressive Disclosure (pointers over inlined docs) — see references/structure-patterns.md.

Platform and Scale

For path-scoped rules, cross-platform symlink/import strategy, large-repo guidance, and the memory progression ladder (flat files → vector → graph-vector hybrid), see references/platform-and-scale.md.

AGENTS.md Essential Coverage Checklist

• Repository layout and key directories
• Build, test, lint commands (exact commands, not descriptions)
• Engineering conventions and PR standards
• Constraints and prohibitions ("never do X")
• Verification methods ("how to confirm the change is correct")
• Worktree lifecycle rules when .worktrees/ is part of the repo flow: merge to the integration branch, run gates, remove worktrees, verify no stale worktrees remain
• Key file patterns and naming conventions
• For large skill catalogs, compact router/discovery pointer before full catalog pointer, with primary routers named explicitly

Keep it practical. A short, accurate AGENTS.md is more useful than a long file full of vague rules. Start with the basics, then add new rules only after you notice repeated mistakes.

Auto-Memory Quick Commands

# Check the version (look up the auto-memory minimum in the Claude Code memory docs)
claude --version

# Which instruction files actually loaded this session (Memory files section)
/context
# Browse or edit CLAUDE.md, rules, and auto-memory files; toggle auto memory
/memory

# Disable auto-memory: a settings key (project) or an environment variable (global);
# look up the current names in the Claude Code memory docs before scripting them.

# Inspect the auto-memory directory directly. The project segment is the repo root's
# absolute path with "/" replaced by "-", not its basename. Confirm with /memory.
ls ~/.claude/projects/"$(git rev-parse --show-toplevel | tr '/' '-')"/memory/

Memory Health Pre-Commit Checklist

• Run bash skills/universal/agents-memory/scripts/lint_claude_memory.sh . — 0 errors (a repo with no memory files exits non-zero; that is a finding, not a pass)
• Run bash skills/universal/agents-memory/scripts/audit_repo.sh . — no HIGH findings
• Every always-loaded file under 200 lines (wc -l CLAUDE.md AGENTS.md .claude/rules/*.md); the lint warns past 200
• No unresolved {{placeholders}} in CLAUDE.md (rg "{{[^}]+}}" CLAUDE.md)
• CLAUDE.md and AGENTS.md not both hand-maintained (use symlink or @AGENTS.md import); no stray CLAUDE.local.md silently suppressing native AGENTS.md reading
• Auto-memory MEMORY.md well inside the runtime's load cap if you edit it manually
• Hard rules across all loaded tiers counted as one pool (see claude-md-instruction-budget.md)
• No personality instructions ("be a senior engineer", "think step by step") consuming instruction budget
• Every hard rule in CLAUDE.md answers: "what mistake does this prevent?"
• Path-scoped rules in .claude/rules/ carry paths: frontmatter for file-type filtering
• No agent-write memory files are in production build artifacts (check with unzip -l app.ipa | grep -iE 'claude|agents')

Validation

Layered validators ship with this skill — pick by scope:

Scope	Script	Checks
Single repo (size/symlink/secrets/imports)	scripts/lint_claude_memory.sh <repo>	Original linter — keep as the cheap pre-commit gate
Validator regression	scripts/test_memory_scripts.sh	Fail-closed contract for the four scripts: missing, empty, or blank input exits non-zero
Single repo (paths + hallucination-bait + lint integration)	scripts/audit_repo.sh <repo>	Stale-path resolution with prefix support, script executability, wrong-layer detection, scaffold-tense, "Agent Execution Style" platitudes; supports --json
Multi-repo portfolio	scripts/audit_portfolio.sh <repo1> <repo2> ... or --from-file <list>	Per-repo report + aggregate HIGH/MED/LOW summary; exits nonzero on any HIGH
Cross-repo alignment review	scripts/compare_blocks.sh <repo1> <repo2> ...	Finds H2 sections shared across repos; classifies IDENTICAL / ALIGNMENT-CANDIDATE / REVIEW / DIVERGENT by line overlap

Author-facing directives (in AGENTS.md head):

• <!-- audit-path-prefix: app/src/, app/lib/ --> — declare prefix conventions for path resolution.
• <!-- audit-ignore: ./gradlew, res/values/strings.xml --> — whitelist intentional non-existent paths (DON'T-do-this examples, future tooling). Glob patterns supported.
• <!-- pre-code --> or a "Pre-Code Caveat" section — auto-suppresses the scaffold-tense MED warning.

Manual checks still required:

• Wrong-identifier (Xcode schemes, function names, build flags) and cross-doc consistency (AGENTS.md vs README vs build plans) are not automated. Run the parallel-subagent recipe in references/cross-doc-audit.md.
• Re-verify platform behavior against official Claude Code and Codex docs before publishing memory advice externally.

Full operator playbook: references/portfolio-audit-runbook.md.

Known Traps and Anti-Patterns

Summary of the highest-impact failure modes:

• storing inferable repo facts in hot memory
• using memory for hard requirements that belong in hooks or CI
• duplicating AGENTS.md and CLAUDE.md without a symlink (drift)
• append-only task logs instead of a concise operating contract
• turning AGENTS.md into a docs folder, repo catalog, or report archive
• creating new root-level Markdown notes when an existing canonical doc or lifecycle-managed report should be updated
• using generated answers as memory truth without a review/promote step
• giving agents write access to the only copy of a memory vault without a dated backup outside the writable path
• treating nested AGENTS.md/CLAUDE.md from vendored deps, submodules, or unreviewed PRs as trusted instructions instead of untrusted input
• running two long-lived sessions against the same working directory while either accumulates memory — file-based memory has no merge/lock semantics, so the later writer silently clobbers the earlier one's additions
• generic philosophy ("write clean code") consuming instruction budget
• missing verification steps (a large, common efficiency gap)
• leaving stale worktrees after merge instead of treating cleanup as part of delivery

Full list including the model-era anti-patterns (progress scaffolding, long "Don't" lists, implicit fan-out): references/traps-and-antipatterns.md.

• Model-specific behavior drifts fast. When mentioning Claude Opus or Codex defaults, cite the official release/migration post and its date. Check the current model line against the vendor's release notes before relying on it; treat any default tied to a superseded generation as stale.

Navigation

Setup and Getting Started

Resource	Purpose
references/zero-to-working-recipe.md	Copy-paste 5-step recipe: empty repo → working AGENTS.md / CLAUDE.md in under 10 minutes
references/typical-scenarios.md	End-to-end walkthroughs (situation → layer → write → verify): instructions ignored, team handoff, prompt→memory migration, bloat recovery, Codex-only setup, portfolio-drift remediation, headless/CI runs
references/loading-and-layers.md	Per-runtime loading semantics (layers concatenate); native AGENTS.md reading and cross-runtime instruction files as lookup steps; config.toml vs AGENTS.md split
references/claude-md-fragments.md	Paste-ready CLAUDE.md / AGENTS.md blocks (Task Delegation, Preferred Tools, Session Model) with cache-protection rationale
references/memory-examples.md	Full AGENTS.md / CLAUDE.md examples by stack
references/nested-feature-memory-examples.md	Bullet-style template for nested per-feature/per-package CLAUDE.md (synthetic worked example) — rule + identifier + inline gotcha pattern, plus build-bundle hygiene

Memory Design and Discipline

Resource	Purpose
references/memory-discipline.md	Intent-first memory, exception test, instruction budget, working-if metric, feedback loops
references/claude-md-instruction-budget.md	Single owner of the instruction budget: hedged ceiling and its source, tier hierarchy, 5-section template, hard caps, delete-line test, auto-memory path
references/structure-patterns.md	Hooks vs memory, three-tier boundaries, progressive disclosure
references/memory-patterns.md	Patterns including progressive disclosure, three-tier boundaries, and feedback loops
references/traps-and-antipatterns.md	Durable trap list and model-era anti-patterns
references/coding-behavior.md	Canonical coding-behavior rules with rationale (a reference, too long to load every turn)
references/coding-behavior-active.md	Condensed active contract (≤150 lines) — the file a repo's .claude/rules/coding-behavior.md should point at
references/coding-behavior-completeness.md	Greenfield counterpart: coding-behavior rules for completeness mode (do not load with defensive mode)
references/reply-clarity-ste.md	ASD-STE100 adapted for agent replies: paste-ready personal-file section, where STE hurts, method to derive rules from your own transcripts
references/instruction-inclusion-checklist.md	Short keep/move/remove review for deciding what belongs in AGENTS.md, with scoped examples and path-freshness checks

Scale and Advanced Architecture

Resource	Purpose
references/platform-and-scale.md	Path-scoped rules, cross-platform bridging, large-repo and memory-progression guidance
references/large-codebase-strategy.md	Monorepo and large-codebase (100K-1M LOC) configuration patterns
references/memory-architecture-ceilings.md	When flat AGENTS.md stops scaling — graph-vector hybrid stores, compiled-truth + timeline schema, tiered enrichment
references/claude-managed-agents-memory.md	Filesystem-backed memory stores for Claude Managed Agents: mount path, multi-agent sync, version history, read_only vs read_write, export API

Migration and Real-World Examples

Resource	Purpose
references/memory-migration-between-model-generations.md	Model-upgrade memory migration checklist (any model generation): regression-test first, retire compensations for old quirks, tighten literal wording, look up the vendor's migration guide
references/real-world-advanced.md	Annotated production AGENTS.md example (multi-agent, quality gates, battle-tested patterns)

Validation and Auditing

Resource	Purpose
references/cross-doc-audit.md	Hallucination-bait taxonomy + parallel-subagent audit recipe; Pre-Code Caveat, source-of-truth/exporter, and "when-X-lands" patterns
references/portfolio-audit-runbook.md	Operator playbook for audit_repo.sh / audit_portfolio.sh / compare_blocks.sh — directives, cadence, worked example
references/harness-audit.md	Harness health-check playbook: inventory → verify current best practices → instrument fires → prune on data; marketplace-skill boundary, gate immutability, divergence tripwires
data/sources.json	Official and community links to platform docs and guides

Related Skills

Skill	Purpose
agents-hooks	Hook automation and compaction survival
agents-mcp	MCP config in project memory files
agents-openclaw-ops	OpenClaw runtime setup, workspaces, skills, and sandboxing
agents-skills	Skill packaging and progressive disclosure
agents-subagents	Agent and subagent setup
ai-coding-agents-safety-envelope	Approval reviewers, sandbox boundaries, permission profiles, and executable rules
ai-coding-agents-state	Session lifecycle, transcript recovery, and cross-worktree resume
ai-coding-agents-settings-policy	Full Codex configuration precedence and managed-policy layering
docs-codebase	Repo documentation patterns

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.