curl

curl - 无需安装，同样的方法。

无需安装 SDK - 任何 HTTP 客户端都可用。设置一次密钥，即可调用 SDK 所封装的相同端点。基础 URL 为 https://api.wontopos.com，通过 X-API-Key 认证，请求与响应均为 JSON。

# set your key once (never hard-code it)
export WOS_API_KEY="wos-live-..."

写入

store

存储一条记忆。写入时即完成索引 - 不调用 LLM。

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"}'
真实响应
{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

store-turn

把一轮对话（用户 + 助手）同时写入短期与长期记忆。

curl -X POST https://api.wontopos.com/api/v1/memory/store-turn \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","user_msg":"hi","assistant_msg":"hello!"}'
真实响应
{"status": "ok"}

speaker

每条记忆都可以记录说话者。先注册一个人，之后把名字作为 speaker 传入；"me"（助手自己的话）无需注册。搜索也接受 speaker，可以只取某个人说过的话。

curl -X POST https://api.wontopos.com/api/v1/memory/speakers \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","speaker":"Bob"}'   # once per person

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":"I promised to send the report on Friday","metadata":{"speaker":"me"}}'

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":"Bob said the deadline moved to Tuesday","metadata":{"speaker":"Bob"}}'

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what did Bob say about deadlines?","speaker":"Bob"}'
说话者和存储库一样是显式的。先注册，再以其名字保存。拼写错误绝不会悄悄变成一个新人。每个存储库起步可注册 50 人（会逐步提高），"me" 永远无需注册也不计数。

supersede

某个事实变了 - 旧记忆被标记为已取代，新记忆在召回中取而代之。

curl -X POST https://api.wontopos.com/api/v1/memory/supersede \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","old_memory_id":"576700aa-...","new_content":"she switched to coffee this year"}'
真实响应
{"new_memory_id": "07e94433-...", "old_memory_id": "576700aa-...", "status": "superseded"}

bulk-store

一次调用回填长历史 - 服务端完成分块与索引。

curl -X POST https://api.wontopos.com/api/v1/memory/bulk-store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"...a long history...","category":"general"}'
真实响应
{"elapsed_secs": 0.138589761, "status": "ok", "stored": 1, "total_chunks": 1}

Idempotency-Key

让同一次写入可以安全重复。当重试来自你这边时使用 - 中断后重跑的任务、会重投的队列。

# same key + same body = the FIRST response is replayed, nothing is stored twice
curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: import:row-42" \
  -d '{"user_id":"alice","content":"she prefers tea over coffee"}'
密钥要从被存储的对象派生（import:row-42），不要用常量：两次不同的写入复用同一密钥会重放第一次的响应，第二次会被悄悄丢弃。格式：1-128 个 [A-Za-z0-9._:-] 字符。

读取

search

语义搜索，最相关的排在最前。任何语言都能找到任何记忆。

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does she drink?","max_results":1}'
真实响应
{"memories": [{"id": "576700aa-...", "content": "she prefers tea over coffee",
   "similarity": 0.63, "is_superseded": false}], "search_ms": 315, "total_found": 1}

search + filters

把搜索收窄到存储的一部分。在排序之前应用，因此得到的是过滤范围内最相关的结果 - 而不是对 top-N 再做过滤。

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what did we decide",
       "filters":{"categories":["work"],"event_from":"2026-01-01","event_to":"2026-06-30"}}'
键：categories · event_from / event_to（内容发生的时间 - metadata.event_date）· time_from / time_to（写入的时间）· min_importance。未列出的键会被丢弃而不是报错，所以拼错会悄悄扩大搜索范围。

get

用 store 或 list 返回的 id 读取单条记忆 - 只有原文与元数据。

curl -X POST https://api.wontopos.com/api/v1/memory/get \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","memory_id":"576700aa-f0e0-4c26-99a0-10e2d5b0d624"}'

list

按游标逐页浏览存储中的全部内容。可用于浏览或导出。

curl -X POST https://api.wontopos.com/api/v1/memory/list \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","limit":100}'   # pass next_cursor back for the next page
真实响应
{"count": 3, "memories": [{"id": "1a1cfc47-...", "content": "...", "category": "general",
   "created_at": "2026-07-31T18:04:51.937117314+00:00", "event_date": null, "is_superseded": false}],
 "next_cursor": "722c08e5-8998-4882-979e-d71995b5b4af", "user_id": "docs_livetest"}

recall

一次往返返回短期 + 长期 + 上下文 + 一条 instruction。直接粘贴进您的提示词即可。

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 she drink?"}'
真实响应（结构）
{"short_term": {"count": 2, "turns": [...]},
 "long_term":  {"count": 4, "memories": [{"content": "she prefers tea over coffee", "similarity": 0.63}]},
 "context":    {"count": 4, "around_top_memory": ["[match] she prefers tea over coffee"]},
 "instruction": "Use short_term for recent context, long_term for relevant past memories..."}

删除

forget

按 id 删除单条记忆，或省略 id 以删除该用户的全部数据（GDPR）。

curl -X POST https://api.wontopos.com/api/v1/memory/forget \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice"}'  # omit memory_id = delete all
真实响应
{"memories_deleted": 1, "status": "deleted", "user_id": "alice"}

全部端点与请求体字段 →

仅 Rust 的变体方法

Python 和 TypeScript 将这些作为可选参数。稳定版 Rust 没有默认参数和关键字参数，因此每一项都是独立的方法，而不是需要你收尾的构建器。

mem.add_with(text, None, json!({}), extra)   // add + extra body fields
mem.search_opts(q, None, 10, &opts)            // search + verify / max_images
mem.search_with(q, None, 10, extra)            // search + any other field
mem.recall_with(q, None, extra)                // recall + extra
mem.search_self_with(q, None, 10, extra)       // self lane + extra
mem.engram_with(name, q, None, extra)          // engram + extra
mem.update_idempotent(old, new, None, key)     // update + Idempotency-Key
mem.add_turn_idempotent(u, a, None, key)
mem.add_bulk_idempotent(text, None, cat, key)
mem.revisions_page(None, "revised", 20, None, None)
mem.list_all_images(None, None)              // = iter_images, collected

list_all_images 同时以 iter_images 的名称导出，与另外两个 SDK 使用的名称一致，从那些文档过来的读者会先输入这个名称。