How It Works
- 3.6k installs
- 89.6k repo stars
- Updated August 4, 2026
- thedotmack/claude-mem
how-it-works explains claude-mem observation capture, second-session memory injection, and local ~/.claude-mem storage for coding agents.
About
how-it-works is an agent skill that explains the claude-mem persistent memory system for Claude coding sessions. Every Read, Edit, and Bash action becomes a compressed observation that is summarized at session end, and relevant observations auto-inject into future prompts so the next session starts with prior context without re-explaining the codebase or rediscovering decisions. Memory injection begins on the second session in a project because the first session seeds memory while subsequent sessions receive auto-injected context for relevant past work. Optional front-loading is available through the learn-codebase command to ingest an entire repository in one pass taking roughly five minutes. All data stays local under the home directory claude-mem folder including SQLite database, vector index, logs, and settings, removed cleanly on npx claude-mem uninstall. The only external calls are to whichever AI provider is configured for compression such as Claude, OpenRouter, or Gemini. Developers reach for it when users ask how claude-mem works, what the tool is doing, when injection kicks in, or where memory data is stored on disk.
- Turns Read, Edit, and Bash actions into compressed session observations.
- Auto-injects relevant past observations starting on the second project session.
- First session seeds memory; learn-codebase optionally front-loads the full repo.
- All data stored locally under ~/.claude-mem including SQLite and vector index.
- Clean removal via npx claude-mem uninstall with no data leaving the machine except compression API calls.
How It Works by the numbers
- 3,617 all-time installs (skills.sh)
- +209 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #224 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Aug 5, 2026 (Skillselion catalog sync)
how-it-works capabilities & compatibility
- Capabilities
- observation capture from read edit bash · session end summarization explanation · second session injection timing · local storage and uninstall behavior
- Use cases
- memory · planning
- Runs
- Runs locally
What how-it-works says it does
Every Read, Edit, and Bash that Claude makes turns into a compressed observation.
Memory injection starts on your second session in a project.
Everything stays in ~/.claude-mem on this machine.
npx skills add https://github.com/thedotmack/claude-mem --skill how-it-worksAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 3.6k |
|---|---|
| repo stars | ★ 89.6k |
| Security audit | 3 / 3 scanners passed |
| Last updated | August 4, 2026 |
| Repository | thedotmack/claude-mem ↗ |
How does claude-mem work, when does memory injection start, and where is my session data stored?
Explain how claude-mem captures observations, when memory injection starts, and where local SQLite and vector data lives.
Who is it for?
Developers onboarding to claude-mem who need to understand capture, injection, and local storage behavior.
Skip if: Skip when the user needs advanced timeline reports or codebase mapping rather than core memory mechanics.
When should I use this skill?
User asks how claude-mem works, what it is doing, when injection kicks in, or where memory data lives.
What you get
Clear explanation of observation compression, injection timing, optional learn-codebase front-load, and local-only data retention.
- memory behavior mental model
- session injection expectations
- optional repo front-load plan
By the numbers
- Memory injection starts on the second project session
- Optional /learn-codebase front-load takes about 5 minutes
Files
How claude-mem works
What it does
Every Read, Edit, and Bash that Claude makes turns into a compressed observation. Observations get summarized at session end. Relevant ones get auto-injected into future prompts so the next session starts with context from the last one — 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 in a fresh project seeds memory; subsequent sessions receive auto-injected context for relevant past work. Run /learn-codebase if you want to front-load the entire repo into memory in a single pass (~5 minutes, optional).
Where data lives
Everything stays in ~/.claude-mem on this machine.
Nothing leaves your machine except calls to whichever AI provider you configured for compression (Claude / OpenRouter / Gemini). The SQLite database, vector index, logs, and settings all live under that directory and are removed cleanly on npx claude-mem uninstall.
How claude-mem works
What it does
Every Read, Edit, and Bash that Claude makes turns into a compressed observation. Observations get summarized at session end. Relevant ones get auto-injected into future prompts so the next session starts with context from the last one — 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 in a fresh project seeds memory; subsequent sessions receive auto-injected context for relevant past work. Run /learn-codebase if you want to front-load the entire repo into memory in a single pass (~5 minutes, optional).
Where data lives
Everything stays in ~/.claude-mem on this machine.
Nothing leaves your machine except calls to whichever AI provider you configured for compression (Claude / OpenRouter / Gemini). The SQLite database, vector index, logs, and settings all live under that directory and are removed cleanly on npx claude-mem uninstall.
Related skills
Setup Matt Pocock SkillsScaffold the per-repo configuration that Matt Pocock’s engineering agent skills rely on so they understand the issue tracker, triage labels, and domain documentation la495k196k
Lark AppsConnect Claude, Cursor or custom agents directly to Lark (Feishu) for messaging, document automation, approval workflows and enterprise data access.402k
CavemanSlash token usage by roughly 75% while keeping every technical detail intact when working with Claude Code, Cursor or similar agents.391k94.7k
Lark Skill MakerQuickly turn any Lark/Feishu OpenAPI call or multi-step workflow into a reusable agent skill with its own SKILL.md.386k16k
Running Claude Code Via Litellm CopilotRun Claude Code at a fraction of the cost by routing requests through LiteLLM to the GitHub Copilot Chat API.270k72
Codex PetGenerate a complete Codex Pet spritesheet and metadata from one reference image without needing an OpenAI key or Codex Pro.246k10How it compares
Read how-it-works to understand claude-mem observation injection before adopting a separate local memory CLI for the same project.
FAQ
When does memory injection begin?
On the second session in a project; the first session seeds memory for later auto-injection.
Where is claude-mem data stored?
Everything stays in ~/.claude-mem on the local machine including SQLite, vector index, logs, and settings.
Does claude-mem send data off the machine?
Nothing leaves except calls to the configured AI provider used for observation compression.
Is How It Works safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.