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.

• List categories

ls memories/

• View all summaries

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

• Search summaries for a keyword

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

• Search by tag

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

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

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

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

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

Operations

Save a memory

• Determine an appropriate category folder

• Check if an existing category fits; otherwise create a new one

• Create a new file (avoid overwriting existing files)

• 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

• Search summaries for relevant terms

• Read only the most promising files

• 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

• Write for resumption: a future reader should be able to continue without prior context

• Keep summaries decisive: reading the summary should indicate whether the full file is worth opening

• Prefer clarity over completeness: store what is useful, not everything

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