所有端点，一个基础 URL。
无需 SDK - 任何 HTTP 客户端都可用。基础 URL 为 https://api.wontopos.com，通过 X-API-Key 请求头认证，请求与响应均为 JSON。记忆操作均为 POST；存储库管理使用 /collection 上的 POST / GET / DELETE。存储库必须先存在（见存储库），否则库内操作返回 404。
请求头
| 请求头 | 作用 |
|---|---|
| X-API-Key | 每次调用都必需。您的密钥，在控制台签发。 |
| X-WOS-Model | 可选。选择由哪个引擎作答。省略则使用账户的默认值。GET /api/v1/models 会列出您的密钥可以选择的模型；更早的引擎无法提供的端点会返回 501，并指出是哪个模型。 |
| Idempotency-Key | 写入时可选。同一密钥配同一请求体时不会重复存储，而是重放首次响应 - 见下面的说明。 |
端点
| 端点 | 用途 | 请求体字段 |
|---|---|---|
| POST /api/v1/memory/collection | 创建存储库 | user_id |
| GET /api/v1/memory/collections | 列出您的存储库 | （无） |
| DELETE /api/v1/memory/collection | 删除存储库及其全部记忆 | user_id |
| /api/v1/memory/store | 存储一条记忆 | user_id · content · metadata? (event_date · speaker) · image? |
| /api/v1/memory/store-turn | 存储一轮对话 | user_id · user_msg · assistant_msg |
| POST /api/v1/memory/speakers | 注册说话者（显式，最多 50 人） | user_id · speaker |
| GET /api/v1/memory/speakers | 列出已注册说话者 + 记忆数 | user_id |
| DELETE /api/v1/memory/speakers | 注销说话者（记忆保留） | user_id · speaker |
| /api/v1/memory/by-speaker | 某个人说过的话，从最新开始（“me” = 智能体自己） | user_id · speaker · limit? · before? · skip_ids? |
| POST /api/v1/memory/image | 图像记忆中我们保存的那张图（不是原图） | user_id · memory_id |
| DELETE /api/v1/memory/image | 删除图像，保留文字 | user_id · memory_id · preview? |
| /api/v1/memory/images | 某个存储的图像，从最新开始（+ 总数） | user_id · limit? · before? · skip_ids? |
| /api/v1/memory/lineage | 一条记忆的修改链，从最早开始 | user_id · memory_id |
| GET /api/v1/won/usage | 此密钥的花费与剩余余额 — 供模型判断是否继续。免费。 | days? |
| GET /api/v1/memory/usage | 此密钥的花费与剩余余额 — 供模型判断是否继续。免费。 | days? |
| /api/v1/won/revisions | 某个存储被改写了多少。免费 | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/revisions | 同一调用在 memory 平面下的名字。免费 | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/bulk-store | 回填一段文本 | user_id · content · category? · timestamp? |
| /api/v1/memory/search | 语义搜索 | user_id · query · max_results? · speaker? · cache_control? · filters? · verify? · max_images? |
| /api/v1/memory/recall | 短期 + 长期 + 上下文 | user_id · query · limit? · context_limit? |
| /api/v1/memory/get | 按 id 取单条记忆 | user_id · memory_id |
| /api/v1/memory/list | 分页浏览存储 | user_id · limit? · cursor? |
| /api/v1/memory/history | 最近的对话轮次 | user_id |
| /api/v1/memory/stats | 记忆条数统计 | user_id |
| /api/v1/memory/supersede | 替换已变更的事实 | user_id · old_memory_id · new_content |
| /api/v1/memory/forget | 删除一条（或全部） | user_id · memory_id? （省略 = 全部删除） |
| GET /api/v1/engram | 该模型可运行的 engram | （无） |
| POST /api/v1/engram/run | 运行一个 engram | name · user_id · query · form? · tz? |
| GET /api/v1/models | 可用模型 | （无） |
写入请求接受
Idempotency-Key 头。同一密钥配同一请求体时不会重复存储，而是重放首次响应（10 分钟）；同一密钥配不同请求体则返回 422。仅缓存 2xx，因此失败的调用可以立即重试。# create the store once (stores are explicit) curl -X POST https://api.wontopos.com/api/v1/memory/collection \ -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"alice"}' # store a memory curl -X POST https://api.wontopos.com/api/v1/memory/store \ -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"alice","content":"she prefers tea over coffee"}' # recall - one call, ready for your prompt curl -X POST https://api.wontopos.com/api/v1/memory/recall \ -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"alice","query":"what does alice drink?"}'
真实响应 - store
{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}