Skip to main content

​
Getting Started with Claude-Mem

​
Automatic Operation

Claude-Mem works automatically once installed. No manual intervention is required.
Every session start, tool execution, and session end is handled by Claude-Mem’s lifecycle hooks running silently in the background. You work normally with Claude Code; Claude-Mem handles the rest.

​
The Full Cycle

1

Start Claude Code

Context from your last 10 sessions appears automatically. Claude immediately knows what you were working on, what files were touched, and what was accomplished.
2

Work Normally

Every tool execution is captured — file reads, writes, edits, bash commands, searches, and all other Claude Code tools.
3

Claude Finishes Responding

The Stop hook fires automatically and generates a structured session summary covering what was requested, investigated, learned, completed, and suggested next steps.
4

Next Session

The summary and captured observations from the previous session appear in context. Claude picks up where it left off.

​
What Gets Captured

Every time Claude uses a tool, Claude-Mem captures the observation:

Read

File reads and content access — including which files were opened and what sections were examined.

Write

New file creation — what was written and where.

Edit

File modifications — what changed, in which file, at what line.

Bash

Command executions — commands run, output returned, exit codes.

Glob

File pattern searches — what patterns were searched and what matched.

Grep

Content searches — search queries, matched files, and result counts.
All other Claude Code tools are also captured automatically.

​
What Gets Extracted

The background worker service processes raw tool observations using the Claude Agent SDK and extracts structured data from each:
FieldDescription
TitleBrief description of what happened
SubtitleAdditional context for the observation
NarrativeDetailed explanation of the tool use and its significance
FactsKey learnings as bullet points
ConceptsRelevant tags and categories for search
TypeClassification: decision, bugfix, feature, exploration, etc.
FilesWhich files were read or modified

​
Session Summaries

When the Stop hook fires at the end of each Claude response, a full session summary is generated and stored:
FieldDescription
RequestWhat you asked for in this session
InvestigatedWhat Claude explored to fulfill the request
LearnedKey discoveries and insights from the session
CompletedWhat was accomplished
Next StepsSuggested follow-up actions

​
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. Checks whether the most recent summary is newer than the most recent observation
  5. Injects formatted context into Claude’s initial context window

​
Summary Display Logic

The most recent summary’s full details appear at the end of the context only when the summary was generated after the most recent observation. This prevents stale summaries from misleading Claude about the current project state:
Last observation captured at 2:00 PM, summary generated at 2:05 PM.Result: Full summary details appear — the summary represents the latest state of the project.

​
Progressive Disclosure

Context injection uses a layered approach to keep token usage efficient while still providing access to full history when needed:
1

Layer 1: Index Display (Session Start)

Shows observation titles with token cost estimates, session markers in a chronological timeline, and observations grouped by file. Shows full summary details only if the summary was generated after the last observation.Token cost: ~50–200 tokens for the index view.
2

Layer 2: On-Demand Details (MCP Tools)

Ask naturally — "What bugs did we fix?" or "How did we implement authentication?" — and Claude auto-invokes MCP search tools to fetch full observation details.Search supports concept, file, type, and keyword filters. The 3-layer workflow (search → timeline → get_observations) minimizes token usage.Token cost: ~100–500 tokens per observation fetched.
3

Layer 3: Perfect Recall (Code Access)

Read source files directly for raw data and original transcripts. Full context is always available on-demand.

​
Privacy Control

Wrap any content in <private> tags to prevent it from being stored: 
<private>
My API key is sk-...
</private>
Tag stripping happens at the hook layer (edge processing) before data reaches the worker or database. The content is never persisted.
The <private> tag prevents storage of the wrapped content only. Any content outside the tags in the same prompt or tool output is still captured normally.

​
Searching Your History

Claude-Mem provides MCP tools for querying your project history. Ask naturally in any Claude Code session: 
"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 MCP search tools, using the 3-layer workflow (search → timeline → get_observations) for efficient token usage.

​
Web Viewer UI

The background worker service hosts a real-time memory stream at http://localhost:37777. The viewer shows:
  • Live observation feed with SSE (Server-Sent Events) updates
  • Infinite scroll through your full observation history
  • Session markers and chronological timeline
  • Full observation details on click
  • Version channel management (switch between stable and beta)
Open the web viewer while Claude is working to watch observations appear in real time as tools are executed.

​
Multi-Prompt Sessions and /clear

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

​
What Happens When You Use /clear

When you use /clear, the session does not end — it continues with a new prompt number:
  • Context is re-injected from recent sessions (SessionStart hook fires with source: "clear")
  • Observations continue being captured and added to the current session
  • A summary is 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 keeps tracking observations.

​
Manual Worker Commands

The worker service auto-starts on your first session (v4.0+). These commands are optional: 
# Start worker service
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

​
Querying the Database Directly

Context is stored in a SQLite database at ~/.claude-mem/claude-mem.db. You can query it directly: 
-- 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 specific session
SELECT tool_name, created_at
FROM observations
WHERE session_id = 'YOUR_SESSION_ID';

# Open the database
sqlite3 ~/.claude-mem/claude-mem.db

​
Next Steps

MCP Search Tools

Deep dive into the 3-layer search workflow and all available search filters.

Configuration

Tune observation limits, context injection, AI model, and privacy settings.

Architecture Overview

Understand how the hooks, worker, database, and search system fit together.

Troubleshooting

Solutions for missing context, worker startup failures, and other common issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us