lore is a semantic search MCP server for searching and managing your local Claude Code conversations using hybrid vector + keyword search — all without external API calls.
Search conversations (
search): Perform semantic and keyword searches across indexed Claude Code sessions, with optional filters for project, branch, and date rangeGet surrounding context (
get_context): Expand a search result by retrieving conversation content before, after, or around a given chunkIndex sessions (
index): Trigger background indexing in incremental mode (new/changed only), full mode (complete rebuild), or cancel a running index jobList sessions (
list_sessions): Browse all indexed conversation sessions, filterable by project and sortable by dateManage projects (
manage_projects): List, register, or unregister Claude Code projects for indexing, with clean removal of unregistered project dataCheck status (
status): Monitor indexing progress, session counts, database size, and overall system health
All processing runs fully locally with conversation-aware chunking (preserving tool-use chains and thinking blocks) and supports over 100 languages.
lore
Semantic search across your Claude Code conversations. Find anything you've ever discussed -- across all projects, all sessions, any branch.
Features
Hybrid search (vector + keyword) Combines multilingual-e5-small embeddings with FTS5/BM25 via Reciprocal Rank Fusion. Finds results by meaning and exact terms.
Fully local, zero API keys Everything runs on your machine. ONNX Runtime for embedding, sqlite-vec for storage. No data leaves your device.
Background indexing Index triggers return instantly. Monitor progress while you keep working. Search what's already indexed while the rest catches up.
Project-selective Register only the projects you care about. Add or remove anytime. Unregistering deletes indexed data to keep things clean. Browsing your session inventory also makes it easy to spot stale or unnecessary sessions you may want to clean up.
Conversation-aware chunking Splits by logical turns (user question + full assistant response chain), not arbitrary token windows. Handles tool-use chains, thinking blocks, and multi-step interactions correctly.
100+ languages Korean, Japanese, Chinese, English, and 90+ more. CJK-aware token estimation for accurate chunking.
Quick Start
Add to Claude Code
# No install needed — always runs latest version
claude mcp add -s user lore -- npx getlore
# Or for a single project only
claude mcp add -s project lore -- npx getloreAdd to OpenAI Codex CLI
# No install needed
codex mcp add lore -- npx getlorenpm install -g getlore
# Then register with your tool:
claude mcp add -s user lore -- getlore # Claude Code
codex mcp add lore -- getlore # Codex CLI
# Manage your install:
getlore --version # Check installed version
getlore update # Update to latestUsage
Once connected, the AI can use lore's tools directly:
You: "What did we discuss about auth refactoring last week?"
Claude: [calls lore search] Found 3 relevant conversations...
In your "my-webapp" project on March 15, you decided to...First time setup:
Browse projects -- lore shows all your Claude Code projects
Register -- pick which ones to index
Index -- runs in background, takes ~15 seconds per project
Search -- ask anything about past conversations
Tools
Tool | Purpose |
| Register/unregister projects for indexing |
| Start background indexing. Modes: |
| Check indexing progress, ETA, skip reasons, DB health |
| Semantic + keyword search across conversations |
| Expand search results with surrounding conversation |
| Browse indexed sessions by project |
fullmode requiresconfirm: trueas a safety gate — the AI doesn't know about this parameter, so it has to ask you before triggering a destructive reindex.
Why This Exists
Claude Code stores every conversation as a JSONL transcript in ~/.claude/projects/. After a few weeks, you have hundreds of sessions across dozens of projects -- discussions about architecture decisions, debugging sessions, code reviews, and design explorations.
But there's no way to search through them. You can't ask "what approach did we take for the auth middleware?" or "which project had that database migration discussion?"
Existing tools either require cloud APIs, spawn zombie processes, or treat conversations as generic documents. lore is purpose-built for Claude Code sessions: it understands turn boundaries, tool-use chains, and thinking blocks. It runs entirely locally with zero dependencies beyond Node.js.
How It Works
~/.claude/projects/*/*.jsonl
|
JSONL Parser (extracts user/assistant messages, skips noise)
|
Turn-pair Chunker (groups by logical conversation turns)
|
Transformers.js (multilingual-e5-small, INT8 quantized, 384d)
|
sqlite-vec + FTS5 (hybrid vector + keyword storage)
|
Reciprocal Rank Fusion (combines both signals for ranking)Storage: Single SQLite file at ~/.lore/lore.db with WAL mode for concurrent reads.
Config: Project registration stored in ~/.lore/config.json.
Environment Variables
Variable | Default | Description |
|
| Data directory |
|
| Database path |
|
| Claude Code transcripts location |
Measured on Apple Silicon (M-series):
Metric | Value |
Search latency | 7-15ms |
Index speed | ~10 sessions/sec |
First search (cold model load) | ~5s |
DB size | ~0.1MB per 10 sessions |
Model size (downloaded once) | ~112MB |
"No projects registered"
Run manage_projects with action list to see available projects, then add the ones you want.
Stale lock file
If indexing was interrupted, the lock file auto-cleans on next run (PID-based detection).
DB corruption
Delete ~/.lore/lore.db and re-index. Your source data (~/.claude/projects/) is never modified.
Development
git clone https://github.com/hyunjae-labs/lore.git
cd lore
npm install
npm run build
npm test # 114 testsTech Stack
Model Context Protocol SDK -- stdio transport
@huggingface/transformers -- multilingual-e5-small (INT8)
better-sqlite3 + sqlite-vec -- embedded vector DB
Reciprocal Rank Fusion -- hybrid search ranking
License
MIT