open-why MCP server
Commit Oct 29, 2026Retrieves recorded decision rationale from Git history, ADRs, and documents to provide AI agents with source evidence and decision history.
Also known as cogitod/open-why
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 29, 2026
- License
- Apache-2.0
What is open-why MCP?
open-why retrieves recorded decision rationale from Git history, ADRs, and documents to provide AI agents with source evidence and decision history.
Summary generated from the project's README
About open-why MCP server
Providing AI agents with the historical context behind technical choices is what open-why enables. It functions as a decision memory system that retrieves recorded rationale from Git history, architecture decision records, and imported documents. This allows coding agents to understand why specific modules were separated or why certain databases were chosen, rather than guessing based on code alone.
Developers use this as a local MCP server by connecting it to clients like Claude Code or Codex. The system stores all records in a local SQLite database. While lexical search works immediately without any external services, users can optionally add semantic retrieval by configuring local embeddings or connecting to remote embedding providers. The server provides specific tools such as open-why_ask for scoped previews and open-why_get to retrieve complete records with their associated source evidence.
This tool is designed for teams and agents that need to maintain continuity across development cycles. It focuses on preserving explicit, recorded explanations and will return unknown if no supporting rationale exists in the indexed history.
What you can do with it
- 1Maintain agent continuityAsk an AI agent to explain the reasoning behind a specific implementation choice made by a previous developer.
- 2Accelerate developer onboardingQuery the repository history to understand the architectural reasons for using specific technologies like SQLite.
- 3Track decision evolutionInvestigate what historical decisions were replaced and what evidence was used to justify those changes.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecogitod/open-why is public and reachablegithub.com/cogitod/open-why ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-29github.com/cogitod/open-why ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubopen-why: decision memory for AI agents
An open-source MCP server, Rust library, and CLI for understanding why decisions were made.
open-why retrieves recorded rationale from Git history, architecture decision records (ADRs), and imported documents or events. Results carry source evidence and decision history so coding agents and teammates can inspect the reason. If no supporting rationale was recorded, the answer should be unknown.

Install · Connect an agent · Try the demo · Integrate · Contribute
An open-source project by Cogito. Apache-2.0.
What it helps you answer
- Agent continuity: Why did a previous agent choose this approach?
- Developer onboarding: Why does this repository use SQLite or separate a module?
- Decision history: What replaced an earlier decision, and what evidence was recorded?
Records live in local SQLite. Search works without a model or API key; optional embeddings add semantic retrieval. Imports can preserve explicit rationale from other tools without a Git repository. open-why stores recorded explanations; it does not reconstruct unrecorded reasoning or establish that a decision was correct.
Status: public beta, 0.1.0-beta.2. Installation, store isolation, retrieval,
and backup/restore have automated verification. An actual Codex CLI session has
passed a bounded evidence-read check. Independent human first use and broader
client coverage remain open; see readiness and limitations.
This version includes the hardening described in SECURITY.md. Recognizable credentials are rejected before ingestion or embedding; ordinary private rationale remains local unless a client or remote embedding provider is explicitly connected. See the data policy and limits.
Install from source
You need Git, Rust 1.88 or newer, and your platform's native build tools:
cargo install --locked --git https://github.com/cogitod/open-why \
--tag v0.1.0-beta.2 --bin why --no-default-features
why --version
Add Cargo's binary directory (normally ~/.cargo/bin) to PATH. This installs
the versioned lexical build without ONNX Runtime or model downloads.
Prebuilt binaries are available for Apple Silicon and Ubuntu 24.04 x86-64 (glibc 2.39 required). Follow release verification and upgrades before using an archive. Linux and macOS are tested; Windows is unsupported.
For local embeddings, omit --no-default-features and run why fetch-model.
See configuration for model selection and
build requirements for native runtime limitations.
A connected AI client receives the records it requests; configured remote
embedding providers also receive text. Lexical retrieval itself needs no service.
Set up your coding agent
Generate a configuration for one database and reuse it across your clients:
why setup --db "$HOME/.cache/open-why/open-why.db" --client codex
Merge the printed TOML into ~/.codex/config.toml. For Claude Code, use
--client claude-code and merge the printed JSON into the project's .mcp.json.
Other MCP clients can use --client generic for command/args/env JSON.
Setup prints configuration without changing client settings. It creates a new
store identity or reads the existing one. Keep both OPEN_WHY_DB and
OPEN_WHY_STORE_INSTANCE_ID, use concrete paths without symlink components,
and replace an existing server entry instead of adding a duplicate.
Never assign a new identity to an existing database.
Reconnect the client and check that open-why's tools appear. Generated settings alone do not prove connectivity; tested client scope and tool approval describe what has actually been exercised.
Get your first answer with evidence
Ask your connected agent, using an absolute Git working-tree path:
Use open-why_ask to answer: why does this repository use SQLite?
Repository: /absolute/path/to/repository
Then call open-why_get with a returned ID and the same scope. Cite the recorded
reason, record ID, and available source or commit evidence. If the records do
not establish the reason, say unknown. Do not edit the repository.
open-why_ask returns scoped previews; open-why_get returns the complete current
record and its evidence. Indexing reads committed history and recognized decision
Markdown, not all conversations or uncommitted files. An empty scope is indexed
on first ask. After new commits, call open-why_index explicitly to refresh it.

Try an isolated example
With why installed:
git clone --branch v0.1.0-beta.2 --depth 1 https://github.com/cogitod/open-why.git
cd open-why
bash examples/quickstart.sh "$PWD/../open-why-demo" codex
The destination must be new and its parent must exist. The script creates a
synthetic repository, separate store, client snippet, and prompts for evidence
retrieval, missing evidence, and supersession. It leaves normal stores and client
settings untouched. Use claude-code or generic for another snippet format.
After testing, disconnect the demo, restore your usual client configuration,
and remove only the demo directory you created.
Build on open-why
| Your application | Integration route |
|---|---|
| Rust host | Embed the library and call its public typed APIs. |
| Agent, IDE, Python, or TypeScript backend | Launch the local MCP stdio server with an MCP client. |
| Research tool or event recorder | Import explicit decisions with stable IDs, scope, author, date, and source references. |
Start with the integration guide, its pinned Cargo example,
and the runnable host adapter. The
open-why.integration/v1 manifest and conformance checker describe and check
compatibility. Integrations use explicit scope and store identity; SQLite tables
are private implementation details.
There is no dynamic plugin loader or built-in HTTP service. A remote application supplies its own backend and authentication. Scope is a retrieval boundary, not multi-user authorization. Task orchestration and raw activity logs stay in the host.
Maintain your store
why doctor --db "$HOME/.cache/open-why/open-why.db" --repo /absolute/path/to/repository
Doctor is read-only and exits nonzero when a check fails or cannot be verified.
Follow backup, restore, and troubleshooting before keeping
important records or upgrading. Backup and restore require new destination paths.
To uninstall the executable, run cargo uninstall open-why; data and models remain.
Documentation and contributions
| Need | Guide |
|---|---|
| Commands, MCP tools, environment settings | Reference |
| Embedding open-why or connecting another stack | Integration contracts |
| Data maintenance and diagnostics | Backup and recovery |
| How records, evidence, and ranking work | Design |
| Reproduce retrieval checks | Public evaluation |
| Release identity, compatibility, and upgrades | Releases · Stability policy |
| What to work on next | Roadmap and contributor tasks |
Report a reproducible bug or propose a focused improvement. The contributor guide covers setup and required checks. Changes go through PRs with passing CI; this single-maintainer project does not claim independent human review. Report vulnerabilities through the private security channel.
Maintenance
open-why is manually maintained. The Rust library, CLI and MCP server share the same source and versioned evidence contracts. Contributions follow CONTRIBUTING.md and the repository’s protected pull-request route, including its required CI checks.
open-why MCP questions
What does open-why actually store?
It stores recorded explanations and rationale; it does not attempt to reconstruct unrecorded reasoning or determine if a decision was correct.
Does searching require an API key or a model?
No, lexical search works without a model or API key, though optional embeddings can be added for semantic retrieval.
How do I refresh the decision index after new commits?
You should explicitly call the open-why_index tool after making new commits to refresh the index.
Is Windows supported?
No, the tool is tested on Linux and macOS, but Windows is currently unsupported.