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

Source	Path	Status
Claude Code	~/.claude/projects/*/*.jsonl	Supported
Codex CLI	~/.codex/sessions/YYYY/MM/DD/*.jsonl	Supported (v0.4+)
Cursor / Gemini / OpenCode	—	Planned (#8)

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

Tool	Description
search	Hybrid semantic + keyword search across all sessions
get_context	Get a chunk with surrounding turns (±window)
get_session_chunks	Get indexed chunks for a session (not raw messages)

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

Metric	Value
Incremental index	< 30 sec
Search latency (warm)	< 500 ms
First search (cold start)	< 5 sec
RAM (search)	~150 MB
RAM (indexing)	~300 MB

Development

pip install -e ".[dev]"
pytest

License

MIT