memory-processor

# Memory Processor

Process changed files and update relevant memory file sections (CLAUDE.md or AGENTS.md, whichever is the active file per project config) following official guidelines.

## Guidelines

**MANDATORY**: All rules below must be followed exactly. Violations produce incorrect CLAUDE.md content.

@../shared/references/guidelines.md

## Algorithm

1. **Parse context**: Read context provided by memory-updater agent:
   - Changed files with categories
   - File content summaries
   - Detected dependencies
   - Git context (commits, diffs)
   - Target memory files (CLAUDE.md or AGENTS.md per project config)

2. **Categorize changes**: Map files to CLAUDE.md sections using the tables in "Section Names" below. Match changed files to their update triggers.

3. **Analyze impact**: Determine what needs updating:
   - New build commands added?
   - Architecture changed (new dirs, renamed components)?
   - New coding patterns detected?
   - Dependencies added/removed?

4. **Verify and update content**: Before modifying documented content, verify accuracy:

   **Key distinction - conventions vs patterns:**
   - `conventions`: Explicit rules humans decided (naming, imports, formatting)
   - `patterns`: Implicit patterns AI detected from recurring code structures

   **Removal verification:**
   - Read the relevant CLAUDE.md section to get currently documented items
   - For each item that appears missing from changed files:
     - Use Grep to search the codebase for that item
     - Search in relevant directories excluding node_modules, vendor, .git
     - If item exists elsewhere: keep it documented
     - If item is not found anywhere: mark for removal

   **Stale command detection:**
   - Compare documented commands against commands that actually executed successfully
   - If documented command differs from successful execution, update to match what worked
   - Examples:
     - Documented: `python pytest` | Actually worked: `python -m pytest` → Update
     - Documented: `npm test` | Actually worked: `npm run test` → Update
     - Documented: `pytest tests/` | Actually worked: `uv run pytest` → Update
   - Source: Successful Bash tool executions from session context or git commit history

   **Examples:**
   - Pattern: `@decorator` removed → search `grep -r "@decorator" src/`
   - Convention: `async/await` style removed → search for `async function` or `await`
   - Architecture: `utils/` directory deleted → verify no `utils/` references remain
   - Build command: `npm run dev` removed from package.json → verify script is gone

5. **Update memory file**: Modify relevant sections in the active memory file:
   - Preserve AUTO-MANAGED markers
   - Never touch MANUAL sections
   - Apply content rules (specific, concise, structured)
   - Do not modify CLAUDE.md redirect files (files containing only "Read AGENTS.md...")

6. **Validate**: Ensure updates follow guidelines:
   - No generic instructions added
   - Specific and actionable content
   - Proper markdown formatting

## Marker Syntax

CLAUDE.md uses HTML comment markers for selective updates:

```markdown
<!-- AUTO-MANAGED: section-name -->
Content that will be automatically updated
<!-- END AUTO-MANAGED -->

<!-- MANUAL -->
Content that will never be touched
<!-- END MANUAL -->
```

## Section Names

### Root CLAUDE.md Sections

| Section | Purpose | Update Triggers |
|---------|---------|-----------------|
| `project-description` | Project overview | README changes, major refactors |
| `build-commands` | Build, test, lint commands | package.json, Makefile, pyproject.toml |
| `architecture` | Directory structure, components | New dirs, renamed files, structural changes |
| `conventions` | Naming, imports, code standards | Pattern changes in source files |
| `patterns` | AI-detected coding patterns | Repeated patterns across files |
| `git-insights` | Decisions from git history | Significant commits |
| `best-practices` | From official Claude Code docs | Manual updates only |

### Subtree CLAUDE.md Sections

| Section | Purpose | Update Triggers |
|---------|---------|-----------------|
| `module-description` | Module purpose | Module README, major changes |
| `architecture` | Module structure | File changes within module |
| `conventions` | Module-specific conventions | Pattern changes in module |
| `dependencies` | Key module dependencies | Import changes, package updates |

## Token Efficiency

- Keep sections concise - bullet points, not paragraphs
- Use imports (`@path/to/file`) for detailed specs
- Follow Content Rules above (< 500 lines, stay current)

## Output

Return a brief summary:
- "Updated [section names] in [memory file path] based on changes to [file names]"
- "Removed [pattern] from [section] - no longer used in codebase"
- "No updates needed - changes do not affect documented sections"