Guide · Agent skill
How to use the mem-search agent skill for past session memory
Updated · written with AI from the project's own documentation and checked against our catalogue data
The mem-search skill lets an AI coding agent look back at a persistent memory database that claude-mem keeps across past coding sessions. It is for developers who already use claude-mem and want the agent to recall earlier fixes and decisions instead of guessing. By the end of this guide you will know what the skill does, how to install it, how to phrase requests so it triggers, and what it needs to work.
Past Session Memory Searchthedotmack/claude-mem · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Get the mem-search ZIP from this page and unzip it so you have the SKILL.md file.
- 2Place the skill folder. Move it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project.
- 3Or upload it in the apps. In the Claude apps, open Settings → Capabilities → Skills and upload the ZIP.
- 4Confirm claude-mem is connected. Make sure claude-mem's local worker or your server or CMEM Pro connection is running so the search and timeline tools exist.
- 5Ask about a past session. Phrase a request like "did we already solve this?" so the agent triggers the skill.
- 6Check the results. Review the summaries the agent returns and ask for raw tool output only if a summary is missing detail.
What an agent skill is and what mem-search makes the agent do
An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to perform a task. This skill is named mem-search. Its description says it searches claude-mem's persistent cross-session memory database in three steps: search, timeline, then selected get_observations.
Use it when you ask about previous sessions rather than the current conversation, for example whether a bug was already fixed or how a problem was handled last time. The skill is meant for past work only.
Install the mem-search skill
Download the ZIP for this skill from our page and unzip it. The skill ships as a single file, SKILL.md. You can install it in one of two ways.
For a personal install, unzip the folder into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder instead. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Make sure the requirements are in place
The skill does not store memory itself. It queries the claude-mem database, so claude-mem must be installed with its local worker, or you must have a configured server or CMEM Pro connection that provides the search, timeline and get_observations tools. Tool names and parameters can differ by runtime, and the skill follows whatever the active connection advertises.
The skill uses the network, but it does not run scripts.
- claude-mem installed with its local worker, or a configured server or CMEM Pro connection
- Tools available: search, timeline, get_observations, and optionally get_tool_uses
- Runs scripts: no. Uses network: yes.
Trigger the skill with natural requests
You do not need special syntax. Ask in plain language about earlier work. The description lists the kinds of requests that match, such as "did we already solve this?", "how did we do X last time?", or a request for work from previous sessions.
Name the topic and, if useful, the time frame. Asking about the current conversation will not match this skill.
- Did we already fix the token expiry bug?
- How did we solve the migration problem last time?
- What happened last week with the login code?
- Find the decision we made about caching in a previous session.
Understand the three-step search workflow
The skill works in layers so the agent loads full records only when needed. First it runs search, which returns a short table of IDs, timestamps, types and titles. Second it runs timeline around promising IDs to see nearby context. Third it runs get_observations on only the IDs that matter.
Search results are short index rows. Full observations are much larger, so filtering first keeps token use down. The skill's own guidance is to filter before fetching.
- Step 1, search: get an index with IDs. Parameters include query, limit (default 20, max 100), project, obs_type and date filters.
- Step 2, timeline: see items around an anchor ID or a query match.
- Step 3, get_observations: fetch full details for the selected IDs in one batch.
search(query="authentication", limit=20, project="my-project")
timeline(anchor=11131, depth_before=3, depth_after=3, project="my-project")
get_observations(ids=[11131, 10942])Use the optional raw tool output layer only when needed
Observations are summaries. If you need the exact output of a command or the exact diff from a past session, the skill can call get_tool_uses. The skill says not to start here. Use it only after the earlier steps point to specific tool calls. Stored payloads over 64 KB were truncated on write.
get_tool_uses(ids=["toolu_01ABC..."], project="my-project")What people use it for
- Checking whether a bug like a token expiry issue was already fixed before writing new code.
- Recovering the reasoning behind an earlier architecture decision.
- Finding what changed in the project during last week's sessions.
- Reviewing how a team handled a failed migration in a previous session.
- Batch-loading a handful of related past observations to compare them.
Frequently asked questions
Is the mem-search skill free?
The skill is licensed under Apache-2.0, as listed on this page. This page does not state prices for claude-mem or CMEM Pro, so check those products directly.
What do I need before mem-search works?
You need claude-mem installed with its local worker, or a configured server or CMEM Pro connection that provides search, timeline and get_observations tools. Without a memory database or those tools, the skill has nothing to query.
Where do I install the skill?
Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
Why won't it answer questions about my current chat?
The skill is designed only for previous sessions. Questions about the current conversation are outside its scope.
Does the skill run scripts on my computer?
No. The skill runs no scripts, but it does use the network to reach the claude-mem tools.
What is the difference between Smart search and dumb_search?
Smart search is the default three-step workflow and reasons about results. dumb_search is a faster one-call lookup that does not reason about results and can be crowded out by matching words from unrelated projects, so use it only for quick direct lookups.
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
Use mem-search if you already run claude-mem and want your agent to recall earlier fixes and decisions with less token use. Skip it if you have no claude-mem memory database or MCP tools, need authoritative records, or only care about the current conversation, since observations are summaries and raw tool output may contain sensitive data.
Download the skill