---

💡 Why dsh-session-index?

DSH archives past conversations as compressed .jsonl.zstd event logs. Built-in search only supports exact whole-word Latin tokens, making Chinese searches return zero results, while full-pass decompression freezes the UI.

dsh-session-index transforms dead logs into an instantly queryable second brain:

• 🇨🇳 Native CJK & Latin Substring FTS: Engineered with FTS5 trigrams. The only implementation allowing Chinese substring & code fragment matching across historical turns.
• 🚀 Non-Blocking Worker Pool: Streaming decompression with multi-core workers. Keeps main-thread event loop lag strictly under p95 < 23ms.
• 🎯 Multi-Signal Relevance Ranking: Combines fzy fuzzy scoring, 21-day half-life recency decay, and workspace affinity (adapted from Atuin and McFly).
• 🔖 Deterministic Bookmarking & Jump-Back: Drop anchors at (sessionId, messageId) to quickly revisit past breakthroughs without modifying original archive files.

---

🚀 Quick Start

Installation

# In your DSH plugin environment
dev_inject_plugin @dsh-external/dsh-session-index

Typical Usage Flow

1. Search with Chinese / Substring: Run session_index_search query="重构 认证中间件" mode="full".
2. Review Relevance-Ranked Hits: Inspect Codex-style snippet previews with exact message IDs.
3. Drop a Bookmark: Save critical moments via session_index_bookmark action="add" label="JWT Auth Fix".

---

🧩 DSH Power Suite

This plugin is part of the DSH Agent Power Suite — 4 modular, zero-hard-dependency plugins forming a complete closed-loop developer workflow:

flowchart LR
    M["🧠 dsh-local-memory<br>(1. Remember rules & prefs)"] --> E["⚡ dsh-context-economy<br>(2. Save 80%+ tokens reading code)"]
    E --> A["🛡️ dsh-evidence<br>(3. Tamper-proof audit receipts)"]
    A --> S["🔍 dsh-session-index<br>(4. CJK search & bookmarks)"]
    S --> M

    style M fill:#e8f4fd,stroke:#2b7de9,stroke-width:2px
    style E fill:#eef9f2,stroke:#1e8e3e,stroke-width:2px
    style A fill:#fef7e0,stroke:#f29900,stroke-width:2px
    style S fill:#f3e8fd,stroke:#8430ce,stroke-width:2px

Plugin	Role in Suite	Synergy with Session Index
🔍 dsh-session-index	Session Search (Current)	Provides high-speed CJK search and bookmarking across compressed session archives.
🧠 dsh-local-memory	Memory Layer	Curates high-level memories. Memory curation belongs to local-memory; log search belongs here.
🛡️ dsh-evidence	Audit & Receipts	Allows searching past sessions to find past evidence bundles, audit logs, and claim anchors.
⚡ dsh-context-economy	Context Economy	Compact pointer output generates 80%+ smaller session logs, reducing search index load.

---

📖 Deep Dive & Reference

🛠️ Available Tools (5 Tools)

Tool	Description
session_index_status	Inspect / refresh indexing state (active, progress, worker health, retention).
session_index_list	List sessions by workspace with stable cursor pagination or relevance sorting.
session_index_search	Search sessions in mode=meta or mode=full (FTS/Worker) with role and time filters.
session_summary	Generate deterministic summaries (timestamps, event breakdown, tool calls, optional LLM 1-liner).
session_index_bookmark	Add/list/remove bookmarks anchored at (sessionId, messageId) for instant jump-back.

🏗️ Architecture & Non-Blocking Pipeline

session_index_status / session_index_list / session_index_search / session_summary
        │
        ▼
SessionIndexBuilder (Singleton per root + indexFile)
 ├─ Single-flight Promise deduplication
 ├─ Durable run-marker: ~/.dsh/session-index/.tmp/build.lock
 ├─ Phase A (Head Pass): Stream-decompress first 10 records ➡️ quick index
 ├─ Phase B (Full Pass): Full event counts & assistant text ➡️ WorkerPool
 └─ Atomic Commit: Unique tmpfile ➡️ fsync ➡️ validate ➡️ rename

⚖️ Technical Trade-offs & Boundaries

Advantage	Trade-off / Boundary
Unique CJK trigram search implementation	Couplings to DSH's compressed session storage format
Non-blocking worker pool (lag < 23ms)	Requires node:sqlite for FTS index
214 test cases covering crash consistency & streaming	Dual index co-exists with official session query service

🧪 Building & Testing

pnpm install --frozen-lockfile  # dependencies are pnpm-managed (peer deps: DSH 0.1.5-rc.1)
pnpm run check:dsh-contract     # Contract validation against the locked DSH runtime
pnpm run build                  # Build TypeScript to lib/
pnpm test                       # Run the test suite

DSH compatibility. The plugin targets DSH 0.1.5-rc.1 (session format v3) and reads every durable generation it has seen on disk: legacy session.jsonl.zstd (v0/v1), session.v2.jsonl.zstd and session.v3.jsonl.zstd. When a session directory holds more than one generation (DSH keeps the pre-migration file), only the highest one is indexed. v3 changed three load-bearing things the reader now models: the closed header (isSeeded + delegationDepth), system/message as the fourth surface type (folded, never indexed as text), and {op:'replace',startSeq,endSeq} replacements (v2 used start/end). The v3 fixture under test/fixtures/ is migrated from a real v0 log by DSH's own restore path, not hand-written.

🙏 Credits & Prior Art

• OpenAI Codex (commit 9ded177): Non-blocking v2 architecture, snippet previews, HEAD_RECORD_LIMIT.
• jhawthorn/fzy: fzyScore TypeScript translation (consecutive matching & bonus matrix).
• Atuin & McFly: Hit tiers × exponential time-decay scoring.
• fzf: Tie-break determinism algorithm.

---