@huangjua

dsh-session-index

Name: dsh-session-index
Availability: InStock
Author: huangjua

🔍 Full-text session search & bookmarking engine for DSH with native CJK substring search

Stars: 0
Language: TypeScript
Created: Sep 1, 2026
Updated: Sep 1, 2026

Memory

GitHub repo

Introduction

🔍 dsh-session-index

Full-text session search & bookmarking engine for DSH
Native CJK Substring Search • Non-Blocking Worker Pool • Multi-Signal Ranking • Jump-Back Bookmarks

Features • Quick Start • DSH Power Suite • Tools • Architecture • 简体中文

💡 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

Search with Chinese / Substring: Run session_index_search query="重构认证中间件" mode="full".
Review Relevance-Ranked Hits: Inspect Codex-style snippet previews with exact message IDs.
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 run check:dsh-contract  # Contract validation
pnpm run build               # Build TypeScript to lib/
npm test                     # Run 214 test cases

🙏 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.

_{Part of the DSH Agent Power Suite. Licensed under BSD-3-Clause.}