重复的召回，只需十分之一的价格。

按请求选择开启后，WOS 会以查询文本为键缓存检索结果，规则与 LLM 提示词缓存相同的前缀方式。缓存有效期间，重复或续写的查询会复用上一次的结果，缓存部分按正常 token 单价的 10% 计费。

一段对话，三个回合

当代理持续与记忆对话时，实际发生的事情如下。每个回合都把到目前为止的对话作为查询发送，并开启 cache_control。

费率

能省多少

一个具体的例子：你的代理把一段 3,000 token 的对话作为查询发送，并在五分钟内重复或续写 10 次。没有缓存时，是按全价计费的 30,000 输入 token。开启 5 分钟缓存后，第一次写入 6,000（2 倍）加上九次缓存读取约 2,700，共计 8,700 计费 token，节省 71%。对话越长，省得越多。

前缀规则

匹配以查询的开头为准。如果开头保持不变、只是在末尾追加了新文本，缓存部分会被复用，只检索新的部分。如果缓存文本结束之前的任何内容发生变化，则什么都无法复用。

cached    [ A B C D E F G ]

○   [ A B C D E F G ] E
✗   [ B C D E F G ] E

○ 命中 - 开头不变，只有 E 是新的部分
✗ 未命中 - 开头变了，整个查询将重新检索并重新缓存

要记住的三条规则

• 续写会连同新尾部一起重新缓存。 在 [A B C D E F G] + E 之后，缓存以 E 结尾：尾部按写入费率计费一次，下一轮可以把 A 到 E 的全部内容再次作为前缀匹配。
• 每个请求只有一个连续前缀。 一个查询不能拆成两段缓存，只有开头才能匹配。
• 写入会立即失效缓存。 任何 store、store-turn、bulk-store、forget、supersede 或删除存储的操作都会丢弃该存储的缓存，缓存的答案绝不会返回过时的记忆。

如何开启

hits = mem.search(
    "...the conversation so far...", user_id="alice",
    cache_control={"ttl": "5m"},   # or "1h"
)

const hits = await mem.search(
  "...the conversation so far...", "alice", 10,
  { cache_control: { ttl: "5m" } },   // or "1h"
);

let hits = mem.search_with(
    "...the conversation so far...", "alice", 10,
    serde_json::json!({"cache_control": {"ttl": "5m"}}),   // or "1h"
).await?;

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":"...the conversation so far...",
       "cache_control":{"ttl":"5m"}}'   # or "1h"

{ "memories": [ ... ],
  "cache": { "status": "hit",              // "write" | "hit" | "extend"
             "ttl": "5m",
             "cache_read_input_tokens": 412,
             "cache_creation_input_tokens": 0 } }

这些功能并不依赖 SDK。缓存只是一次 HTTP 调用上的一个字段，因此任何编程语言都能使用。curl 标签页就是通用配方，Python、TypeScript 和 Rust SDK 只是对同一个调用的便捷封装。