claude-lens

MCP server that gives Claude Code searchable memory across all past sessions.

Indexes every Claude Code session JSONL file into a SQLite database with FTS5 full-text search. Claude gets tools to search conversations, find past tool calls, filter by project or date, and look up errors it's solved before.

How it works

Claude Code stores sessions as JSONL files in ~/.claude/projects/. claude-lens parses these on startup, builds an FTS5 search index, and exposes 9 tools via MCP. Claude's agent loop decides when to search its own history — no manual invocation needed.

This is active recall, not passive RAG. Claude decides what to search for, reads results, and can drill deeper with follow-up queries. Same pattern as a human using a search engine — multiple targeted queries beat one blind retrieval.

Tools

Tool	What it does
search_sessions	Full-text search across all session messages
search_tool_calls	Search past Bash commands, file edits, grep patterns
get_session	Read a full session transcript
get_session_summary	Quick metadata: project, model, tools used, files touched
filter_by_project	List sessions for a specific project
filter_by_date	Find sessions within a date range
list_projects	All projects with session counts
get_stats	Overall index statistics
search_errors	Find past tool errors and how they were resolved

Install

git clone https://github.com/jasonpaulmichaels/claude-lens.git
cd claude-lens
bash scripts/install.sh

Or manually:

# Sync repo to runtime install location
rsync -a --exclude=node_modules --exclude=.git --exclude=test \
  ./ ~/.claude/mods/claude-lens/
cd ~/.claude/mods/claude-lens && npm install --omit=dev

# Register MCP server (user scope so it's available everywhere)
claude mcp add -s user claude-lens -- node ~/.claude/mods/claude-lens/src/index.js

install.sh does this for you. Source repo stays separate from runtime install — edit source, re-run install.sh to deploy.

Restart Claude Code after installing. First startup indexes all sessions (takes a few minutes). Subsequent startups are incremental (<5 seconds).

Usage

Just use Claude Code normally. When context from past sessions would help, Claude will search automatically. You can also ask directly:

• "What was I working on last week?"
• "How did I fix the auth bug in betterclaw?"
• "Find the session where I set up the cloudflare tunnel"
• "What command did I run to rebuild the kernel module?"
• "Show me errors I hit while working on listforge"

Requirements

• Node.js 20+
• Claude Code with MCP support

Data

• Sessions indexed from: ~/.claude/projects/
• Database stored at: ~/.claude-lens/claude-lens.db
• Subagent sessions are skipped
• Tool outputs truncated to 500 chars to keep DB manageable
• Incremental indexing via file mtime tracking

License

MIT