Explanation
读懂每一个响应字段
这一页不教你怎么调接口,只解释接口返回的东西为什么长这样。读完你应当能看懂任意一个 /v1/memories:recall 响应,并知道每个字段是从哪来的。
1. 记忆是原文,状态是结论
写进 World Machine 的任何一句话,首先都会被完整保存为一条记忆。原文不会被改写、摘要或覆盖,它在写入那一刻就固定下来。这份文档里「原文」「记忆」「memory」「event」指的都是同一个东西,返回时放在 memories[] 里,标识是 eventId。
字段名 summary 容易误解:它的内容是原文本身,不是摘要。
在这批原文之上,系统会尝试读出结构化状态:谁、处于什么状况、从什么时候起。状态不是原文的副本,而是从原文推出来的结论。
两者在接口里分成两组字段,这是理解整个产品最重要的一条分界线:
| 你看到的 | 来自哪里 | 会不会随模型升级而变 |
|---|---|---|
| memories[].summary | 原文逐字保存 | 不会 |
| entities[].components | 从原文抽取或推断 | 可能,新写入才会变化 |
当前对外接口写入的原文类型固定为 text.employment.v1,召回响应里的 eventType 就是这个值。原文能否变成状态,取决于服务端是否配置了抽取能力;未配置时原文照样被完整保存,只是没有对应实体出现。这决定了你第一次接入时会看到什么:原文写入后立刻可读,实体要等后台抽取完成才出现。
2. 实体是「谁」,组件是「关于它的什么」
实体(entity)指一个可以被指称的对象:一个人、一家公司、一个地点。每个实体有 entityId、canonicalName(规范名)、entityType,以及可能的 aliases。
组件(component)是挂在实体上的一组属性,带自己的类型名。一个人可以同时有 Employment(任职)和 Location(居住地),它们是两个独立组件,各自有独立的生效时间。
响应里组件放在 components 这个对象中,键的格式是 <组件类型>/<实例标识>,例如 Location/loc:home、Employment/emp:69df4761-…。同一类型允许多个实例时,键的后半段区分它们。取值时按键遍历,不要假设类型名是唯一的键。
一个实体可以只有一个头部信息、没有任何组件——刚被提及但还没有属性写入的组织就是这种形态。
3. 认知分级:这条信息凭什么可信
每条组件带一个 epistemicStatus,它是字符串,不是数字。分级决定这条记录在冲突时能不能压过别的记录,也决定调用方该怎么看待它。
| epistemicStatus | 含义 | 典型来源 |
|---|---|---|
| observed_fact | 经过验证的客观事实 | 具备验证权限的写入 |
| stated_claim | 某一方单方面的陈述 | 对外接口的默认等级 |
| inferred_belief | 从其他信息推断出来的结论 | 抽取与推理 |
| hypothetical_simulation | 假设情景下的值 | 推演,不出现在对外接口 |
| disputed_claim | 有争议、待裁定的陈述 | 冲突旁路 |
| unknown | 无法归类,解析时也要处理这个值 | 历史数据 |
对外接口写入的原文一律记为 stated_claim。这是刻意的:一句话被记录下来,代表「有人这么说过」,不代表「世界确实如此」。所以你从 /v1/memories:recall 拿到的组件,epistemicStatus 基本都是 stated_claim。
stated_claim 只够支撑「用户这么说过」,不够支撑「必须如此」。对外接口不产生 observed_fact,所以这类判断要在你自己的业务侧补确认,不要指望召回结果本身带验证。4. 两个时间:现实什么时候成立,系统什么时候知道
每个组件有两个时间字段,它们回答不同的问题:
| 字段 | 回答的问题 | 缺省 |
|---|---|---|
| validFromMs | 这件事从什么时候起在现实里成立 | 写入时刻 |
| validToMs | 到什么时候为止成立;0 表示至今有效 | 0(开放区间) |
这是一条有效时间轴,只有它出现在对外字段里。上游系统内部还维护另一条「系统什么时候知道这件事」的轴,那属于实现细节,不通过这四个接口暴露。
查询接口里的 asOfValidTimeMs 就是沿有效时间轴取快照:给它一个过去的时间点,返回的是那一刻成立的状态。
asOfValidTimeMs 时取当前时刻,这也是查询接口的常用形态。写入时传入的 occurredAtMs 决定这条原文的发生时刻,抽取出的组件从该时刻开始生效。写入时还要传 timezone,因为「上个月」这类相对表达需要落在说话人所在地的日历日上,而不是服务器所在地。
5. 身份不在请求体里,在凭证里
四个接口的请求体都没有租户、用户这类标识字段。这些值全部从 Authorization: Bearer <token> 推出。你只需要关心「这份凭证是谁的」,不需要、也无从指定别人的身份。
这条设计带来三个可以直接观察到的行为:
- 改请求体不能越权。在 JSON 里加
tenantId或userId不会切换到别的租户,而是直接返回400 invalid_argument,提示unknown field。请求体里的未知字段一律拒绝,不静默忽略。 - 数据按人隔离,不按 token 隔离。归属由凭证解析出的那个人决定:不同的人互相看不到对方的数据;如果两份凭证解析到同一个人,它们看到的是同一份数据。
- 删除没有「删谁」这个参数。
DELETE /v1/users/me/data里没有 user 路径段,被删的永远是凭证对应的那个人。
6. 召回怎么排序,以及上限怎么生效
GET /v1/memories:recall 同时返回两类东西:entities 和 memories。它们的排序与截断规则不同。
memories 是多路评分融合的结果
memories 的排序不是简单的时间倒序。服务端把三路候选合并打分:与 query 的词法相似度、语义向量距离、以及按发生时间衰减的新鲜度。三路各自排名后加权,分高的在前。
这个设计的效果是:一段很久以前说过、但和当前查询高度相关的原文,可能排在昨天一句无关的话之前。返回顺序与时间远近不成单调关系。
occurredAtMs 自己排序;要精确取某个实体,用实体接口按 ID 直取。entities 按相关度排序,受 maxEntities 截断
entities 的候选来自实体名与查询词的匹配,再按拓扑关系与新鲜度打分排序。相关的实体排前面,但与查询词无关的实体也可能出现——当没有比它更相关的候选时,系统宁可多给,也不返回空。
| 参数 | 作用对象 | 缺省 / 上限 |
|---|---|---|
| query | 实体的候选与排序 | 必填 |
| maxEntities | 返回的实体条数 | 缺省 20,上限 100 |
| maxEvents | 返回的记忆条数 | 缺省 20,上限 100 |
| asOfValidTimeMs | 两侧的时间快照 | 缺省为当前时刻 |
maxEntities=0 不是「取零条」。传 0 或超过 100 都会被替换成缺省值 20。想限制条数就传 1..100。7. 数值都是字符串,这是协议约定
响应里的 64 位整数以 JSON 字符串出现:"occurredAtMs":"1794968245880",而不是数字。这是 proto3 的 JSON 映射要求,目的是避免 JavaScript 等语言在大整数上丢精度。
处理方式很直接:解析时按字符串读,需要运算时再转。不要用「判断类型是不是 number」的宽松解析,否则你会在这类字段上失败。
请求方向是自由的:occurredAtMs 在 JSON body 里直接写数字即可,URL 查询参数 asOfValidTimeMs 同样用数字,例如 ?asOfValidTimeMs=1790784000000。两处都只接受整数,单位是毫秒。