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:

Identify the topic/context to remember
Generate a descriptive memory ID (e.g., issue-123, feature-auth, bug-database)
Create markdown file in memories/ directory
Include YAML frontmatter with metadata
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:

Quick scan - Search summaries first:

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

Detailed search - If needed, search full content:

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

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

Be Proactive: Suggest saving important context without being asked
Use Clear Names: Memory IDs should be descriptive (auth-oauth-impl, not temp-123)
Link Related Memories: Cross-reference related work
Update, Don't Duplicate: Add to existing memories when relevant
Progressive Detail: Summaries for scanning, details for deep reading
Action-Oriented: Include clear next steps
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.