severity1/claude-code-auto-memory/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)

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

1. Analyze impact: Determine what needs updating:

• New build commands added?
• Architecture changed (new dirs, renamed components)?
• New coding patterns detected?
• Dependencies added/removed?

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

1. 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...")

1. 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:

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

Subtree CLAUDE.md Sections

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"