How to Use Claude-mem for Memory Persistence in Claude Code

What if your AI assistant remembered every architectural decision, bug fix, and refactoring session across weeks of development? Claude-mem eliminates the friction of lost context by automatically capturing tool usage observations, compressing them into semantic summaries, and injecting relevant history into every new Claude Code session.

Every Claude Code session starts as a blank slate. When you close your terminal or disconnect from a session, Claude forgets everything; your project structure, recent refactoring decisions, debugging discoveries, and architectural patterns. This forces you to repeatedly explain your codebase, burning tokens on redundant context and breaking workflow continuity.

Developers currently work around this by manually maintaining CLAUDE.md files, jotting notes in separate documents, or re-explaining project context at the start of every session. These approaches are brittle, time-consuming, and never capture the full richness of your development history. Claude-mem solves this by automatically observing every tool invocation, compressing the output into searchable semantic memories, and intelligently retrieving relevant context when you need it.

Claude-mem operates as a persistent memory compression system that hooks into Claude Code's lifecycle. It captures tool outputs—typically 1,000 to 10,000 tokens—and compresses them into roughly 500-token semantic observations using Claude's Agent SDK. These observations are categorized by type (decision, bugfix, feature, refactor, discovery, change) and tagged with relevant concepts and file references, then stored in a local SQLite database with full-text search capabilities.

The system uses five lifecycle hooks to capture context:

This architecture enables progressive disclosure—a layered memory retrieval system that balances coverage with token efficiency. Instead of dumping your entire history into context, Claude-mem retrieves observations in layers, saving approximately 2,250 tokens per session compared to manual context management.

Install Claude-mem directly from the plugin marketplace with two commands:

/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem Enter fullscreen mode Exit fullscreen mode Restart Claude Code after installation. The plugin automatically downloads prebuilt binaries, installs dependencies including Bun and SQLite, configures hooks for session lifecycle management, and auto-starts the worker service on your first session.

For development or testing, clone and build from source on GitHub:

git clone https://github.com/thedotmack/claude-mem.git cd claude-mem npm install npm run build npm run worker:start Enter fullscreen mode Exit fullscreen mode This approach is useful if you need to modify the plugin or run beta features like Endless Mode.

After installation, verify everything is working:

cat plugin/hooks/hooks.json Enter fullscreen mode Exit fullscreen mode Verify the worker service is running: curl http://localhost:37777/api/health Enter fullscreen mode Exit fullscreen mode View recent worker logs: npm run worker:logs Enter fullscreen mode Exit fullscreen mode Test context retrieval by starting a new Claude Code session. You should see context from previous sessions automatically loaded in the initial prompt.

Claude-mem stores all data locally in ~/.claude-mem/:

Override the default data directory with an environment variable:

export CLAUDE_MEM_DATA_DIR = /custom/path Enter fullscreen mode Exit fullscreen mode Configuration Options Settings are managed in ~/.claude-mem/settings.json (auto-created on first run). Key configurations include:

When you use Claude Code with claude-mem enabled, the system captures every tool invocation automatically. Whether Claude reads a file, executes a bash command, searches with glob patterns, or edits code, claude-mem observes the input and output.

The worker service processes these observations and extracts:

This compression happens automatically without manual intervention. The raw tool output might be 5,000 tokens, but the semantic observation stored in the database is roughly 500 tokens—preserving meaning while eliminating noise.

When Claude finishes responding (triggering the Stop hook), claude-mem automatically generates a session summary containing:

These summaries are injected into future sessions alongside individual observations, providing both granular detail and high-level narrative context.

Claude-mem exposes four MCP tools that follow a token-efficient 3-layer workflow pattern. This design retrieves context progressively, minimizing token usage while maximizing relevance.

This approach achieves approximately 10x token savings by filtering before fetching full details.

# Step 1: Search for the bug search ( query = "authentication bug", type = "bugfix", limit = 10 ) # Step 2: Review index, identify relevant IDs (e.g., #123, #456) # Step 3: Fetch full details for relevant observations get_observations ( ids =[ 123, 456] ) Enter fullscreen mode Exit fullscreen mode Explore recent architectural decisions:

search ( query = "database schema", type = "decision", limit = 5 ) Enter fullscreen mode Exit fullscreen mode Find everything related to a specific file:

search ( query = "worker-service.ts", limit = 20 ) Enter fullscreen mode Exit fullscreen mode Natural Language Queries You can ask Claude naturally about your project history:

Claude automatically invokes the appropriate MCP tools to retrieve relevant context, presenting findings with claude-mem:// URI citations that reference specific observations.

Claude-mem automatically generates CLAUDE.md files in project folders, creating activity timelines that complement the global memory database.

When you work with files in a folder, claude-mem:

Each folder's CLAUDE.md contains a Recent Activity section showing observation IDs, timestamps, type indicators (bug fixes, features, discoveries), brief titles, and estimated token counts.

# Authentication Module This folder contains all authentication-related code. Follow the established patterns for new auth providers. <claude-mem-context> # Recent Activity | ID | Time | Type | Title | Tokens | |----|------|------|-------|--------| | #1234 | 4:30 PM | 🔵 | Implemented user authentication | ~250 | | #1235 | 4:45 PM | 🔴 | Fixed login redirect bug | ~180 | </claude-mem-context> ## Manual Notes - OAuth providers go in /providers/ - Session handling uses Redis Enter fullscreen mode Exit fullscreen mode Web Viewer UI and Real-Time Monitoring

Claude-mem runs a web viewer at http://localhost:37777 for real-time memory stream visualization. The interface shows:

If the worker fails to start on port 37777:

lsof -i:37777 Enter fullscreen mode Exit fullscreen mode Configure an alternative port: export CLAUDE_MEM_WORKER_PORT = 8080 Enter fullscreen mode Exit fullscreen mode Manually start the worker: bun plugin/scripts/worker-service.cjs Enter fullscreen mode Exit fullscreen mode Memory Not Being Saved If Claude doesn't remember previous sessions:

npm run worker:status Enter fullscreen mode Exit fullscreen mode Check the database file exists: ls -la ~/.claude-mem/claude-mem.db Enter fullscreen mode Exit fullscreen mode Review worker logs for errors: npm run worker:logs Enter fullscreen mode Exit fullscreen mode Empty CLAUDE.md Files If claude-mem creates empty CLAUDE.md files throughout your project, this is a known issue in v9.0.5. Current workarounds include manually deleting created directories, adding patterns to.gitignore, or waiting for the fix in a subsequent release.

Claude-mem transforms Claude Code from a stateless assistant into a persistent development partner that accumulates knowledge about your codebase over time. By automatically capturing tool usage, compressing observations into searchable memories, and intelligently retrieving relevant context, it eliminates the repetitive context-building that slows down AI-assisted development.

When building APIs or working with external services in your Claude-mem enhanced workflow, streamline your testing with Apidog. It offers visual API testing, automatic documentation generation, and collaborative debugging that complements your persistent memory setup.