AI Agent Memory File Management

Core Concepts

AGENTS.md as the Single Source of Truth

Project Information Sources (codebase + documentation)
    │
    │  Distill key information
    ▼
AGENTS.md (concise, stable, cross-AI-tool compatible) ← Only edit point for general information
    │
    ├── CLAUDE.md (@AGENTS.md import + Claude Code exclusive supplements)
    ├── .claude/rules/devdocs-state.md (DevDocs projects only, numbered status)
    └── Future: .cursorrules / .windsurfrules (reserved, not implemented)

• AGENTS.md remains tool-agnostic and does not include syntax exclusive to specific AI tools
• CLAUDE.md imports general information via

  @AGENTS.md

  and can append Claude Code-exclusive supplements
• Tool-specific information is supplemented via respective rule files (e.g.,

  .claude/rules/

  )

Reference Best Practices

• During initial creation: acts as a quality benchmark
• During

  --update

  : used as content filtering criteria
• During

  --restructure

  : used as structure validation and anti-pattern detection standard

Collaboration with

/init

/init

/init

• If AGENTS.md does not exist: automatically scan project sources and create it
• If

  /init

  has already created AGENTS.md: subsequent

  --update

  will perform incremental updates based on it
• best-practices.md serves as content quality reference
• memory-template.md serves as the output template for AGENTS.md

Language Rules

• Supports Chinese and English queries
• Responses are uniformly in Chinese

Operation Modes

/agent-memory                    → Intelligent detection (Does AGENTS.md exist? Does it need an update?)
/agent-memory --update           → Extract information from project sources and update AGENTS.md
/agent-memory --restructure      → Restructure existing AGENTS.md according to best practices

--update

--restructure

Intelligent Detection Flow

Check if AGENTS.md exists
        │
        ├── Does not exist → Scan project sources, create AGENTS.md + CLAUDE.md for the first time
        │
        └── Exists → Analyze content status
                    ├── Outdated information → Recommend --update
                    └── Disorganized structure → Recommend --restructure

Information Extraction Layers

General Extraction (All Projects)

Enhanced Extraction for DevDocs (When docs/devdocs/ exists)

--update

Workflow

1. Scan project information sources
   ├── General extraction (package managers, README, git, code structure)
   └── DevDocs enhanced extraction (if docs/devdocs/ exists)
   │
   ▼
1.5 Check if AGENTS.md exists
   ├── Does not exist → Create using memory-template.md
   └── Exists → Perform incremental update
   │
   ▼
2. Distill key information
   ├── Tech stack
   ├── ADR summaries (if available; extract key decisions from change logs if no ADR format exists)
   ├── Domain terminology
   ├── Active tasks + progress
   ├── Numbered status (DevDocs projects only)
   └── Run commands
   │
   ▼
2.5 Filter according to best-practices.md
   ├── Content filtering criteria: Should include vs. Should exclude
   └── Quality guidelines: 6 checks
   │
   ▼
3. Update AGENTS.md (using templates/memory-template.md)
   │
   ▼
4. Ensure CLAUDE.md exists (create import file if missing; skip if already exists, do not overwrite supplement section)
   │
   ▼
5. Generate/update .claude/rules/devdocs-state.md (DevDocs projects only)

Routing Rules

.claude/rules/devdocs-state.md

docs/devdocs/

--restructure

Workflow

1. Read existing AGENTS.md
   │
   ▼
2. Detect non-compliant items according to best-practices.md
   ├── Line limit (≤ 60 lines)
   ├── Tool agnosticism
   ├── Section order (align with structure standards)
   ├── Anti-pattern detection
   └── Missing sections
   │
   ▼
3. Restructure according to templates/memory-template.md
   │
   ▼
4. Display restructuring proposal, write to file after confirmation
   │
   ▼
5. Ensure CLAUDE.md exists (create import file if missing; skip if already exists)

Output Files

AGENTS.md

• Location: Project root directory
• Template: templates/memory-template.md
• Constraint: No more than 60 lines, tool-agnostic

CLAUDE.md

• Location: Project root directory
• Structure:

  @AGENTS.md

  import + Claude Code exclusive supplement section
• Creation timing: Created together when AGENTS.md is first generated; do not overwrite if already exists
• Supplement section is manually maintained by users, not modified by

  /agent-memory

.claude/rules/devdocs-state.md

• Location:

  .claude/rules/devdocs-state.md

• Template: templates/devdocs-state-template.md
• Condition: DevDocs projects only (when docs/devdocs/ exists)

Constraints

Content Constraints

• AGENTS.md does not exceed 60 lines
• AGENTS.md does not include syntax exclusive to specific AI tools
• CLAUDE.md imports general information via @AGENTS.md (do not overwrite after initial creation)
• Numbered status is only written to

  .claude/rules/devdocs-state.md

Quality Guidelines

• 6 guidelines (short and stable / widely applicable / actionable / avoid duplication / keep details in place / tool-agnostic)
• Content filtering criteria (Should include vs. Should exclude)
• Anti-pattern list

Operation Constraints

• Do not generate/modify

  00-context.md

• Delete when possible, prioritize commands, constraints, checkpoints
• Must confirm before restructuring with

  --restructure

Skill Collaboration

/agent-memory

/init

/devdocs-onboard

/devdocs-dev-workflow

/devdocs-onboard

Template References

• AGENTS.md template: templates/memory-template.md
• Numbered status template: templates/devdocs-state-template.md
• Best practices: templates/best-practices.md