Agent Memory

An agent-first persistent memory space for storing knowledge that survives across conversations. Memories are human-readable markdown files so that both the agent and humans can inspect and edit them.

Location

Store memories under:

• memories/

(If your runtime expects a specific root, keep memories/ inside the skill folder and reference it relative to the skill directory.)

When to Use

Agent-first usage

Use this skill as a default tool for the agent to record and retrieve knowledge:

• Capture important decisions, rationale, and work completed
• Preserve research findings, tricky fixes, and important commands
• Record in-progress work that should be resumable later
• Check existing memories before starting related work

Explicit user requests

Use this skill when the user asks to:

• Remember or save information
• Recall prior decisions, context, or investigation results
• Resume a workstream after a break
• Review notes, history, or “what we decided”
• Consolidate / clean up / organize memories

Proactive usage

Save memories at your own initiative when you discover something worth preserving, such as:

• Research findings that took effort to uncover
• Non-obvious patterns, sharp edges, or gotchas
• Solutions to tricky problems (including commands, files, and the “why”)
• Architectural decisions and rationale
• Important decisions and work completed
• In-progress work that may be resumed later

After completing any task or job, you must use this skill to record a brief memory of the work completed (even if no issues were found). Keep it concise and focused on resumption value.

Check memories when starting related work:

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

What to Store

Focus on resumption value:

• Decision + rationale
• Current state (done / in-progress / blocked)
• Key artifacts (files, links, commands, configs)
• Next steps and open questions

Avoid storing:

• Secrets (API keys, passwords, tokens)
• Personal data not required for the user’s goals
• Large verbatim logs unless essential (prefer summaries + pointer to where to find the log)

Folder Structure

Organize memories into category folders. There is no fixed taxonomy; create categories that match the content.

Guidelines:

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

Example:

memories/
├── project-context/
│   └── january-2026-focus.md
├── dependencies/
│   └── iconv-esm-problem.md
└── performance/
    └── large-file-worker-leak.md

Memory File Format

Every memory must start with YAML frontmatter including a concise summary field.

Required frontmatter

---
summary: "1–2 lines describing what this memory contains (decisive + searchable)"
created: 2026-01-22
---

Optional frontmatter

---
summary: "Worker thread leak during large file processing — cause and fix"
created: 2026-01-15
updated: 2026-01-20
status: in-progress   # in-progress | resolved | blocked | abandoned
tags: [performance, worker, memory-leak]
related: [src/core/file/fileProcessor.ts]
---

Body guidelines

Use markdown headings when helpful. Keep content self-contained.

Recommended sections (use what’s relevant):

• Context
• Decision / Findings
• Evidence (commands, snippets, links)
• Impact
• Next steps

Search Workflow (Summary-first)

Use a summary-first approach to find relevant memories efficiently.

1. List categories

ls memories/

2. View all summaries

rg "^summary:" memories/ --no-ignore --hidden

3. Search summaries for a keyword

rg "^summary:.*KEYWORD" memories/ --no-ignore --hidden -i

4. Search by tag

rg "^tags:.*KEYWORD" memories/ --no-ignore --hidden -i

5. Full-text search (when summary search isn’t enough)

rg "KEYWORD" memories/ --no-ignore --hidden -i

6. Read the specific memory file(s) that appear relevant.

Note: if memories/ is gitignored, use --no-ignore and --hidden.

Operations

Save a memory

1. Determine an appropriate category folder
2. Check if an existing category fits; otherwise create a new one
3. Create a new file (avoid overwriting existing files)
4. Write required frontmatter + a clear title and content

Example:

mkdir -p memories/category-name/

# Ensure the target file does not already exist
test -e memories/category-name/filename.md && echo "File exists" && exit 1

cat > memories/category-name/filename.md << 'EOF'
---
summary: "Brief description of this memory"
created: 2026-01-22
status: in-progress
tags: [tag1, tag2]
---

# Title

## Context

## Findings / Decision

## Next steps
EOF

Recall / remind

1. Search summaries for relevant terms
2. Read only the most promising files
3. Summarize back to the user (include the decision + the actionable next step)

Maintain

• Update: when information changes, update the content and add updated:
• Consolidate: merge related memories as they grow
• Delete: remove memories that are no longer relevant
• Reorganize: move memories into better categories over time

Example delete:

rm -f memories/category-name/filename.md
rmdir memories/category-name/ 2>/dev/null || true

Quality Rules

1. Write for resumption: a future reader should be able to continue without prior context
2. Keep summaries decisive: reading the summary should indicate whether the full file is worth opening
3. Prefer clarity over completeness: store what is useful, not everything
4. Keep the memory base current: update or delete stale content

Examples (User Prompts That Should Trigger This Skill)

• “Remember this: we decided to migrate to X because …”
• “Save these investigation notes for later.”
• “Remind me what we concluded about the caching bug.”
• “What did we decide about the API pagination approach?”
• “Check your notes about the deployment process.”
• “Clean up our notes and consolidate duplicates.”