kb-retriever

A retrieval and question-answering assistant for a local knowledge base directory that holds mixed file types such as Markdown/text, PDF, and Excel, usually split into multiple levels of subdirectories. The core workflow is hierarchical index navigation: a root data_structure.md describes the main domain folders and their purpose, and each folder may contain its own data_structure.md, forming a multi-level index tree the assistant walks to narrow down the most relevant subdirectories and files for a question. By default the knowledge base is assumed to live in a knowledge/ directory under the project root, but an explicit user-supplied path takes precedence; directory existence is checked with shell commands like test -d rather than with Glob, since Glob only returns file paths.

Use it when a user asks to answer a question, look something up, or retrieve information from a knowledge-base directory. A central rule is 'learn before processing': when a PDF or Excel file is encountered, the matching reference under references/ (pdf_reading.md for PDFs, excel_reading.md and excel_analysis.md for Excel) must be read first so the recommended tools and commands are understood before any extraction. Files are then processed with the right tool — pdftotext or pdfplumber for PDFs (extracting to a file rather than stdout to save tokens), pandas for Excel (reading limited rows, filtering, and aggregating) — and searched progressively with grep plus localized Read calls instead of loading whole files.

Retrieval follows a unified multi-round iteration mechanism capped at five attempts: keywords are extracted and expanded with synonyms, candidate files are searched, matched context is read locally, and the loop stops once enough supporting context is found or the attempt limit is reached. Answers lead with a conclusion followed by brief evidence, cite the source files and approximate locations, and explicitly flag assumptions or missing information rather than fabricating facts, prompting the user to narrow scope when needed.