Guide · Agent skill
How to use the How claude-mem Works agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains the how-it-works skill, a plain-language explainer for claude-mem, a memory add-on for Claude Code. Agent skills are folders of instructions that Claude can load when a task matches them. After reading this page you will know how to install the skill, how to ask for it, and what it tells you about what claude-mem records, when it injects memory, and where data is kept.
How claude-mem Worksthedotmack/claude-mem · Apache-2.0 Download the skill Quick start
- 1Install claude-mem. Install the claude-mem plugin first, since the skill only describes it and does not run it.
- 2Download the skill ZIP. Get the how-it-works ZIP from this page.
- 3Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project.
- 4Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 5Ask a natural question. Type something like "how does claude-mem work?" to trigger the skill.
- 6Review the data notes. Check where data is stored and which provider receives compression calls.
What does the how-it-works skill make the agent do?
The skill lets the agent explain claude-mem's behaviour in plain language. According to the skill text, every Read, Edit and Bash action Claude takes is turned into a compressed observation. Observations are summarized at the end of a session, and relevant ones are injected into future prompts so the next session starts with context from the previous one.
The skill also covers where that data lives, which is the part most people ask about first.
- Observations: compressed records of Claude's Read, Edit and Bash actions.
- Session summaries: observations summarized at session end.
- Memory injection: relevant past context added to future prompts.
- Data location: everything stays in ~/.claude-mem on your machine, apart from calls to your chosen AI provider for compression.
Install the skill from the ZIP or the Claude apps
You can install the skill in one of three ways, depending on where you want it to be available. The page you downloaded from provides a ZIP archive of the skill.
For a personal install across all projects, unzip the archive into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. If you use the Claude apps, you can upload the skill under Settings → Capabilities → Skills instead.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload
Check that the skill's files are in place
The skill folder contains two files: SKILL.md, which holds the instructions and the description Claude uses to decide when to load the skill, and onboarding-explainer.md, a longer walkthrough of the same material. Make sure both are present after unzipping so the skill is complete.
- SKILL.md
- onboarding-explainer.md
Trigger the skill with natural requests
You do not need a special command. The skill's description says it applies when you ask questions such as "how does claude-mem work?" or "what is this thing doing?". Asking in your own words usually works, and you can ask follow-up questions about storage or injection in the same conversation.
The skill is most useful right after you have installed claude-mem, when you want to know what it has been recording.
- How does claude-mem work?
- What is this thing doing?
- When does claude-mem start injecting memory?
- Where is my claude-mem data stored?
What you need before using it
The skill describes claude-mem; it does not run claude-mem itself. You need the claude-mem plugin installed. According to the skill text, compression requires an API key from an AI provider: Claude, OpenRouter or Gemini.
The skill does not run scripts, but it relies on network access to explain the data flows described below.
- The claude-mem plugin installed
- An API key for Claude, OpenRouter or Gemini, used for compression
- No scripts are run by the skill itself
Understand the safety and data notes
The skill's source says everything stays in ~/.claude-mem on your machine. The SQLite database, vector index, logs and settings are kept under that directory and are removed on npx claude-mem uninstall.
Data does leave your machine in two cases: calls to the AI provider you configured for compression, and a one-time contact with cmem.ai at signup to create the sign-in link. The source says nothing else is sent to cmem.ai. The skill summarizes the documented design and does not verify it against the code, so if you need a guaranteed audit of data flows, you need a separate review.
- Local data: ~/.claude-mem
- Outbound: your compression provider (Claude, OpenRouter or Gemini)
- One-time contact with cmem.ai at signup
- Uninstall: npx claude-mem uninstall
npx claude-mem uninstallWhat people use it for
- Explaining to a teammate what claude-mem records during a coding session.
- Checking whether claude-mem's data handling fits your team's privacy requirements.
- Learning when memory injection starts on a project you use repeatedly.
- Finding where claude-mem keeps its database, logs and settings on your machine.
Frequently asked questions
Is the how-it-works skill free?
The source for this skill is licensed under Apache-2.0. The source does not state a price for the skill, and it does not cover the cost of any AI provider API key you need for compression.
What do I need to use this skill?
You need the claude-mem plugin installed and an API key for Claude, OpenRouter or Gemini, which the skill text says is used for compression. The skill itself does not run any scripts.
Where does claude-mem store my data?
According to the skill, everything stays in ~/.claude-mem on your machine, including the SQLite database, vector index, logs and settings. Removing it is handled by npx claude-mem uninstall.
When does memory injection start?
The skill says memory injection starts on your second session in a project. The first session in a fresh project seeds memory.
Does claude-mem send my code to the internet?
The skill says nothing leaves your machine except calls to the AI provider you configured for compression. Local installs also contact cmem.ai once at signup to create the sign-in link.
Does this skill verify claude-mem's behaviour?
No. The skill summarizes the documented design and does not verify it against the code. If you need a guaranteed audit of data flows, use a separate review.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers who have just installed claude-mem and want a plain-language account of what it records, plus teams checking its data handling against their privacy needs. It is not a general memory tool for anything outside Claude Code, and it does not change claude-mem's behaviour or provide an audit, so choose another option if you need either.
Download the skill