Reference
接口参考
四个接口的完整定义。字段名、类型、取值范围与错误码均按当前服务实现列出。
总览
| 方法 | 路径 | 作用 |
|---|---|---|
| POST | /v1/memories | 写入一条原文记忆 |
| GET | /v1/entities/{entityId} | 按 ID 读一个实体 |
| GET | /v1/memories:recall | 按查询召回实体与记忆 |
| DELETE | /v1/users/me/data | 擦除当前凭证主体的全部数据 |
四个接口都不接受身份字段。租户与用户从 Authorization: Bearer <token> 派生。
Authorization: Bearer $WM_TOKEN Content-Type: application/json
写记忆
POST
/v1/memories
写入一条原文
请求头
| 头 | 必需 | 说明 |
|---|---|---|
| Authorization | 是 | Bearer <token> |
| Content-Type | 是 | application/json |
| Idempotency-Key | 否 | 幂等键,每条不同的写入各用一个。格式 [A-Za-z0-9][A-Za-z0-9_.:@-]{0,127};不合法返回 400。省略时按内容派生 |
请求体
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
| text | string | 是 | 自然语言陈述,去除首尾空白后长度 1..8192 字节 |
| occurredAtMs | int64 | 否 | 发生时刻,epoch 毫秒。省略取服务器当前时间;负数或超过当前时间 24 小时返回 400 |
| source | string | 否 | 来源标签,如 crm、chat。原样保存 |
| metadata | object | 否 | 任意 JSON 对象,原样保存,不参与解释与检索 |
| timezone | string | 否 | IANA 时区名,如 Asia/Shanghai。缺省按 UTC。非法值返回 400 |
请求体出现未定义字段时返回 400,不静默忽略。
响应 200
| 字段 | 类型 | 说明 |
|---|---|---|
| eventId | string | 该条记忆的稳定标识。同一幂等键重放时保持不变 |
| deduplicated | bool | 仅在重放时为 true;首次写入时该字段不出现 |
{"eventId": "0136159b-eb97-54b5-a05d-e37619881c70"}
写入是同步的:返回 200 时原文已经可以被召回接口读到。结构化状态可能在稍后由抽取产生,本接口不承诺实体已经存在。
读实体
GET
/v1/entities/{entityId}
按 ID 读一个实体
参数
| 参数 | 位置 | 必需 | 说明 |
|---|---|---|---|
| entityId | path | 是 | 实体标识,来自召回或写入后的响应 |
| asOfValidTimeMs | query | 否 | 返回该时刻成立的状态。省略为当前时刻;负数返回 400;未来时间可以传 |
响应 200
{ "entity": { …见 EntityView } }
实体在该时刻还不存在时返回 404 not_found。判断依据是实体头部本身:如果一个实体在指定时刻之前尚未被创建,就是 404;如果它已存在但没有任何组件(例如刚被提及的组织),返回 200,且响应里没有 components 字段(空对象按协议省略,不会出现 {})。可见性之外的数据同样返回 404,而不是 403——存在性本身也是信息。
curl -sS "$WM_API/v1/entities/ce7b7b0c-4dbd-5524-9392-13067cf6415c?asOfValidTimeMs=1759248000000" \ -H "Authorization: Bearer $WM_TOKEN"
召回
GET
/v1/memories:recall
按查询召回实体与记忆
参数
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
| query | string | 是 | 自然语言查询,上限 8192 字节(URL 编码后计入,过长会先撞上 400)。空或全空白返回 400 |
| maxEntities | uint32 | 否 | 实体条数上限。缺省 20、硬上限 100;传 0 或超过 100 时替换为缺省值 20 |
| maxEvents | uint32 | 否 | 记忆条数上限。缺省 20、硬上限 100;传 0 或超过 100 时同样替换为 20 |
| asOfValidTimeMs | int64 | 否 | 有效时间快照,同时作用于 entities 和 memories:晚于该时刻发生的原文不会返回。省略为当前时刻;负数返回 400;未来时间可以传 |
响应 200
| 字段 | 类型 | 说明 |
|---|---|---|
| entities | EntityView[] | 按相关度排序的实体,含全部组件。可能为空 |
| memories | MemoryView[] | 原文列表,按词法相似度、向量距离与时间新鲜度三路融合评分排序。query 参与打分,但这里是排序权重而非硬过滤 |
两类结果都受各自的上限约束,且都不返回总数或游标。
{ "entities": [ … ], "memories": [ … ] }
擦除
DELETE
/v1/users/me/data
擦除当前主体全部数据
没有参数,也没有请求体。被擦除的主体由凭证决定。
响应 200
{"completed": true}
成功后,该主体进入抑制状态:其后用任何指向这个人的凭证调用任何接口都返回 403 permission_denied,换一份同属此人的凭证也不例外;上游重放历史事件也不会使数据复活。擦除不可撤销,没有恢复接口。
数据模型 · EntityView
| 字段 | 类型 | 说明 |
|---|---|---|
| entityId | string | 实体标识,稳定不变 |
| canonicalName | string | 规范名。当前用户本人的实体规范名是 self,通过召回结果按名字筛选即可定位;没有按名字直查的接口 |
| entityType | string | 类型,如 Person、Organization。可能为空 |
| aliases | string[] | 别名。无别名时该字段不出现 |
| components | object<string, ComponentView> | 以 <类型>/<实例> 为键。实体只有头部时该字段不出现,解析时请给缺省分支 |
不要在代码里假设
entityType 非空。刚被提及、尚未归类实体会没有类型。判断类型时给缺省分支。数据模型 · ComponentView
| 字段 | 类型 | 说明 |
|---|---|---|
| componentType | string | 组件类型,如 Employment、Location |
| schemaVersion | string | 该组件使用的结构版本,如 wm.r1 |
| payload | object | 属性键值,结构由 componentType 与 schemaVersion 决定 |
| validFromMs | int64(字符串) | 生效时刻 |
| validToMs | int64(字符串) | 失效时刻;0 或缺省表示至今有效 |
| confidence | float | 抽取给出的置信度,0..1。可选字段,缺省时该字段不出现;示例数据里为 1。不要用它做召回阈值,召回不返回相关度分数 |
| epistemicStatus | string | 认知分级,见下 |
epistemicStatus 取值
| 值 | 含义 |
|---|---|
| observed_fact | 经过验证的客观事实 |
| stated_claim | 单方陈述。对外接口写入的默认等级 |
| inferred_belief | 推断得出的结论 |
| hypothetical_simulation | 假设情景下的值 |
| disputed_claim | 有争议、待裁定 |
| unknown | 无法归类。解析时必须处理这个取值,不要假设只有上面五种 |
数据模型 · MemoryView
| 字段 | 类型 | 说明 |
|---|---|---|
| eventId | string | 记忆标识,与写入响应的 eventId 一致 |
| occurredAtMs | int64(字符串) | 发生时刻 |
| eventType | string | 原文类型。对外写入为 text.employment.v1 |
| summary | string | 原文内容,即写入时提交的 text |
| affectedEntityIds | string[] | 该记忆影响到的实体。无关联时该字段不出现 |
错误码
所有错误共用一个信封,包括 401:
{"error": {"code": "invalid_argument", "message": "invalid argument: text must be 1..8192 bytes"}}
| code | HTTP | 触发条件 |
|---|---|---|
| invalid_argument | 400 | 缺少必需参数、超长、时区非法、幂等键格式非法、请求体含未知字段 |
| unauthenticated | 401 | 缺少 Authorization 头,或凭证无法识别 |
| permission_denied | 403 | 凭证有效,但该主体已进入抑制状态 |
| not_found | 404 | 实体不存在,或在指定时刻不存在 |
| conflict | 409 | 同一幂等键配了不同内容 |
| unsupported | 501 | 该部署缺少请求所依赖的后端能力。四个接口的正常路径不会返回它,因此不能靠它探测是否启用了抽取 |
| unavailable | 503 | 依赖暂时不可用 |
| deadline_exceeded | 504 | 服务端等待超时 |
| canceled | 499 | 客户端提前断开 |
| internal | 500 | 未归类的内部错误。不返回细节 |
message 是给人读的诊断文本,措辞可能变化。程序逻辑请只依赖 code。
编码与类型
| 约定 | 细节 |
|---|---|
| 64 位整数 | 响应中一律是 JSON 字符串,如 "occurredAtMs":"1794968245880"。请求体可直接写数字 |
| 字段命名 | JSON 使用 lowerCamelCase,如 entityId、validFromMs |
| 空值字段 | 协议默认省略零值:validToMs 为 0、aliases 为空时字段不出现。解析时按缺省处理,不要当成错误 |
| 时间单位 | 全部为 epoch 毫秒 |
| 未知字段 | 请求体中的未知字段导致 400 |
| 请求体上限 | 4 MiB。而 text 只占 8192 字节,其余空间留给 metadata |
OpenAPI 3.1 描述文件暂未公开。本页覆盖上面四个路径与全部模型,字段以本页为准;需要机器可读文件时向服务方索取。
限制
以下是当前接口的硬约束,写入代码前先确认它们不会挡住你的用法。
| 项 | 当前行为 |
|---|---|
| 写入粒度 | 一次请求一条记忆,没有批量接口 |
| 文本长度 | 1..8192 字节 |
| 查询结果条数 | 每类上限 100,无分页游标,不返回总数 |
| 查询词的作用 | 影响 entities 的候选与 memories 的排序权重,但不做硬过滤:无关查询仍会返回结果 |
| 未来时间写入 | 上限为当前时间 + 24 小时 |
| 擦除 | 主体级、不可撤销、无恢复接口;之后同一凭证返回 403 |
| 结构化抽取 | 取决于部署是否配置抽取能力;未配置时只有原文,没有实体 |
| 分支与推演 | 不通过对外接口提供 |
| 跨用户读取 | 不存在。一份凭证只能访问一个主体空间 |