how-it-works

thedotmack/claude-mem

Auto-capture observations and inject past context into future Claude sessions without manual re-explanation.

What is how-it-works?

claude-mem automatically records your file reads, edits, and bash commands as compressed observations, then injects relevant context into future sessions so you start with prior work already in scope. Use this to understand how memory capture, injection timing, and data storage work.

Converts every Read, Edit, and Bash command into compressed observations
Summarizes observations at session end for efficient storage
Auto-injects relevant past context into subsequent sessions
Optionally front-loads entire repository with /learn-codebase command
Stores all data locally in ~/.claude-mem with no cloud sync except AI provider calls

How to install how-it-works

npx skills add https://github.com/thedotmack/claude-mem --skill how-it-works

Claude Code

Cursor

Windsurf

Cline

How to use how-it-works

1.Install the skill via npx skills add
2.Ask 'how does claude-mem work?' or 'what is this thing doing?' to trigger the explanation
3.Review the memory injection timeline: first session seeds memory, second session onwards receives auto-injected context
4.Optionally run /learn-codebase in your first session to pre-populate memory with the entire codebase (~5 minutes)
5.Check ~/.claude-mem on your machine to verify all data is stored locally

Use cases

Good for

Understanding how context persists across multiple coding sessions in the same project
Learning when memory injection activates (second session onwards)
Verifying where sensitive project data is stored (local machine only)
Deciding whether to use /learn-codebase for faster initial context loading
Checking privacy implications of compression API calls to your configured AI provider

Who it's for

Claude Code and Cursor users working on multi-session projects
Developers concerned about data privacy and local-first storage
Teams wanting to reduce context re-explanation overhead across sessions

how-it-works FAQ

When does memory injection start?

Memory injection begins on your second session in a project. The first session seeds the memory; subsequent sessions automatically receive relevant context from past work.

Where is my data stored?

All data lives in ~/.claude-mem on your local machine. The SQLite database, vector index, logs, and settings remain local; nothing is sent to cmem.ai except a one-time signup call for local installs.

What gets sent to external services?

Only compression calls go to your configured AI provider (Claude, OpenRouter, or Gemini). No project data is sent to cmem.ai beyond the initial signup link creation.

Can I speed up memory loading in the first session?

Yes, run /learn-codebase to front-load the entire repository into memory in a single pass (~5 minutes), though this is optional.

What happens when I uninstall?

Running npx claude-mem uninstall cleanly removes the ~/.claude-mem directory and all stored observations, database, and settings.

Full instructions (SKILL.md)

Source of truth, from thedotmack/claude-mem.

name: how-it-works description: 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

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). Local installs contact cmem.ai once, at signup, to create the sign-in link; nothing else is sent to cmem.ai. The SQLite database, vector index, logs, and settings all live under that directory and are removed cleanly on npx claude-mem uninstall.