Metadata-Version: 2.5
Name: kiro-session-index
Version: 0.3.0
Summary: Locate, outline, and build disposable TF-IDF search indexes over Kiro agent session logs (IDE directory format and CLI three-file format).
License: MIT
Keywords: agent,kiro,logs,search,session,tf-idf
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.9
Provides-Extra: semantic
Requires-Dist: model2vec>=0.4; extra == 'semantic'
Requires-Dist: numpy; extra == 'semantic'
Description-Content-Type: text/markdown

# kiro-session-index

Locate, outline, index and search [Kiro](https://kiro.dev) 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

```bash
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]
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]
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 and titles.
- `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.
- `clean` removes an index directory, refusing to delete anything it did not create.

## Semantic search (optional extra)

```bash
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](https://huggingface.co/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](https://github.com/fanjie/kiro-steering-agents); built to back a session-loader sub agent that reads big sessions in an isolated context.
