# Nomicore

[English](README.md) | 中文

[![CI](https://github.com/nomicore-ai/nomicore/actions/workflows/ci.yml/badge.svg)](https://github.com/nomicore-ai/nomicore/actions/workflows/ci.yml)

> **面向 Agent 的数据库**

## 示例：只有 `revenue: 120` 为什么不够

假设一个 Agent 从传统数据库中收到如下结果：

```json
{
  "month": "2025-01",
  "revenue": 120
}
```

这个值看起来很简单，但 Agent 无法在不询问更多信息的情况下安全地使用它：

- `revenue` 的单位是美元、千美元，还是其他货币？
- 它表示已确认收入、已开票收入，还是实际回款？
- 它是否包含税费、退款和关联方交易？
- 这条记录由哪个 schema 版本生成？
- 这个指标的定义是否在当前月份与历史记录之间发生过变化？

在 Nomicore 中，读取结果会同时包含数据及解读数据所需的信息：

```js
{
  ok: true,
  value: {
    month: '2025-01',
    revenue: 120
  },
  schema: `# readData []

{
  month: Pattern<"^[0-9]{4}-(0[1-9]|1[0-2])$"> // 报告月份，格式为 YYYY-MM
  revenue: Range<0, 999999999> // 已确认收入，单位为千美元，不含税费和退款；会计政策 2025-v2
}
`,
  truncated: false
}
```

`Pattern<"…">` 表示这个值必须符合指定格式；`Range<0, 999999999>` 表示这个值必须是该范围内的数字。字段后的注释则说明数据的含义和解读口径。

现在，Agent 可以确定 `120` 表示按 `2025-v2` 会计政策计算的 12 万美元已确认收入。如果较早的记录使用不同的数据形状或业务口径，它可以继续保留自己的 schema 和口径，而不会被默认套用当前规则。

当这份结果被发送给另一个 Agent 时，它的 schema 和业务口径也会随之传递。接收方无需先找到独立的数据字典，也无需依赖未写明的组织背景，就能正确理解这个值。

## 为什么需要 Nomicore

### 为什么传统数据库在 Agent 时代不好用

传统数据库主要为人编写的应用程序设计。应用程序可以把数据结构、业务规则和异常处理预先写进代码，但 Agent 面对的是动态任务，需要在读取、修改、分享和持续关注数据的过程中，随时理解数据及其边界。传统数据库在这些环节都存在明显缺口：

1. **拿到数据，却没有拿到完整的解释。** Agent 查询数据库时通常只能拿到数据，拿不到 schema；即使另外取得了 schema，也往往拿不到字段真正的业务口径。它知道一个值是数字，却不知道单位、统计范围、计算方法和适用版本，只能依赖猜测或到处寻找文档。
2. **修改数据时缺少约束。** 如果约束只存在于应用代码或人的共识中，Agent 直接修改数据时就无法确认自己的写入是否合法。字段写错、类型不对或违反业务规则，都可能在没有明确提示的情况下进入数据库并继续传播。
3. **改错后缺少低成本的后悔药。** 传统数据库要么没有面向单次语义变更的回滚能力，要么只能通过事务、备份或整库恢复处理。回滚粒度大、操作复杂、成本高，一次错误修改可能影响大量无关数据。
4. **数据难以安全分享。** Agent 把查询结果发送给另一个 Agent 时，通常只发送数值，不会连同 schema 和业务口径一起发送。接收方只能按自己的理解解释数据；参与者越多、版本越多，结果越容易变成一团糟。
5. **对快速迭代不友好。** 一旦 schema 升级，通常就需要迁移所有历史数据，才能让新旧数据继续被同一套应用逻辑处理。数据量越大、历史越长，迁移的风险和成本就越高，schema 演进也因此变得谨慎而缓慢。
6. **Agent 无法感知数据已经变化。** 数据更新后，Agent 通常不会收到通知。为了避免使用过期数据，它只能在每次使用前重新读取；大型数据被反复塞进上下文，不仅响应慢，还会大量消耗宝贵的上下文空间。

### 让数据解释自己

Nomicore 将每一份数据与其 schema 和业务口径绑定在一起。Agent 读取数据时，也会同时获得理解其结构和含义所需的信息。数据不再依赖散落在其他位置的隐含上下文，而是可以自描述、自解释。

每一份数据都可以拥有自己的 schema 和业务口径。因此，不同的数据形状和定义可以共存，不必先要求所有生产者和消费者对齐到同一个全局版本，也不必一次性迁移全部历史数据。

这也使 Nomicore 天然适合 Agent 协作。当一个 Agent 将数据发送给另一个 Agent 时，与之关联的 schema 和业务口径也会一起传递。接收方能够根据数据自身携带的信息判断应当如何读取它，从而显著减少歧义和误读。

## 当前能力

- **用熟悉的语法定义数据**：使用接近 TypeScript 的语法描述数据结构，并把字段含义、业务规则和解读口径直接写在结构定义中，让数据规范既便于人阅读，也便于 Agent 理解。
- **由数据库内核执行 Schema 约束**：所有写入都会经过 Schema 校验，数据库从底层阻止不符合规范的数据进入，避免数据结构和业务约束随着时间逐渐漂移。
- **实时感知数据变更**：数据发生变化时，Agent 可以立即收到变更信号并作出响应，不必依赖周期性轮询，也不必反复读取整个数据集。
- **多种数据访问与搜索方式**：既可以按精确路径读取单个字段、对象或集合，也可以限制读取深度和宽度，按需获取大型数据结构的一部分；还可以对数组或键值集合进行窗口读取，按索引、键或字段排序，选取最新记录、稳定区间或 Top-K 结果。每次读取都会同时返回相应的数据规范和业务口径。
- **原生支持多方协作**：同一份数据可以由多个参与者持续协作修改，并保留细粒度、可合并的数据变更。它既适用于 Agent 与 Agent 之间共享和协同处理数据，也适用于 Agent 与 Human 围绕同一份数据共同工作。
- **灵活部署并可横向扩展**：Nomicore 可以作为模块嵌入任意应用程序，也可以作为独立服务运行；当规模扩大时，可部署为通过 Hub/Peer 同步的多实例集群，在不同节点之间维护完整副本。
- **原生支持 DeepSeek Harness**：Nomicore 可直接为 DeepSeek Harness 提供持久化、带 Schema 和业务口径的数据访问，以及跨 Session、跨 Agent 的协作数据基础。

## 进一步了解

- [安装、集成、部署与开发](INSTALL_zh.md)
- [权威领域术语](CONTEXT.md)
- [架构决策](docs/adr/)
- [Instance replication wire contract](docs/protocols/instance-replication-v1.md)