Agent Memory

Agent Memory Skill

Enable context retention across Claude Code sessions by saving and recalling work memories.

Purpose

This skill allows Claude to:

• Remember important context, decisions, and work items
• Recall previous discussions and findings
• Maintain continuity across multiple sessions
• Reduce repetition by referencing past work

When to Use

Automatically triggered by phrases like:

• "Remember this for later"
• "Save this information"
• "Recall what we discussed about X"
• "What was our approach for Y?"
• "Retrieve memory about Z"

Memory Operations

1. Saving Memories

When the user asks to remember something, create a new memory file:

Process:

1. Identify the topic/context to remember
2. Generate a descriptive memory ID (e.g., issue-123, feature-auth, bug-database)
3. Create markdown file in memories/ directory
4. Include YAML frontmatter with metadata
5. Write detailed context in markdown body

File Format:

---
summary: "Brief one-line description"
topic: "Main topic or feature"
created: "2026-01-14"
tags: ["tag1", "tag2"]
related: ["other-memory-id"]
---

# Detailed Context

## Background
[What led to this discussion]

## Key Points
- Important point 1
- Important point 2
- Decision made

## Next Steps
- [ ] Action item 1
- [ ] Action item 2

## References
- File: `src/module.js:42`
- PR: #123
- Issue: #456

Example Memory Creation:

# Create memory file
cat > .claude/skills/agent-memory/memories/database-migration.md << 'EOF'
---
summary: "Database migration strategy for user profiles"
topic: "database"
created: "2026-01-14"
tags: ["database", "migration", "users"]
---

# Database Migration Strategy

## Context
We need to add a `preferences` column to the users table to support
dark mode and notification settings.

## Decisions Made
- Use Alembic for migrations
- Add JSONB column for flexibility
- Default value: `{}`
- Backfill existing users in separate migration

## Code Location
- Migration script: `migrations/versions/add_user_preferences.py`
- Model: `src/models/user.py:15`

## Next Steps
- [ ] Create migration script
- [ ] Test on staging database
- [ ] Deploy during maintenance window
EOF

2. Recalling Memories

When asked to recall information:

Progressive Disclosure Search:

1. Quick scan - Search summaries first:

   # Search memory summaries
   grep -r "^summary:" .claude/skills/agent-memory/memories/ | \
     grep -i "search_term"
   

2. Detailed search - If needed, search full content:

   # Full-text search across memories
   grep -r "search_term" .claude/skills/agent-memory/memories/ \
     --include="*.md"
   

3. Read relevant memories - Load matching files:

   # Read specific memory
   cat .claude/skills/agent-memory/memories/topic-name.md
   

Search Strategy:

• First, scan summaries to identify relevant memories
• Then, read only the most relevant files in detail
• Report findings in a structured format

3. Listing Memories

Show available memories:

# List all memories
find .claude/skills/agent-memory/memories/ -name "*.md" -type f

# Show summaries
for file in .claude/skills/agent-memory/memories/*.md; do
  echo "Memory: $(basename $file .md)"
  grep "^summary:" "$file" || echo "  (no summary)"
done

4. Updating Memories

When new information relates to existing memory:

# Append to existing memory
cat >> .claude/skills/agent-memory/memories/topic.md << 'EOF'

## Update: $(date +%Y-%m-%d)

New information or progress update:
- Updated point
EOF

5. Organizing Memories

Optionally organize into subdirectories:

memories/
├── features/
│   ├── auth-system.md
│   └── payment-flow.md
├── bugs/
│   ├── issue-123.md
│   └── memory-leak.md
├── decisions/
│   └── architecture-choice.md
└── investigations/
    └── performance-analysis.md

Memory Content Guidelines

What to Remember

✅ Do Save:

• Design decisions and rationale
• Investigation findings
• Approaches tried (what worked/didn't work)
• Key conversation insights
• Important file locations
• Configuration details
• Action items and next steps
• Links to related issues/PRs

❌ Don't Save:

• Entire code files (reference them instead)
• Trivial information
• Easily searchable facts
• Sensitive credentials (never!)
• Temporary debugging notes

Writing Good Memories

Be Specific:

# Good
summary: "JWT token expiration issue - increased from 1h to 24h based on user feedback"

# Too Vague
summary: "Changed some settings"

Include Context:

# Good
## Background
Users complained about frequent re-logins. Analytics showed
average session length is 6 hours. Increased token TTL to 24h
with sliding window refresh.

# Incomplete
## Background
Increased token expiration.

Reference Code Locations:

# Good
- Implementation: `src/auth/jwt.js:45-67`
- Config: `config/auth.json`
- Tests: `tests/auth.test.js:120`

# Less Useful
- Changed auth code

Usage Examples

Example 1: Saving Investigation Results

User: "Remember our findings about the performance issue"

Claude Response:

I'll save our investigation findings about the performance issue.

[Creates memory file: performance-investigation.md]

Saved memory: "Performance bottleneck in database queries - added indexes"
Location: .claude/skills/agent-memory/memories/performance-investigation.md

Key points saved:
- Identified N+1 query problem in user dashboard
- Added composite index on (user_id, created_at)
- Reduced query time from 2.5s to 80ms
- Next: Monitor production metrics

Example 2: Recalling Previous Work

User: "What did we decide about the authentication approach?"

Claude Response:

Let me search our memories about authentication...

[Searches summaries, finds auth-strategy.md]

Found memory from 2026-01-10:

Summary: "OAuth 2.0 with PKCE for authentication"

Key decisions:
- Use OAuth 2.0 with PKCE flow (more secure than implicit)
- Support Google and GitHub providers initially
- Store tokens in httpOnly cookies
- Session duration: 7 days with refresh

Implementation status:
- ✅ OAuth integration complete
- ✅ Google provider working
- 🔄 GitHub provider in progress
- ⏳ Token refresh mechanism pending

Would you like me to continue work on the GitHub provider?

Example 3: Creating Feature Memory

User: "Save our plan for the notification system"

Claude Response:

I'll create a memory for the notification system plan.

[Creates: notification-system.md]

Memory created: "notification-system"

Saved details:
- Architecture: Event-driven with message queue
- Tech stack: Redis pub/sub + WebSockets
- Notification types: Email, push, in-app
- Priority levels: urgent, normal, low
- User preferences: per-channel opt-in/out

Next steps saved:
- [ ] Set up Redis pub/sub
- [ ] Implement WebSocket server
- [ ] Create notification preferences UI
- [ ] Email template system
- [ ] Push notification service (FCM)

This memory is available for future sessions.

Memory Management

Periodic Cleanup

Suggest cleanup when memories accumulate:

# List old memories (>90 days)
find .claude/skills/agent-memory/memories/ -name "*.md" -mtime +90

# Archive completed work
mkdir -p .claude/skills/agent-memory/archive/
mv memories/completed-*.md archive/

Memory Hygiene

• Review and update memories when context changes
• Archive completed work
• Consolidate related memories
• Remove obsolete information

Best Practices

1. Be Proactive: Suggest saving important context without being asked
2. Use Clear Names: Memory IDs should be descriptive (auth-oauth-impl, not temp-123)
3. Link Related Memories: Cross-reference related work
4. Update, Don't Duplicate: Add to existing memories when relevant
5. Progressive Detail: Summaries for scanning, details for deep reading
6. Action-Oriented: Include clear next steps
7. Context-Rich: Explain "why", not just "what"

Tips for Users

• Ask Claude to "remember this" for important discussions
• Request "recall memories about X" to continue previous work
• Use "list all memories" to see what's been saved
• Say "update memory about X" to add new information

Technical Notes

• Memories are stored as markdown files (human-readable)
• .gitignore excludes memories/ (private workspace)
• Uses ripgrep for fast searching
• YAML frontmatter for structured metadata
• Works across Claude Code sessions
• Repository-scoped (each project has own memories)

Limitations

• Not suitable for very large codebases (use search instead)
• Manual memory creation (not automatic)
• Local only (not synced across machines)
• Requires user to explicitly save/recall

Integration

Works with other skills:

• code-review: Save review findings for future reference
• systematic-debugging: Remember investigation results
• testing-patterns: Store testing decisions and approaches

Remember: This skill helps maintain continuity and reduces context-switching overhead. Use it liberally to preserve valuable discussions and decisions.