AutoGineer
Generated banner for data-olympus
Generated logo for data-olympus

data-olympus

Memory serverOfficial Knaisoma project

Created by Knaisoma

Published in knaisoma/data-olympus. Publisher page

30 GitHub stars

What it is

Governance-grade, OKF-compatible knowledge-base format with a single-writer MCP server and CLI. Pre-release.
— the description by Knaisoma

Summary from the brain’s metadata

Governance-grade, OKF-compatible knowledge-base format with a single-writer MCP server and CLI. Pre-release. 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.

How it works

Memory model: Markdown vault

AutoGineer overview, from the brain’s own files

Memory model: Markdown vault. Folders: .github (agent config, 20 files); bin (scripts, 7 files); docs (docs, 47 files); scripts (scripts, 29 files); src (source code, 81 files); tests (tests, 286 files). The agent reads .rules/versioning.md, example-bundle.

Folders
FolderRoleFiles
.githubagent-config20
binscripts7
docsdocs47
scriptsscripts29
srcsource-code81
teststests286
.rulesfolder5
benchmarksfolder328
deployfolder19
example-bundlefolder27
releasefolder2

The agent reads

Requirements

Runtimes: Python >=3.13

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. Not scanned by AutoGineerIts dependencies are installed by pip or uv when you run it and were not scanned by AutoGineer (5 declared). https://pypi.org/project/data-olympus/
  2. Not scanned by AutoGineerAutoGineer could not scan everything it runs. https://pypi.org/project/data-olympus/

  3. Created by Knaisoma. Published in knaisoma/data-olympus. Licence: Apache License 2.0.

Usage

From the brain’s own files

  • Requires Python 3.13+ and uv.
  • Run the stable CLI directly from PyPI:
  • Install it persistently when you are ready to create a bundle and run the server:
  • 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:
  • 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.
  • See docs/adoption.md for the full bundle authoring guide.

Documentation by Knaisoma

data-olympus

Image: knaisoma/data-olympus MCP server Image: MCP Marketplace

<!-- mcp-name: io.github.knaisoma/data-olympus -->

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.

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.

docs/quickstart.md

Quickstart: Install and run data-olympus

This guide installs Data Olympus from PyPI, starts the MCP server against a local bundle, checks readiness, and connects coding agents. Python 3.13 and uv are required.

1. Install

Run the current stable CLI without cloning the repository:

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

For repeated use, install both console commands as a persistent tool:

uv tool install data-olympus
data-olympus --help
data-olympus-mcp --help

To test an announced release candidate without replacing the persistent stable tool, select its exact PEP 440 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

Release channels explains each channel, verifying a candidate before adopting it, and rolling back.

2. Create a bundle and run the server

Create a valid starter bundle and initialize its git history:

data-olympus init my-kb
git -C my-kb init -b main
git -C my-kb config user.name "Local Operator"
git -C my-kb config user.email "operator@localhost"
git -C my-kb add .
git -C my-kb commit -m "docs: initialize knowledge bundle"

Start the installed MCP server. Runtime state stays outside the bundle:

mkdir -p .data-olympus
KB_MAIN_PATH="$PWD/my-kb" \
KB_INDEX_PATH="$PWD/.data-olympus/kb.db" \
KB_REMOTE_URL="" \
KB_WORKTREE_ROOT="$PWD/.data-olympus/worktrees" \
KB_PENDING_ROOT="$PWD/.data-olympus/pending" \
KB_PUSH_QUEUE_ROOT="$PWD/.data-olympus/push-queue" \
KB_AUDIT_LOG_PATH="$PWD/.data-olympus/audit.log" \
data-olympus-mcp

Wait for readiness in another terminal:

curl -fsS http://localhost:8080/readyz
curl -fsS http://localhost:8080/api/v1/health

3. Connect coding agents

Run the guided setup to register the MCP endpoint with detected Claude Code, Codex, Gemini, and OpenCode installations. The doctor command is read only.

data-olympus setup --endpoint http://localhost:8080
data-olympus setup --check --endpoint http://localhost:8080

4. Query with curl

# Health
curl -fsS http://localhost:8080/api/v1/health

# Search
curl -fsS "http://localhost:8080/api/v1/search?q=writing"

# Outline
curl -fsS http://localhost:8080/api/v1/outline
Compact responses by default

The read tools (kb_search, kb_get, kb_list, kb_outline, kb_health) return a token-compact shape by default, because their consumer is almost always an LLM paying for every token in its context. Compared with the full representation, the compact default:

  • kb_search: each hit is {id, title, snippet} plus status only when a hit is not currently in force (e.g. superseded) and type when set. The query echo, the per-hit path, and the raw relevance score are dropped. To read a hit in full, call kb_get with its id; array order conveys rank.

  • kb_get: keeps the full content_markdown body (that is why you call it) plus source_commit/last_modified provenance, and trims low-value envelope fields (path, git_remote_url, last_modified_source). path is recoverable with kb_get(id, verbose=true).

  • kb_list: drops the per-entry path (fetch via kb_get(id)).

  • kb_health: keeps the core snapshot and omits diagnostic fields that are unset.

  • kb_outline: already lean; unchanged.

Pass verbose=true (REST query param, or the verbose MCP tool argument) to get the full legacy shape with every field:

# Full/legacy shape (query, path, score, and full health envelope restored)
curl -fsS "http://localhost:8080/api/v1/search?q=writing&verbose=true"

The kb CLI always requests verbose=true so its plain-text output keeps showing paths.

5. Lifecycle-aware retrieval: in-force vs superseded

The generated starter bundle ships a real supersession pair in universal/foundation/: STD-INIT-001 (status: superseded, superseded_by: STD-INIT-002) and STD-INIT-002 (status: active, supersedes: STD-INIT-001), the standard that replaced it. This section shows the two ways kb_search treats that pair differently.

Default search applies a soft status-aware rerank: an active document is promoted ahead of the superseded document it replaced, but the superseded document is still returned (useful when an agent or human is tracing decision history).

curl -fsS "http://localhost:8080/api/v1/search?q=example%20standard&limit=5"

The top two hits are STD-INIT-002 (currently in force) ranked ahead of STD-INIT-001 (status: superseded), both present, active first. In the compact default the in-force hit carries no status field while the superseded hit shows "status": "superseded" (the deviation an agent must act on); add verbose=true to see "status": "active" spelled out on every hit.

in_force=true is a hard filter, not a rerank: it excludes every not-currently-governing status (superseded, deprecated, draft, proposed, rejected) from the result set entirely, before ranking, and, for docs carrying a validity frontmatter block, any doc outside its validity window (past valid_until, or before a future valid_from).

curl -fsS "http://localhost:8080/api/v1/search?q=example%20standard&limit=5&in_force=true"

STD-INIT-001 does not appear in the response at all: an agent that only wants guidance currently in force (for example, before writing a commit message) gets a result set that can never surface retired governance, rather than relying on the rerank to have pushed it down far enough.

Note that a doc past its validity.valid_until is excluded from DEFAULT search results too, not just from in_force=true queries; pass include_expired=true to see it, or fetch it directly with kb_get (which always resolves by id). See docs/serving.md and SPEC.md section 4.2 for the full validity semantics.

6. Docker path

Build and start with Docker Compose:

docker compose -f deploy/docker/compose.yaml up --build

By default the container serves an empty volume. Bind-mount a git-initialized bundle to KB_MAIN_PATH to serve real content:

docker compose -f deploy/docker/compose.yaml run \
  -e KB_MAIN_PATH=/my-kb \
  -v /path/to/my-kb:/my-kb:ro \
  data-olympus-mcp

The bundle at /path/to/my-kb must be a git repository (run git init inside it first).

7. Serve an existing bundle

Point the server at any git-initialized directory following the example-bundle/ layout:

KB_MAIN_PATH=/path/to/your-bundle \
  KB_INDEX_PATH=/tmp/your-kb.db \
  KB_REMOTE_URL="" \
  uv run data-olympus-mcp

See SPEC.md for the full document schema and tier conventions.

8. Contributor installation

Editable installation is for repository development, not normal onboarding:

git clone https://github.com/knaisoma/data-olympus.git
cd data-olympus
uv sync --all-groups
uv run pytest -q

Use uv run data-olympus and uv run data-olympus-mcp while developing. The repository also provides the lower level ./bin/kb REST helper for maintainer diagnostics.

512 files · 486 not served here

Advantages

  • Local-first: the memory stays in files or a database on your own machine (a rule-derived fact from the brain’s files, evidence: README.md)
  • Works with 14 MCP clients (a rule-derived fact from the brain’s files, evidence: README.md)
  • Plain markdown memory that you can read and edit yourself (a rule-derived fact from the brain’s files, evidence: README.md)
  • No API key is named in its files (a rule-derived fact from the brain’s files, evidence: README.md)
  • Open licence (Apache-2.0) (a rule-derived fact from the brain’s files)

Limitations

  • No ZIP download: install it from its source (a rule-derived fact from the brain’s files)

Security

Risk level: Low risk

This brain runs

Agent instructions that run or fetch something (5)

  • AGENTS.md: `uv run pytest` on its own is not equivalent.
  • AGENTS.md: `tests/test_server_cli.py` and `tests/test_smoke.py` spawn a subprocess with `sys.executable` and read installed distribution metadata, so without the editable install they fail with `No module named data_olympus.server` and a stale version assertion.
  • AGENTS.md: Anything that gates on `uv run pytest` without the editable install (a release routine, a scheduled job) will block on a false failure.
  • AGENTS.md: Run the linter before the tests.
  • tests/importer-fixtures/.cursorrules: Run the type checker in CI and treat type errors as build failures rather than warnings.
  • Low risk: network-instructions (AGENTS.md:75)
  • Low risk: scripts-present (scripts/check_benchmark_docs.py)
  • Low risk: scripts-present (scripts/okf_conformance.py)

Attribution and licence

Created by
Knaisoma
Declared authors
  • knaisoma (declared in pyproject.toml)
Publisher
Knaisoma (Official Knaisoma project)
Source
knaisoma/data-olympus · commit 6d46033
Licence
Apache License 2.0 (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Knaisoma.

Install from source

486 of its files are not served here, so there is no ZIP. knaisoma/data-olympus at 6d46033