session-indexer

Product Introduction

1. Definition: Session-indexer is a local, per-project semantic search engine for Claude Code session history. It is a command-line tool written in Go that transforms raw JSONL chat transcripts into a queryable knowledge base stored in a local SQLite database.
2. Core Value Proposition: It solves the problem of developer context loss by providing instant, semantic recall of past technical decisions and discussions from AI coding sessions, directly within your project's workflow. Its core value is per-project memory isolation and zero-deployment semantic search using local embeddings.

Main Features

1. Hybrid Semantic & Keyword Search: Performs vector similarity search using bge-m3 embeddings via a local Ollama instance for meaning-based recall. It automatically falls back to a fast FTS5 BM25 full-text search if embeddings are unavailable, ensuring search always works.
2. Automatic Context Injection: Integrates directly with Claude Code via SessionStart and Stop hooks. At the start of a new coding session, it automatically injects relevant past context (based on git branch and recent commits) into the chat, bridging the gap between sessions without manual lookup.
3. Durable Facts Layer with Supersession: Beyond raw text search, it includes a manual distill command that uses an LLM (like glm-5.2:cloud) to extract structured, atomic facts (subject-predicate-object) from session chunks. This layer supports manual supersede commands and automatic confidence gating to maintain a current, accurate set of project truths over time, preventing citation of stale information.

Problems Solved

1. Pain Point: The "What did we decide?" problem. Developers returning to a project after days or weeks struggle to find specific technical decisions, rationale, or implementation details buried across dozens of past AI coding sessions, making grep-based searches ineffective.
2. Target Audience: Solo software developers, engineers, and technical leads who use Claude Code intensively for project work. It is specifically designed for individual developers managing complex, long-term codebases where session history is valuable personal context.
3. Use Cases: Essential for recalling the chosen architecture for a module, the rationale behind a specific dependency, the agreed-upon API contract, or troubleshooting steps that were previously resolved. It turns session history from a passive log into an active project memory.

Unique Advantages

1. Differentiation: Unlike centralized memory systems like MemPalace (ChromaDB) or MemMachine (Neo4j), session-indexer adopts a radically decentralized, per-project architecture. Each project's .claude/sessions.db is isolated, eliminating the single point of failure where a corrupted central database breaks memory for all projects. Recovery is trivial: delete the local DB and re-run the idempotent mine command.
2. Key Innovation: Its append-only, rebuildable storage strategy. The SQLite database is treated as a derived cache from the primary source of truth—the immutable JSONL transcript files. This design guarantees that the worst-case failure (a corrupted DB) only results in a re-indexing operation, not permanent data loss, making it exceptionally robust for personal use.

Frequently Asked Questions (FAQ)

1. How does session-indexer handle data privacy and where is my session data stored? All data processing occurs locally on your machine. Session transcripts are indexed into a SQLite database (.claude/sessions.db) within your project's directory. Embeddings are generated using your local Ollama instance, and no data is ever transmitted to external servers, ensuring complete privacy and offline operation.
2. Can session-indexer be used for team collaboration or shared project memory? No, session-indexer is explicitly scoped for single-developer, single-machine use. It indexes your individual Claude Code sessions. For team knowledge sharing, the output should be converted into conventional project documentation, commit messages, or PR descriptions, not via a shared instance of this tool.
3. What happens if the Ollama service is down or the embedding model isn't loaded? The system gracefully degrades. The mine command will store chat chunks without embeddings, and the search command will automatically switch to using the built-in SQLite FTS5 engine for keyword-based (BM25) search, ensuring you never lose query functionality.
4. Why is the .claude/sessions.db file gitignored and how do I back it up? It is gitignored to prevent team visibility conflicts and merge issues, as the DB is personal context. It is fully rebuildable from your local JSONL files using session-indexer mine. For backup, you should include it in your personal backup solution (e.g., Time Machine, restic, or a private dotfiles repo), not the project repository.
5. What is the difference between session-indexer and the companion tool session-end? session-end focuses on providing immediate continuity by answering "where did I leave off last time?" at the start of a session. session-indexer provides deep, cross-session semantic search to answer "what did we decide about X?" across the entire project history. They are complementary tools that use the same Claude Code hook system.