Seance

Summon insights from past conversations. 🔮

Semantic search across all your Claude Code session logs.

---

✨ Features

• 🔍 Semantic Search - Find conversations by meaning, not just keywords
• ⚡ Fast Local Index - ChromaDB-powered vector store on your machine
• 🎯 Project Filtering - Scope searches to specific projects
• 📅 Date Filtering - Find conversations from specific time periods
• 🔌 JSON Output - Pipe results into other tools

📦 Installation

git clone https://github.com/pj4533/seance.git
cd seance
python -m venv .venv
source .venv/bin/activate
pip install -e .

🔑 Configuration

Seance uses OpenAI's text-embedding-3-small model for embeddings. You'll need an API key:

# Option 1: Environment variable
export OPENAI_API_KEY=your-key

# Option 2: Local .env file (recommended for standalone use)
echo "OPENAI_API_KEY=your-key" > .env

Note: The .env file is gitignored. If both are set, the environment variable takes precedence.

🚀 Quick Start

1. Index your sessions

# Full index (first time)
seance index

# Incremental updates (subsequent runs)
seance index --incremental

2. Search!

seance search "how did we implement retry logic"

📖 Usage

Search Commands

# Basic semantic search
seance search "authentication bug fix"

# Filter by project
seance search "debugging" --project my-app

# Filter by date
seance search "refactoring" --since 2025-01-01

# Get more results
seance search "API design" --results 10

# JSON output for scripting
seance search "streaming audio" --json

Index Management

# Full re-index
seance index

# Incremental (only new sessions)
seance index --incremental

# Verbose output
seance index --incremental --verbose

Utilities

# List all indexed projects
seance list

# Show index statistics
seance stats

🔧 How It Works

~/.claude/projects/     seance index      ~/.seance/
┌──────────────────┐    ──────────────►   ┌─────────────────┐
│  session.jsonl   │    embed + store     │  ChromaDB       │
│  session.jsonl   │                      │  (vectors)      │
│  session.jsonl   │                      │                 │
└──────────────────┘                      └─────────────────┘
                                                  │
                        seance search             │
                        "retry logic"             ▼
                        ◄─────────────────────────┘
                        returns file_path + message_id

Seance parses JSONL logs from ~/.claude/projects/ and creates embeddings for searchable content.

What Gets Indexed

Content	Source	Why
💬 User messages	type: "user" entries	Your questions and requests
📝 Summaries	type: "summary" entries	Session topic/domain context

What Gets Skipped

• 🤖 Assistant responses (too verbose with "let me read..." boilerplate)
• ⚙️ System messages, file snapshots, queue operations
• 🧠 Thinking blocks, tool calls

📁 Storage

Location	Contents
~/.seance/	ChromaDB vector database
~/.seance/cursor.json	Last indexed timestamp per project

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE for details.

---

Made with 🔮 for Claude Code users