Preface¶

DSH comes with a built-in session_search tool for finding content within session history. It is sufficient when the number of sessions is low; however, once the local session history grows large, it fails to build the index, leading to timeouts or storage unavailable errors. The more sessions there are, the more frequently this issue occurs. The plugin introduced below is specifically designed for this: separating “building the index” from “querying,” persisting the index to SQLite, and using FTS5 for queries.

What is it¶

dsh-session-find is maintained by BrainZombie under the MIT license and is a plugin for DeepSeek Harness (DSH). It builds a persistent SQLite FTS5 index locally, covering all session transcripts, supporting incremental sync and redaction. The plugin directory page (skillhub.cn) categorizes it under “Memory,” and its GitHub repository description reads: Fast local cross-session search for DeepSeek Harness: persistent SQLite FTS5 index over session transcripts, incremental sync, redaction.

Essentially, it replaces the unavailable session_search under large session histories: the index is derived data; once persisted to disk, queries no longer require full index rebuilding on every call.

Environment Requirements¶

The prerequisites listed in the README are as follows:

node:sqlite is optional: if the Node version is sufficient, an FTS5 index is created; if not, the plugin degrades to directly reading session files for scanning. Functionality remains the same, but speed is slower.

Installation and Enablement¶

The installation command comes from the original README:

dsh plugin add dsh-session-find

After installation, restart the host, and the tool will appear. The dsh.compatibility.dsh declared in the plugin code is >=0.2.0-rc.1 <0.3.0-0; before installing, you can check if your DSH version falls within this range.

The index is built upon the first call to the tool. The README provides local test data: 479 sessions, 32,015 events.

Configuration¶

The plugin mounts as a configuration block with id: session-find in the DSH configuration:

- id: session-find
  name: dsh-session-find
  config:
    indexPath: ''            # Empty = <DSH_HOME>/storages/session-find/index.db
    redact: false            # true = default redaction (can also pass redact: true per call)
    extraRedactPatterns: []  # Additional redaction regex patterns
    includeArchived: true
    maxResults: 40
    snippetChars: 240
    autoSync: true           # Incremental sync only for sessions where mtime/size changed before each call

Explanation of each:

• indexPath: When left empty, the index database is placed at <DSH_HOME>/storages/session-find/index.db.
• redact: Controls whether redaction is enabled by default. Redaction can also be triggered by passing redact: true during a single call without changing the global setting.
• extraRedactPatterns: Custom redaction regex patterns to append.
• autoSync: When enabled, incremental sync is performed only on sessions where mtime or size has changed before each call.

Three Tools¶

The plugin registers three tools:

Parameters for session_find: query (required), cwd, since / until, types (user / reply / tool), limit, perSession, redact, titleMode (search by title only), sortBy (score / time).

Typical usage involves three steps: first search, then read the original text of the selected session.

1. Use session_find to pass the query to retrieve the session id.
2. Use session_show to read the original text by id; use seqFrom / seqTo to get a range when examining a specific section in detail.
3. If the index status is incorrect or the table structure has changed, use session_index status to check, session_index sync for incremental processing, and session_index rebuild for a full rebuild.

How Indexing Works¶

Index database table structure:

• sessions: id / workspace / cwd / title / created_at / mtime / size / events
• events: FTS5 virtual table, handles full-text search
• state: Records lastSync

Incremental strategy: events for a session are only re-injected if the session file’s mtime or size changes. rebuild clears the table and starts over.

Consistency: Writes for a single session are wrapped in a BEGIN / COMMIT / ROLLBACK transaction; PRAGMA journal_mode = WAL and synchronous = NORMAL are enabled on the database.

An implementation detail worth noting: FTS5’s MATCH does not participate in joins (otherwise ambiguity arises), so sorting is handled by the rank column. Also, if upgrading the plugin version involves changing the table structure, it will automatically DROP and rebuild; old data is not migrated—as the index is a derived asset, losing it and rebuilding is acceptable.

Privacy and Security¶

The index is derived from raw text: session snippets are stored in the database file and are not redacted by default, on the grounds that “raw text is the retrieval capability.” The database file is located under <DSH_HOME>/storages/; it is not committed to the repository and is not sent externally.

Points to note:

1. When redaction is needed, set config.redact to true, or pass redact: true in a single call.
2. extraRedactPatterns is used to append your own regex to cover sensitive strings outside the default rules.
3. The plugin runs with the permissions of the current DSH process; it can read the session directory and write to the index database. It is recommended to review the source code before enabling to confirm the license (MIT) and behavior.
4. The index database is a local file and will not be automatically synced elsewhere; just be aware of its existence when moving or cleaning up disk space.

Testing and Development¶

Self-test scripts included in the repository:

npm test            # node test/selftest.mjs (custom fixture sessions + temp db: search/incremental/redaction/tool interface)
npm run doctor      # checklist check before release
dsh-plugin verify . # real packaging, real installation, mount check (requires machine with DSH installed)

npm test constructs its own fixture sessions (temporary DSH home + zstd transcription) and does not read your ~/.dsh, so it is green on CI and clean machines as well. verify requires a real host and runs locally only.

Package info: dsh-session-find, version 0.1.0, MIT.

Conclusion¶

dsh-session-find solves a very specific pain point: once the DSH session history grows, cross-session search becomes unavailable. It persists the index as SQLite FTS5 and performs incremental sync. The changes required are minimal, but the benefit is millisecond-level response times. If the number of sessions has already caused session_search to timeout, it is worth trying.

Directory page: https://www.skillhub.cn/plugins/BrainZombie/dsh-session-find
Source code: https://github.com/BrainZombie/dsh-session-find