Introduction¶

After using DeepSeek Harness for a while, when a conversation ends, wanting to find out “how the conclusion about session search last week was derived” often relies on memory alone. The native approach is to manually sift through session files under ~/.dsh and use command-line tools to fish for full text. The plugin introduced this time takes a different path: directly reusing the built-in sessionQuery service of the harness runtime, attaching three tools—search, list, and read—to the agent, allowing the model to find content in its own sessions based on memory.

dsh-session-search-pro is a DSH plugin belonging to the “Memory” category, maintained by YaoleWu, with an MIT license. Below is an introduction to its capability boundaries, installation method, and actual usage.

What is it¶

It provides three tools for the agent: agent_session_search, agent_session_list, and agent_session_read. All of these rely on the harness’s sessionQuery service at the bottom. The plugin itself does no text parsing, does not build a database, and has no runtime dependencies (no ripgrep, no zstd parsing). It reads data that is already indexed at runtime and is read-only regarding session files.

Compared to dsh-session-search in the same ecosystem, the trade-offs are different: the former reads session files directly and decompresses/scans zstd frames on its own, therefore it can cover sessions from other runtimes like Codex, Claude Code, PI, and OpenCode; this plugin only uses the harness API. The cost is that it can only search DSH’s own sessions, but the trade-off is the ability to search ongoing current sessions, without relying on file format assumptions or external binaries.

Three Tools¶

Before breaking them down, a note: the tools are registered by the plugin for the agent; actual invocation is usually initiated by the model, so you can simply ask in natural language.

agent_session_search¶

Performs full-text search across all DSH sessions, with each result carrying the highest-scoring snippet. Parameters:

• query (required, string): The text to search for. Case-insensitive, whitespace tolerant, matches literally, regular expression meta-characters have no special meaning.
• limit (number): The maximum number of sessions to return, 1–50. Defaults to the plugin configuration maxResults (10 if not overridden).
• maxScan (number): The maximum number of sessions to open when falling back to the scanning path, 1–500. Defaults to the plugin configuration maxScan (200). Ignored when using the index.

The return value includes engine: "index" | "scan", from which you can know which path produced the result this time; the scanning path also includes scanned and truncated.

agent_session_list¶

Lists sessions, including both active and ended ones, with optional filtering and sorting by working directory.

• limit (number): The maximum number of sessions to return, 1–100. Defaults to 20.
• cwd (string): Substring filter based on the session working directory.
• sort ("newest" | "oldest"): Sort method, defaults to newest.

agent_session_read¶

Reads a single session by ID: title, metadata, and events ordered by sequence.

• sessionId (required, string): The session ID to read, e.g., "a4d75296-fc89-44b1".
• maxEvents (number): The maximum number of events to return (taking the most recent ones), 1–200. Defaults to 50.

Installation and Enablement¶

This package has not yet been published to npm, so it is installed directly from GitHub and written into the package.json of the profile:

// ~/.dsh/profiles/<profile>/package.json
{
  "dependencies": {
    "dsh-session-search-pro": "github:LeslieWylie/dsh-session-search-pro"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-session-search-pro"]
    }
  }
}

Then reinstall dependencies and restart the profile:

cd ~/.dsh/profiles/<profile> && pnpm install
dsh --profile <profile>

To pin a version instead of following the default branch, you can use github:LeslieWylie/dsh-session-search-pro#v0.1.0.

Here is a mandatory note regarding the source change: the installation command above, as well as the package paths mentioned below, are written as in the original plugin README (the author in the README is LeslieWylie). Now the actual ownership of this repository is YaoleWu—GitHub redirects LeslieWylie/dsh-session-search-pro to YaoleWu/dsh-session-search-pro, and the repository field in package.json still says LeslieWylie. The package.json version is 0.2.0, and the repository currently has 5 stars and 1 fork. You can install according to the README, but if you care about not following the default branch, it is recommended to verify the package’s source and version yourself.

If you don’t want to modify the profile, you can mount it temporarily once first. This package comes with cordis.patch.yml; as long as it is already installed in the profile’s node_modules, you can mount it using the launcher’s --patch parameter:

cd ~/.dsh/profiles/<profile> && pnpm add github:LeslieWylie/dsh-session-search-pro
dsh --profile <profile> --patch ./node_modules/dsh-session-search-pro/cordis.patch.yml

The constraints on the runtime environment are written in engines: Node ^22.19.0 || >=24.0.0; peer dependencies are @deepseek-ai/cordis ^4.0.1 and @deepseek-ai/dsh-tools ^0.1.0-rc.6.

Typical Usage¶

After the plugin is bundled into the profile, the agent automatically gets these three tools. You can ask directly in natural language, for example:

“Help me search for sessions about session search”
“List my recent sessions under ~/Desktop”
“Read the session a4d75296-fc89-44b1”

The model will call agent_session_search, agent_session_list, or agent_session_read on its own.

Search Paths on the Default Profile¶

This step deserves separate mention because it is the easiest place to get tripped up. agent_session_search has two engines, selected automatically when called:

• Index: searchSessions() provided by @deepseek-ai/dsh-session-query-sqlite in the dsh-base bundle, based on SQLite FTS5. When available, the plugin uses it and returns engine: "index".
• Bounded Scan: When the index is unavailable, it falls back to scanning sessions one by one using listSessions() + filterEvents() with latest priority, returning engine: "scan".

The problem is that the index is off by default. dsh-base wires it up like this:

- id: session-query-sqlite
  name: '@deepseek-ai/dsh-session-query-sqlite'
  config:
    path: ':memory:'
    openAt: never

The engine’s own guard throws SESSION_QUERY_SEARCH_DISABLED when openAt is never. Content search is opt-in: the deployment party needs to override openAt to first-search or startup in the subsequent patch layer, and usually needs to configure a persistent path. Therefore, on the default profile, index calls will definitely fail.

This plugin only catches the “index unavailable” type of error and falls back to scanning; if the failure is that the backend is truly broken, it reports the error truthfully—using a slower scan to answer a question about a broken storage is meaningless.

The README provides a practical comparison based on local 24-session corpus: for words that match, both index and scan return 3 results; for words that don’t match, index is 17ms, scan is 3,042ms. The index is worth enabling, but it shouldn’t be the only path. The plugin in version 0.1.0 and earlier treated it as the only path, resulting in {"error": "session search is disabled…"} for any query on every default installation, without throwing an exception, making it look like a normal tool that can never find anything.

To enable the index, override that bundle line in the profile’s cordis.patch.yml:

- update:
    id: session-query-sqlite
    config:
      path: '~/.dsh/session-index.db'
      openAt: first-search

The plugin’s own configuration options are only two, written in the bundle line of cordis.patch.yml:

Suitable Scenarios and Notes¶

Suitable for scenarios where you are only running the DSH runtime and want the agent to retrieve content from its past and ongoing sessions within the current session, without needing to maintain an index file format or external command-line tools.

Points to note:

• The plugin runs with the permissions of the current dsh process and can read session data accessible in the profile. Before installing, you should check the source code under lib/ and the MIT license; do not install just because you see a bundle name.
• Only supports DSH; does not search sessions for Codex, Claude Code, PI, or OpenCode. For cross-runtime retrieval needs, choose dsh-session-search.
• Depends on sessionQuery: All three tools depend on it, with no degradation mode. If this service is not injected, the plugin will log a warning and not register any tools, rather than registering a batch of tools that error immediately upon invocation.
• The scan fallback opens sessions one by one; filterEvents() needs to read the entire session log. A single missed search will traverse the entire corpus; maxScan is used as a safety net, and truncated: true indicates hitting the limit. If the corpus is large, open the index.
• agent_session_read does not support cancellation: the underlying filterEvents() does not accept an abort signal; when a call is aborted, the read itself still runs to completion, only the result is discarded.

Pure JavaScript implementation, no build steps, source code and release use the same file lib/index.js. There are two sets of tests: tests/tools.test.mjs targets a stubbed sessionQuery driver apply(), and tests/boot.test.mjs starts a real cordis Context, loads the harness session service, loads this package via the profile method, and executes these tools through a real tool registry. The reason the second set exists is exactly the way 0.1.0 broke—unit test stubs defined their own searchSessions, all tests were green, but the SESSION_QUERY_SEARCH_DISABLED thrown by the real backend was treated as the answer for every query. Run in node_modules of the profile:

cd ~/.dsh/profiles/<profile>/node_modules/dsh-session-search-pro && node tests/boot.test.mjs

Conclusion¶

What dsh-session-search-pro does is narrow: it wraps the search capability of sessionQuery into three tools usable by the agent, allowing the model to find historical and ongoing content within its own session. Its value lies in zero runtime dependencies, read-only access to session files, and the coexistence of an index path and a scan fallback, thereby still providing results on the default profile. The community directory page is at https://www.skillhub.cn/plugins/YaoleWu/dsh-session-search-pro, and the repository is at https://github.com/YaoleWu/dsh-session-search-pro; the directory is an independent site with no official affiliation to DeepSeek, so verify the source yourself when using.