跳到主要内容

Retrieve API

POST /v1/users/:user_id/streams/:stream_id/retrieve​

对某个用户和 stream 执行混合检索。

这个路由用来做什么​

这是运行时最主要的 recall 接口。它不会只走一条检索路径，而是把多种信号融合起来。

可能参与的信号包括：

  • 语义相似度
  • 文本检索
  • 图谱扩展
  • 时间过滤
  • 组织知识
  • 多模态查询输入

请求​

POST /v1/users/dylan/streams/11111111-1111-1111-1111-111111111111/retrieve
Authorization: Bearer <token>
Content-Type: application/json

{
  "org_id": "default",
  "agent_id": "coding-assistant",
  "query": "What does Dylan prefer for systems work?",
  "limit": 10,
  "enable_arbitration": false,
  "min_score": 0.2,
  "graph_depth": 1,
  "start_time": "2026-03-01T00:00:00Z",
  "end_time": "2026-03-31T23:59:59Z",
  "as_of": "2026-03-25T12:00:00Z"
}

请求字段​

字段类型必填说明
querystring是检索查询文本
limitnumber否最大返回条数，服务端会限制上限
enable_arbitrationboolean否是否开启仲裁式检索
min_scorenumber否最低分数阈值
graph_depthnumber否图谱扩展深度
start_timeISO8601否有效时间起点
end_timeISO8601否有效时间终点
as_ofISO8601否事务时间点查询
org_idstring否是否带上组织共享知识
agent_idstring否偏向某个 agent 的程序性记忆
imagestring否Base64 图片，用于跨模态检索
audiostring否Base64 音频，用于跨模态检索
videostring否Base64 视频，用于跨模态检索

返回​

{
  "stream_id": "11111111-1111-1111-1111-111111111111",
  "query": "What does Dylan prefer for systems work?",
  "results": [
    {
      "unit": {
        "id": "9db1d859-0a32-4c33-8b94-8cab9f8e0d16",
        "memory_type": "Fact",
        "content": "Dylan prefers Rust for systems work.",
        "keywords": ["rust", "systems"],
        "level": 1
      },
      "score": 0.94
    }
  ],
  "query_time_ms": 8
}

返回字段​

字段含义
stream_id本次检索使用的 stream
query最终被嵌入和检索的文本查询
results[].unit命中的记忆单元视图
results[].score融合后的最终排序分数
query_time_ms服务端观测到的检索耗时

实践说明​

  • 即使是多模态检索，query 文本也仍然是必填。
  • 提供 org_id 后，结果集可以包含组织级共享知识。
  • graph_depth 允许检索从直接命中扩展到图谱邻接上下文。
  • 当你想偏向某个 agent 的程序性记忆时，agent_id 很有用。

相关页面​