Data Olympus

本地服务

github.com记忆与知识313 天前更新

关于 Data Olympus

Data Olympus 是面向 Agent 团队的治理级知识库格式、命令行工具和单写入者 MCP 服务，兼容 OKF v0.2 读取。知识库以 git 管理的 markdown 文件保存，用于标准与决策的检索。它关注的是 Agent 做出选择时应遵循的既定规则，而非代码搜索。

主要功能

01兼容 OKF v0.2 目录结构与 frontmatter 约定
02稳定 id、type、status、tier 等治理字段
03supersedes 链追踪决策历史
04单写入者 MCP 流水线与待提交队列
05基于 git 的版本管理与差异审查

适用场景

01Agent 在引入库或模式前检索团队既定标准
02记录与追踪架构决策的演变历史
03在多 Agent 并发写入时避免写入冲突

MCP 相关

该项目提供 MCP 服务，向 MCP 客户端暴露知识库的检索与受控写入能力。写入经过建议锁、按会话的 worktree 和持久推送队列处理。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "knaisoma-data-olympus": {
      "command": "uvx",
      "args": [
        "data-olympus"
      ],
      "env": {
        "KB_MAIN_PATH": "<KB_MAIN_PATH>",
        "KB_INDEX_PATH": "<KB_INDEX_PATH>",
        "KB_HTTP_PORT": "<KB_HTTP_PORT>"
      }
    }
  }
}

启动命令uvx data-olympus

需要配置的环境变量

KB_MAIN_PATHPath to the git-backed knowledge bundle this server indexes and serves.

KB_INDEX_PATHPath to the generated SQLite index. Rebuilt atomically and swapped in.

KB_HTTP_PORTPort the streamable HTTP MCP server listens on. Defaults to 8080.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypidata-olympus0.11.4Streamable HTTP

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

data-olympus

初次了解？请从 WHY.md 开始。 这里讲述了项目背后的故事：我们在使用编码 Agent 时反复遇到的问题、data-olympus 的不同之处、它与 Google Open Knowledge Format 的关系，以及我们的基准测试显示它擅长和不擅长的领域。本 README 的其余部分是技术参考。

data-olympus 是一种面向 Agent 工作团队、达到治理级别的知识库格式和服务。它可供 Open Knowledge Format（OKF）v0.2 使用方读取：它沿用了 OKF 的目录结构、frontmatter 约定、保留文件名和链接模型，并在此基础上增加治理扩展（稳定的 id、受控的 type/status/tier 字段、supersedes 链），以及单写入者 MCP 服务和 CLI。CI 针对 Google 官方 OKF v0.2 提交 ad30107c31c06aec8a7d5636e0d1058118604e6f 验证了两个具体方向：其参考可视化使用方会读取 example-bundle 中的每个概念；data-olympus 则会导入、检查、建立索引、搜索并检索固定版本的官方 Bitcoin 示例。这是针对固定测试样本的互操作性证据，并不代表对所有 OKF 包或未来上游修订版的全面保证。最终得到的是一个以 Git 为基础、受版本控制的文档图谱，其中包含工程标准、架构决策和项目知识；Agent 和人类都能读取、搜索和扩展它，且无需任何专有服务。

它管理的是决策，而不是代码。当 Agent 即将做出选择（库、模式或迁移）时，data-olympus 会提供应当指导该选择的既定标准或决策。它有意不提供代码搜索、引用查找或“X 在哪里被使用”这类功能：LSP、grep 和 Sourcegraph 已经很擅长处理这些需求。它针对的检索任务是从编码意图找到治理规则，并在当前模型交互于氛围式编码时最薄弱的环节提供帮助：让模型遵循团队已经确立为正确的模式。

状态：1.0 之前的 Beta 版。稳定版本通过 PyPI 和 GHCR 分发。

为什么

可移植，无锁定。 整个知识库都是 Git 中的 Markdown 文件目录。没有数据库、专有架构或供应商依赖。
基于 Git 的差异比较和评审。 每项更改都是一次提交。拟议编辑会先进入待处理队列，再进行提交；历史记录就是普通的 Git 日志。
Agent 和人类均可读取。 使用带 YAML frontmatter 的纯 Markdown。读取或编写文档无需 SDK。
受治理的多 Agent 写入。 单写入者 MCP 流水线（咨询锁、按会话隔离的工作树、持久化推送队列）可防止并发写入冲突，无需分布式锁基础设施。
可按状态、层级和类型查询。 无需后处理即可按 status: accepted、tier: T1 或 type: decision 筛选。supersedes 链支持跨图谱追溯决策历史。
经过官方 OKF 工具测试。 CI 固定了 Google OKF 的确切修订版本，并通过已提交的测试样本验证了两个方向的使用能力。固定版本、测试样本校验和及 Apache 2.0 许可证来源记录在 tests/okf/reference.json 中。

快速入门

需要 Python 3.13+ 和 uv。直接从 PyPI 运行稳定版 CLI：

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

准备创建知识库包并运行服务时，可将其持久安装：

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

已公布的候选版本需要通过其确切的 PyPI 版本选择加入。如有候选版本，请将 X.Y.ZrcN 替换为发布页面上列出的版本：

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

请参阅发布渠道，了解各渠道的含义、采用候选版本前如何验证，以及如何回滚。

请参阅 docs/quickstart.md，了解知识库包初始化、服务启动、就绪状态、Agent 注册，以及贡献者源代码安装。

请参阅 docs/adoption.md，了解完整的知识库包编写指南。

文档

SPEC.md：格式规范（知识库包布局、frontmatter 架构、服务契约）。
docs/quickstart.md：经过验证的本地运行流程。
docs/adoption.md：自带知识库指南（编写、检查、索引、提供服务、接入 Agent）。
docs/serving.md：单副本服务模型、只读副本、git pull 循环、健康/就绪/存活状态划分、代理标头、审计日志轮转。
docs/operations.md：生产运行手册：备份、升级、恢复操作指南（服务降级/获取失败、历史重写、被冻结/降级的推送条目、孤立锁）、健康/告警模型和发布渠道（稳定版与候选版、验证、回滚）。
docs/comparison.md：data-olympus 与 OKF、企业目录、Markdown 知识库工具、Agent 上下文惯例、RAG 和 ADR 工具的关系。
docs/okf-profile.md：逐字段 OKF 配置：哪些治理扩展已稳定，哪些是仅限运行时的服务字段，哪些是实验性候选项。
docs/glama.md：Glama 注册表认领、发布和评分维护说明。
docs/mcp-registry.md：官方 MCP Registry 说明、server.json 声明的内容，以及发布检查清单。
docs/enforcement.md：将知识库设为强制查阅关卡（钩子、kb enforce）。
benchmarks/README.md：检索基准测试方法，以及如何复现 docs/comparison.md 中的数据。
SECURITY.md：受支持的版本及漏洞报告方式。