Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

data-olympus

knaisoma/data-olympus MCP server MCP Marketplace

New here? Start with WHY.md. It is the story behind the project: the problem we kept hitting with coding agents, what data-olympus does differently, how it relates to Google's Open Knowledge Format, and where our benchmarks say it is strong and where it is not. The rest of this README is the technical reference.

data-olympus is a governance-grade knowledge-base format and server for agent workforces. It is readable by Open Knowledge Format (OKF) v0.2 consumers: it inherits OKF's directory structure, frontmatter conventions, reserved filenames, and link model, then layers governance extensions on top (stable id, controlled type/status/tier fields, supersedes chains) plus a single-writer MCP server and a CLI. CI proves two concrete directions against official Google OKF v0.2 commit ad30107c31c06aec8a7d5636e0d1058118604e6f: its reference visualization consumer reads every concept in example-bundle, and data-olympus imports, lints, indexes, searches, and retrieves the pinned official Bitcoin sample. This is fixture-scoped interoperability evidence, not a blanket guarantee for every OKF bundle or future upstream revision. The result is a git-native, version-controlled document graph of engineering standards, architectural decisions, and project knowledge that agents and humans can read, search, and extend without any proprietary service.

It governs decisions, not code. When an agent is about to make a choice (a library, a pattern, a migration), data-olympus surfaces the established standard or decision that should govern that choice. It is deliberately not a code-search, reference-finding, or "where is X used" tool: LSP, grep, and Sourcegraph already do that well. The retrieval task it targets is coding-intent to governing-rule, and it helps where current model interaction during vibe-coding is weakest: keeping the model aligned to patterns the team has already established as correct.

Status: pre-1.0 beta. Stable releases are distributed through PyPI and GHCR.

Why

  • Portable, no lock-in. The entire KB is a directory of markdown files in git. No database, no proprietary schema, no vendor.
  • Git-native diffs and review. Every change is a commit. Proposed edits go through a pending queue before commit; history is plain git log.
  • Agent and human readable. Plain markdown with YAML frontmatter. No SDK required to read or author a document.
  • Governed multi-agent writes. The single-writer MCP pipeline (advisory locks, per-session worktrees, durable push queue) prevents concurrent write races without requiring distributed locking infrastructure.
  • Queryable by status, tier, and type. Filter by status: accepted, tier: T1, or type: decision without post-processing. The supersedes chain makes it possible to trace decision history across the graph.
  • Tested with official OKF tooling. CI pins an exact Google OKF revision and proves both consumption directions over committed fixtures. The pin, fixture checksum, and Apache 2.0 license provenance live in tests/okf/reference.json.

Quickstart

Requires Python 3.13+ and uv. Run the stable CLI directly from PyPI:

uvx --from data-olympus data-olympus --help

Install it persistently when you are ready to create a bundle and run the server:

uv tool install data-olympus
data-olympus init my-kb
data-olympus-mcp --help

An announced candidate remains opt in through its exact PyPI version. Replace X.Y.ZrcN with the candidate named on the releases page, if any:

uvx --from 'data-olympus==X.Y.ZrcN' data-olympus --help

See release channels for what each channel means, how to verify a candidate before adopting it, and how to roll back.

See docs/quickstart.md for bundle initialization, server startup, readiness, agent registration, and the contributor source installation.

The optional embeddings extra (local embedding ranking through fastembed) needs Python below 3.15 until onnxruntime publishes Python 3.15 wheels. On Python 3.15 the extra installs nothing, so leave KB_EMBEDDINGS_MODE unset there; everything else, including the container image, runs on 3.15.

See docs/adoption.md for the full bundle authoring guide.

Documentation

  • SPEC.md: format specification (bundle layout, frontmatter schema, serving contracts).
  • docs/quickstart.md: verified local-run procedure.
  • docs/adoption.md: bring-your-own-KB guide (author, lint, index, serve, wire an agent).
  • docs/serving.md: single-replica serving model, read-only replicas, git pull loop, health/readiness/liveness split, proxy headers, audit-log rotation.
  • docs/operations.md: production runbook: backup, upgrade, recovery playbooks (degraded/fetch-failed, history rewrite, frozen/demoted push entries, orphaned locks), the health/alerting model, and release channels (stable and candidate, verification, rollback).
  • docs/comparison.md: how data-olympus relates to OKF, enterprise catalogs, markdown KB tools, agent-context conventions, RAG, and ADR tooling.
  • docs/okf-profile.md: field-by-field OKF profile: which governance extensions are stable, which are runtime-only serving fields, and which are experimental candidates.
  • docs/glama.md: Glama registry claim, release, and score-maintenance notes.
  • docs/mcp-registry.md: official MCP Registry notes, what server.json declares, and the checklist for publishing.
  • docs/enforcement.md: turning the KB into a mandatory consultation gate (hooks, kb enforce).
  • benchmarks/README.md: retrieval benchmark methodology and how to reproduce the numbers in docs/comparison.md.
  • SECURITY.md: supported versions and how to report a vulnerability.

License

Apache 2.0. See LICENSE and NOTICE.

Metadata

Release files for data-olympus 0.11.5rc28

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for data-olympus 0.11.5rc28
File Size Uploaded Provenance Actions
data_olympus-0.11.5rc28.tar.gz 515.0 kB With provenance Details for data_olympus-0.11.5rc28.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for data-olympus 0.11.5rc28
File Interpreter ABI Platform Actions
data_olympus-0.11.5rc28-py3-none-any.whl Python 3 none any Details for data_olympus-0.11.5rc28-py3-none-any.whl

Total release size: 971.3 kB

Release files / data_olympus-0.11.5rc28.tar.gz

Download URL data_olympus-0.11.5rc28.tar.gz
Size 515.0 kB
Tags Source
SHA-256 checksum
How to use checksums
2c6f24e9d94be1703f3aa5a117707dc1ab3bf6131d6fad58674899109e44a2f6
BLAKE2b-256 checksum
How to use checksums
ac4af3b16f21ee92fab0334e8d30f5d5beda8df43404d0aa9dd7de310e93106a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / data_olympus-0.11.5rc28-py3-none-any.whl

Download URL data_olympus-0.11.5rc28-py3-none-any.whl
Size 456.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
48fb8edc4f3f922116fddcef974230d7ccdceac113f034ef191d1e4092166fb9
BLAKE2b-256 checksum
How to use checksums
350ba4dab08ff0c0af7967a43df99f4a2415eee866594e7f9a7036fc75434906
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for data-olympus 0.11.5rc28

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for data_olympus-0.11.5rc28.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page