攒批写入
攒批写入(Buffer)用于把高频、碎片化的消息先缓冲起来,再批量整理成记忆。它帮助业务在实时对话、事件流等高频写入场景中大幅降低写入开销,同时让抽取出的记忆拥有更完整的上下文。
解决的问题
在未使用攒批写入时,高频消息写入场景可能出现以下问题:
每条消息单独写入时,每条都要消耗一次模型调用,成本高、速度慢。
碎片消息(如“嗯”、“好的”半句话)单独无法抽取出有价值的记忆。
高频写入场景下,写入接口成为 Agent 链路的瓶颈。
主要能力
能力 | 说明 |
自动攒批 | 消息写入后先进入缓冲区,积累到一定量或超过等待时间后自动整理入库,无需业务侧控制节奏。 |
按用户和标签分组 | 不同用户、不同 metadata 的消息分开攒批,互不混淆,入库后的记忆保留写入时的 metadata。 |
手动触发 | 会话结束等时机可以立即触发整理,不必等待自动触发。 |
状态可查 | 可以随时查询某个用户当前缓冲了多少消息、等待了多久。 |
节奏可调 | 攒批的触发节奏可以查看和调整,适配不同业务的消息量。 |
失败自动重试 | 整理失败的消息不会丢失,系统会自动重试直到成功。 |
适用场景
实时对话流:用户消息逐条到达,希望降低写入成本。
IoT / 事件流:设备上报高频事件,需要攒够一批再形成记忆。
多轮短消息会话:单条消息信息量低,合并后才能抽取出完整结论。
批量导入场景:对写入延迟不敏感、但对成本敏感的场景。
如何使用
操作 | 接口 | 说明 |
写入缓冲 | POST /memories/buffer | 参数与记忆写入一致,默认异步立即返回。 |
手动整理 | POST /memories/flush | 立即触发指定用户的批量整理。 |
查看缓冲状态 | GET /memories/buffer/status?user_id=xxx | 查看缓冲中的消息数量与等待时长。 |
查看攒批配置 | GET /memories/buffer/config | 查看当前攒批触发节奏。 |
调整攒批配置 | PUT /memories/buffer/config | 按需调整攒批节奏,修改即时生效。 |
写入时通过 async_mode 控制返回方式:默认 true(立即返回,后台处理);设为 false 时同步等待并返回完整结果,适合需要确认落库的关键写入。
缓冲中的消息在整理入库前不会被搜索到。需要“写入即可见”的消息请使用普通的 POST /memories 写入。
查看与调整攒批配置
查看当前配置:
curl -sS "${MEMORY_URL}/memories/buffer/config" \
-H "Authorization: Token ${MEMORY_API_KEY}"返回示例:
{
"char_threshold": 10000,
"time_threshold_seconds": 1800,
"scan_interval_seconds": 300,
"retry_alert_threshold": 5
}各参数说明如下:
char_threshold:触发整理所需的消息量(按字符数),单组缓冲消息累计达到该值即触发整理。
time_threshold_seconds:最长等待时间(秒),未达到消息量但超过该时间也会自动整理。
scan_interval_seconds:系统检查缓冲的间隔(秒)。
retry_alert_threshold:整理连续失败达到多少次时输出告警。
按需修改(只提交要调整的项,参数不合法时返回 400):
curl -sS -X PUT "${MEMORY_URL}/memories/buffer/config" \
-H "Authorization: Token ${MEMORY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"char_threshold": 5000}'示例
以下示例直接调用线上服务,连续写入 3 条碎片消息,再手动触发整理并查看结果。
API Key 建议通过环境变量传入,不要直接写在代码或公共文档中。
步骤一:配置服务地址和认证信息
export MEMORY_URL="https://api-longmemory-cn-beijing.opentrust.net"
export MEMORY_API_KEY="<替换为您的 API Key>"
export USER_ID="demo-user-001"步骤二:连续写入 3 条消息到缓冲
curl -sS -X POST "${MEMORY_URL}/memories/buffer" \
-H "Authorization: Token ${MEMORY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"我下周要去杭州出差"}],"user_id":"'${USER_ID}'","async_mode":false}'curl -sS -X POST "${MEMORY_URL}/memories/buffer" \
-H "Authorization: Token ${MEMORY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"顺便去看看西湖"}],"user_id":"'${USER_ID}'","async_mode":false}'curl -sS -X POST "${MEMORY_URL}/memories/buffer" \
-H "Authorization: Token ${MEMORY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"帮我推荐家西湖附近的酒店"}],"user_id":"'${USER_ID}'","async_mode":false}'同步模式下,消息进入缓冲时返回 status 为 buffered;若本次写入恰好触发整理,则返回 flush_triggered。
步骤三:手动触发整理
curl -sS -X POST "${MEMORY_URL}/memories/flush" \
-H "Authorization: Token ${MEMORY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"user_id":"'${USER_ID}'"}'接口返回 202,表示整理任务已接受并在后台执行。
步骤四:查看整理出的记忆
curl -sS "${MEMORY_URL}/memories?user_id=${USER_ID}" \
-H "Authorization: Token ${MEMORY_API_KEY}"三条碎片消息被合并理解,形成一条更完整的记忆:
{
"results": [
{
"memory": "用户下周要去杭州出差,计划顺便游览西湖,希望入住西湖附近的酒店。"
}
],
"total": 1
}如果逐条单独写入,这三条消息各自都难以形成有价值的记忆;攒批后一次性理解,既省调用又更完整。
使用建议
高频低值消息走攒批,关键事实走普通写入:“用户明确说了重要事项”这类一次性关键信息建议直接 POST /memories 立即入库。
会话结束时手动触发一次整理:避免残余消息等待超时才入库,保证记忆时效。
接受“写入到可检索”的延迟:攒批的本质是用实时性换成本与质量,对检索时效敏感的路径不要用攒批。
关键写入用同步模式:async_mode=false 可以拿到落库确认,更可靠。
按业务消息量调整攒批节奏:消息量小、希望记忆尽快入库时可调小 char_threshold;消息量大且对时效不敏感时可调大,进一步降低成本。
用状态接口做监控:pending 数量持续增长且等待时间过久时,说明该用户的消息量长期偏低,可考虑主动触发整理。