I Use Custom Agent Skills to Give Claude Code a Memory

#agents #ai #llm #productivity

Sometimes I want to have an agent remember my work so I can "just forget about it for now."

When an interruption comes in during work. When I have the agent investigate something and want to let it sit for a while.

Claude Code can resume from history, but history keeps growing day by day, and going back through old sessions is tedious. I don't bother digging through history for small interrupted tasks.
If it could just remember things, I wouldn't have to search. It would be nice to save conversational context more casually.

So I've been trying out a skill I created locally called agent-memory.

What It Does

It's a simple skill.

When I stop working, I say "remember this" or "save this," and the key points get saved as a markdown file.
When I want to continue, I say "remind me about ○○," and it finds the saved content so I can pick up where I left off.

What to save is up to you. Investigation results, decisions, policies, summaries of what I was doing.
What I especially want to preserve is the intent and decisions that emerged from the conversation. As long as those are saved, it's easy to resume.

The skill's folder structure looks like this.
I leave the organization of the memories folder entirely up to the agent, and since I treat it as a private memory space, I exclude it with .gitignore.

.claude/skills/agent-memory/
├── SKILL.md          # Skill definition (read by Claude Code)
├── .gitignore        # Excludes memories/
└── memories/         # Where memories are stored
    ├── issue-123/
    │   └── investigation.md
    └── feature-x/
        └── design-decision.md

The description in SKILL.md defines what utterances trigger the skill. Phrases like "remember this," "save this," "remind me," and "check notes" become triggers.

https://github.com/yamadashy/repomix/blob/main/.claude/skills/agent-memory/SKILL.md

Memories are saved as markdown files. I also instruct it to write a summary in the frontmatter, which makes it easier for the agent to search and improves scannability.

---
summary: "Investigation results and decisions for Issue #123"
created: 2025-01-01
---

When told "remind me," Claude Code first uses rg (ripgrep) to extract just the summary lines, decides which files to read, and then reads only the necessary files.
This follows the same "judge by overview first, read details if needed" approach as Progressive Disclosure in Agent Skills.

With a small tweak, you could even create a self-improving skill.

How to Set It Up

Let me briefly explain how to set it up.

Create the folders

   mkdir -p .claude/skills/agent-memory/memories

Copy the SKILL.md from here and place it at .claude/skills/agent-memory/SKILL.md
Create .claude/skills/agent-memory/.gitignore with the following content

   memories/

Now you can use "remember this" and "remind me."

Why Agent Skills

Anthropic has released an official Memory MCP, which was another option. However, it stores memories in a shared location that's harder for humans to review, and I felt using MCP was overkill for this.

There's also the more full-featured claude-mem. If you want automatic capture or vector search, that's an option too. However, since it's a Claude Code plugin, it currently can't be used with other tools. I prioritized being able to use it across multiple tools.

What I wanted was "a memory space per repository," so storing memories as files and searching with rg is sufficient. Plus, markdown files are human-readable.

Agent Skills is an open standard that can be referenced by agent tools like Codex, Cursor, and Copilot, so it has the advantage of being tool-agnostic. Compared to MCP, it offers better portability, and I appreciate being able to achieve a highly customizable system with a simple structure.