buptwz/holmes-kb

Holmes is a knowledge base tool for engineering teams that tries to solve a common problem: when someone spends hours debugging an issue, that knowledge usually disappears into a Slack message or gets forgotten entirely. The next time someone hits the same problem, they start from scratch. Holmes aims to close that loop by automatically capturing what was learned during each debugging session and turning it into structured, searchable documentation. The system has two parts that work together. The first is this repository, a Python library and command-line tool that manages the knowledge base itself. Knowledge is stored as plain Markdown files with metadata headers inside a regular git repository, so there is no proprietary format or special database to maintain. The second part is a separate AI agent terminal interface (in a companion repository) that you interact with while debugging. When you describe a problem to the agent, it searches the knowledge base for relevant past incidents and presents them to you. When the problem is resolved, it automatically extracts the symptoms, root cause, and resolution steps and saves them as a new entry in draft form. Entries move through confidence levels over time. A draft entry becomes verified once it gets referenced in a real debugging session, and it becomes proven after being consulted multiple times. The system also automatically downgrades entries that have not been referenced recently, so the knowledge base reflects what is actually useful today rather than accumulating stale information indefinitely. A linter scans continuously for contradictions between entries, near-duplicate titles, and pending contributions that have not been confirmed. New entries go through a three-step validation check covering structure, deduplication, and a required human preview before anything is added to the official knowledge base. You can also import existing documentation from other sources using an AI-powered import command that reads any document and converts it into the standard entry format. The CLI handles setup, search, import, validation, and knowledge base maintenance without needing the agent component.