Agents Memory

---
name: agents-memory
description: "Owns instruction files: AGENTS.md, CLAUDE.md, personal and repo rules. Use when writing, pruning, auditing them, sharing rules across Claude and Codex, or fixing ignored rules."
compatibility: Claude Code + Codex. Claude Code CLAUDE.md plus Codex AGENTS.md — runtime-specific file conventions.
version: "1.6"
last_validated: 2026-10-02
---

# 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](../ai-context-layer/SKILL.md). Context architecture beyond those files (hot/warm/cold layers, compiled knowledge bases, context graphs, maturity models) belongs to [dev-context-engineering](../dev-context-engineering/SKILL.md), 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](references/loading-and-layers.md#agentsmd-in-claude-code-lookup-step)) |
| 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](references/loading-and-layers.md#personal-layer-shared-by-claude-code-and-codex)) |
| 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](references/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](references/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](references/loading-and-layers.md).

## Workflow

Use the [AGENTS.md inclusion checklist](references/instruction-inclusion-checklist.md)
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](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](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:

```markdown
## 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](references/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](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](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](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 `dev`, 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

```bash
# 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](references/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

Three 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](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](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](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](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](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](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](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](references/memory-examples.md) | Full AGENTS.md / CLAUDE.md examples by stack |
| [references/nested-feature-memory-examples.md](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](references/memory-discipline.md) | Intent-first memory, exception test, instruction budget, working-if metric, feedback loops |
| [references/claude-md-instruction-budget.md](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](references/structure-patterns.md) | Hooks vs memory, three-tier boundaries, progressive disclosure |
| [references/memory-patterns.md](references/memory-patterns.md) | 15 patterns including progressive disclosure, three-tier boundaries, and feedback loops |
| [references/traps-and-antipatterns.md](references/traps-and-antipatterns.md) | Durable trap list and model-era anti-patterns |
| [references/coding-behavior.md](references/coding-behavior.md) | Canonical coding-behavior rules with rationale (a reference, too long to load every turn) |
| [references/coding-behavior-active.md](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](references/coding-behavior-completeness.md) | Greenfield counterpart: coding-behavior rules for completeness mode (do not load with defensive mode) |
| [references/reply-clarity-ste.md](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](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](references/platform-and-scale.md) | Path-scoped rules, cross-platform bridging, large-repo and memory-progression guidance |
| [references/large-codebase-strategy.md](references/large-codebase-strategy.md) | Monorepo and large-codebase (100K-1M LOC) configuration patterns |
| [references/memory-architecture-ceilings.md](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](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](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](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](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](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](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](data/sources.json) | Official and community links to platform docs and guides |

## Related Skills

| Skill | Purpose |
|-------|---------|
| [agents-hooks](../agents-hooks/SKILL.md) | Hook automation and compaction survival |
| [agents-mcp](../agents-mcp/SKILL.md) | MCP config in project memory files |
| `agents-openclaw-ops` | OpenClaw runtime setup, workspaces, skills, and sandboxing |
| [agents-skills](../agents-skills/SKILL.md) | Skill packaging and progressive disclosure |
| [agents-subagents](../agents-subagents/SKILL.md) | Agent and subagent setup |
| [ai-coding-agents-safety-envelope](../ai-coding-agents-safety-envelope/SKILL.md) | Approval reviewers, sandbox boundaries, permission profiles, and executable rules |
| [ai-coding-agents-state](../ai-coding-agents-state/SKILL.md) | Session lifecycle, transcript recovery, and cross-worktree resume |
| [ai-coding-agents-settings-policy](../ai-coding-agents-settings-policy/SKILL.md) | Full Codex configuration precedence and managed-policy layering |
| [docs-codebase](../docs-codebase/SKILL.md) | 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.