> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorose.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 检索 API

> 融合语义、文本、图、时间和多模态信号的混合检索。

# 检索 API（Retrieve API）

## POST `/v1/users/:user_id/streams/:stream_id/retrieve`

对单个用户和流执行混合检索（Hybrid Retrieval）。

## 此路由的用途

这是运行时的主要召回路由。它融合多种检索信号，而非依赖单一搜索路径。

可用信号包括：

* 语义相似度（Semantic Similarity）
* 文本检索（Text Retrieval）
* 图扩展（Graph Expansion）
* 时间过滤（Time Filtering）
* 组织知识（Organization Knowledge）
* 多模态查询输入（Multimodal Query Input）

## 请求

```http theme={null}
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"
}
```

## 请求字段

| Field                | Type    | Required | 描述                                                           |
| -------------------- | ------- | -------- | ------------------------------------------------------------ |
| `query`              | string  | Yes      | 检索查询文本                                                       |
| `limit`              | number  | No       | 最大结果数，服务端有上限                                                 |
| `enable_arbitration` | boolean | No       | 启用 API 层的仲裁检索行为。它和服务端 `[reranker] type = "arbitrator"` 是两件事。 |
| `min_score`          | number  | No       | 最低分数阈值                                                       |
| `graph_depth`        | number  | No       | 图扩展深度                                                        |
| `start_time`         | ISO8601 | No       | 有效时间下界                                                       |
| `end_time`           | ISO8601 | No       | 有效时间上界                                                       |
| `as_of`              | ISO8601 | No       | 事务时间时间点过滤                                                    |
| `org_id`             | string  | No       | 包含组织知识范围                                                     |
| `agent_id`           | string  | No       | 过滤至某个 Agent 的程序性记忆                                           |
| `image`              | string  | No       | Base64 图像，用于跨模态检索                                            |
| `audio`              | string  | No       | Base64 音频，用于跨模态检索                                            |
| `video`              | string  | No       | Base64 视频，用于跨模态检索                                            |

## 响应

```json theme={null}
{
  "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": "factual",
        "content": "Dylan prefers Rust for systems work.",
        "keywords": ["rust", "systems"],
        "level": 1
      },
      "score": 0.94
    }
  ],
  "query_time_ms": 8
}
```

## 响应字段

| Field             | 含义            |
| ----------------- | ------------- |
| `stream_id`       | 本次检索请求使用的流    |
| `query`           | 最终被嵌入和搜索的文本查询 |
| `results[].unit`  | 匹配的记忆单元视图     |
| `results[].score` | 检索融合后的最终排名分数  |
| `query_time_ms`   | 服务端检索延迟       |

## 实用说明

* 即使是多模态检索，查询文本也始终是必需的。
* 当提供 `org_id` 时，共享的组织知识可以进入结果集。
* `graph_depth` 允许检索通过图链接的邻居进行扩展，而不仅限于直接匹配。
* `agent_id` 在你希望偏向某个 Agent 的程序性记忆时非常有用。

## 相关页面

* [混合搜索指南](/zh/guides/hybrid-search)
* [组织知识 API](/zh/api/organization-knowledge)
* [图 API](/zh/api/graph)