Kumbuka

状态：pre-beta。 kumbuka 正在积极开发中。其架构和数据模型已经确定，私有记忆保证也是一项严格的设计约束，但该项目尚未打磨成熟并正式发布。请预期会遇到一些不完善之处和破坏性变更。

kumbuka 在斯瓦希里语中意为祈使语气的 “记住！”。项目网站为 kumbuka.ai。

---

问题：有结果，却没有记录

AI 助手在不同会话之间没有状态，它们完成的工作会留下结果，却很少留下记录。使用它们的团队因此要付出双重代价。

他们要承担上下文税：每次开启新会话，都要重新解释同一套规则——“我们用 Postgres 作为事实记录系统”、“金额使用整数的最小货币单位，绝不使用浮点数”——因为本应指导工作的决策、约定和限制，都散落在人的脑海和聊天记录中。

他们也会失去工作的完整轨迹。助手或 Agent 完成某项工作后，日后要回答一些重要问题并不容易：是谁提出的请求、依据哪条规则、返回了什么结果，以及是谁接受了结果。会话记录会随着会话结束；而完成的文件本身并不会说明它由哪个请求产生。

kumbuka 是什么

kumbuka 是一组服务，用对象形式保存团队已达成共识的内容、委托并收到的工作成果，以及仍计划开展的事项。每个对象都可单独寻址，由助手通过 Model Context Protocol (MCP) 读取，并由团队维护。

服务	保存内容
Memory	团队已达成共识并整理维护的规则——决策、惯例、约束、定义、待解决问题和状态；这些内容有类型和范围，并由助手在工作开始时读取。
Dispatch	委托并交付的工作：一方提出任务，另一方接手并作答，而是否接受答案本身也是独立的操作；委托发出时即被冻结，因此之后仍可查看是谁提出了什么、谁作了答，以及接受了什么。
Worklist	待办事项及其顺序清单：事项经过创建、描述、规划、认领、处理和终止，并且在整个生命周期内都可编辑。
Documents	说明当前有效内容的文档。kumbuka-documents 尚未公开提供。

每项服务都是独立产品，并在自己的代码仓库中发布。每项服务都有完整的 REST 接口。Dispatch 和 Worklist 各自也提供 MCP 端点；Memory 没有自己的 MCP 适配器，助手通过平台的 MCP 入口访问它（参见架构）。

kumbuka 有意不做文档存储或 RAG 索引，也不会监视人们的操作。它保存的是有人记录、且团队认可的精选内容，而不是文档或源代码的副本；后者仍保留在各自的系统中。

私人记忆保障

成员的私人记忆只属于该成员。 只有该成员本人才能通过自己的身份验证 MCP 会话访问。管理员、控制台界面和面向团队的 API 均无法读取。

这是产品的核心保障，不是功能开关。它由数据访问层强制执行——特权（管理员/控制台）代码路径中不存在可返回私人记录的途径——而非通过可切换的配置项实现。停用成员会暂停其账户，但其私人记忆仍会原样保留，并继续归其本人所有。

有关如何通过结构设计强制执行此保障，请参阅安全与隐私指南。

租户隔离

每项服务在 PostgreSQL 中都有自己的架构和数据库角色。租户沿租户维度通过行级安全进行隔离：策略采用默认拒绝，因此未绑定到租户的请求看不到任何记录，而不会看到所有记录。服务的运行时角色不拥有任何对象，只持有迁移脚本明确列出的权限，因此无法关闭策略。

所有服务共用一个登录入口

登录由身份提供方前端的 OAuth 2.1 授权服务器 cimd-proxy 负责。对外，它使用 Client ID Metadata Documents：MCP 客户端通过其控制的 URL 标识自身，因此客户端只需知道端点 URL，无需复制或分发客户端 ID 和客户端密钥。对内，它将登录请求转交给 Keycloak，由其签发令牌。

从外部看，平台是一个具有单一 audience 的资源。登录一次即可获得一个令牌，该令牌适用于入口点后面的所有服务。每项服务都会自行验证未更改的令牌；没有任何服务依赖上游服务已验证令牌这一事实。

连接你的助手

AI 客户端通过自定义 MCP 连接器访问 kumbuka。在 claude.ai 中，你可以在设置 → 连接器下添加它，通过 OAuth 流程登录一次，之后助手便可以代表你调用各项服务的工具，包括你自己的私有记忆范围。

通过平台入口访问时，工具命名为 <service>_<verb> —— memory_query、dispatch_claim、worklist_create 等等，因此一个连接器就能承载所有服务的工具。

架构

下图展示了当前运行的托管部署。Caddy 是边缘层，不会验证令牌。cimd-proxy 是授权服务器，Keycloak 是其背后的身份提供方。platform 是入口：它是一个路由器，会读取地址中指定的服务，并通过 REST 将调用转发给该服务，同时提供用于管理范围、团队和设置的核心功能。Memory、Dispatch 和 Worklist 各自验证令牌，并在同一个 PostgreSQL 实例中维护自己的架构。ops console 是运营人员专用的界面，仅允许通过 IP 白名单访问。

flowchart TD
    C["AI assistant or agent<br/>(any MCP client)"]
    O["Operator browser"]

    E["Caddy edge<br/>(validates no token)"]

    X["cimd-proxy<br/>OAuth 2.1 authorization server<br/>(Client ID Metadata Documents)"]
    K["Keycloak<br/>(identity provider, issues the token)"]

    R["platform<br/>router + management core"]

    subgraph services["Domain services (each validates the token itself)"]
      M["Memory"]
      D["Dispatch"]
      W["Worklist"]
    end

    OC["ops console<br/>(operator, IP allow-list)"]
    P[("PostgreSQL<br/>one schema and one role per service")]

    C -- "1 · sign-in" --> E
    E -- "auth host" --> X
    X -- "federates sign-in" --> K
    C -- "2 · MCP or REST + bearer token" --> E
    E -- "/mcp, /api" --> R
    R -- "REST, token forwarded unchanged" --> M
    R -- "REST, token forwarded unchanged" --> D
    R -- "REST, token forwarded unchanged" --> W

    O --> E
    E -- "ops host" --> OC

    R --> P
    M --> P
    D --> P
    W --> P
    K --> P
    OC --> P

路由器和统一界面仅在企业版中提供。社区版安装中没有路由器，需直接访问各项服务。

快速开始

目前没有可用于这些服务的自托管软件包，本 README 不会假装有。每个服务仓库都说明了如何构建服务、运行完整测试套件，以及如何为你自己的数据库和身份提供方进行配置。测试套件需要 Docker；它们会通过 Testcontainers 启动各自的 PostgreSQL（Dispatch 和 Worklist 还会启动各自的 Keycloak）。

• kumbuka-memory — 配置和构建
• kumbuka-dispatch — 配置、构建和测试
• kumbuka-worklist — 配置、构建和测试
• cimd-proxy — 授权服务器的快速入门和配置

kumbuka-server 中的 Docker Compose 配置会启动管理核心，以及 PostgreSQL、Keycloak 和 Caddy。记忆引擎已从该仓库移出，因此这套配置不再单独提供记忆服务。

仓库一览

仓库	内容
kumbuka	本仓库——项目入口和公开文档。
kumbuka-memory	记忆服务：整理后的条目、范围和作者信息，以及条目之间的类型化关系。AGPL-3.0。
kumbuka-dispatch	派发服务：委托的工作及其答复，作为持久且可寻址的对象。AGPL-3.0。
kumbuka-worklist	工作清单服务：范围计划要做的事项，以经过流程处理的条目形式呈现。AGPL-3.0。
kumbuka-documents	文档服务。尚未公开提供。
cimd-proxy	OAuth 2.1 授权服务器：对外提供 Client ID Metadata Documents，对内与现有 OIDC 提供方（例如 Keycloak）进行联邦。Apache-2.0。
kumbuka-server	管理核心：范围、团队、设置和租户目录。AGPL-3.0。
kumbuka-console	Next.js 管理控制台。AGPL-3.0。

路由器和企业版模块位于私有仓库中。

文档

文档网站位于**docs.kumbuka.ai**（英语和德语）。部分内容仍在介绍早期仅包含记忆服务的架构；如果文档网站与本 README 对现有服务的描述不一致，请以本 README 为准。

版本与许可证

kumbuka 采用开放核心模式，两个版本的界限就是仓库的界限： 仓库边界即许可证边界。

• 社区版。 公共服务仓库（kumbuka-memory、 kumbuka-dispatch、kumbuka-worklist，以及 kumbuka-server 和 kumbuka-console）均采用 GNU Affero 通用公共许可证 v3.0 (AGPL-3.0) 开源，且每项服务都可独立构建为 完整产品。 cimd-proxy 是一款独立工具，采用 Apache-2.0 许可证发布。
• 企业版。 每项服务都有一个独立的闭源企业模块，可在构建时与开放核心组合。 企业版只添加，不修改：版本管理和审计是它首先添加的功能。 位于所有服务前方的唯一入口路由器，以及构建于其上的统一界面，均属于企业版。

由于 kumbuka 通常部署为可通过网络访问的服务，因此适用 AGPL §13：如果你运行修改后的版本，并允许用户通过网络与其交互，就必须向这些用户提供 修改后版本的对应源代码。

贡献

欢迎贡献。请先阅读 CONTRIBUTING.md，了解如何贡献，以及各仓库的开发环境配置所在位置。若要报告安全问题，请参阅 SECURITY.md——请勿公开提交漏洞问题。