Heirloom: Codebase Memory for People and AI Agents

When a senior engineer leaves, the reasoning behind their code leaves with them. New developers spend days digging through file trees and git logs to rebuild it. AI coding agents have the same blind spot: they edit code with no idea why it was written that way, and they quietly break decisions nobody wrote down. We measured it on a popular open-source project. In pallets/click, 41.7% of the 31,919 lines of code have a bus factor of 1, meaning one person accounts for at least half of what survives in those files. 18 files are at risk: their main owner has not committed in 180 days. Heirloom is a codebase memory tool. It ingests a repository's git history, blame, code comments that carry intent (NOTE, HACK, DO NOT, "because"...), pull requests, docs and ADRs, and turns them into a decision graph where every decision links back to the commit, PR or line it came from. On click it ingested 2,000 commits in 22 seconds and found 854 decisions. Who it is for and how they use it: - A new developer opens a Why Card for any file: what it does, the decisions behind it with evidence links, who still knows it, what breaks if it changes, and the warnings to respect. Onboarding Trails give them a reading order, dependencies first. - A tech lead opens the Bus Factor Map, a treemap colored by bus factor, and uses "If this person left" to see where knowledge is concentrated. - A reviewer gets the PR guard, a GitHub Action that comments on each pull request with the decisions it may conflict with, impacted files outside the PR, and DO NOT comments near the changed lines. - An AI agent connects to Heirloom's MCP server. Before editing a file it calls ask_why and impact_if_changed; after a real design choice it calls record_decision. - Anyone can Ask Heirloom a question and get an answer built only from recorded decisions, with citations. What makes it different is that the knowledge base keeps growing. New decisions, from the web form, the CLI or an agent, are written as Markdown into .heirloom/decisions/ inside the repo, so they live in git, survive without Heirloom, and load back on the next ingest. It is built to be trustworthy and cheap. It never invents data: an unknown value shows "unknown", and Ask can only cite decisions that exist. Every LLM feature has a deterministic fallback, so the whole app, including the demo, runs offline with zero API keys. Re-ingestion is incremental, and LLM responses are cached. It ships as a web UI, a CLI, a REST API, an MCP server with seven tools, and a GitHub Action, all sharing one core library. It has 155 Python tests with 87% coverage on the core, and passes mypy strict.