deja

Semantic search over your AI coding agent session history. Ask questions about past conversations by meaning, not just keywords.

deja is an MCP server that indexes JSONL sessions from supported AI coding agents and provides hybrid search (vector + full-text) directly from Claude Code.

Supported sources

How it works

~/.claude/projects/*/        deja index         index.db
     *.jsonl           ──────────────►    (SQLite + vec + FTS5)
                        embeddings
                                           │
                                           │  deja serve (MCP stdio)
                                           ▼
                                      Claude Code
                                    "search past sessions"

1. Index — parses JSONL session files, extracts conversation turns, embeds with multilingual-e5-small, stores in SQLite
2. Serve — MCP server opens the index and answers search queries via stdio transport

Search combines vector KNN (semantic similarity) and FTS5 (keyword matching) via Reciprocal Rank Fusion.

Install

pip install dejasearch

Or from source:

git clone https://github.com/CynepMyx/deja.git
cd deja
pip install -e .

First run downloads the embedding model (~117 MB).

Usage

Build the index

deja index                       # incremental, all sources
deja index --reindex             # full rebuild
deja index --source claude-code  # only Claude Code sessions
deja index --source codex        # only Codex CLI sessions

Scans every supported source by default. Filter with --source.

Add to Claude Code

Add to ~/.claude.json under mcpServers:

"deja": {
    "type": "stdio",
    "command": "/path/to/deja/.venv/Scripts/deja.exe",
    "args": ["serve"],
    "env": {
        "PYTHONUNBUFFERED": "1"
    }
}

Restart Claude Code — deja will appear as a connected MCP server.

MCP Tools

search parameters:

• query (string) — what to search for
• limit (int, default 10) — max results
• project (string, optional) — filter by project
• source (string, optional) — filter by source: claude-code, codex
• date_from / date_to (string, optional) — ISO date range

Auto-indexing (optional)

Index automatically when a Claude Code session ends. Add a Stop hook to ~/.claude/settings.json:

"hooks": {
    "Stop": [
        {
            "matcher": "",
            "hooks": [
                {
                    "type": "command",
                    "command": "/path/to/deja/.venv/bin/deja index"
                }
            ]
        }
    ]
}

On Windows with Git Bash, wrap in a shell script:

#!/bin/bash
DEJA="/path/to/deja/.venv/Scripts/deja.exe"
[ -f "$DEJA" ] && "$DEJA" index >/dev/null 2>&1 &

"command": "bash /path/to/deja-index.sh"

PID lock prevents concurrent indexers — safe with multiple sessions.

Stack

• fastembed — ONNX embeddings (intfloat/multilingual-e5-small, 384-dim)
• sqlite-vec — vector KNN search in SQLite
• SQLite FTS5 — full-text keyword search
• FastMCP — MCP server framework

Performance

Development

pip install -e ".[dev]"
pytest

License

MIT