Memory Md Management

Memory.md Management

Provides comprehensive project memory file management capabilities including auditing, quality assessment, and targeted improvements. This skill ensures the coding agent has optimal project context by maintaining high-quality documentation files such as CLAUDE.md.

Overview

Project memory files such as CLAUDE.md are the primary mechanism for providing project-specific context to coding agent sessions. This skill manages their complete lifecycle: discovery, quality assessment, reporting, and improvement. It follows a 5-phase workflow that ensures documentation is current, actionable, and concise.

The skill evaluates CLAUDE.md files against standardized quality criteria across 6 dimensions: Commands/Workflows, Architecture Clarity, Non-Obvious Patterns, Conciseness, Currency, and Actionability. Each file receives a score (0-100) and letter grade (A-F) with specific improvement recommendations.

When to Use

Use this skill when:

• User explicitly asks to "check", "audit", "update", "improve", "fix", or "maintain" CLAUDE.md
• User mentions "CLAUDE.md quality", "documentation review", or "project memory optimization"
• A project memory file needs to be created from scratch for a new project
• User asks about improving Claude's understanding of the codebase
• Documentation has become stale or outdated
• Starting work on a new codebase and need to understand existing documentation
• User presses # during a session to incorporate learnings into a memory file

Trigger phrases: "audit CLAUDE.md", "check documentation quality", "improve project context", "review CLAUDE.md", "validate documentation"

Instructions

Phase 1: Discovery

Find all CLAUDE.md files in the repository:

find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50

File Types & Locations:

Phase 2: Quality Assessment

For each CLAUDE.md file, read references/quality-criteria.md and evaluate against these criteria:

Quality Scores: A (90-100), B (70-89), C (50-69), D (30-49), F (0-29)

Phase 3: Quality Report Output

CRITICAL: Always output the quality report BEFORE making any updates.

Format:

## CLAUDE.md Quality Report

### Summary
- Files found: X
- Average score: X/100
- Files needing update: X

### File-by-File Assessment
#### 1. ./CLAUDE.md (Project Root)
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]

Phase 4: Targeted Updates

After report output, ask user for confirmation before updating.

Read [references/update-guidelines.md](references/update-guidelines.md) for detailed update principles.

Key principles: 1. Propose targeted additions only - commands, gotchas, patterns, configs 2. Keep it minimal - avoid obvious info, generic advice, one-off fixes 3. Show diffs - file, change (diff format), explanation

Diff format:

### Update: ./CLAUDE.md
**Why:** [Brief explanation of why this helps]

+ ## Quick Start + + ``bash + npm install + npm run dev + ``

Phase 5: Apply Updates

After user approval, use Edit tool to apply changes. Preserve existing content structure.

Examples

Example 1: Quality Assessment

User request: "Check if my CLAUDE.md is good"

Response: ~~~markdown

CLAUDE.md Quality Report

Summary

• Files found: 1
• Average score: 65/100
• Files needing update: 1

File-by-File Assessment

1. ./CLAUDE.md

Score: 65/100 (Grade: C)

Issues:

• Missing test command
• Missing build command
• No documentation of auth flow complexity
• References to old src/structure

Recommended additions:

• Add Commands section with test/build
• Document auth module gotcha
• Update architecture paths

### Example 2: Creating from Scratch

**User request:** "Create a CLAUDE.md for this React project"

**Response:**

I'll create a CLAUDE.md for your React project. Let me first analyze the codebase structure.

[Scans package.json, src/, and key config files]

CLAUDE.md Quality Report

Summary

• Files found: 0
• Creating new CLAUDE.md at project root

Proposed CLAUDE.md Content:

Project Name

Commands

Architecture

src/
├── components/    # Reusable UI components
├── pages/         # Route pages
├── hooks/         # Custom React hooks
├── lib/           # Utilities and API clients
└── main.tsx       # Entry point

Gotchas

• Vite requires files in public/ for static assets
• State updates in useEffect need proper dependency arrays

Shall I create this file?

Example 3: Update Proposal

User request: "Update my CLAUDE.md with what you learned"

Response:

### Update: ./CLAUDE.md

**Why:** Discovered that tests require database setup which wasn't documented.

Testing

+ Prerequisites: Start test database first with docker-compose up -d test-db + npm run test - Run all tests + npm run test:unit - Unit tests only (no DB required)

Also found issue with API_BASE_URL:

Environment

• API_BASE_URL - API endpoint (default: localhost:3000)

+ API_BASE_URL - API endpoint (required for production, defaults to http://localhost:3000 in dev)

Apply these changes?
~~~

## Best Practices

1. **Always read references before acting**: Quality criteria, templates, and update guidelines contain essential details
2. **Report before editing**: Never modify CLAUDE.md without first presenting a quality report
3. **Preserve existing structure**: When updating, maintain the existing organization and style
4. **Be project-specific**: Only add information specific to this codebase, not generic advice
5. **Verify commands work**: Before suggesting commands, mentally or actually verify they execute correctly
6. **Use progressive disclosure**: Keep SKILL.md lean, reference detailed rubrics in separate files
7. **Score consistently**: Apply the same scoring standards across all files for fair comparison

## Constraints and Warnings

1. **Never modify without approval**: Always get user confirmation before editing CLAUDE.md files
2. **Don't remove content without asking**: If suggesting deletions, explicitly mark them and get approval
3. **Respect `.claude.local.md`**: These are personal settings; never suggest modifying them in shared docs
4. **Avoid generic advice**: Do not add "write good code" type content - focus on project-specific patterns
5. **Keep diffs concise**: Show only the actual changes, not entire file contents
6. **Verify file paths**: Ensure all referenced files exist before documenting them
7. **Score objectively**: Use the rubric consistently; don't inflate scores for incomplete documentation

Memory File Quality Criteria

Scoring Rubric

1. Commands/Workflows (20 points)

20 points: All essential commands documented with context

• Build, test, lint, deploy commands present
• Development workflow clear
• Common operations documented

15 points: Most commands present, some missing context

10 points: Basic commands only, no workflow

5 points: Few commands, many missing

0 points: No commands documented

2. Architecture Clarity (20 points)

20 points: Clear codebase map

• Key directories explained
• Module relationships documented
• Entry points identified
• Data flow described where relevant

15 points: Good structure overview, minor gaps

10 points: Basic directory listing only

5 points: Vague or incomplete

0 points: No architecture info

3. Non-Obvious Patterns (15 points)

15 points: Gotchas and quirks captured

• Known issues documented
• Workarounds explained
• Edge cases noted
• "Why we do it this way" for unusual patterns

10 points: Some patterns documented

5 points: Minimal pattern documentation

0 points: No patterns or gotchas

4. Conciseness (15 points)

15 points: Dense, valuable content

• No filler or obvious info
• Each line adds value
• No redundancy with code comments

10 points: Mostly concise, some padding

5 points: Verbose in places

0 points: Mostly filler or restates obvious code

5. Currency (15 points)

15 points: Reflects current codebase

• Commands work as documented
• File references accurate
• Tech stack current

10 points: Mostly current, minor staleness

5 points: Several outdated references

0 points: Severely outdated

6. Actionability (15 points)

15 points: Instructions are executable

• Commands can be copy-pasted
• Steps are concrete
• Paths are real

10 points: Mostly actionable

5 points: Some vague instructions

0 points: Vague or theoretical

Assessment Process

1. Read the memory file completely 2. Cross-reference with actual codebase:

• Run documented commands (mentally or actually)
• Check if referenced files exist
• Verify architecture descriptions

3. Score each criterion 4. Calculate total and assign grade 5. List specific issues found 6. Propose concrete improvements

Red Flags

• Commands that would fail (wrong paths, missing deps)
• References to deleted files/folders
• Outdated tech versions
• Copy-paste from templates without customization
• Generic advice not specific to the project
• "TODO" items never completed
• Duplicate info across multiple memory files

Memory File Templates

Key Principles

• Concise: Dense, human-readable content; one line per concept when possible
• Actionable: Commands should be copy-paste ready
• Project-specific: Document patterns unique to this project, not generic advice
• Current: All info should reflect actual codebase state

---

Recommended Sections

Use only the sections relevant to the project. Not all sections are needed.

Commands

Document the essential commands for working with the project.

~~~markdown

Commands

~~~

Architecture

Describe the project structure so Claude understands where things live.

~~~markdown

Architecture

~~~ <tree-structure>

# <directory-name>

# <directory-name>

### Key Files

List important files that Claude should know about.

Key Files

• <path> - <purpose>
• <path> - <purpose>

### Code Style

Document project-specific coding conventions.

Code Style

• <convention 1>
• <convention 2>

### Environment

Document required environment variables and setup.

Environment

Required:

• <VAR> - <purpose>

Setup:

• <setup steps>

### Testing

Document testing approach and commands.

Testing

• <approach 1>
• <approach 2>

### Gotchas

Document non-obvious patterns, quirks, and warnings.

Gotchas

• <gotcha 1>
• <gotcha 2>

### Workflow

Document development workflow patterns.

Workflow

• <workflow pattern>

---

## Template: Project Root (Minimal)

<Project Name>

Commands

Architecture

<tree>

Gotchas

• <gotcha>

---

## Template: Project Root (Comprehensive)

<Project Name>

Commands

Architecture

<tree>

Key Files

• <path> - <purpose>

Code Style

• <convention>

Environment

• <VAR> - <purpose>

Testing

• <approach>

Gotchas

• <gotcha>

---

## Template: Package/Module

For packages within a monorepo or distinct modules.

<Package/Module Name>

Usage

```<language> <example>

## Key Exports

- `<export>` - <purpose>

## Dependencies

- <dependency>

## Notes

- <note>

---

Template: Monorepo Root

# <Monorepo Name>

## Packages

| Package | Description | Path |
|---------|-------------|------|
| `<name>` | <description> | `<path>` |

## Commands

| Command | Description |
|---------|-------------|
| `<cmd>` | <description> |

## Cross-Package Patterns

- <pattern>

---

Update Principles

When updating any CLAUDE.md:

1. Be specific: Use actual file paths, real commands from this project 2. Be current: Verify info against the actual codebase 3. Be brief: One line per concept when possible 4. Be useful: Would this help a new Claude session understand the project?

Memory File Update Guidelines

Core Principle

Only add information that will genuinely help future Claude sessions. The context window is precious - every line must earn its place.

What TO Add

1. Commands/Workflows Discovered

## Build

`npm run build:prod` - Full production build with optimization
`npm run build:dev` - Fast dev build (no minification)

Why: Saves future sessions from discovering these again.

2. Gotchas and Non-Obvious Patterns

## Gotchas

- Tests must run sequentially (`--runInBand`) due to shared DB state
- `yarn.lock` is authoritative; delete `node_modules` if deps mismatch

Why: Prevents repeating debugging sessions.

3. Package Relationships

## Dependencies

The `auth` module depends on `crypto` being initialized first.
Import order matters in `src/bootstrap.ts`.

Why: Architecture knowledge that isn't obvious from code.

4. Testing Approaches That Worked

## Testing

For API endpoints: Use `supertest` with the test helper in `tests/setup.ts`
Mocking: Factory functions in `tests/factories/` (not inline mocks)

Why: Establishes patterns that work.

5. Configuration Quirks

## Config

- `NEXT_PUBLIC_*` vars must be set at build time, not runtime
- Redis connection requires `?family=0` suffix for IPv6

Why: Environment-specific knowledge.

What NOT to Add

1. Obvious Code Info

Bad:

The `UserService` class handles user operations.

The class name already tells us this.

2. Generic Best Practices

Bad:

Always write tests for new features.
Use meaningful variable names.

This is universal advice, not project-specific.

3. One-Off Fixes

Bad:

We fixed a bug in commit abc123 where the login button didn't work.

Won't recur; clutters the file.

4. Verbose Explanations

Bad:

The authentication system uses JWT tokens. JWT (JSON Web Tokens) are
an open standard (RFC 7519) that defines a compact and self-contained
way for securely transmitting information between parties as a JSON
object. In our implementation, we use the HS256 algorithm which...

Good:

Auth: JWT with HS256, tokens in `Authorization: Bearer <token>` header.

Diff Format for Updates

For each suggested change:

1. Identify the File

File: ./CLAUDE.md
Section: Commands (new section after ## Architecture)

2. Show the Change

## Architecture
...

+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Dev server with HMR |
+| `npm run build` | Production build |
+| `npm test` | Run test suite |

3. Explain Why

> **Why this helps:** The build commands weren't documented, causing
> confusion about how to run the project. This saves future sessions
> from needing to inspect `package.json`.

Validation Checklist

Before finalizing an update, verify:

• [ ] Each addition is project-specific
• [ ] No generic advice or obvious info
• [ ] Commands are tested and work
• [ ] File paths are accurate
• [ ] Would a new Claude session find this helpful?
• [ ] Is this the most concise way to express the info?