agents-project-memory

Original：🇺🇸 English

Translated

Configure project memory files (CLAUDE.md, AGENTS.md, CODEX.md) for persistent context, coding standards, architecture decisions, and team conventions. Reference for the 4-tier memory hierarchy, cross-platform compatibility, and quick-add commands.

2installs

Sourcevasilyu1983/ai-agents-public

Added on2026-02-26

NPX Install

npx skill4agent add vasilyu1983/ai-agents-public agents-project-memory

SKILL.md Content

View Translation Comparison →

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:

bash

# 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:

yaml

---
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