About
What KEP Brain is
A company brain for the Kubernetes enhancement process: every KEP, SIG, person, decision and record in one graph, read live from public GitHub, answered only with evidence.
What a KEP is
A KEP is a Kubernetes Enhancement Proposal: the design document every significant change to Kubernetes goes through before code lands. It explains the motivation and design and the criteria for alpha, beta and stable. A KEP that changes kubernetes/kubernetes (in-tree) also passes a production readiness review (PRR); older or out-of-tree KEPs may have none.
Each KEP is a folder in kubernetes/enhancements(opens GitHub in a new tab) with a README (the proposal) and a kep.yaml (status, stage, owning SIG, authors, approvers, target releases). It also has a tracking issue in the same repository, and the issue number is the KEP number since early 2019: KEP-4671 is issue #4671 and the folder keps/sig-scheduling/4671-gang-scheduling. A few older KEPs carry a pull request number or none.
The KEP process document(opens GitHub in a new tab) makes kep.yaml the record of a KEP's state, pairs replaces with superseded-by on the other KEP, and says the metadata exists to communicate status and to support tooling. KEP Brain stores that document too, so you can ask about the process itself.
| Status | Definition |
|---|---|
| provisional | The KEP has been proposed and is actively being defined. |
| implementable | The approvers have approved this KEP for implementation. |
| implemented | The KEP has been implemented and is no longer actively changed. |
| deferred | The KEP is proposed but not actively being worked on. |
| rejected | The approvers and authors have decided that this KEP is not moving forward. |
| withdrawn | The authors have withdrawn the KEP. |
| replaced | The KEP has been replaced by a new KEP. The superseded-by metadata value should point to the new KEP. |
What KEP Brain does
Why a KEP is designed the way it is, who approved it and on what evidence, who knows an area, what changed since a release, whether a record is still current, and what a KEP or a status is. Every answer shows the graph path it read and cites the records behind it.
KEPs with facts, status history, derived decisions, lineage and findings; SIGs with leadership and their KEPs; people with their roles, what they author, review, approve and decide on.
Every pair of records that disagree, both sides linked to GitHub, who set each value, a suggested fix and a drafted issue text. Also what changed since a release, and the sync log.
The read-only graph tools behind every answer, callable directly with their parameters, and the same catalog served over the Model Context Protocol so other agents can query the graph.
Data sources and what is loaded
How the graph is built
- Ingest. The worker clones kubernetes/enhancements and kubernetes/community, reads OWNERS files from kubernetes/kubernetes through the GitHub API, and fetches tracking issues, timelines, pull requests and review threads for the SIGs in scope. Nothing ships pre-populated; every run upserts into the same graph, so re-running is safe.
- History, not snapshots. Every kep.yaml revision is replayed. State edges (owner, approver, tracked-by, targets, replaces…) carry the interval they were valid for, so “current” and “as of release X” are the same graph with a different filter. Edges that disappear from a source are closed, not deleted.
- Derive. Field changes become StatusChange nodes linked to their commit and pull request; Decision nodes are derived from them and linked to the people who decided and the evidence; the five checks below write Finding nodes; PageRank over decisions gives each person an influence score.
- Serve. The API reads the kep graph with read-only queries only; answers are cached in a separate ops graph, and your memory lives in a graph of its own. The web app, the answering agent and the MCP server all go through the same parameterised tool catalog. The browser talks only to this app's same-origin proxy.
| Nodes | What they hold |
|---|---|
| KEP | one per proposal folder, with the kep.yaml fields as properties |
| Document, Section | the kep.yaml, README (split by heading), PRR file, sigs.yaml and the KEP process documents |
| Person, Alias, SIG, Subproject, OwnersFile | who is who, from sigs.yaml and OWNERS files; GitHub logins only |
| Issue, PullRequest, Commit, Review, Comment | the tracking issue, its timeline, and the pull requests that changed each file |
| StatusChange | one per field change in a kep.yaml revision or per issue label and milestone event |
| Decision | derived from status, stage and milestone changes, PRR approvals and replacement declarations, linked to deciders and evidence |
| Finding | one per disagreement between two records, with both sides, a suggested fix and a lifecycle |
| Release, FeatureGate, Label | the targets a KEP points at |
Why a graph
“Did this person take part in a decision on this KEP, and where?” crosses three records: the person, the review or comment they wrote, and the decision that cites it as evidence. A vector store finds similar text but cannot follow who wrote what and what cites it; in SQL each hop is another join through link tables. In the graph it is one pattern, and the tool behind it runs this query as written:
MATCH (p:Person {key: $login})-[r:SUBMITTED|COMMENTED]->(x)<-[e:EVIDENCED_BY]-(d:Decision {kep_path: $key})
WHERE size($kinds) = 0 OR d.kind IN $kinds
RETURN d AS decision, type(r) AS rel, x AS via, e.evidence_kind AS evidence_kind
ORDER BY d.decided_at DESC, d.key, x.key
LIMIT 50Longer connections, such as how a person reaches a KEP through other KEPs and SIGs, use the database's shortest-path search over the same edges, up to four hops.
Indexes and constraints
How an answer is produced, and when there is none
- The question goes to a language model that may only call the read-only graph tools, in at most three rounds.
- Every tool result is a set of graph records, each with an evidence id and a public GitHub URL. The model writes its answer with those ids as inline citations.
- A validator checks every citation against the records actually returned in that request. An answer with a citation it cannot tie to a record, or with none at all, is replaced by an abstention. Plain mentions of a returned KEP, issue or person are linked to that record.
- Abstention reasons: no_evidence (the graph holds nothing relevant), out_of_scope (not about KEPs, the process, the loaded SIGs or KEP Brain itself), unsupported_claims (the model wrote something the records do not back), budget_exhausted (the answering budget ran out before an answer was checked), graph_unavailable (the graph database did not answer).
- Answers are cached per question and graph version. A per-browser memory id lets the model recall your earlier questions; it can be inspected and deleted under Memory.
The five checks behind the audit
| Check | What it means |
|---|---|
| Active status closed issueactive_status_closed_issue | kep.yaml says provisional or implementable while the tracking issue is closed. Usually the feature shipped and status was never set to implemented; when a lifecycle bot closed the issue, the status may be right. |
| Terminal status future targetsterminal_status_future_targets | kep.yaml says withdrawn, rejected, deferred or replaced, but the KEP still targets a future release or is still tracked for one. |
| One sided replacementone_sided_replacement | A KEP declares that it replaces another, but the replaced KEP does not list it as superseded-by. |
| Stage mismatchstage_mismatch | The stage in kep.yaml is not among the stage labels of the closed tracking issue. |
| Milestone mismatchmilestone_mismatch | The latest milestone in kep.yaml differs from the milestone of the tracking issue. |
Each finding keeps both records with their source URLs, the people who set each value, a suggested fix and a lifecycle (open, triaged, drafted, confirmed, dismissed, resolved upstream). The audit page reports how many findings have been hand-checked; recall is not measured because there is no complete list of disagreements to compare against.
Scope and limits
- Only the SIGs listed under data sources are loaded. Other SIGs appear on the explore page as “not loaded” and have no KEP data behind them. Widening scope is a configuration change and a worker run.
- The data is as fresh as the last worker run; the date and commit are shown in the top bar on every page.
- Answers cite records in the graph. Fixes are drafted for a human to review, with read-only access to GitHub. People are stored by public GitHub login only.
- A long list is shown in full on the explore and audit pages; in an answer, the model sees a bounded slice and must say how many records are not shown.
Licences
- Code: MIT. KEP Brain itself is open source under the MIT licence; see the LICENSE file(opens GitHub in a new tab) in its repository. It is provided as is, without warranty of any kind.
- Data: Apache-2.0. KEP texts, metadata and issues are written by The Kubernetes Authors and published under the Apache License 2.0(opens GitHub in a new tab). KEP Brain reads them in place and links back to them; it changes nothing upstream.
- Terms. The software and this site are provided as is, without warranty of any kind. The data is read from public GitHub sources published under Apache-2.0 and is shown as recorded there.
- Fonts and icons. Geist and Geist Mono are used under the SIL Open Font License 1.1 and served from this site, not from a font network. Icons are Lucide, under the ISC licence. The mark and the screenshots are the project's own.
- Kubernetes is a trademark of The Linux Foundation. KEP Brain is an independent open-source project by one developer and is not affiliated with, or endorsed by, the Kubernetes project, the CNCF or FalkorDB.
Privacy and your data
No account, no cookies, no tracking. KEP Brain sets no cookies and loads no analytics, advertising or other third-party script, so there is no consent banner because there is nothing to consent to. Pages make requests only to this site's own API.
What your browser keeps. Three values in local storage: your theme choice, an anonymous memory id generated in your browser, and whether the evidence chain keeps several branches open. None of them identifies you; clearing site data removes all three.
What leaves your browser. The text of a question is sent to the API with your memory id. The API sends the question and the graph rows it read to the model provider named in the footer to compose the answer; that provider's own terms govern what it retains.
What the server keeps. Only what the Memory page shows you: per memory id, each answered question, a 300-character answer summary, the record keys it cited, the KEP, SIG and release names found in the question, the sequence of tools used, and timestamps. This is kept in a graph of its own, so no other visitor can read it, and the API does not write question text to its logs.
Deleting your data. “Forget everything” on the Memory page deletes that whole graph at once, and “New identity” starts a fresh id; the API also deletes single facts and playbooks. There is nothing else to request, because nothing else about you is stored.
People in the graph. The graph holds public GitHub logins and the public roles they hold: author, reviewer and approver from kep.yaml in kubernetes/enhancements, chair and tech lead from sigs.yaml in kubernetes/community, and OWNERS roles from kubernetes/kubernetes. E-mail addresses are never ingested. The service is free, has no paid tier and sends no e-mail. It is not directed at children and collects no personal data beyond the questions you choose to type.
Accessibility
- Keyboard. Every action is reachable without a mouse: a skip link, roving focus in the tabs, ARIA comboboxes for both searches, focusable finding rows, and the shortcuts below. The focus ring is visible in both themes.
- Contrast. Every text colour in the palette was measured against each surface it is used on; the lowest ratio is 4.52:1 in the light theme and 4.50:1 in the dark theme, at or above the WCAG AA minimum of 4.5:1. Chart fills carry text labels and legends, so colour is never the only cue.
- Structure. One heading per section, tables with captions and column headers, decorative icons hidden from screen readers, live regions for search and answer status, and a page title and description on every route.
- Found something that does not work with your assistive technology? Open an issue in the repository(opens GitHub in a new tab).
Keyboard shortcuts
Press ? on any page for this list. Single-letter shortcuts pause while you type in a field.
| Key | Action |
|---|---|
| ? | Show or hide this list |
| / | Focus the question box on Ask, otherwise the page search |
| Ctrl Kor⌘ K | Focus the KEP search in the top bar |
| t | Switch the theme (system, light, dark) |
| Esc | Close a dialog, a search list or a menu |
| Key | Action |
|---|---|
| g h | Home |
| g a | Ask |
| g e | Explore |
| g u | Audit |
| g m | Memory |
| g b | About |
| Key | Action |
|---|---|
| Enter | Send the question |
| Shift Enter | New line in the question |
| Esc | Cancel the running question |
| Key | Action |
|---|---|
| ↓or↑ | Move through the results |
| HomeorEnd | First or last result (Explore) |
| Enter | Open the highlighted result, or KEP-n when the query is a number |
| Key | Action |
|---|---|
| o | Open the KEP on GitHub |
| y | Open kep.yaml on GitHub |
| a | Ask about this KEP |
| ←or→ | Previous or next tab, when a tab is focused |
| Key | Action |
|---|---|
| jork | Next or previous finding |
| EnterorSpace | Expand or collapse the finding |
| o | Open the finding's KEP page |
| d | Draft the fix as an issue text (nothing is posted) |
| ]or[ | Next or previous page of findings |