Documentation
文档
四个接口的完整文档。按你的目的选一条路:先动手跑一遍,先理解设计,或直接查某个任务的写法。
它能回答什么
把记忆存成文本切片,你会得到「谁在某时说过什么」。World Machine 存的不是切片,是结构化的世界状态——所以它能回答另外几类问题:
| 你想知道的 | World Machine 的答案形态 |
|---|---|
| 这个人现在在哪工作 | 实体 self 的 Employment 组件,含 organization 与生效时间 |
| 他是什么时候搬过去的 | Location 组件的 validFromMs |
| 上个月的状态是什么 | 带 asOfValidTimeMs 查询同一实体的结果 |
| 这条信息是陈述还是事实 | 组件的 epistemicStatus。经本接口写入的一律是 stated_claim |
| Agent 上一轮看到了什么 | memories 里的原文,逐字保留 |
原文与结构化状态是两套并存的表示。原文永不改写,状态是从原文推出来的结论,两者在同一个响应里一起返回。
读和写的形状
写入只有一句话加几个可选字段。读回来的响应里同时有原文和由它推出的实体、组件与生效时间。
四个接口
| 接口 | 作用 | 常见用途 |
|---|---|---|
POST /v1/memories |
写入一条原文记忆 | Agent 每轮对话后落一条;业务系统同步一条记录 |
GET /v1/entities/{entityId} |
按 ID 读一个实体及其全部组件 | 已知是谁,要它的完整状态与历史时点 |
GET /v1/memories:recall |
按查询召回实体与记忆 | Agent 每一轮取上下文;不确定实体 ID 时的入口 |
DELETE /v1/users/me/data |
擦除当前凭证主体的全部数据 | 用户行使删除权;测试环境清理 |
没有「列出全部实体」的接口。想知道有什么,用召回;想精确取一个,用实体接口。
从哪开始
按你的目的选一条路:
先动手
教程:走通四个接口
从写入到擦除完整跑一遍。每步都有可复制的命令和真实响应。
开始 → 先理解概念:为什么这样设计
实体与组件、认知分级、有效时间、身份派生、召回排序。读懂每一个响应字段。
阅读 → 已经在接操作指南:按任务查
批量导入、幂等重试、错误处理、控制体积、擦除与合规、上线检查清单。
查阅 → 查细节参考:字段与错误码
四个接口的完整参数、响应结构、数据模型、错误码与硬性限制。
查阅 →最小验证
如果只想确认凭证可用,发这一条:
curl -sS -X POST "$WM_API/v1/memories" \
-H "Authorization: Bearer $WM_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"text":"测试一条记忆"}'
返回 {"eventId":"…"} 就说明通了。