Tutorial
二十分钟,走通四个接口
这是一次完整的学习路径,不是为了解决某个具体问题。按顺序做完,你会亲手写入一条记忆、看到它变成结构化状态、把它召回,最后把自己的数据擦掉。每一步都能复制粘贴执行。
开始之前
你需要两样东西。第一,服务地址: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 步的写入确认凭证可用,再往下走。
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"
}
]
}
这段响应里有三处要注意:
- 两个实体,其中一个只有头部。Acme 被识别为组织,但这句话里没有任何关于它的属性,所以没有
components。这是正常形态。 - 两个组件的
validFromMs不一样。任职信息从写入时刻起;居住地从「上个月」被解析出的日历月起点起,所以比写入时刻早。 - 等级是
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=1 | entities 只剩一条,最相关的那条。 |
maxEvents=1 | memories 只剩评分最高的一条,未必是时间最近的那条。 |
把 query 换成完全无关的词 | memories 仍会返回记录,只是排序变了——查询词影响权重,不做硬过滤。 |
省略 maxEntities | 按缺省值 20 返回。 |
量一下返回体积,决定要不要调 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"}}
关于擦除的设计取向、以及它和「不返回数据」的区别,见操作指南 · 擦除与抑制。
你刚刚做了什么
| 步骤 | 接口 | 你验证的事实 |
|---|---|---|
| 1 | POST /v1/memories | 原文同步落盘,返回稳定 eventId |
| 2 | GET /v1/memories:recall | 刚写的原文立即可读 |
| 3 | GET /v1/entities/{id} | 原文已被抽出实体、组件与生效时间 |
| 4 | GET /v1/memories:recall | 一次拿到实体与原文,条数受上限约束 |
| 5 | DELETE /v1/users/me/data | 擦除生效并进入抑制状态 |
接下来按你的任务查文档: