Keel

Keel

不必再为每个 Agent 重建一遍流水线。

在线演示 · 文档 · 托管控制台（测试版） · 原因：我们构建了 4 个 Agent，也构建了 4 份客户上下文副本

Keel 是产品内 AI Agent 的上下文层，适用于垂直 SaaS、消费级应用或内部工具。产品中的领域事件输入后，会输出每个租户对应的双时态上下文图；租户单位可以是终端客户、家庭或团队。你构建的每个 Agent 都通过同一组 5 个工具，经由 MCP、HTTP 或类型化 SDK 读取和写入该图。

你只需在 cartridge 中描述一次你的垂直领域（本体、事件目录、语义规则、记忆策略）。Keel 的核心与领域无关。你的第二个 Agent 一天就能接入，而不是等上几周，因为你无需再编写第二条流水线。

使用示例 cartridge 及其事件，一分钟即可上手：

pip install keel-context
keel init fleet --example fleet          # also crm, clinics, finance
keel context fleet fleet/events.jsonl unit:MXK-4821

状态：0.34.0，alpha。容器：ghcr.io/angelkurten/keel。通过 MCP 和 HTTP JSON API（/v1）提供的 5 个工具、Postgres、webhook、Kafka 和 SQS 适配器、语义搜索、整合功能、Agent 注册表，以及适用于 TypeScript、Python、Go 和 PHP 的 SDK；支持内存存储、SQLite（--db keel.db，标准库，无需运行服务器）或 MySQL（--db mysql://...）。

问题所在

产品中的每个新 Agent 都会重复相同的工作：提取客户数据、对数据进行规范化、判断“关键”意味着什么、维护自己的记忆，并向模型开放自己的工具。4 个 Agent，4 份客户上下文副本，4 套“关键”的定义，4 份彼此无法沟通的记忆。

现有记忆层（Zep、Mem0、AgentCore Memory、Neo4j 的 MKG）会摄取文本和文档，并按用户或 Agent 建模记忆。它们都不以领域事件为起点，也都不对你的产品已有的租户建模：B2B SaaS 的终端客户、消费级应用中的家庭，或内部工具中的团队。

Keel 有何不同

1. Cartridge。 使用 YAML 加上几个十行左右的处理程序即可声明一个垂直领域。核心保持通用。你可以为车队、诊所、物流或自己的产品编写 cartridge。
2. 输入事件，而非文档。 Keel 会摄取带有时间信息的结构化事实：通过 CDC、outbox、类型化 SDK、webhook、Kafka 或 SQS 接入你的 Postgres 表。摄取过程确定且成本低廉。图谱是精确的，因为它源自事件，而非从文本推断而来。
3. 每条事实都带有来源信息。 包含来源、valid_from、valid_to、recorded_at，以及更正者。系统从构建之初就满足审计要求。
4. 每个租户一张图。 每位终端客户、每个家庭或每个团队都有自己的子图，并拥有独立的权限和过期策略。

五种工具，适用于任何 Agent

工具	它回答的问题
context	我现在或过去某个时刻对这个主题了解什么？当前有效的事实、关系和规则判定。
history	它随时间发生了哪些变化？我们何时得知这些信息？
search	哪些主题符合条件？可按文本、类型、规则、属性值或含义搜索。
related	它与哪些内容有关联？最多追溯三跳。
annotate	记录 Agent 或某个人根据证据和适用范围得出的结论。

所有参数均见规范。

search(mode="semantic") 可按含义查找主题：先查找查询中的 ID，再融合密集检索和词法检索结果，最后可选择使用重排序器。向量存储位置和生成向量所用的模型由你选择适配器：内存、Chroma、Weaviate、任何兼容 OpenAI 的嵌入端点，或你自己的向量数据库和模型（方法、示例）。

通过 MCP（keel serve）公开这些工具，并将任何 Agent 框架连接到它们。在 cartridge 中声明 agents:，再用 keel serve --agent <id> 将服务绑定到其中一个 Agent：它可以读写的内容由这一层强制执行，而不是由 Agent 决定。

快速开始

uv sync --extra dev
uv run keel validate examples/fleet --events examples/fleet/events.jsonl
uv run keel ingest examples/fleet examples/fleet/events.jsonl
uv run keel context examples/fleet examples/fleet/events.jsonl unit:MXK-4821

然后编写自己的 cartridge：参见 docs/first-cartridge.md（20 分钟）。设置项（数据库、密钥、嵌入密钥）放在 .env 中：复制 .env.example（参考）。

在自己的产品中可将其作为库使用：uv add keel-context（或 pip install keel-context）；导入语句为 import keel。如果使用其他语言，可根据 cartridge 生成类型化客户端：keel sdk typescript|python|go|php examples/fleet -o <file>，每种语言都配有精简的运行时（参见 docs/sdks.md）。

与我们一起开展试点

在我们的帮助下，使用你的 Agent 在产品事件上运行 Keel：一天内完成首次试点提供了操作流程，并为每个步骤规划了时间。提交试点申请，通过calendar.app.google/3oKUSqXTQPYmjya56预约 30 分钟，或发送邮件至 [email protected]。

连接真实事件流

将 MCP 客户端连接到这五种工具：

uv sync --extra mcp
uv run keel serve examples/fleet --tenant acme-logistics --events examples/fleet/events.jsonl

使用 Claude Code 时，只需一条命令即可注册，Agent 便能看到恰好五种工具：

claude mcp add keel -- uv run --directory $PWD keel serve examples/fleet --tenant acme-logistics --events examples/fleet/events.jsonl

Codex CLI（OpenAI）也能以相同方式通过 ~/.codex/config.toml 使用；四种只读工具已标记为只读，因此运行时无需提示。两个客户端通过相同的五种工具回答了相同的问题：参见提供工具服务。后端或单个进程中的多个租户可通过 JSON API 使用相同的五种工具：keel serve --transport http（提供 OpenAPI 的 /v1/context、/v1/events 等端点；每个请求指定租户和 Agent）。

从产品中已有的事件源发送事件（各方式说明）：

• Postgres CDC，无需在产品中编写代码：keel cdc <cartridge> --dsn postgresql://... --map cdc.yaml --db keel.db --setup 会跟踪你自己的数据表；每次行变更都会成为一个事件。
• 类型化 SDK，从后端发送：keel sdk typescript <cartridge> -o src/keel.ts，然后调用 keel.events([emit.tireDepthMeasured({...})])（也支持 Python、Go、PHP）。
• outbox 表：PostgresTableAdapter 会按顺序使用游标轮询；重启后可从断点继续。
• Webhook：使用 keel serve --transport http 上的 POST /v1/events，或使用 build_app(ingestor, token=...)。
• SQS 或 Kafka：使用 keel consume --queue <url>，或在 Python 中使用 KafkaAdapter；采用至少一次投递，并在每次提交后确认。
• .jsonl 文件，用于回填和测试：keel ingest <cartridge> events.jsonl --db keel.db。

keel export <tenant> --db keel.db 会将某个租户的完整审计记录写入 JSONL，其中包括已关闭的事实和溯源信息；keel import 可将其原样还原到任何存储中的空租户。

架构

每个方框、各自的选项以及如何选择：docs/architecture.md。

核心强制执行的设计规则：

• 事件即真相。 仅追加日志；图谱由日志派生，可重新回放。Agent 和人员写入的内容会在回放后保留。
• 指针，而非副本。 图谱保存对你的行、语义和已获得的记忆的引用。绝不会复制你的表。
• 明确时间。 事实会关闭，而非被覆盖。
• 作用域，而非扁平存储。 global > tenant > task > agent。任何内容都不会意外提升到更宽泛的作用域。Agent 记忆仅由写入它的 Agent 读取；与任务 ID 绑定的任务记忆，仅由传入该任务的调用读取（context(task=)、history(task=)）；全局记忆存储在一个保留分区中，所有租户都可读取，且没有事件会写入其中。

仓库布局

keel/            core: envelope, handlers, store, scopes, cartridge loader, ingest, tools, cli
cartridges/      your own cartridges (empty here)
examples/        fleet (reference), crm, finance and clinics: four domains, one core, no core change between them;
                 each a cartridge, its events and its test; fleet also has a minimal agent and a multi-agent workflow
sdk/             SDK runtimes: typescript, go, php (the Python client ships in keel)
evals/           the semantic-search eval bench
docs/            site sources (mkdocs.yml at the root): architecture, first-cartridge, ingest, serve, sdks, operate, SPEC
tests/

路线图

以下为摘要；包含各版本交付内容的完整计划见 ROADMAP.md。

已交付：

• 事件信封、处理器注册表、按事件 ID 去重并支持回放的确定性摄取
• 双时态存储：内存、SQLite 和 MySQL 实现，采用存储协议并配有一致性测试套件
• 具有 TTL、证据策略、过期处理和整合为持久事实功能的记忆作用域（keel expire、keel consolidate）
• 通过 MCP（stdio 和 HTTP）提供的五种工具及 JSON API，包含 Agent 注册表（也包括人员）
• 适配器：Postgres outbox、webhook、Kafka、SQS
• 可组合、可沿关系跟踪并可测量持续时间的规则
• 事务时间（as_known_at）、自某个水位标记以来的变更、任务 ID、幂等写入、提案、冲突、跟踪记录
• 从 cartridge 生成的 SDK：TypeScript、Python、Go、PHP
• 批量摄取（在 MySQL 上，不到 1.5 分钟即可处理一百万个事件）
• 语义搜索：混合搜索、优先 ID、重排序器、可插拔向量索引和嵌入器，并提供评测基准
• Postgres CDC：通过逻辑复制跟踪你自己的表（0.28.0）

待办：

• 在语义搜索评测基准中加入来自试点项目的真实 Agent 查询
• Cartridge 目录、托管版 Keel、企业功能（2027）

论文

Keel：面向产品 Agent 的统一确定性上下文层（Zenodo 上的 PDF，源文件位于 docs/paper/）。针对三个真实 Jira 项目上的 387 个问题，使用三个 Agent 进行测试后，Keel 在租户级问题上比产品自身的 API 高出 21 至 32 个百分点，并且每个正确答案的成本最低；测试框架和每一条结果记录均位于 evals/jira/。

@misc{kurten2026keel,
  author    = {K{\"u}rten, Angel},
  title     = {Keel: one deterministic context layer for product agents},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.23571090},
  url       = {https://doi.org/10.5281/zenodo.23571090}
}

许可证

Apache 2.0。事件信封、cartridge 格式和五种工具是标准；它们将始终免费。