# 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

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

Or manually:

```bash
# 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