kiro-session-index

Locate, outline, index and search Kiro agent session logs. Standard library only, no network access, sessions are opened read-only.

Supports both on-disk formats under ~/.kiro/sessions/:

• directory format (Kiro IDE / Kiro CLI --agent-engine=v3): session.json + messages.jsonl + sub-executions/
• three-file format (Kiro CLI default engine): cli/<id>.json + <id>.jsonl + <id>.lock

Usage

uvx kiro-session-index locate <session-id> [--children]
uvx kiro-session-index outline <session-id> [--json]
uvx kiro-session-index list [--workspace <path>] [--since-days N] [--sort created|modified]
uvx kiro-session-index build --session <session-id> [--include-sub]
uvx kiro-session-index build --workspace <path> [--since-days N]   # all sessions of a workspace
uvx kiro-session-index build <files-or-dirs...>                    # index a codebase
uvx kiro-session-index search "query" --index <dir> [--top N] [--kind user,assistant]
uvx kiro-session-index clean --index <dir>                         # always clean up

• locate resolves an id (with or without sess_ prefix, prefix match allowed) or a path, detects the format, and prints metadata, lock liveness, and derived sessions.
• outline segments a transcript into turns with start/end line numbers, per-turn tool usage, credits, sub-agent dispatches, and compaction/tombstone markers.
• list shows storage areas, or every session of a workspace (dir-format workspacePaths plus cli-format cwd) with sizes, titles, and both timestamps. --sort created (oldest first) answers "earliest discussion" questions directly and stays correct even when bulk copies have homogenized file mtimes.
• build creates a disposable index as SQLite under .tmp/session-index/<name>/ in the current directory: a TF-IDF inverted index (ASCII words + CJK bigrams), plus dense multilingual embeddings with --semantic. --workspace indexes every session of a workspace incrementally: per-session shards skip unchanged sessions, duplicate copies across buckets are deduplicated (newest wins), and a fully fresh index returns in about a second. Measured worst case: 914 sessions / 640 MB → 72 s cold, ~0.2 s per query.
• search ranks chunks and every hit carries file:lineStart-lineEnd so the caller can read exactly the lines it needs. --mode auto uses hybrid ranking (reciprocal rank fusion of lexical + semantic) when the index has embeddings, else lexical. Identical content repeated across checkpoint-fork session copies is collapsed to one hit with a copies count; --kind user,assistant (dir format) or --kind Prompt,AssistantMessage (cli format) filters out tool-call noise.
• clean removes an index directory, refusing to delete anything it did not create.

Semantic search (optional extra)

uvx --from 'kiro-session-index[semantic]' kiro-session-index build --session <id> --semantic
uvx --from 'kiro-session-index[semantic]' kiro-session-index search "查询内容" --index <dir>

Embeddings come from minishlab/potion-multilingual-128M — a local open-source static embedding model (101 languages, 256 dims), run on CPU via model2vec + numpy; no torch, no cloud embedding API. The model downloads once (~230 MB) from Hugging Face into the local cache and is fully offline afterwards. Static embeddings make indexing fast enough for whole workspaces (thousands of chunks per second). Vectors are stored per content hash (float16 blobs in the same SQLite file), so incremental rebuilds only embed new text; scoring is exact brute-force cosine via one matrix product — no ANN needed at this scale. Cross-language recall works: a Chinese query like "硬件安全模块保管密钥" ranks English/mixed CloudHSM key-custody content at the top. Without the extra installed, the same index still serves lexical searches.

Indexes are temporary artifacts. Delete them with clean when the task is done.

Part of kiro-steering-agents; built to back a session-loader sub agent that reads big sessions in an isolated context.