Preface¶

The most common practice when attaching project specifications, product manuals, or standard documents to an agent is to stuff the document into a vector database and inject relevant content into the context via semantic retrieval. This approach works well in question-answering scenarios, but it is not good at one type of requirement: what you want is not just “seemingly relevant”, but the ability to point out exactly which section of the original document the content comes from, ensure identical results for the same query every time, and allow the entire knowledge package to be taken offline and verified afterwards.

DeepSeek Harness (dsh) packages models, tools, skills, and sessions as plugins, and as a result, many memory extensions have emerged in the community. Some of these use knowledge graphs or session沉淀, while others are closer to traditional full-text retrieval. dsh-kb-sieve belongs to the latter category: it does not hand documents to external vector services, but instead extracts the original text locally, builds a SQLite FTS5 index, and lets the model answer according to the workflow of “first retrieve, then精读, then cite the chapter”.

This article is organized after cross-checking the plugin directory page, GitHub repository README, and source code, introducing what problem it solves, how the three tools work together, and the boundaries to note during installation. The community plugin directory mentioned in the article is an independent site and has no official affiliation with DeepSeek / Fangyuan, so it should not be interpreted as an official app store.

What is this¶

dsh-kb-sieve is a memory plugin for DeepSeek Harness, maintained by omdsh-dev, with the npm package name @dsh-external/dsh-kb-sieve. The current version of the repository is 0.1.0, the main language is TypeScript, and the license is Apache-2.0. Both the directory page and GitHub show 2 stars.

What it does can be summed up in one sentence: turn .md / .txt / .docx / .pdf into auditable knowledge packages — leaving the original text in references/ while building a local retrieval index using SQLite FTS5. The build process does not call large models, and the same input will produce the same output.

The repository positions itself as the “DSH version of kb-sieve”. The original version generates skills with Python kbtool scripts, wrappers, and optional PyInstaller binaries; this plugin moves retrieval and精读 into TypeScript tools, and the generated skills only contain data: SKILL.md instructions, original text in references/, and kb.sqlite, with no dependency on the Python runtime.

What do the three tools do separately¶

The plugin only registers three tools, and does not modify the agent loop, TUI, or system prompts. The inject function in the source code only deals with tools, meaning it attaches the capabilities after the tool registration service is ready.

1. kb_build: Turn documents into knowledge packages

The required parameters are the knowledge base name name (lowercase letters, numbers, hyphens) and the input path array inputs. Optional parameters include the output parent directory out, display title title, whether to perform a full rebuild force, and the extraction concurrency workers (default 4, range 1–8).

The default output location is not the global skill directory under the user’s home directory, but .dsh/skills/<name>/ in the current project root (find the nearest .git directory upwards, or use the current working directory if none is found). This is exactly the skill root directory that DSH listens to: after the build is completed, the model will be able to see this knowledge base in the skill directory in the next round of conversation.

force defaults to false. Both the后半部分 of the repository README and src/index.ts specify that when build_state.json already exists, incremental updates will be performed based on the byte fingerprint of the source file and the extracted text fingerprint, and documents will fall into four states: unchanged / changed / new / removed. Set force to true only when you need to rebuild the entire package. The “differences from the original version” comparison table in the README still states that v1 does not support incremental updates, which conflicts with the incremental update instructions in the same README and the current source code; refer to the source code and the more specific incremental paragraphs as the standard.

There are several implementation details on the extraction side worth noting separately:
- .md files are read as-is; .txt files will perform title inference (underlined titles, chapter numbers, short line heuristics).
- .docx files use fflate to decompress OOXML, read w:p / w:t, and recognize Heading1–6 or “Heading N” styles.
- .pdf files do not have a built-in parser, but instead call the system’s pdftotext -layout (poppler-utils). If this command is not found in the PATH, the build will fail, and you need to install poppler first, or convert the PDF to TXT/MD before importing.

The build proceeds according to the document pipeline: each document is extracted, stored in the database, and then released. The README gives the order of magnitude: a 32MB document build peaks at approximately 0.6–2GB; reduce workers if memory is tight. SQLite writes are committed in batches of 50,000 rows.

2. kb_query: Deterministic retrieval

The required parameters are the knowledge package path pack and the query term query. Optional parameters include limit (default 10, maximum 100) and doc_ids (comma-separated, used to limit the document scope).

The retrieval chain is lexical, with no vectors or randomness: FTS5 BM25 (title weight 10, body weight 1) → exact identifier matching for standard numbers / chapter numbers / model numbers → document type weighting → window density rearrangement → return doc_id, line number, matching line, score. The result comes with a status: high_confidence, needs_verification, or no_hits. When the query clearly exceeds the corpus domain (for example, a non-existent standard number in the library, or most words not appearing in the documents), no_hits and oos_reason will be returned.

The line number is only used for subsequent kb_read positioning. The generated SKILL.md clearly requires the model to cite the chapter name when answering (for example, “Section D21.3”), and not report the internal line number to the reader.

3. kb_read:精读 the original text by chapter

The required parameters are pack and doc_id. Common modes include:
- around: Read the complete chapter where a certain line is located, and you can use expand to expand to adjacent chapters;
- sections: Output the document map (title + line number range);
- find / after: Search for keywords backward from a specified line;
- jump: Jump to multiple segments, for example "210-230,450-460";
- start / count: Read according to a range.

tokens is used to mark hit words in the output. kb_read will reject path traversal; both the input and output paths of kb_build are resolved relative to the current working directory.

What is in the knowledge package¶

A successful build will produce a directory roughly as follows:

<pack>/
├── SKILL.md
├── manifest.json
├── kb.sqlite
└── references/<doc_id>/
    ├── doc.md
    ├── metadata.md
    └── structure_report.json

SKILL.md is the instruction manual for the model: first use kb_query, then use doc_id and line number to call kb_read, and the conclusion must fall on the chapter title in the original text of references/; stop when two consecutive rounds of no_hits are returned, and do not fabricate content. manifest.json lists the doc_id, title, path, and hash of all documents. kb.sqlite contains the document table, external-content FTS5, and row-level secondary indexes (line_text / line_rowmap / line_fts). The current index layout version in the source code is 3 (INDEX_VERSION), and old packages may carry a warning during query, and a full rebuild will be triggered next time based on build_state.index_version.

kb_query / kb_read read from kb.sqlite and references/. The repository states that the schema is consistent with the original Python kb-sieve product, so knowledge packages already built by the original version can be directly used for retrieval without rebuilding them with this plugin. Old packages without row-level indexes will fall back to the full-text scanning path.

Installation and activation¶

The installation command given on the directory page is as follows, run it in the DeepSeek Harness terminal:

dsh plugin add github:omdsh-dev/dsh-kb-sieve

For reproducible installations, fix the commit hash according to the method on the directory page:

dsh plugin add github:omdsh-dev/dsh-kb-sieve#<commit>

Replace <commit> with the specific commit in the repository. The dsh CLI will parse the plugin from GitHub and install it into the current configuration.

The repository README also adds an installation method by profile: install the plugin into the tui / headless / web or a custom profile, then restart with the corresponding profile to enable the injection of kb_build / kb_query / kb_read. Uninstall using the package name @dsh-external/dsh-kb-sieve. The local dsh version needs to already provide the dsh plugin subcommand. The Node engine declared in package.json is ^22.19.0 || >=24.0.0; the peer dependencies @deepseek-ai/dsh-tools and cordis are provided by the dsh combination, and the runtime additional dependency fflate (for docx extraction) will be installed along with the plugin installation process.

The git source writing methods on the directory page and README are not exactly the same. The directory page uses github:omdsh-dev/dsh-kb-sieve, which matches the current public repository; the README example once showed git+https://github.com/dsh-external/dsh-kb-sieve.git. Use the command on the directory page for installation, and do not guess another GitHub organization based on the @dsh-external in the package name.

Typical usage¶

The recommended usage by the repository is to build and dynamically load. Speak naturally to the model, for example “Turn these documents into a knowledge base” and provide the document paths. kb_build writes to .dsh/skills/ under the project by default, and DSH will dynamically discover new skills; after the model loads, it will call kb_query / kb_read according to the SKILL.md instructions. The skill content is read on demand, and there are no additional cache invalidation steps.

You can also point out to any parent directory, and then explicitly pass the pack path during query. The third scenario is to only query old packages: as long as there is a compatible kb.sqlite and references/ in the directory, there is no need to rebuild them.

The generated skill specifies the default workflow in great detail:
1. Use kb_query to get a compact summary (doc_id, line number, matching line, status).
2. Use kb_read with the around mode to精读 the hit chapter; if positioning is difficult, first use sections: true to view the chapter map.
3. Cite the chapter name when answering, do not output internal line numbers; clearly state that no content was found when there is no evidence.

Do not stuff all keywords into a single query for multi-hop questions. SKILL.md requires only 1–2 links to be queried per round, and extract new entities from the hit lines before querying the next hop.

These are all tool parameters, not separate CLI subcommands. After the plugin is installed, the model in the current session will call the tools according to the skill instructions; do not expect to directly type kb_query in the shell.

Applicable scenarios and notes¶

It is very suitable for handing materials such as specifications, manuals, interface descriptions, institutional documents, etc., that require “speaking against the original text” to the agent. The retrieval uses BM25 plus density windows, and is more friendly to identifiers such as standard numbers, chapter numbers, and model numbers; it is not semantic vector memory, nor does it automatically extract triples from conversations. graph-memory and mnemon, which also belong to the “Memory” category in the community directory, take another path and are not alternatives to dsh-kb-sieve.

It is recommended to review these boundaries before use:
- Currently supported input formats are only md / txt / docx / pdf. PDF depends on the system’s pdftotext, which is often missing in container or minimal environments.
- Original version capabilities such as aliases, graph edges, LLM query variants, and TSV indexes are still marked as unimplemented in v1 in the repository comparison table.
- Line numbers refer to the physical lines of doc.md, used for tool positioning, not printed page numbers.
- Large documents will consume memory. The README states that a 32MB document build peaks at approximately 0.6–2GB, reduce workers if memory is tight.
- The knowledge package is placed in .dsh/skills/ under the project, and travels with the project, and is not written to ~/.dsh/skills by default.

The plugin runs with the permissions of the current dsh process, and may execute code during installation. You should check the source code repository and license before installing; fix the commit in production or shared environments. DeepSeek Harness itself is still in developer preview, and the official repository also reminds that there may be breaking changes, and the plugin API may also change accordingly.

Summary¶

dsh-kb-sieve bundles “citable original text” and “repeatable local retrieval” into a single knowledge package: the build does not go through LLM, the query uses SQLite FTS5, and精读 returns to the references/ chapter. It does not solve the problem of making memory more human-like, but rather prevents the agent from speaking based on impression when dealing with specifications, manuals, and similar materials.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-kb-sieve/

GitHub: https://github.com/omdsh-dev/dsh-kb-sieve

Using dsh-kb-sieve to Build Auditable Local Knowledge Base for DeepSeek Harness