World MachineAPI v1

Documentation

文档

四个接口的完整文档。按你的目的选一条路:先动手跑一遍,先理解设计,或直接查某个任务的写法。

风格:REST / JSON 鉴权:Bearer token 版本:v1

它能回答什么

把记忆存成文本切片,你会得到「谁在某时说过什么」。World Machine 存的不是切片,是结构化的世界状态——所以它能回答另外几类问题:

你想知道的World Machine 的答案形态
这个人现在在哪工作实体 self 的 Employment 组件,含 organization 与生效时间
他是什么时候搬过去的Location 组件的 validFromMs
上个月的状态是什么带 asOfValidTimeMs 查询同一实体的结果
这条信息是陈述还是事实组件的 epistemicStatus。经本接口写入的一律是 stated_claim
Agent 上一轮看到了什么memories 里的原文,逐字保留

原文与结构化状态是两套并存的表示。原文永不改写,状态是从原文推出来的结论,两者在同一个响应里一起返回。

读和写的形状

写入只有一句话加几个可选字段。读回来的响应里同时有原文和由它推出的实体、组件与生效时间。

写入的原文如何变成可召回的实体与组件 左侧是 POST /v1/memories 提交的一句话,写入后保存为原文并返回 eventId。原文经抽取得到实体与组件,两侧一起进入召回结果。右侧 GET /v1/memories:recall 同时返回 entities 与 memories。 写入 POST /v1/memories "我上个月搬到上海, 现在在 Acme 当架构师。" 原文 eventId 抽取 实体与组件 读取 GET /v1/memories:recall?query=… 一次拿到两类结果 entities[ ] self · Person Employment → organization: Acme Location → city: 上海 每个组件带 validFromMs 与 epistemicStatus Acme · Organization memories[ ] summary: "我上个月搬到上海,现在在 Acme 当架构师。" occurredAtMs: "1794968245880" 原文逐字保留,按相关度与新鲜度排序
写进去一句话,读回来两层。原文写入后立刻可读;组件由后台抽取产生,通常几秒后出现。未启用抽取的部署只有原文这一层。

四个接口

接口作用常见用途
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":"…"} 就说明通了。