World MachineREST API v1

Agent 记得的,应该是世界的样子。

把自然语言记忆写成实体与组件,每个属性带自己的生效时间。四个 HTTP 接口:写入、读实体、召回、擦除。

对外接口
4 个

写入 / 读实体 / 召回 / 擦除

写入延迟
同步

返回 eventId 即可召回

时间语义
validFrom

每个组件各自生效

数据边界
1 人

一份凭证只看到一个主体空间

存文本切片,只能回答「谁说过什么」。

Agent 出错往往不是读得不够多,而是拿到的是一堆互相矛盾的历史片段,也不知道哪条还算数。

维度
文本记忆 / 向量检索
World Machine
数据形态
文本切片,新旧信息冲突时两条都在,读的人自己判断。
实体与组件。同一实体的属性挂在组件上,各自带生效时间。
时间
只有写入时间,回答不了「上个月他住哪」。
有效时间。asOfValidTimeMs 取任意历史时刻的状态。
可信度
所有片段同等对待,没有「这是谁说的」的区分。
认知分级。每个组件标注 stated_claim 等状态,应用层据此决定要不要二次确认。
原文
切片被改写、摘要,追溯不到原话。
原文逐字保留。结构化状态是推出来的,原文不改写,两者一起返回。

一次写入,三个时刻。

左侧切换场景,右侧逐步发生。演示用真实接口的字段,数据是示意。

world · 写入后依次发生的事

切换场景会重放整条链路

调用过程

    响应 · 结构化部分

    字段名与接口一致,数据为示意 完整示例见文档教程

    四个接口,覆盖写入到擦除。

    没有「列出全部实体」,也没有批量写入。少一点接口,语义就少一点歧义。

    POST

    写入一条记忆

    /v1/memories

    一句话加可选的来源、时间与时区。返回 eventId,支持 Idempotency-Key 安全重试。

    GET

    读一个实体

    /v1/entities/{entityId}

    已知 ID 时直取,拿到全部组件与各自的生效时间。可加 asOfValidTimeMs 回到过去。

    GET

    召回

    /v1/memories:recall

    不确定 ID 时的入口。一次返回实体与原文,条数受 maxEntities / maxEvents 约束。

    DELETE

    擦除本人数据

    /v1/users/me/data

    没有「删谁」这个参数。主体从凭证推出,擦除后进入抑制状态,重放也写不回来。

    接入从一个请求开始。

    服务地址是 https://api.worldmachine.dev。凭证需要向接入方申请,拿到后先发这一条确认链路通。

    # 把 $WM_TOKEN 换成发给你的凭证
    curl -sS -X POST "https://api.worldmachine.dev/v1/memories" \
      -H "Authorization: Bearer $WM_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"text":"我上个月搬到上海,现在在 Acme 当架构师。","timezone":"Asia/Shanghai"}'
    
    # {"eventId":"0136159b-eb97-54b5-a05d-e37619881c70"}

    接下来读什么

    • 教程:五步走通四个接口,每步可复制
    • 概念:实体与组件、认知分级、有效时间
    • 操作指南:批量导入、重试、错误处理、上线清单
    • 参考:字段、错误码、硬性限制

    几件容易踩的事

    • 原文立刻可读,实体要等后台抽取,通常几秒
    • maxEntities 传 0 或超过 100 会被替换成 20
    • 响应里的 64 位整数是字符串,不是数字
    • 擦除不可撤销,同一人的任何凭证都会被拒绝
    关于可用范围。抽取质量取决于服务端配置,未启用时只有原文层可用。具体能力以接入方告知为准,文档不承诺未验证的效果。