• 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

• Before investigating a problem area
• When working on a feature you've touched before
• When resuming work after a conversation break

• Consolidate scattered memories on the same topic
• Remove outdated or superseded information
• Update status field when work completes, gets blocked, or is abandoned

• Use kebab-case for folder and file names
• Consolidate or reorganize as the knowledge base evolves

memories/
├── file-processing/
│   └── large-file-memory-issue.md
├── dependencies/
│   └── iconv-esm-problem.md
└── project-context/
    └── december-2025-work.md

1. Determine appropriate category for the content
2. Check if existing category fits, or create new one
3. 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

• Update: When information changes, update the content and add

  updated

  field to frontmatter
• Delete: Remove memories that are no longer relevant
  bash

  trash .claude/skills/agent-memory/memories/category-name/filename.md
  # Remove empty category folders
  rmdir .claude/skills/agent-memory/memories/category-name/ 2>/dev/null || true

• Consolidate: Merge related memories when they grow
• Reorganize: Move memories to better-fitting categories as the knowledge base evolves

1. 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.
2. Write self-contained notes: Include full context so the reader needs no prior knowledge to understand and act on the content
3. Keep summaries decisive: Reading the summary should tell you if you need the details
4. Stay current: Update or delete outdated information
5. Be practical: Save what's actually useful, not everything

• 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