memory-management

Memory Meta

🚨 MANDATORY: Invoke docs-management First

STOP - Before providing ANY response about Claude Code memory (CLAUDE.md):

1. INVOKE docs-management skill
2. QUERY using keywords: CLAUDE.md, static memory, memory hierarchy, import syntax, or related topics
3. BASE all responses EXCLUSIVELY on official documentation loaded

Skipping this step results in outdated or incorrect information.

Verification Checkpoint

Before responding, verify:

• Did I invoke docs-management skill?
• Did official documentation load?
• Is my response based EXCLUSIVELY on official docs?

If ANY checkbox is unchecked, STOP and invoke docs-management first.

Meta-skill for Claude Code memory system - 100% driven by official documentation

Zero Duplication Policy

This skill contains ZERO duplicated content from official documentation. ALL implementation details delegate to the docs-management skill using natural language queries. This skill provides stable principles and navigation that won't change, while docs-management provides current official guidance.

Overview

This meta-skill provides stable principles, keyword registries, and patterns for working with Claude Code's memory system (CLAUDE.md files, static memory). It does NOT duplicate official documentation - instead, it teaches you how to efficiently query the docs-management skill for any memory-related information you need.

What this skill provides:

• Stable principles that won't change (timeless guidance)
• Keyword registry for efficient documentation lookups
• Common organization patterns
• Quick decision trees for navigation
• Troubleshooting guidance

What this skill delegates to docs-management:

• Current import syntax specifications
• Exact file locations and paths
• Version-specific behaviors
• Implementation details that may evolve
• Complete best practices documentation

When to Use This Skill

This skill should be used when:

• Working with CLAUDE.md files - Creating, editing, or organizing memory
• Memory hierarchy questions - Understanding enterprise/project/user/local precedence
• Import syntax questions - How to import files, @ syntax, recursive lookup
• Progressive disclosure patterns - Organizing always-loaded vs on-demand content
• Memory organization - Hub-and-spoke, token budgets, cross-references
• Best practices lookup - Efficient queries to find official guidance

Stable Principles (Won't Change)

These principles are fundamental to how LLMs and memory systems work. They won't change even as Claude Code's implementation evolves.

1. Progressive Disclosure

Principle: Load context on-demand, not everything upfront.

Why stable: Context windows are finite resources. This is a fundamental LLM constraint that won't change.

Application:

• Always-loaded content should be minimal and high-signal
• Detailed content loads only when needed
• Hub files link to detailed references

2. Strategic Emphasis

Principle: Use emphasis keywords (CRITICAL, NEVER, MUST, IMPORTANT) strategically for must-follow rules.

Why stable: Human communication patterns for priority signaling are universal.

Application:

• Reserve emphasis for truly critical rules
• Don't overuse (dilutes effectiveness)
• Use consistently across your memory files

3. Specificity Over Vagueness

Principle: "Use 2-space indent" beats "format code properly"

Why stable: Specific instructions are universally more actionable than vague ones.

Application:

• Concrete examples over abstract guidance
• Exact commands over general directions
• Measurable criteria over subjective standards

4. Structure Aids Parsing

Principle: Bullets, headings, and clear organization improve comprehension.

Why stable: Both humans and LLMs process structured content more effectively.

Application:

• Use markdown headings consistently
• Bullet points for lists of items
• Tables for structured comparisons
• Code blocks for commands/examples

5. Hierarchy/Layering

Principle: Configuration layers override each other (enterprise → project → user → local).

Why stable: Standard configuration pattern used across all software systems.

Application:

• Higher levels set defaults
• Lower levels can override
• Understand which level your changes belong to

6. Token Efficiency

Principle: Context is finite - be efficient with tokens.

Why stable: LLM context windows have limits. Even as they grow, efficiency matters.

Application:

• Remove redundant content
• Link instead of duplicate
• Use progressive disclosure
• Monitor token budgets

Detailed explanations: See Stable Principles Reference

Quick Decision Tree

What do you want to do?

1. Create a new CLAUDE.md file → Query docs-management: "Find documentation about creating CLAUDE.md files and /init command"

2. Organize memory for a project → See Common Patterns

3. Understand import syntax → Query docs-management: "Find documentation about CLAUDE.md import syntax and @ references"

4. Set up memory hierarchy → Query docs-management: "Find documentation about memory hierarchy enterprise project user"

5. Optimize token usage → See Stable Principles + Common Patterns

6. Fix memory not loading → See Troubleshooting

7. Find official best practices → See Keyword Registry for efficient queries

Keyword Registry for docs-management

Use these keywords when querying the docs-management skill for memory-related documentation:

Core Memory System

Keywords: CLAUDE.md, static memory, memory hierarchy, memory system

Example query:

Find documentation about CLAUDE.md static memory system and memory hierarchy

Import Syntax

Keywords: import syntax, @ references, recursive lookup, file imports

Example query:

Find documentation about CLAUDE.md import syntax and @ file references

Memory Commands

Keywords: /init command, /memory command, # shortcut, memory commands

Example query:

Find documentation about /init and /memory commands for CLAUDE.md

Best Practices

Keywords: memory best practices, CLAUDE.md tuning, memory organization

Example query:

Find documentation about CLAUDE.md best practices and memory tuning

Agent SDK Integration

Keywords: settingSources, memory API, Agent SDK memory

Example query:

Find documentation about Agent SDK settingSources and memory integration

Complete keyword registry: See Keyword Registry Reference

Common Patterns

Hub-and-Spoke Organization

Pattern: Central hub file (CLAUDE.md) links to detailed reference files.

CLAUDE.md (hub)
├─ Quick Reference (essential, always loaded)
├─ Core principles (brief)
└─ Links to detailed docs
    ├─→ .claude/memory/architecture.md
    ├─→ .claude/memory/workflows.md
    └─→ .claude/memory/testing.md

Benefits:

• Hub stays small (token efficient)
• Details load on-demand
• Single entry point
• Easy navigation

Always-Loaded vs Context-Dependent

Pattern: Separate critical content from detailed content.

Always-loaded (@-prefixed imports):

• Core principles that apply to every task
• Critical rules that must never be violated
• Quick reference for common operations
• ~10-15k tokens maximum recommended

Context-dependent (loaded on-demand):

• Detailed guides for specific topics
• Reference documentation
• Examples and templates
• Can be larger since loaded selectively

Token Budget Strategy

Pattern: Allocate tokens intentionally across memory tiers.

Tier	Target Budget	Content Type
Always-loaded	~10-15k tokens	Core principles, critical rules
On-demand	~30-50k tokens	Detailed guides, references
External (skills)	Unlimited	Delegated documentation

Detailed patterns: See Common Patterns Reference

Troubleshooting

Memory Not Loading

Symptoms: CLAUDE.md content doesn't appear in context

Diagnostic steps:

1. Check file location:

   • Project: ./CLAUDE.md at repo root
   • User: ~/.claude/CLAUDE.md

2. Check import syntax:

   • Valid: @path/to/file.md
   • Invalid: @path/to/file (missing extension)
   • Invalid: Inside code blocks (imports not processed)

3. Check file exists:

   • Imported files must exist at specified paths
   • Relative paths resolve from importing file's location

Query docs-management for current troubleshooting:

Find documentation about CLAUDE.md troubleshooting and memory loading issues

Import Syntax Issues

Common mistakes:

• Missing @ prefix for always-loaded imports
• Using imports inside code blocks (won't be processed)
• Circular imports (A imports B imports A)
• Exceeding max import depth

Query docs-management for syntax specification:

Find documentation about CLAUDE.md import syntax requirements and limitations

Hierarchy Conflicts

Symptoms: Unexpected behavior due to conflicting instructions

Resolution:

1. Identify which level each instruction comes from
2. Higher levels (enterprise) override lower levels (user)
3. Within same level, later content may override earlier
4. Use specific instructions to override general ones

Query docs-management for hierarchy details:

Find documentation about memory hierarchy precedence and conflict resolution

Reference Loading Guide

All references in this skill are conditional load - they are loaded only when needed.

When to Load Each Reference

• stable-principles.md → When you need detailed explanation of why principles are stable
• keyword-registry.md → When you need comprehensive keyword list for docs-management queries
• common-patterns.md → When implementing memory organization patterns

Progressive Disclosure Strategy

Layer 1: Always in Context

• SKILL.md (this file) - Navigation hub, quick reference

Layer 2: Load on Demand

• Reference files when specific topic needed

Layer 3: External Delegation

• Official documentation via docs-management skill (always current)

Related Skills

Skills that work well with memory-management:

• docs-management - Official documentation access (memory-management delegates all documentation queries here)
• skill-development - If you're creating skills that use memory patterns
• current-date - For Last Updated timestamps in memory files

Best Practices Summary

DO:

• Query docs-management for all official documentation
• Use stable principles as foundation (they won't change)
• Apply progressive disclosure (always-loaded vs on-demand)
• Keep hub files small and focused
• Use keyword registry for efficient lookups
• Monitor token budgets

DON'T:

• Duplicate official documentation
• Put everything in always-loaded imports
• Use vague instructions ("do things properly")
• Ignore token budgets
• Skip verification of import syntax

Auditing Memory Files

This skill provides the validation criteria used by the memory-component-auditor agent for formal audits.

Audit Resources

Resource	Location	Purpose
Audit Framework	references/audit-framework.md	Query guides and scoring criteria

Scoring Categories

Category	Points	Key Criteria
Structure	25	Valid markdown, proper sections
Import Syntax	25	Correct @path syntax, files exist
Hierarchy Compliance	20	Correct level (enterprise/project/user)
Content Organization	20	Progressive disclosure, appropriate size
No Anti-Patterns	10	No circular imports, excessive nesting

Thresholds: 85+ = PASS, 70-84 = PASS WITH WARNINGS, <70 = FAIL

Related Agent

The memory-component-auditor agent (Haiku model) performs formal audits using this skill:

• Auto-loads this skill via skills: memory-management
• Uses audit framework and docs-management for rules
• Generates structured audit reports
• Invoked by /audit-memory command

External Technology Validation

When auditing memory files that reference external technologies (scripts, packages, runtimes), the auditor MUST validate claims using MCP servers before flagging findings.

Technologies Requiring MCP Validation:

• .NET/C# scripts: Validate with microsoft-learn + perplexity
• Node.js/npm packages: Validate with context7 + perplexity
• Python scripts/packages: Validate with context7 + perplexity
• Shell scripts: Validate with perplexity
• Any version-specific claims: ALWAYS validate with perplexity

Validation Rule:

Never flag a technology usage as incorrect without first:

1. Querying appropriate MCP server(s) for current documentation
2. Verifying with perplexity for recent changes (especially .NET 10+)
3. Documenting MCP sources in the finding

Stale Data Warning:

• microsoft-learn can return cached/outdated documentation
• ALWAYS pair microsoft-learn with perplexity for version verification
• Trust perplexity for version numbers and recently-released features

References

Reference files:

• Stable Principles - Detailed explanation of timeless principles
• Keyword Registry - Complete keyword list for docs-management queries
• Common Patterns - Memory organization patterns and examples
• Audit Framework - Audit scoring and query guides

Version History

• v1.0.0 (2025-11-26): Initial release - Delegation-first meta-skill with stable principles, keyword registry, and common patterns

---