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

# 写入与搜索会话记忆

> 使用语义搜索检索，在智能体会话中存储键值形式的上下文片段。使用 POST 写入，使用 GET 搜索记忆项。

会话记忆以键值对的形式作为上下文片段持久化，使用 pgvector。用 POST 请求写入记忆，之后通过语义 GET 搜索检索相关条目。

## 写入记忆

### 接口

```http theme={null}
POST /v1/agents/sessions/{session_id}/memory
```

## 认证

传递 `Authorization: Bearer <api-key>` 或 `Authorization: ApiKey <key>` 之一。

## 路径参数

<ParamField path="session_id" type="string" required>
  智能体会话标识符。
</ParamField>

## 请求体

<ParamField body="key" type="string" required>
  记忆项的唯一 key。
</ParamField>

<ParamField body="value" type="string" required>
  要存储的文本值。
</ParamField>

<ParamField body="metadata" type="object">
  可选的任意元数据对象。
</ParamField>

### 响应

<ResponseField name="key" type="string">
  已存储的 key。
</ResponseField>

<ResponseField name="value" type="string">
  已存储的值。
</ResponseField>

<ResponseField name="metadata" type="object">
  已存储的元数据。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://agent.example.com/v1/agents/sessions/sess_01J5X8/memory \
    -H "Authorization: Bearer <api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "key": "user_preference_temperature",
      "value": "User prefers Celsius.",
      "metadata": {"topic": "units"}
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "key": "user_preference_temperature",
    "value": "User prefers Celsius.",
    "metadata": {"topic": "units"}
  }
  ```
</ResponseExample>

## 搜索记忆

### 接口

```http theme={null}
GET /v1/agents/sessions/{session_id}/memory
```

## 查询参数

<ParamField query="q" type="string" required>
  语义搜索查询。
</ParamField>

<ParamField query="limit" type="integer">
  返回的最大结果数。
</ParamField>

<ParamField query="filter" type="string">
  可选的元数据过滤表达式。
</ParamField>

### 响应

<ResponseField name="items" type="array">
  匹配的记忆项数组。
</ResponseField>

<ResponseField name="items[].key" type="string">
  条目 key。
</ResponseField>

<ResponseField name="items[].value" type="string">
  条目值。
</ResponseField>

<ResponseField name="items[].score" type="number">
  语义相似度分数。
</ResponseField>

<ResponseField name="items[].metadata" type="object">
  条目元数据。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://agent.example.com/v1/agents/sessions/sess_01J5X8/memory?q=preference&limit=5" \
    -H "Authorization: Bearer <api-key>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "items": [
      {
        "key": "user_preference_temperature",
        "value": "User prefers Celsius.",
        "score": 0.92,
        "metadata": {"topic": "units"}
      }
    ]
  }
  ```
</ResponseExample>