World MachineAPI v1

Tutorial

二十分钟,走通四个接口

这是一次完整的学习路径,不是为了解决某个具体问题。按顺序做完,你会亲手写入一条记忆、看到它变成结构化状态、把它召回,最后把自己的数据擦掉。每一步都能复制粘贴执行。

前置知识:会用 curl;看得懂 JSON 需要:一个 API 凭证 耗时:约 20 分钟

开始之前

你需要两样东西。第一,服务地址:https://api.worldmachine.dev,下文统一写作 $WM_API。第二,一个调用凭证,下文写作 $WM_TOKEN。

凭证需要向接入方申请,本套接口不包含自助注册或签发。凭证代表一个人,不要多人共用一个。

# 设好这两个变量,后面的命令直接复制就能跑
export WM_API='https://api.worldmachine.dev'
export WM_TOKEN='你的凭证'

凭证决定你能看到谁的数据,请求体里不需要也不允许出现用户或租户标识。如果凭证无效,你会拿到:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":{"code":"unauthenticated","message":"unauthenticated"}}

先跑一次第 1 步的写入确认凭证可用,再往下走。

建议用另一个人的凭证来做这个教程。第 5 步会真的删掉这个凭证名下的所有数据,之后任何属于这个人的凭证都会被拒绝。只换一个新 token 不解决问题——数据按人隔离,同一人的 token 共享同一份数据。

STEP 1写入一条记忆

写入接口接收一句自然语言陈述。text 必需,其余可选。

curl -sS -X POST "$WM_API/v1/memories" \
  -H "Authorization: Bearer $WM_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: tutorial-001' \
  -d '{
    "text": "我上个月刚从北京搬到上海,现在在 Acme 当架构师。",
    "source": "chat",
    "timezone": "Asia/Shanghai"
  }'

你会得到:

{"eventId": "0136159b-eb97-54b5-a05d-e37619881c70"}

记下这个 eventId,后面要用。响应里没有 deduplicated 字段,说明这是一次新写入;如果是重放,会变成 {"eventId":"…", "deduplicated":true}。

三个字段为什么要这么填

字段为什么填
text原文逐字保存。这段文字里同时包含人、组织、城市与相对时间,能演示后面的抽取效果。
timezone没有它,「上个月」会按服务器所在时区解释。写上 Asia/Shanghai,相对时间才会落在说话人的日历日上。
Idempotency-Key网络超时后你可以用同一个键重发,不会产生第二条记忆。不传也能工作,但这时重试的去重依赖内容完全一致。
幂等键的复用要小心。同一个键配不同内容会返回 409 conflict,不是覆盖。要改内容,用新键。

STEP 2确认它被存下

返回 200 时原文已经落盘,可以立刻读回。用召回接口看看。

curl -sS -G "$WM_API/v1/memories:recall" \
  --data-urlencode 'query=Acme' \
  --data-urlencode 'maxEvents=5' \
  -H "Authorization: Bearer $WM_TOKEN"

响应里这段原文会出现在 memories 中:

{
  "memories": [
    {
      "eventId": "0136159b-eb97-54b5-a05d-e37619881c70",
      "occurredAtMs": "1794968245880",
      "eventType": "text.employment.v1",
      "summary": "我上个月刚从北京搬到上海,现在在 Acme 当架构师。"
    }
  ]
}

到这里,"原文被存下来"这件事已经验证完了。注意 occurredAtMs 是字符串不是数字,这是协议约定。

如果你的响应里只有 memories、没有 entities,有两种可能。一是抽取还在进行:原文同步落盘,实体由后台抽取产生,通常几秒后出现,隔几秒重试召回即可。二是该部署没有启用抽取:这种情况下重试多久都不会有实体。两种情况都无法从接口上直接区分,如果持续没有实体,请联系接入方确认。

STEP 3读回结构化状态

原文要变成实体和组件,需要服务端具备抽取能力,而且要等后台抽取跑完。等几秒再召回一次,本该出现的实体大致长这样:

{
  "entities": [
    {
      "entityId": "ce7b7b0c-4dbd-5524-9392-13067cf6415c",
      "canonicalName": "self",
      "entityType": "Person",
      "components": {
        "Employment/emp:69df4761-c60a-5f01-86d7-8b884c69d2e4": {
          "componentType": "Employment",
          "schemaVersion": "wm.r1",
          "payload": { "organization": "Acme", "title": "架构师" },
          "validFromMs": "1794968245880",
          "confidence": 1,
          "epistemicStatus": "stated_claim"
        },
        "Location/loc:home": {
          "componentType": "Location",
          "schemaVersion": "wm.r1",
          "payload": { "category": "home", "city": "上海" },
          "validFromMs": "1790784000000",
          "confidence": 1,
          "epistemicStatus": "stated_claim"
        }
      }
    },
    {
      "entityId": "ecf5ec2f-ddbe-5453-98ff-5d5635a7911a",
      "canonicalName": "Acme",
      "entityType": "Organization"
    }
  ]
}

这段响应里有三处要注意:

  1. 两个实体,其中一个只有头部。Acme 被识别为组织,但这句话里没有任何关于它的属性,所以没有 components。这是正常形态。
  2. 两个组件的 validFromMs 不一样。任职信息从写入时刻起;居住地从「上个月」被解析出的日历月起点起,所以比写入时刻早。
  3. 等级是 stated_claim。这句话是用户说的,不是系统验证过的事实。

按 ID 单独读一个实体

拿到 entityId 之后,可以用实体接口精确读取:

curl -sS "$WM_API/v1/entities/ce7b7b0c-4dbd-5524-9392-13067cf6415c" \
  -H "Authorization: Bearer $WM_TOKEN"

返回结构是 {"entity": { … }},字段与上面 entities[] 中的一项完全一致。还可以加时间快照:

# 回到 2025-10-01 00:00(Asia/Shanghai)那一刻看这个实体
curl -sS "$WM_API/v1/entities/ce7b7b0c-4dbd-5524-9392-13067cf6415c?asOfValidTimeMs=1759248000000" \
  -H "Authorization: Bearer $WM_TOKEN"
如果那一刻实体还不存在,会返回 404 not_found。时间早于该实体被创建的时点就会 404。注意区分另一种情况:实体已存在但没有组件(第 3 步响应里的那个 Acme),按 ID 读会返回 200,只是响应里没有 components 字段,不是 404。

STEP 4召回一片世界

召回接口是 Agent 每轮取上下文时最常用的入口。它一次给你两类结果:实体(带全部组件)与原文。

curl -sS -G "$WM_API/v1/memories:recall" \
  --data-urlencode 'query=上海 工作' \
  --data-urlencode 'maxEntities=5' \
  --data-urlencode 'maxEvents=10' \
  -H "Authorization: Bearer $WM_TOKEN"

试着改几个值,观察响应怎么变:

试这个你会看到
maxEntities=1entities 只剩一条,最相关的那条。
maxEvents=1memories 只剩评分最高的一条,未必是时间最近的那条。
把 query 换成完全无关的词memories 仍会返回记录,只是排序变了——查询词影响权重,不做硬过滤。
省略 maxEntities按缺省值 20 返回。
无关的词为什么也能召回到。检索不是精确匹配:词法、语义与新鲜度三路打分后,总有记录能拿到名次,所以结果集很少为空。响应里不返回分数,你只能从顺序判断相关性,没法设阈值。需要精确取某一个实体时,用第 3 步的实体接口,它按 ID 直取。

量一下返回体积,决定要不要调 maxEntities:

curl -sS -G "$WM_API/v1/memories:recall" \
  --data-urlencode 'query=上海' \
  -H "Authorization: Bearer $WM_TOKEN" \
  | wc -c

STEP 5擦除自己的数据

最后一个接口没有参数。它删除凭证对应的那个人名下全部记录,并且进入抑制状态:之后再用同一个凭证调用任何接口,都会返回 permission_denied。

curl -sS -X DELETE "$WM_API/v1/users/me/data" \
  -H "Authorization: Bearer $WM_TOKEN"
{"completed": true}

验证一下确实生效了:

curl -sS -G "$WM_API/v1/memories:recall" \
  --data-urlencode 'query=Acme' \
  -H "Authorization: Bearer $WM_TOKEN"

# {"error":{"code":"permission_denied","message":"permission denied"}}
这一步不可撤销。擦除不是软删除,也不提供恢复接口。教程请用专用凭证;真实用户发起擦除时,要确认这就是他要的语义。

关于擦除的设计取向、以及它和「不返回数据」的区别,见操作指南 · 擦除与抑制。

你刚刚做了什么

步骤接口你验证的事实
1POST /v1/memories原文同步落盘,返回稳定 eventId
2GET /v1/memories:recall刚写的原文立即可读
3GET /v1/entities/{id}原文已被抽出实体、组件与生效时间
4GET /v1/memories:recall一次拿到实体与原文,条数受上限约束
5DELETE /v1/users/me/data擦除生效并进入抑制状态

接下来按你的任务查文档: