Skip to main content

​
Getting Started with Claude-Mem

​
Automatic Operation

Claude-Mem works automatically once installed. No manual intervention required!

​
The Full Cycle

  1. Start Claude Code - Context from last 10 sessions appears automatically
  2. Work normally - Every tool execution is captured
  3. Claude finishes responding - Stop hook automatically generates and saves a summary
  4. Next session - Previous work appears in context

​
What Gets Captured

Every time Claude uses a tool, claude-mem captures it:
  • Read - File reads and content access
  • Write - New file creation
  • Edit - File modifications
  • Bash - Command executions
  • Glob - File pattern searches
  • Grep - Content searches
  • And all other Claude Code tools

​
What Gets Processed

The worker service processes tool observations and extracts:
  • Title - Brief description of what happened
  • Subtitle - Additional context
  • Narrative - Detailed explanation
  • Facts - Key learnings as bullet points
  • Concepts - Relevant tags and categories
  • Type - Classification (decision, bugfix, feature, etc.)
  • Files - Which files were read or modified

​
Session Summaries

When Claude finishes responding (triggering the Stop hook), a summary is automatically generated with:
  • Request - What you asked for
  • Investigated - What Claude explored
  • Learned - Key discoveries and insights
  • Completed - What was accomplished
  • Next Steps - What to do next

​
Context Injection

When you start a new Claude Code session, the SessionStart hook:
  1. Queries the database for recent observations in your project (default: 50)
  2. Retrieves recent session summaries for context
  3. Displays observations in a chronological timeline with session markers
  4. Shows full summary details (Investigated, Learned, Completed, Next Steps) only if the summary was generated after the last observation
  5. Injects formatted context into Claude’s initial context
Summary Display Logic: The most recent summary’s full details appear at the end of the context display only when the summary was generated after the most recent observation. This ensures you see summary details when they represent the latest state of your project, but not when new observations have been captured since the last summary. For example:
  • ✅ Shows summary: Last observation at 2:00 PM, summary generated at 2:05 PM → Summary details appear
  • ❌ Hides summary: Summary generated at 2:00 PM, new observation at 2:05 PM → Summary details hidden (outdated)
This prevents showing stale summaries when new work has been captured but not yet summarized. This means Claude “remembers” what happened in previous sessions!

​
Manual Commands (Optional)

​
Worker Management

v4.0+ auto-starts the worker on first session. Manual commands below are optional. 
# Start worker service (optional - auto-starts automatically)
npm run worker:start

# Stop worker service
npm run worker:stop

# Restart worker service
npm run worker:restart

# View worker logs
npm run worker:logs

# Check worker status
npm run worker:status

​
Testing

# Run all tests
npm test

# Test context injection
npm run test:context

# Verbose context test
npm run test:context:verbose

​
Development

# Build hooks and worker
npm run build

# Build only hooks
npm run build:hooks

# Publish to NPM (maintainers only)
npm run publish:npm

​
Viewing Stored Context

Context is stored in SQLite database at ~/.claude-mem/claude-mem.db. Query the database directly: 
# Open database
sqlite3 ~/.claude-mem/claude-mem.db

# View recent sessions
SELECT session_id, project, created_at, status
FROM sdk_sessions
ORDER BY created_at DESC
LIMIT 10;

# View session summaries
SELECT session_id, request, completed, learned
FROM session_summaries
ORDER BY created_at DESC
LIMIT 5;

# View observations for a session
SELECT tool_name, created_at
FROM observations
WHERE session_id = 'YOUR_SESSION_ID';

​
Understanding Progressive Disclosure

Context injection uses progressive disclosure for efficient token usage:

​
Layer 1: Index Display (Session Start)

  • Shows observation titles with token cost estimates
  • Displays session markers in chronological timeline
  • Groups observations by file for visual clarity
  • Shows full summary details only if generated after last observation
  • Token cost: ~50-200 tokens for index view
  • Ask naturally: “What bugs did we fix?” or “How did we implement X?”
  • Claude auto-invokes search skill to fetch full details
  • Search by concept, file, type, or keyword
  • Timeline context around specific observations
  • Token cost: ~100-500 tokens per observation fetched
  • Skill uses HTTP API (v5.4.0+) for efficient retrieval

​
Layer 3: Perfect Recall (Code Access)

  • Read source files directly when needed
  • Access original transcripts and raw data
  • Full context available on-demand
This ensures efficient token usage while maintaining access to complete history when needed.

​
Multi-Prompt Sessions & /clear Behavior

Claude-Mem supports sessions that span multiple user prompts:
  • prompt_counter: Tracks total prompts in a session
  • prompt_number: Identifies specific prompt within session
  • Session continuity: Observations and summaries link across prompts

​
Important Note About /clear

When you use /clear, the session doesn’t end - it continues with a new prompt number. This means:
  • ✅ Context is re-injected from recent sessions (SessionStart hook fires with source: "clear")
  • ✅ Observations are still being captured and added to the current session
  • ✅ A summary will be generated when Claude finishes responding (Stop hook fires)
The /clear command clears the conversation context visible to Claude AND re-injects fresh context from recent sessions, while the underlying session continues tracking observations.

​
Searching Your History (v5.4.0+)

Claude-Mem now uses skill-based search for querying your project history. Simply ask naturally: 
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
Claude automatically recognizes your intent and invokes the search skill, which uses HTTP API endpoints to query your memory efficiently. Token Savings: ~2,250 tokens per session start vs previous MCP approach

​
Next Steps