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/

1. •View all summaries

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

1. •Search summaries for a keyword

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

1. •Search by tag

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

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

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

1. •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.”