Lore, ADRs you can ask questions to (local hybrid search + MCP)
A new open-source tool called lore-cli has been released to help engineering teams manage and retrieve architecture decisions through semantic search.
Developed by Jose Ernesto Torres Zamora, lore-cli addresses a common challenge in software development: finding and maintaining architecture decisions over time. The tool provides a complete lifecycle for Architecture Decision Records (ADRs) with zero-configuration local semantic retrieval capabilities.
Unlike traditional approaches that rely on grep or static documentation sites, lore-cli enables teams to search through their technical decisions using natural language queries. It combines vector similarity with keyword matching through Reciprocal Rank Fusion (RRF), making it possible to find relevant decisions even when exact wording isn't remembered.
Key Features
The tool offers a full ADR lifecycle management system, allowing teams to create, list, supersede, and deprecate decisions while maintaining them as plain markdown files in repositories. Its hybrid search capability combines vector cosine similarity with Okapi BM25 technical token matching.
Lore-cli runs entirely locally using embedded ONNX embeddings via Transformers.js, requiring no API keys or external services. It features incremental caching based on content hashes, allowing re-indexing of unchanged repositories in under 25 milliseconds.
AI Integration
A standout feature is the built-in Model Context Protocol (MCP) server that enables AI assistants like Claude Desktop and Cursor to search and respect existing decisions. This integration helps prevent AI coding agents from generating code that violates team consensus on technical approaches.
The MCP server provides five tools that allow AI workflows to search, list, record, and supersede decisions natively. Configuration is straightforward, with JSON settings that can be added to AI assistant configurations.
Workflow Integration
Teams can install lore-cli globally via npm or run it as a one-off command. The initialization process creates a configuration file and sample ADR in a .lore directory. Once indexed, documentation can be queried using natural language questions about technical decisions.
The tool also supports optional Git hooks that automatically re-index repository documentation after each commit, ensuring the search index stays current with minimal overhead. Results include exact source links with clickable file:// URIs pointing to specific file paths and line ranges.
Lore-cli is designed to work with existing documentation patterns, including ADRs, RFCs, and markdown files in various locations. The configuration allows customization of included and excluded file patterns, embedding models, and chunk sizes to suit different project needs.
Related
