Memory 模块

更新时间：2026-11-03

记忆接口（Retain / Recall / Reflect）

本文介绍记忆相关的 13 个接口。写入、检索和反思记忆（Retain → Recall → Reflect），以及记忆的列出、查看、更新和清空。

调用说明

接入地址：https://cloud.memory.bj.baidubce.com/api，下文路径直接拼接在该地址后。
请求头：Authorization: Bearer <token> 必填；有 JSON 请求体时需携带 Content-Type: application/json。
错误码、异步操作和 operationId 的说明见 API 简介。

接口列表

接口	方法	路径
获取记忆图	`GET`	`/v1/default/banks/{bank_id}/graph`
写入记忆（Retain）	`POST`	`/v1/default/banks/{bank_id}/memories`
清空 bank 记忆	`DELETE`	`/v1/default/banks/{bank_id}/memories`
试运行抽取记忆	`POST`	`/v1/default/banks/{bank_id}/memories/dry-run-extract`
列出记忆	`GET`	`/v1/default/banks/{bank_id}/memories/list`
检索记忆（Recall）	`POST`	`/v1/default/banks/{bank_id}/memories/recall`
获取单条记忆	`GET`	`/v1/default/banks/{bank_id}/memories/{memory_id}`
更新记忆	`PATCH`	`/v1/default/banks/{bank_id}/memories/{memory_id}`
观察历史	`GET`	`/v1/default/banks/{bank_id}/memories/{memory_id}/history`
清除记忆观察	`DELETE`	`/v1/default/banks/{bank_id}/memories/{memory_id}/observations`
列出 observation scopes	`GET`	`/v1/default/banks/{bank_id}/observations/scopes`
推理反思（Reflect）	`POST`	`/v1/default/banks/{bank_id}/reflect`
列出 tags	`GET`	`/v1/default/banks/{bank_id}/tags`

获取记忆图

GET /v1/default/banks/{bank_id}/graph

获取用于可视化的图数据，可按 type（world/experience/observation）筛选。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`type`	query	`string?`	否	类型。
`limit`	query	`integer`	否	默认值：`1000`；最小值：`0`
`q`	query	`string?`	否	查询参数 q。
`tags`	query	`array<string>?`	否	标签。
`tags_match`	query	`string`	否	默认值：`"all_strict"`
`document_id`	query	`string?`	否	Document 的唯一 ID。
`chunk_id`	query	`string?`	否	Chunk 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`nodes`	`array<object>`	是	图中的节点列表。
`edges`	`array<object>`	是	图中的边列表。
`table_rows`	`array<object>`	是	表格行列表。
`total_units`	`integer`	是	单元总数。
`limit`	`integer`	是	返回数量上限。

响应示例

                JSON
                
            

                {
  "edges": [
    {
      "from": "1",
      "to": "2",
      "type": "semantic",
      "weight": 0.8
    }
  ],
  "limit": 1000,
  "nodes": [
    {
      "id": "1",
      "label": "Alice works at Google",
      "type": "world"
    },
    {
      "id": "2",
      "label": "Bob went hiking",
      "type": "world"
    }
  ],
  "table_rows": [
    {
      "context": "Work info",
      "date": "2024-01-15 10:30",
      "entities": "Alice (PERSON), Google (ORGANIZATION)",
      "id": "abc12345...",
      "text": "Alice works at Google"
    }
  ],
  "total_units": 2
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=get_graph

写入记忆（Retain）

POST /v1/default/banks/{bank_id}/memories

写入 memory items，并自动抽取 facts。

这是存储 memories 的主要接口。通过 async 参数同时支持同步和异步处理。

功能：

高效批处理
自动从自然语言中抽取事实
识别实体并建立链接
自动追踪 document，并在提供 document_id 时执行 upsert
建立时序链接和语义链接
可选的异步处理

系统会自动：

从内容中抽取语义事实
生成 embedding
对相似事实去重
创建时序、语义和实体链接
追踪 document 元数据

当 async=true 时： 加入队列后立即返回。可通过异步操作接口监控进度。

当 async=false（默认）时： 等待处理完成。

注意： 如果 memory item 的 document_id 已存在，系统会先删除旧 document 及其 memory unit，再创建新内容（upsert 行为）。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`items`	`array<MemoryItem>`	是	结果项目列表。
`async`	`boolean`	否	为 true 时在后台异步处理；为 false 时等待处理完成（默认值为 false）；默认值：`false`
`operation_id`	`string?`	否	客户端可选提供的 UUID，用作异步 Retain 异步操作的身份标识。使用相同 operation_id 重新提交时会返回原 operation，不会创建新工作；因此在确认丢失或超时后重试不会重复入队。复用属于其他异步操作的 ID 会返回 HTTP 409。同步 Retain 会忽略此字段。

items[] · MemoryItem

数据结构 MemoryItem：

字段	类型	必填	说明
`content`	`string`	是	资源的正文内容；对 directive/page 等资源含其可编辑文本。
`timestamp`	`string(date-time) \\| string \\| null`	否	内容发生的时间。可传 ISO 8601 datetime 字符串（例如`2024-01-15T10:30:00Z`）、null/省略（默认为当前时间），或特殊值 `unset`，明确表示不保存时间戳（适用于虚构文档或静态参考资料等无时间内容）。
`context`	`string?`	否	上下文信息。
`metadata`	`map<string, string>?`	否	附加元数据。
`document_id`	`string?`	否	此 memory item 的可选 document ID。
`entities`	`array<EntityInput>?`	否	可与自动抽取 entities 合并的可选 entities。
`tags`	`array<string>?`	否	用于可见性 scope 的可选 tags。带 tags 的 memories 可在 recall 时筛选。
`observation_scopes`	`"per_tag" \\| "combined" \\| "all_combinations" \\| "shared" \\| array<array<string>> \\| null`	否	consolidation 时 observation 的 scope 方式。`per_tag` 为每个独立 tag 运行一次 consolidation，并为每个 tag 创建独立 observations；`combined`（默认）将所有 tags 合并后运行一次；`shared` 在全局无标签 scope 上运行一次，使 memories 无论 tags 如何都合并在一起，适用于跨易变的调用来源 tags（如每会话 ID）去重，同时保留源 facts 上的 tags。传入 tag 列表的列表时，每个内层列表运行一次，可完全控制使用哪些组合。
`strategy`	`string?`	否	此 item 使用的命名 Retain strategy。仅覆盖该 item 的 Bank 默认 strategy。Strategies 在 Bank 配置的 retain_strategies 中定义。
`update_mode`	`"replace" \\| "append"?`	否	如何处理 document_id 相同的已有 document。`replace`（默认）删除旧数据并从头重新处理；`append` 将新内容拼接到现有 document 文本后再处理。

entities[] · EntityInput

数据结构 EntityInput：

字段	类型	必填	说明
`text`	`string`	是	Entity 名称或文本。
`type`	`string?`	否	可选的 entity type（例如 PERSON、ORG、CONCEPT）。

请求示例

                JSON
                
            

                {
  "async": false,
  "items": [
    {
      "content": "Alice works at Google",
      "context": "work",
      "document_id": "conversation_123"
    },
    {
      "content": "Bob went hiking yesterday",
      "document_id": "conversation_123",
      "timestamp": "2024-01-15T10:00:00Z"
    }
  ]
}
            

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`success`	`boolean`	是	操作是否成功。
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`items_count`	`integer`	是	项目数量。
`async`	`boolean`	是	该异步操作是否以异步方式处理。
`operation_id`	`string?`	否	用于跟踪异步操作的 ID。可通过`GET /v1/default/banks/{bank_id}/operations` 列出异步操作。仅在 async=true 时出现；item 使用不同 per-item strategies 时应改用 operation_ids。
`operation_ids`	`array<string>?`	否	当 items 按多个 strategy group 提交时的 operation IDs（async=true 且 per-item strategies 混合）。为保持向后兼容，operation_id 会设置为第一项。
`usage`	`TokenUsage?`	否	Fact 抽取期间 LLM 调用的 token 用量指标（仅同步 operation 返回）。

usage · TokenUsage

数据结构 TokenUsage：

字段	类型	必填	说明
`input_tokens`	`integer`	否	消耗的输入／prompt token 数量；默认值：`0`
`output_tokens`	`integer`	否	生成的可见输出／completion token 数量（不含推理／思考 token）；默认值：`0`
`total_tokens`	`integer`	否	token 总数（输入加输出，不含推理 token）；默认值：`0`
`cached_tokens`	`integer`	否	provider 报告的缓存命中／缓存读取 prompt token 数量；默认值：`0`
`thoughts_tokens`	`integer`	否	模型生成的推理／思考 token 数量。部分 provider（如 Gemini 2.5+ 系列）按输出费率计费，但不会显示在可见响应中；默认值：`0`

响应示例

                JSON
                
            

                {
  "async": false,
  "bank_id": "user123",
  "items_count": 2,
  "success": true,
  "usage": {
    "input_tokens": 500,
    "output_tokens": 100,
    "total_tokens": 600
  }
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=retain_memories

清空 bank 记忆

DELETE /v1/default/banks/{bank_id}/memories

删除 memory bank 中的 memory units。可按 type（world、experience、observation）筛选，仅删除指定类型。此操作无法撤销，但会保留 bank profile（disposition 和 background）。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`type`	query	`string?`	否	可选的 fact type 筛选器（world、experience、observation）。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`success`	`boolean`	是	操作是否成功。
`message`	`string?`	否	操作结果消息。
`deleted_count`	`integer?`	否	已删除数量。

响应示例

                JSON
                
            

                {
  "deleted_count": 10,
  "message": "Deleted successfully",
  "success": true
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=clear_bank_memories

试运行抽取记忆

POST /v1/default/banks/{bank_id}/memories/dry-run-extract

预览 retain 将从文本中抽取的内容，不会修改 bank，也不会执行 entity resolution、links、embeddings 或持久化。返回候选 facts 和 LLM token 用量。所有会影响 prompt 的设置（retain mission、extraction mode、chunk size 等）都可在请求体中覆盖，用于将候选配置与 bank 当前配置进行 A/B 对比。此接口为只读操作，不会保存任何内容。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`content`	`string`	是	用于抽取 facts 的文本（例如 document 或单个 chunk）。
`context`	`string`	否	关于内容的可选上下文；默认值：`""`
`timestamp`	`string(date-time)?`	否	用于解析相对时间的参考时间戳（ISO 8601）。
`retain_mission`	`string?`	否	Retain 使用的 mission。
`retain_extraction_mode`	`string?`	否	Retain 的 fact 抽取模式。
`retain_custom_instructions`	`string?`	否	Retain 的自定义抽取指令。
`retain_extract_causal_links`	`boolean?`	否	是否抽取因果链接。
`retain_chunk_size`	`integer?`	否	Retain 内容 chunk 的大小。
`entity_labels`	`array<LabelGroup-Input>?`	否	Entity label 受控词表；仅覆盖本次调用的 Bank 配置。
`entities_allow_free_form`	`boolean?`	否	是否允许自由格式 entity。
`llm_output_language`	`string?`	否	LLM 输出语言。

entity_labels[] · LabelGroup-Input

数据结构 LabelGroup-Input：

字段	类型	必填	说明
`key`	`string`	是	字段键名。
`description`	`string`	否	字段说明；默认值：`""`
`type`	`"value" \\| "multi-values" \\| "text" \\| "map"`	否	字段类型；默认值：`"value"`
`optional`	`boolean`	否	是否为可选字段；默认值：`true`
`tag`	`boolean`	否	是否将字段值用作 tag；默认值：`false`
`values`	`array<LabelValue>`	否	`category` 类型允许的值；默认值：`[]`
`fields`	`map<string, MapField-Input>`	否	子字段定义；默认值：`{}`

values[] · LabelValue

字段	类型	必填	说明
`value`	`string`	是	Label 值。
`description`	`string`	否	Label 说明；默认值：`""`

请求示例

                JSON
                
            

                {
  "content": "string",
  "context": "",
  "timestamp": "2026-01-01T00:00:00Z",
  "retain_mission": "string",
  "retain_extraction_mode": "string",
  "retain_custom_instructions": "string",
  "retain_extract_causal_links": false,
  "retain_chunk_size": 0,
  "entity_labels": [],
  "entities_allow_free_form": false,
  "llm_output_language": "string"
}
            

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`facts`	`array<ExtractedFact>`	否	Retain 步骤可能抽取的候选 facts。
`usage`	`TokenUsage`	否	所有抽取 LLM 调用汇总后的 token 用量。

facts[] · ExtractedFact

数据结构 ExtractedFact：

字段	类型	必填	说明
`text`	`string`	是	抽取出的 fact 文本。
`fact_type`	`string`	是	视角分类：world 或 experience。
`occurred_start`	`string?`	否	Fact 事件开始时间的 ISO 时间戳（如果有日期）。
`occurred_end`	`string?`	否	Fact 事件结束时间的 ISO 时间戳（如果有日期）。
`entities`	`array<string>`	否	Fact 中提及的原始 entity 名称（尚未解析）。

usage · TokenUsage

数据结构 TokenUsage：

字段	类型	必填	说明
`input_tokens`	`integer`	否	消耗的输入／prompt token 数量；默认值：`0`
`output_tokens`	`integer`	否	生成的可见输出／completion token 数量（不含推理／思考 token）；默认值：`0`
`total_tokens`	`integer`	否	token 总数（输入加输出，不含推理 token）；默认值：`0`
`cached_tokens`	`integer`	否	provider 报告的缓存命中／缓存读取 prompt token 数量；默认值：`0`
`thoughts_tokens`	`integer`	否	模型生成的推理／思考 token 数量。部分 provider（如 Gemini 2.5+ 系列）按输出费率计费，但不会显示在可见响应中；默认值：`0`

响应示例

                JSON
                
            

                {
  "facts": [
    {
      "text": "string",
      "fact_type": "string",
      "occurred_start": "string",
      "occurred_end": "string",
      "entities": [
        "string"
      ]
    }
  ],
  "usage": {
    "input_tokens": 1500,
    "output_tokens": 500,
    "total_tokens": 2000
  }
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=dry_run_extract_memories

列出记忆

GET /v1/default/banks/{bank_id}/memories/list

分页列出 memory unit，并可进行全文搜索。支持按类型、来源 document 和关联 entity ID 筛选。结果按最近时间优先排序（先按 mentioned_at DESC，再按 created_at DESC）。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`type`	query	`string?`	否	类型。
`q`	query	`string?`	否	查询参数 q。
`consolidation_state`	query	`string?`	否	Consolidation 状态。
`state`	query	`string?`	否	状态。
`document_id`	query	`string?`	否	Document 的唯一 ID。
`entity_id`	query	`string?`	否	Entity 的唯一 ID。
`tags`	query	`array<string>?`	否	标签。
`tags_match`	query	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"`	否	默认值：`"any"`
`limit`	query	`integer`	否	默认值：`100`；最小值：`0`
`offset`	query	`integer`	否	默认值：`0`；最小值：`0`

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`items`	`array<object>`	是	结果项目列表。
`total`	`integer`	是	总数量。
`limit`	`integer`	是	返回数量上限。
`offset`	`integer`	是	分页偏移量。

响应示例

                JSON
                
            

                {
  "items": [
    {
      "context": "Work conversation",
      "date": "2024-01-15T10:30:00Z",
      "entities": "Alice (PERSON), Google (ORGANIZATION)",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": {
        "channel": "engineering",
        "source": "slack"
      },
      "text": "Alice works at Google on the AI team",
      "type": "world"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 150
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=list_memories

检索记忆（Recall）

POST /v1/default/banks/{bank_id}/memories/recall

使用语义相似度和 spreading activation Recall memories。

type 参数可选，且必须是以下值之一：

world: General knowledge about people, places, events, and things that happen
experience: Memories about experience, conversations, actions taken, and tasks performed

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`query`	`string`	是	查询文本。
`types`	`array<string>?`	否	Recall 的 fact type 列表：world、experience、observation。未指定时默认为 world 和 experience。
`prefer_observations`	`boolean`	否	同时召回原始 facts（`world`／`experience`）和 `observation` 时，如果结果中的 observation 由某条原始 fact consolidation 而来，则移除该 fact，由 observation 取代它，以避免重复内容。空出的结果位会由后续结果补齐，从而保持请求的结果数量。默认关闭；设为 true 可启用。仅当请求同时包含 `observation` 和至少一种原始 fact 类型时生效；默认值：`false`
`budget`	`Budget`	否	默认值：`"mid"`
`max_tokens`	`integer`	否	默认值：`4096`
`trace`	`boolean`	否	默认值：`false`
`query_timestamp`	`string?`	否	ISO 格式日期字符串（例如`2023-05-30T23:40:00`）。用作查询时间锚点，以解析相对时间表达式并计算新近度得分。
`include`	`IncludeOptions`	否	控制是否包含附加数据（默认包含 entities）；默认值：`{}`
`tags`	`array<string>?`	否	按 tags 筛选 memories。未指定时返回所有 memories。tags_match=exact 且省略 tags（或传入 []）时，仅筛选无标签/全局 observations（即 observation_scopes=shared 写入的 scope）。
`tags_match`	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"`	否	tag 的匹配方式: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged), 'exact' (set-equality on the full scope, excludes untagged). With 'exact' and no tags (or []), the empty global scope is selected and only untagged memories match；默认值：`"any"`
`tag_groups`	`array<TagGroupLeaf \\| TagGroupAnd-Input \\| TagGroupOr-Input \\| TagGroupNot-Input>?`	否	使用布尔分组的复合 tag 筛选器。列表中的 groups 按 AND 组合；每个 group 可以是叶节点 {tags, match}，也可以是复合结构 {and: [...]}、{or: [...]} 或 {not: ...}。
`min_scores`	`MinScores?`	否	各阶段可选的最低 score（均包含边界，并按 AND 组合）。`semantic` 和 `keyword` 是检索级 cutoff，会被推送到查询参数 q，用于覆盖本次请求的全局相似度／BM25 最低分；`reranker` 和 `final` 是对已评分结果执行的排序后过滤器。未设置的字段不施加最低分；完全省略 `min_scores`（默认行为）则不进行分数过滤。请谨慎使用：reranker 的绝对分数未在不同查询之间校准，即使结果排名第一，明显相关的匹配也可能只有约 0.001 分。

budget · Budget

类型：Budget

include · IncludeOptions

数据结构 IncludeOptions：

字段	类型	必填	说明
`entities`	`EntityIncludeOptions?`	否	包含 entity observations。设为 null 可禁用 entity 包含；默认值：`{"max_tokens": 500}`
`chunks`	`ChunkIncludeOptions?`	否	是否包含原始 chunks。设置为 {} 启用，设置为 null 禁用（默认禁用）。
`source_facts`	`SourceFactsIncludeOptions?`	否	是否为 observation 类型结果包含 source facts。设置为 {} 启用，设置为 null 禁用（默认禁用）。

entities · EntityIncludeOptions

数据结构 EntityIncludeOptions：

字段	类型	必填	说明
`max_tokens`	`integer`	否	entity observations 的最大 token 数量；默认值：`500`

chunks · ChunkIncludeOptions

数据结构 ChunkIncludeOptions：

字段	类型	必填	说明
`max_tokens`	`integer`	否	chunks 的最大 token 数量（可能截断 chunk）；默认值：`8192`

source_facts · SourceFactsIncludeOptions

数据结构 SourceFactsIncludeOptions：

字段	类型	必填	说明
`max_tokens`	`integer`	否	Maximum total tokens for source facts across all observations (-1 = unlimited)；默认值：`4096`
`max_tokens_per_observation`	`integer`	否	每条 observation 可使用的来源 facts 最大 token 数量 (-1 = unlimited)；默认值：`-1`

min_scores · MinScores

数据结构 MinScores：

字段	类型	必填	说明
`semantic`	`number?`	否	Retrieval 层的最低向量相似度（0-1）。
`keyword`	`number?`	否	Retrieval 层的最低 keyword/full-text（BM25）score。
`reranker`	`number?`	否	查询后处理的最低归一化 reranker score（0-1）。
`final`	`number?`	否	查询后处理的最低最终排名 score。

请求示例

                JSON
                
            

                {
  "budget": "mid",
  "include": {
    "entities": {
      "max_tokens": 500
    }
  },
  "max_tokens": 4096,
  "query": "What did Alice say about machine learning?",
  "query_timestamp": "2023-05-30T23:40:00",
  "tags": [
    "user_a"
  ],
  "tags_match": "any",
  "trace": true,
  "types": [
    "world",
    "experience"
  ]
}
            

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`results`	`array<RecallResult>`	是	结果列表。
`trace`	`object?`	否	执行 trace。
`entities`	`map<string, EntityStateResponse>?`	否	结果中提及 entities 的当前状态。
`chunks`	`map<string, ChunkData>?`	否	按 chunk_id 索引的 fact chunks。
`source_facts`	`map<string, RecallResult>?`	否	observation 类型结果的 source facts，按 fact ID 索引。

results[] · RecallResult

数据结构 RecallResult：

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`text`	`string`	是	文本内容。
`type`	`string?`	否	对象或错误的类型。
`entities`	`array<string>?`	否	相关 entities 列表。
`context`	`string?`	否	上下文信息。
`occurred_start`	`string?`	否	事件开始时间。
`occurred_end`	`string?`	否	事件结束时间。
`mentioned_at`	`string?`	否	被提及时间。
`document_id`	`string?`	否	Document 的唯一标识符。
`metadata`	`map<string, string>?`	否	附加元数据。
`chunk_id`	`string?`	否	Chunk 的唯一标识符。
`tags`	`array<string>?`	否	标签列表。
`source_fact_ids`	`array<string>?`	否	来源 fact 的 ID 列表。
`scores`	`RecallScores?`	否	各检索阶段的 score。

scores · RecallScores

数据结构 RecallScores：

字段	类型	必填	说明
`final`	`number`	是	最终排名 score（综合 reranker、时效/时间和 proof boosts）。
`reranker`	`number?`	否	Cross-encoder 相关性，归一化范围为 0-1。reranker 直通时为 null（rrf/interleave 模式）。
`semantic`	`number?`	否	向量余弦相似度（0-1）。结果不是由 semantic 检索召回时为 null。
`keyword`	`number?`	否	Keyword/full-text（BM25）score（>= 0，无上限）。结果不是由 keyword 搜索召回时为 null。

响应示例

                JSON
                
            

                {
  "chunks": {
    "456e7890-e12b-34d5-a678-901234567890": {
      "chunk_index": 0,
      "id": "456e7890-e12b-34d5-a678-901234567890",
      "text": "Alice works at Google on the AI team. She's been there for 3 years..."
    }
  },
  "entities": {
    "Alice": {
      "canonical_name": "Alice",
      "entity_id": "123e4567-e89b-12d3-a456-426614174001",
      "observations": [
        {
          "mentioned_at": "2024-01-15T10:30:00Z",
          "text": "Alice works at Google on the AI team"
        }
      ]
    }
  },
  "results": [
    {
      "chunk_id": "456e7890-e12b-34d5-a678-901234567890",
      "context": "work info",
      "entities": [
        "Alice",
        "Google"
      ],
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "occurred_end": "2024-01-15T10:30:00Z",
      "occurred_start": "2024-01-15T10:30:00Z",
      "text": "Alice works at Google on the AI team",
      "type": "world"
    }
  ],
  "trace": {
    "num_results": 1,
    "query": "What did Alice say about machine learning?",
    "time_seconds": 0.123
  }
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=recall_memories

获取单条记忆

GET /v1/default/banks/{bank_id}/memories/{memory_id}

按 ID 获取单个 memory unit 及其全部 metadata，包括 entities 和 tags。注意：history 字段已弃用且始终返回空列表，请改用 GET /memories/{memory_id}/history。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`memory_id`	path	`string`	是	Memory 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

无展开字段（标量、自由 object 或未声明 properties）

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=get_memory

更新记忆

PATCH /v1/default/banks/{bank_id}/memories/{memory_id}

编辑 memory 文本和/或更改其整理状态（invalidate / revert）。已 invalidate 的 memories 会从 recall、consolidation 和图维护中排除，但会保留用于审计（可恢复）。只有 world/experience facts 可整理；observations 是派生数据。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`memory_id`	path	`string`	是	Memory 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`text`	`string?`	否	新的 fact 文本。系统会重新生成该 memory 的 embedding，删除其派生 observations 和链接，并触发重新 consolidation。
`context`	`string?`	否	fact 的新 context。传入空字符串会清除；省略则保持不变。
`occurred_start`	`string?`	否	新的发生时间范围起点（ISO 8601）。传入空字符串会清除；省略则保持不变。
`occurred_end`	`string?`	否	新的发生时间范围终点（ISO 8601）。传入空字符串会清除；省略则保持不变。
`fact_type`	`string?`	否	重新分类 fact：'world' 或 'experience'。省略则保持不变。
`entities`	`array<string>?`	否	替换 fact 的 entities。名称按 Retain 相同的方式解析或查找/创建；传入 [] 会解绑所有 entities。省略则保持不变。
`state`	`string?`	否	整理状态：`invalidated` 将 memory 软停用（从 recall/consolidation 中排除，清理 links 和派生 observations，并移入 archive），`valid` 可恢复。此操作可逆。
`reason`	`string?`	否	使其失效时记录的可选自由文本原因。

请求示例

                JSON
                
                {
  "reason": "superseded: server decommissioned 2026-06-01",
  "state": "invalidated"
}

响应

状态码：200 — 成功响应
格式：application/json

无展开字段（标量、自由 object 或未声明 properties）

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=update_memory

观察历史

GET /v1/default/banks/{bank_id}/memories/{memory_id}/history

获取 observation 的完整历史，并将每次变更的源 facts 解析为对应文本。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`memory_id`	path	`string`	是	Memory 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

无展开字段（标量、自由 object 或未声明 properties）

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=get_observation_history

清除记忆观察

DELETE /v1/default/banks/{bank_id}/memories/{memory_id}/observations

删除指定 memory 派生的所有 observations，并重置该 memory 以便重新 consolidation。memory 本身不会删除；系统会自动触发 consolidation，使其生成新的 observations。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`memory_id`	path	`string`	是	Memory 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`deleted_count`	`integer`	是	已删除数量。

响应示例

                JSON
                
                {
  "deleted_count": 3
}

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=clear_memory_observations

列出 observation scopes

GET /v1/default/banks/{bank_id}/observations/scopes

枚举 Bank observations 中的不同 scope。每个 observation 属于一个 scope，即与其一起 consolidation 的完整 tags 集合。返回所有不同 scope（tags 顺序已规范化）及其中 observation 数量；空 tags 列表表示全局/无标签 scope。可将返回的 scope 与 graph 接口（tags= 且 tags_match=exact）配合使用，将 observations 精确筛选到该 scope。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`scopes`	`array<ObservationScope>`	是	不同的 observation scopes，按数量最多优先。

scopes[] · ObservationScope

数据结构 ObservationScope：

字段	类型	必填	说明
`tags`	`array<string>`	是	定义此 scope 的精确 tags 集合（顺序已规范化）。空列表表示全局/无标签 scope。
`count`	`integer`	是	此 scope 下的 observation 数量。

响应示例

                JSON
                
            

                {
  "scopes": [
    {
      "count": 12,
      "tags": [
        "user:alice"
      ]
    },
    {
      "count": 4,
      "tags": [
        "user:alice",
        "project:apollo"
      ]
    },
    {
      "count": 2,
      "tags": []
    }
  ]
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=list_observation_scopes

推理反思（Reflect）

POST /v1/default/banks/{bank_id}/reflect

使用 bank identity、world facts、observations 和 mental models 进行 Reflect 并组织回答。

此接口：

检索 experience（对话和事件）
检索与查询相关的 world facts
检索 observations 和 mental models（Bank 的综合视角）
使用 LLM 生成符合上下文的回答
返回纯文本回答及所使用的事实

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`query`	`string`	是	查询文本。
`budget`	`Budget`	否	默认值：`"low"`
`max_tokens`	`integer`	否	响应的最大 token 数量；默认值：`4096`
`include`	`ReflectIncludeOptions`	否	是否包含附加数据的选项（默认禁用）。
`response_schema`	`object?`	否	可选的结构化输出 JSON Schema。提供后，响应会包含 structured_output 字段，其中是按此 schema 解析的 LLM 响应。
`tags`	`array<string>?`	否	Reflect 期间按 tags 筛选 memories。未指定时考虑所有 memories。
`tags_match`	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"`	否	tag 的匹配方式: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged)；默认值：`"any"`
`tag_groups`	`array<TagGroupLeaf \\| TagGroupAnd-Input \\| TagGroupOr-Input \\| TagGroupNot-Input>?`	否	使用布尔分组的复合 tag 筛选器。列表中的 groups 按 AND 组合；每个 group 可以是叶节点 {tags, match}，也可以是复合结构 {and: [...]}、{or: [...]} 或 {not: ...}。
`apply_all_directives`	`boolean`	否	Apply every active directive regardless of tags. By default directives are scoped like memories: untagged directives always apply, and tagged directives apply only when the request's tags match them. Set true to apply all active directives, ignoring tag scope；默认值：`false`
`fact_types`	`array<"world" \\| "experience" \\| "observation">?`	否	筛选 Reflect 时检索的 fact type。null 表示全部类型（world、experience、observation）。
`exclude_mental_models`	`boolean`	否	为 true 时，从 Reflect 循环中排除所有 mental models（跳过 search_mental_models 工具）；默认值：`false`
`exclude_mental_model_ids`	`array<string>?`	否	按 ID 从 Reflect 循环中排除指定 mental models。

budget · Budget

类型：Budget

include · ReflectIncludeOptions

数据结构 ReflectIncludeOptions：

字段	类型	必填	说明
`facts`	`FactsIncludeOptions?`	否	是否包含回答依据的 facts。设置为 {} 启用，null 禁用（默认禁用）。
`tool_calls`	`ToolCallsIncludeOptions?`	否	是否包含 tool calls trace。设置为 {} 返回完整 trace（input+output），设置为 {output: false} 仅返回 inputs。

facts · FactsIncludeOptions

类型：FactsIncludeOptions

tool_calls · ToolCallsIncludeOptions

数据结构 ToolCallsIncludeOptions：

字段	类型	必填	说明
`output`	`boolean`	否	在 trace 中包含工具输出。设为 false 时仅包含输入，可减小 payload；默认值：`true`

请求示例

                JSON
                
            

                {
  "budget": "low",
  "include": {
    "facts": {}
  },
  "max_tokens": 4096,
  "query": "What do you think about artificial intelligence?",
  "response_schema": {
    "properties": {
      "summary": {
        "type": "string"
      },
      "key_points": {
        "items": {
          "type": "string"
        },
        "type": "array"
      }
    },
    "required": [
      "summary",
      "key_points"
    ],
    "type": "object"
  },
  "tags": [
    "user_a"
  ],
  "tags_match": "any"
}
            

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`text`	`string`	是	Reflect 响应，采用格式规范的 Markdown（标题、列表、粗体/斜体、代码块等）。
`based_on`	`ReflectBasedOn?`	否	生成响应所依据的证据。仅在设置 include.facts 时出现。
`structured_output`	`object?`	否	按请求 response_schema 解析的结构化输出。仅在请求提供 response_schema 时出现。
`usage`	`TokenUsage?`	否	Reflect 期间 LLM 调用的 token 用量指标。
`trace`	`ReflectTrace?`	否	Tool 和 LLM 调用的执行 trace。仅在设置 include.tool_calls 时出现。

based_on · ReflectBasedOn

数据结构 ReflectBasedOn：

字段	类型	必填	说明
`memories`	`array<ReflectFact>`	否	用于生成响应的 memory facts；默认值：`[]`
`mental_models`	`array<ReflectMentalModel>`	否	Mental models used during reflection；默认值：`[]`
`directives`	`array<ReflectDirective>`	否	Directives applied during reflection；默认值：`[]`

memories[] · ReflectFact

数据结构 ReflectFact：

字段	类型	必填	说明
`id`	`string?`	否	对象的唯一标识符。
`text`	`string`	是	Fact 文本。当 type=observation 时，此字段包含 Markdown 格式的 consolidation 知识。
`type`	`string?`	否	对象或错误的类型。
`context`	`string?`	否	上下文信息。
`occurred_start`	`string?`	否	事件开始时间。
`occurred_end`	`string?`	否	事件结束时间。

mental_models[] · ReflectMentalModel

数据结构 ReflectMentalModel：

字段	类型	必填	说明
`id`	`string`	是	Mental model 的唯一 ID。
`text`	`string`	是	Mental model 内容。
`context`	`string?`	否	附加 context。

directives[] · ReflectDirective

数据结构 ReflectDirective：

字段	类型	必填	说明
`id`	`string`	是	Directive 的唯一 ID。
`name`	`string`	是	Directive 名称。
`content`	`string`	是	Directive 内容。

usage · TokenUsage

数据结构 TokenUsage：

字段	类型	必填	说明
`input_tokens`	`integer`	否	消耗的输入／prompt token 数量；默认值：`0`
`output_tokens`	`integer`	否	生成的可见输出／completion token 数量（不含推理／思考 token）；默认值：`0`
`total_tokens`	`integer`	否	token 总数（输入加输出，不含推理 token）；默认值：`0`
`cached_tokens`	`integer`	否	provider 报告的缓存命中／缓存读取 prompt token 数量；默认值：`0`
`thoughts_tokens`	`integer`	否	模型生成的推理／思考 token 数量。部分 provider（如 Gemini 2.5+ 系列）按输出费率计费，但不会显示在可见响应中；默认值：`0`

trace · ReflectTrace

数据结构 ReflectTrace：

字段	类型	必填	说明
`tool_calls`	`array<ReflectToolCall>`	否	Tool calls made during reflection；默认值：`[]`
`llm_calls`	`array<ReflectLLMCall>`	否	LLM calls made during reflection；默认值：`[]`

tool_calls[] · ReflectToolCall

数据结构 ReflectToolCall：

字段	类型	必填	说明
`tool`	`string`	是	Tool 名称：lookup、recall、learn、expand。
`input`	`object`	是	Tool 输入参数。
`output`	`object?`	否	Tool 输出（仅在 include.tool_calls.output 为 true 时包含）。
`duration_ms`	`integer`	是	执行耗时，单位为毫秒。
`iteration`	`integer`	否	调用此工具时的迭代轮次（从 1 开始）；默认值：`0`

llm_calls[] · ReflectLLMCall

数据结构 ReflectLLMCall：

字段	类型	必填	说明
`scope`	`string`	是	调用 scope：agent_1、agent_2、final 等。
`duration_ms`	`integer`	是	执行耗时，单位为毫秒。

响应示例

                JSON
                
            

                {
  "based_on": {
    "memories": [
      {
        "id": "123",
        "text": "AI is used in healthcare",
        "type": "world"
      },
      {
        "id": "456",
        "text": "I discussed AI applications last week",
        "type": "experience"
      }
    ]
  },
  "structured_output": {
    "key_points": [
      "Used in healthcare",
      "Discussed recently"
    ],
    "summary": "AI 具有变革性"
  },
  "text": "## AI Overview\n\nBased on my understanding, AI is a **transformative technology**:\n\n- Used extensively in healthcare\n- Discussed in recent conversations\n- Continues to evolve rapidly",
  "trace": {
    "llm_calls": [
      {
        "duration_ms": 1200,
        "scope": "agent_1"
      }
    ],
    "observations": [
      {
        "id": "obs-1",
        "name": "AI Technology",
        "subtype": "structural",
        "type": "concept"
      }
    ],
    "tool_calls": [
      {
        "duration_ms": 150,
        "input": {
          "query": "AI"
        },
        "tool": "recall"
      }
    ]
  },
  "usage": {
    "input_tokens": 1500,
    "output_tokens": 500,
    "total_tokens": 2000
  }
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=reflect

列出 tags

GET /v1/default/banks/{bank_id}/tags

列出 memory bank 中所有不重复的 tags 及使用次数。支持使用通配符 * 搜索（例如 user:、-fred、tag*-2），不区分大小写。使用 source=mental_models 可列出 mental models 使用的 tags，而不是 memories 使用的 tags。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`q`	query	`string?`	否	用于筛选 tags 的通配模式（例如 user: 匹配 user:alice，-admin 匹配 role-admin）。使用 * 作为通配符，不区分大小写。
`source`	query	`"memories" \\| "mental_models"`	否	Where to read tags from: 'memories' (memory_units, default) or 'mental_models'；默认值：`"memories"`
`limit`	query	`integer`	否	返回 tag 的最大数量；默认值：`100`；最小值：`0`
`offset`	query	`integer`	否	分页偏移量；默认值：`0`；最小值：`0`

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`items`	`array<TagItem>`	是	结果项目列表。
`total`	`integer`	是	总数量。
`limit`	`integer`	是	返回数量上限。
`offset`	`integer`	是	分页偏移量。

items[] · TagItem

数据结构 TagItem：

字段	类型	必填	说明
`tag`	`string`	是	Tag 值。
`count`	`integer`	是	带有此 tag 的 memories 数量。

响应示例

                JSON
                
            

                {
  "items": [
    {
      "count": 42,
      "tag": "user:alice"
    },
    {
      "count": 15,
      "tag": "user:bob"
    },
    {
      "count": 8,
      "tag": "session:abc123"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 25
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=list_tags

评价此篇文章

有帮助没帮助

Bank Templates 模块

Knowledge Base 模块

上下文数据服务

Memory 模块

记忆接口（Retain / Recall / Reflect）

调用说明

接口列表

获取记忆图

参数

请求头

响应

响应示例

响应

响应示例

写入记忆（Retain）

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

清空 bank 记忆

参数

请求头

响应

响应示例

响应

响应示例

试运行抽取记忆

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

列出记忆

参数

请求头

响应

响应示例

响应

响应示例

检索记忆（Recall）

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

获取单条记忆

参数

请求头

响应

响应

响应示例

更新记忆

参数

请求头

请求体

请求示例

响应

响应

响应示例

观察历史

参数

请求头

响应

响应

响应示例

清除记忆观察

参数

请求头

响应

响应示例

响应

响应示例