retrieval_id 标识已记录的一次结果列表展示,session_id 标识会话日志。将每个 retrieval_id 与对应列表一同保留,尤其是同一记忆出现在多个并行查询时。retrieval_id 为 null 表示该响应无法精确归因。只要回执、记忆和调用者仍满足访问条件,旧查询或已关闭会话也可接收显式反馈;不要重开源日志。
单次实际使用通过 engram_report_outcome 传入 memory_id、success、retrieval_id。批量使用 outcomes,最多 20 个唯一的查询/记忆组合。也可将相同条目作为 pending_feedback 附在下一次 start、recall、smarter、store、reflect、cross_pollinate、get_context、skill、report_outcome 调用中。需要 outcome:write,但不额外消耗调用配额。无法评价的条目应省略,不能编造结论。
重试精确反馈时,发送相同的 retrieval_id、memory_id 和实际使用字段。Engram 会在响应中返回 duplicate=true,不增加票数。duplicate 不是输入,也不存在 retry 开关。相同重试不报 409;只有修改已记录的使用票才返回 409。旧格式缺少 retrieval_id 时,会选取过去 24 小时内同一认证成员和工作区中,包含该记忆的最新展示。session_id 可把范围限制到指定日志。旧格式重试可能增加票数,这种推断不能当成精确关联。真正的新使用应有新的检索展示。
反馈批次先于主操作提交。即使主操作失败,也应查看 feedback_receipt,因为反馈可能已成功保存。远程 MCP 和 npm 客户端都会在错误中保留回执。已提交反馈后的错误不会自动重试,但主操作本身仍可能不具幂等性。reflect.used_memories 中,最多 20 个精确反馈条目必须各带 retrieval_id,作为一个原子批次提交;旧格式放到另一次 reflect 中。后续学习或检查点可能失败,feedback_receipt 会说明已接受的结果。
示例:将占位符替换为实际返回的值。
{
"repo": "example",
"query": "Which deployment rule applies?",
"pending_feedback": [
{
"retrieval_id": "<id from the previous result list>",
"memory_id": "<memory in that list>",
"relevance": "irrelevant",
"usefulness": "not_used"
}
]
}
推荐:精确关联检索的使用结果(engram_reflect 参数)
{
"store": false,
"summary": "Applied the recalled approval rule.",
"used_memories": [
{
"retrieval_id": "<id from that result list>",
"memory_id": "<memory in that list>",
"success": true,
"detail": "Checked owner approval before releasing."
}
]
}
仅用于兼容:单独提交旧格式反馈(engram_reflect 参数)
{
"store": false,
"summary": "Reported a use without a retained query receipt.",
"used_memories": [
{
"memory_id": "<accessible memory id>",
"success": true,
"detail": "This use has inferred attribution, not an exact query link."
}
]
}