Claude-Mem v5.0 Skills Integration Guide

[thedotmack]

Claude-Mem v5.0 Skills Integration Guide

This guide will help you implement Skills into Claude-Mem to create a more context-efficient and intelligent memory system.

Overview: Skills Architecture

Skills are directories containing SKILL.md files that give Claude additional capabilities[(1)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills). They use progressive disclosure - metadata loads initially, full instructions load when triggered, and supporting files load as needed[(1)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills). This solves your context window degradation problem by keeping complex logic available but not always loaded.

Phase 1: Project Structure Setup

1.1 Add Skills Directory

Add the skills directory to your plugin structure[(2)](https://docs.claude.com/en/docs/claude-code/plugins#quickstart):

claude-mem/
├── plugin/
│   ├── skills/                    # New directory
│   │   ├── observation-classifier/
│   │   │   ├── SKILL.md
│   │   │   ├── classification-examples.xml
│   │   │   └── concept-taxonomy.md
│   │   ├── memory-deduplicator/
│   │   │   ├── SKILL.md
│   │   │   ├── search-strategies.md
│   │   │   └── scripts/
│   │   │       └── similarity-check.js
│   │   ├── summary-intelligence/
│   │   │   ├── SKILL.md
│   │   │   ├── summary-templates.xml
│   │   │   └── examples/
│   │   └── memory-orchestrator/
│   │       └── SKILL.md
│   ├── .claude-plugin/plugin.json
│   └── hooks/hooks.json

1.2 Update Plugin Manifest

Skills are automatically discovered when the plugin is installed[(2)](https://docs.claude.com/en/docs/claude-code/plugins#quickstart). No changes needed to plugin.json - the skills/ directory is loaded by default[(3)](https://docs.claude.com/en/docs/claude-code/plugins-reference#plugin-components-reference).

Phase 2: Create Core Skills

2.1 Observation Classifier Skill

Create plugin/skills/observation-classifier/SKILL.md:

---
name: Development Observation Classification
description: Classify development tool executions into structured memory observations. Use when processing PostToolUse events to determine what should be recorded vs skipped.
---

# Development Observation Classification

## When to Use This Skill
- Processing tool executions from Claude Code sessions
- Deciding what deserves memory storage
- Classifying the type and importance of development activities

## Classification Types
Use EXACTLY one of these 6 types:
- **bugfix**: something was broken, now fixed
- **feature**: new capability or functionality added
- **refactor**: code restructured, behavior unchanged
- **change**: generic modification (docs, config, misc)
- **discovery**: learning about existing system
- **decision**: architectural/design choice with rationale

## Skip Criteria
Skip these routine operations:
- Empty status checks (git status with no changes)
- Package installations with no errors
- Simple file listings (ls, dir commands)
- Repetitive operations already documented in this session

## Output Format
When creating observations, use the XML structure defined in classification-examples.xml.

## Concept Taxonomy
Reference concept-taxonomy.md for the exact list of allowed concept keywords.

Create plugin/skills/observation-classifier/concept-taxonomy.md:

# Concept Taxonomy

Use ONLY these exact concept keywords (2-5 per observation):

- **how-it-works**: understanding mechanisms and processes
- **why-it-exists**: purpose, rationale, or business logic
- **what-changed**: specific modifications made
- **problem-solution**: issues identified and their fixes
- **gotcha**: traps, edge cases, or unexpected behaviors
- **pattern**: reusable approaches or architectural patterns
- **trade-off**: pros/cons of decisions made

IMPORTANT: Do NOT include the observation type (bugfix/feature/etc) as a concept. Types and concepts are separate dimensions.

2.2 Memory Deduplicator Skill

Create plugin/skills/memory-deduplicator/SKILL.md:

---
name: Memory Deduplication Check
description: Search existing memory before creating new observations to prevent redundant storage. Use before saving tool observations that might duplicate existing knowledge.
---

# Memory Deduplication Check

## When to Use This Skill
- Before creating any new observation
- When tool execution patterns seem familiar
- When investigating previously explored areas

## Deduplication Process

### Step 1: Extract Investigation Intent
Identify what question the tool execution is trying to answer:
- What problem is being solved?
- What system behavior is being explored?
- What configuration is being changed?

### Step 2: Search Existing Memory
Use your MCP search tools strategically:
- `search_observations` for similar investigation patterns
- `find_by_concept` for related technical concepts  
- `find_by_file` when tool execution involves specific files
- `find_by_type` for similar types of work

### Step 3: Compare and Decide
**Create new observation if:**
- Genuinely new information discovered
- Different context, parameters, or approach used
- New outcome or solution found
- Builds meaningfully on existing knowledge

**Reference existing observation if:**
- Same question already answered with same result
- Similar tool usage pattern already documented
- Concept already well-covered in recent observations

## Search Strategy Examples
Reference search-strategies.md for detailed examples of effective search patterns.

2.3 Summary Intelligence Skill

Create plugin/skills/summary-intelligence/SKILL.md:

---
name: Session Summary Intelligence  
description: Generate intelligent summaries of development sessions, focusing on deliverables and shipped capabilities. Use when completing sessions to create meaningful memory.
---

# Session Summary Intelligence

## When to Use This Skill
- At the end of Claude Code sessions (Stop hook)
- When user requests session summary
- Before session cleanup to capture learnings

## Summary Criteria

### Create Summary ONLY If:
- Code was shipped to users/production
- System capabilities actually changed
- Real problems were solved or features built
- Configuration was deployed
- Meaningful documentation was created

### Skip Summary If:
- Conversational banter or casual chat
- Meta-discussions about the memory system itself
- Trivial questions or simple status checks
- Work already covered in previous session summary
- No meaningful deliverables or changes

## Focus on Deliverables
Describe what was DELIVERED to the project, NOT what was observed:

✅ **Good Examples:**
- "Authentication now supports OAuth2 with PKCE flow"
- "Deployment pipeline runs canary releases with auto-rollback"  
- "Database indexes optimized for common query patterns"

❌ **Bad Examples:**
- "Analyzed authentication implementation and stored findings"
- "Tracked deployment steps and logged outcomes"
- "Monitored database performance and recorded metrics"

## Summary Structure
Use the XML format defined in summary-templates.xml with required fields:
- request, investigated, learned, completed, next_steps
- Optional: notes for additional insights

2.4 Memory Orchestrator Skill

Create plugin/skills/memory-orchestrator/SKILL.md:

---
name: Memory Pipeline Orchestration
description: Orchestrate the complete memory pipeline from tool observation through final summary. Use when managing complex development sessions with multiple phases.
---

# Memory Pipeline Orchestration

## When to Use This Skill
- Managing long development sessions
- Coordinating between other memory skills
- Handling context window pressure during memory processing

## Pipeline Stages

### Stage 1: Tool Observation Processing
1. Use Development Observation Classification skill to evaluate tool executions
2. Apply Memory Deduplication Check before storage
3. Create structured observations only for meaningful activities

### Stage 2: Context Management
- Monitor context window usage during session
- Trigger memory compaction when context gets tight
- Maintain pipeline state across context resets

### Stage 3: Session Completion
1. Use Session Summary Intelligence skill for final summary
2. Ensure all observations are properly linked
3. Clean up temporary session state

## Coordination Logic
This skill coordinates the other memory skills to ensure:
- No redundant observations are created
- Context window is used efficiently
- Summary captures real deliverables
- Memory remains searchable and useful

Phase 3: Refactor Hook Logic

3.1 Simplify PostToolUse Hook

Modify your src/hooks/save.ts to leverage Skills:

// Before: Complex embedded logic
export async function handlePostToolUse(hookInput: any): Promise<void> {
  // Remove the complex buildInitPrompt logic
  // Let Skills handle classification decisions
  
  const toolData = extractToolData(hookInput);
  
  // Simple decision delegation to Skills
  const shouldProcess = await claudeDecision(`
    Should this tool execution be recorded as a memory observation?
    Use your Development Observation Classification and Memory Deduplication Check skills.
    
    Tool: ${toolData.tool_name}
    Input: ${JSON.stringify(toolData.tool_input, null, 2)}
    Output: ${JSON.stringify(toolData.tool_output, null, 2)}
  `);
  
  if (shouldProcess) {
    await sendToWorkerService(toolData);
  }
}

async function claudeDecision(prompt: string): Promise<boolean> {
  // Use your existing Claude Agent SDK integration
  // Skills will be automatically triggered based on the prompt content
  const response = await sdkAgent.query(prompt);
  return response.includes('YES') || response.includes('should record');
}

3.2 Streamline Summary Hook

Modify your src/hooks/summary.ts:

export async function handleStop(hookInput: any): Promise<void> {
  const sessionData = await getSessionData(hookInput.session_id);
  
  // Let Skills handle complex summary logic
  const summary = await generateIntelligentSummary(`
    Generate a session summary using your Session Summary Intelligence skill.
    
    Original user request: ${sessionData.user_prompt}
    Session duration: ${calculateDuration(sessionData)}
    
    Review the observations from this session and create a summary of what was delivered.
  `);
  
  if (summary && !summary.includes('<skip_summary')) {
    await storeSummary(sessionData.sdk_session_id, summary);
  }
}

Phase 4: Context Window Optimization

4.1 Remove Embedded Prompts

Skills eliminate the need for your complex buildInitPrompt, buildSummaryPrompt functions. The logic moves into Skills that load progressively[(1)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills):

// Before: Large embedded prompts
export function buildInitPrompt(project: string, sessionId: string, userPrompt: string): string {
  return `You are observing a development session to create searchable memory FOR FUTURE SESSIONS.
  
  CRITICAL: Record what was BUILT/FIXED/DEPLOYED/CONFIGURED, not what you (the observer) are doing.
  
  [... 200+ lines of detailed instructions ...]`;
}

// After: Skill-delegated decisions
export function buildInitPrompt(project: string, sessionId: string, userPrompt: string): string {
  return `Process development tool executions for memory storage.
  Use your memory skills to classify, deduplicate, and store observations.
  
  User's Goal: ${userPrompt}
  Date: ${new Date().toISOString().split('T')[0]}`;
}

4.2 Progressive Context Loading

Skills use progressive disclosure[(1)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - only metadata stays loaded until triggered:

• Always loaded: ~400 tokens (4 skill names + descriptions)
• Loaded when triggered: ~2-5K tokens per skill
• Supporting files: Load as needed

This maintains instruction integrity even in long sessions.

Phase 5: Testing and Validation

5.1 Test Skill Integration

Create test scripts to validate Skills work correctly:

# Test that Skills are discovered
/plugin install claude-mem
claude  # Start session
# Ask: "What skills do you have available for memory management?"

# Test classification skill
# Perform some tool operations, verify proper classification

# Test deduplication skill  
# Repeat similar operations, verify no duplicates created

# Test summary skill
# Complete session, verify intelligent summary generation

5.2 Context Window Testing

Test behavior under context pressure:

# Create long session with many tool operations
# Verify Skills maintain consistent behavior
# Check that complex logic doesn't degrade

Phase 6: Migration Strategy

6.1 Backward Compatibility

Maintain compatibility during transition:

// Feature flag for Skills vs legacy prompts
const USE_SKILLS = process.env.CLAUDE_MEM_USE_SKILLS === 'true';

if (USE_SKILLS) {
  // Use Skills-based approach
  await processWithSkills(toolData);
} else {
  // Use legacy embedded prompts
  await processWithEmbeddedPrompts(toolData);
}

6.2 Gradual Rollout

1. Phase 6.1: Release Skills alongside existing logic
2. Phase 6.2: Default to Skills, keep legacy as fallback
3. Phase 6.3: Remove legacy prompting logic entirely

Phase 7: Documentation and Release

7.1 Update README

Document the Skills enhancement:

## v5.0.0 - Skills Integration

**NEW**: Agent Skills for intelligent memory processing
- Context-efficient observation classification
- Automatic deduplication checking
- Intelligent session summarization
- Orchestrated memory pipeline

Skills maintain instruction integrity even in long sessions, solving context window degradation issues.

7.2 Version Bump

Update to v5.0.0 in package.json and plugin.json to reflect the major Skills integration.

This implementation will make your memory system much more context-efficient and reliable, with complex logic maintained in Skills rather than competing for context window space with actual development work.