| name | agent-memory |
| description | Use this skill when the user asks to save, remember, recall, or organize memories. Triggers on: 'remember this', 'save this', 'note this', 'what did we discuss about...', 'check your notes', 'clean up memories'. Also use proactively when discovering valuable findings worth preserving. |
Agent Memory
A persistent memory space for storing knowledge that survives across conversations.
Location: .claude/skills/agent-memory/memories/
Proactive Usage
Save memories when you discover something worth preserving:
- Research findings that took effort to uncover
- Non-obvious patterns or gotchas in the codebase
- Solutions to tricky problems
- Architectural decisions and their rationale
- In-progress work that may be resumed later
Check memories when starting related work:
- Before investigating a problem area
- When working on a feature you've touched before
- When resuming work after a conversation break
Organize memories when needed:
- Consolidate scattered memories on the same topic
- Remove outdated or superseded information
- Update status field when work completes, gets blocked, or is abandoned
Folder Structure
When possible, organize memories into category folders. No predefined structure - create categories that make sense for the content.
Guidelines:
- Use kebab-case for folder and file names
- Consolidate or reorganize as the knowledge base evolves
Example:
memories/
├── file-processing/
│ └── large-file-memory-issue.md
├── dependencies/
│ └── iconv-esm-problem.md
└── project-context/
└── december-2025-work.md
This is just an example. Structure freely based on actual content.
Frontmatter
All memories must include frontmatter with a summary field. The summary should be concise enough to determine whether to read the full content.
Summary is the decision point: Agents scan summaries via rg "^summary:" to decide which memories to read in full. Write summaries that contain enough context to make this decision - what the memory is about, the key problem or topic, and why it matters.
Required:
---
summary: "1-2 line description of what this memory contains"
created: 2025-01-15
---
Optional:
---
summary: "Worker thread memory leak during large file processing - cause and solution"
created: 2025-01-15
updated: 2025-01-20
status: in-progress
tags: [performance, worker, memory-leak]
related: [src/core/file/fileProcessor.ts]
---
Search Workflow
Use summary-first approach to efficiently find relevant memories:
ls .claude/skills/agent-memory/memories/
rg "^summary:" .claude/skills/agent-memory/memories/ --no-ignore --hidden
rg "^summary:.*keyword" .claude/skills/agent-memory/memories/ --no-ignore --hidden -i
rg "^tags:.*keyword" .claude/skills/agent-memory/memories/ --no-ignore --hidden -i
rg "keyword" .claude/skills/agent-memory/memories/ --no-ignore --hidden -i
Note: Memory files are gitignored, so use --no-ignore and --hidden flags with ripgrep.
Operations
Save
- Determine appropriate category for the content
- Check if existing category fits, or create new one
- Write file with required frontmatter (use
date +%Y-%m-%d for current date)
mkdir -p .claude/skills/agent-memory/memories/category-name/
cat > .claude/skills/agent-memory/memories/category-name/filename.md << 'EOF'
---
summary: "Brief description of this memory"
created: 2025-01-15
---
Content here...
EOF
Maintain
Guidelines
- Write for resumption: Memories exist to resume work later. Capture all key points needed to continue without losing context - decisions made, reasons why, current state, and next steps.
- Write self-contained notes: Include full context so the reader needs no prior knowledge to understand and act on the content
- Keep summaries decisive: Reading the summary should tell you if you need the details
- Stay current: Update or delete outdated information
- Be practical: Save what's actually useful, not everything
Content Reference
When writing detailed memories, consider including:
- Context: Goal, background, constraints
- State: What's done, in progress, or blocked
- Details: Key files, commands, code snippets
- Next steps: What to do next, open questions
Not all memories need all sections - use what's relevant.
