# Agent Memory Lifecycle & Config Ownership

## MEMORY.md Structured Format

Every agent MEMORY.md follows a 3-section lifecycle structure:

```markdown
# {Agent Name} Agent Memory ({Persona})

## Active Patterns
<!-- Current, verified patterns used by this agent -->
- Pattern 1 description
- Pattern 2 description

## Promotion Candidates
<!-- Patterns seen across 3+ agents — candidates for CLAUDE.md or .claude/rules/ -->
<!-- Format: - **{pattern}** | Source: {agent} | Detected: {YYYY-MM-DD} -->

## Archived
<!-- Patterns no longer relevant — kept for history -->
<!-- Format: - ~~{pattern}~~ | Archived: {YYYY-MM-DD} | Reason: {reason} -->
```

### Section Rules

| Section | Purpose | Content |
|---------|---------|---------|
| **Active Patterns** | Current, verified knowledge | Sub-headings for categories (Key Patterns, Git Rules, etc.) |
| **Promotion Candidates** | Cross-agent patterns pending promotion | Pattern + source agent + detection date |
| **Archived** | Superseded or stale entries | Strikethrough pattern + archive date + reason |

## Lifecycle Flow

```
Capture (auto-memory) → Active Patterns → Promotion Candidates → CLAUDE.md/rules/ OR Archived
```

1. **Capture**: Agent learns a pattern during work (auto-memory or manual addition)
2. **Active**: Pattern lives in agent's `## Active Patterns` section
3. **Promote**: Pattern appears in 3+ agents → moved to `## Promotion Candidates` with metadata
4. **Elevate or Archive**:
   - Elevated: Pattern added to `.claude/CLAUDE.md` or `.claude/rules/` (project-wide)
   - Archived: Pattern moved to `## Archived` with reason (superseded, contradicted, irrelevant)

## Promotion Criteria

A pattern qualifies for promotion when ANY of:

- **Cross-agent frequency**: Pattern appears in 3+ agent MEMORY.md files
- **Session stability**: Pattern confirmed stable across 5+ development sessions
- **Framework impact**: Pattern affects framework behavior (not just agent-specific knowledge)

## Archive Criteria

A pattern should be archived when ANY of:

- **Superseded**: A code change made the pattern obsolete (e.g., API replaced)
- **Contradicted**: A newer pattern directly contradicts it
- **Irrelevant**: No longer applicable to the current project state

## CLAUDE.md Section Ownership Map

Each section of `.claude/CLAUDE.md` has a clear ownership classification:

| CLAUDE.md Section | Ownership | Layer | Notes |
|---|---|---|---|
| Constitution | Framework | L1 | Generated by installer, references `.aiox-core/constitution.md` |
| Language Configuration | Framework | L2 | Set by installer, overridable |
| Premissa Arquitetural: CLI First | Framework | L1 | Constitution Article I |
| Estrutura do Projeto | Framework | L2 | Generated from directory scan |
| Framework vs Project Boundary | Framework | L1 | Core architecture |
| Sistema de Agentes | Framework | L2 | Agent definitions from `.aiox-core/development/agents/` |
| Story-Driven Development | Framework | L2 | Process definition |
| Padroes de Codigo | Project | L3 | Customizable per project |
| Testes & Quality Gates | Project | L3 | Customizable test commands |
| Convencoes Git | Project | L3 | Customizable conventions |
| Otimizacao Claude Code | Framework | L2 | Best practices |
| Comandos Frequentes | Project | L3 | Project-specific commands |
| MCP Usage | Framework | L2 | References `.claude/rules/mcp-usage.md` |
| Debug | Project | L4 | Runtime debugging config |

### Ownership Annotations

Sections in CLAUDE.md are annotated with HTML comments:

- `<!-- FRAMEWORK-OWNED: Generated by AIOX installer, do not customize -->` for L1/L2 sections
- `<!-- PROJECT-CUSTOMIZED: Safe to modify for your project -->` for L3/L4 sections

These annotations are invisible in rendered markdown but visible in source, serving as documentation for contributors and future automation.

## Memory Audit Process

Use `.aiox-core/development/checklists/memory-audit-checklist.md` periodically to:

1. Identify cross-agent patterns for promotion
2. Find stale entries for archival
3. Maintain memory hygiene across all 10 agents

Recommended frequency: once per sprint or after completing an epic.