how-it-works
π―SkillExplains how claude-mem remembers your work from one session to the next, when those saved notes start being used, and where the data is stored. Use it when you ask "how does claude-mem work?"
Installation
npx skills add thedotmack/claude-mem --skill how-it-worksRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/how-it-worksInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/how-it-works/ - All projects
~/.claude/skills/how-it-works/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βExplain how claude-mem captures observations, when memory injection kicks in, and where data lives. Use when the user asks "how does claude-mem work?" or "what is this thing doing?".
How claude-mem works
What it does
While you work, an observer (a second agent) watches what your agent reads, edits and runs, and writes short notes about what mattered. Those notes are called observations. When a session ends, the observer writes a summary. When the next session starts, your agent gets a compact index of the observations that matter for this project and fetches full details only when it needs them.
So the next session starts where the last one left off: no re-explaining the codebase, no re-discovering decisions.
When it kicks in
Memory injection starts on your second session in a project.
The first session seeds memory as you work. To front-load a whole repo in one pass instead, run /learn-codebase (~5 minutes on a typical repo, optional).
Where data lives
Your memory lives in ~/.claude-mem on this machine: the SQLite database, vector index, logs and settings. npx claude-mem uninstall removes it.
What leaves the machine:
- What the observer reads goes to the model you chose to run it: your Claude plan unless you picked another provider (Codex, OpenRouter, Gemini, or the claude-mem observer on CMEM Pro).
- During install, cmem.ai gets only your email and optional note if you share them when the installer asks (it's optional and asked once), and a numbers-only usage summary (observation counts and token totals; no prompts, paths, or project names) when setup creates a sign-in link. Nothing else goes to cmem.ai unless you sign in and turn on something that uses it (cloud sync, CMEM Pro's hosted observer, a provider that runs through your cmem.ai account) or choose to upload your prompts during browser setup.
- Anonymous usage analytics (telemetry) are on by default. Turn them off with
npx claude-mem telemetry disable, or setDO_NOT_TRACK=1.
More from this repository10
Claude-Mem gives Claude Code a memory that stays after a session ends. It keeps that memory in a compressed, shorter form.
claude-mem gives Claude Code a memory that lasts between sessions. It records what Claude does while you work, saves short summaries, and shows that context automatically when you start a new session.
Searches your saved Claude-Mem memory on cmem.ai to recall what happened in earlier sessions. It answers questions like what you did last time on a project, file or decision.
Lets your AI agent explore a codebase by looking at its outline first, such as function and class names, instead of reading whole files. This saves the agent's reading budget. It uses three companion tools to search code, show a file's structure, and open only the part you need.
Helps your AI agent write a step-by-step plan before building a feature. It first checks the real documentation for what is available, then splits the work into phases. Each phase has a clear goal, examples to copy, checks to prove it works, and mistakes to avoid.
Carries out a step-by-step plan by handing each piece of work to separate helper agents. After each step it checks the result, reviews the code and saves the changes to git only when the checks pass.
Writes a story-style report of a project's whole development history, based on the notes that claude-mem has saved over time. It needs the claude-mem background service to be running.
Automated semantic versioning and release workflow for Claude Code plugins, bumps package.json, marketplace.json, and plugin.json in lockstep, runs the build, tags the commit, creates a GitHub release, and generates changelog entries. Enforces 'nothing left uncommitted or unpushed' by running git status at the end.
Turns the notes claude-mem keeps about your past work into focused knowledge bases you can chat with. You pick notes by project, topic, file, or date, load them into a session, then ask questions about past decisions and fixes.
Reviews a design against Dieter Rams' ten principles of good design, scoring each one with evidence. It then recommends a new design, a refinement or a redesign, and writes a ready-to-use prompt for /make-plan.