{"componentChunkName":"component---src-templates-acg-portal-new-template-tsx","path":"/amw04lci7","result":{"data":{"markdownRemark":{"html":"本文介绍记忆相关的 13 个接口。写入、检索和反思记忆（Retain → Recall → Reflect），以及记忆的列出、查看、更新和清空。
\n\n接入地址：https://cloud.memory.bj.baidubce.com/api，下文路径直接拼接在该地址后。 \n请求头：Authorization: Bearer <token> 必填；有 JSON 请求体时需携带 Content-Type: application/json。 \n错误码、异步操作和 operationId 的说明见 API 简介 。 \n \n\n\n\n接口 \n方法 \n路径 \n \n \n\n\n获取记忆图 GET/v1/default/banks/{bank_id}/graph \n\n写入记忆（Retain） POST/v1/default/banks/{bank_id}/memories \n\n清空 bank 记忆 DELETE/v1/default/banks/{bank_id}/memories \n\n试运行抽取记忆 POST/v1/default/banks/{bank_id}/memories/dry-run-extract \n\n列出记忆 GET/v1/default/banks/{bank_id}/memories/list \n\n检索记忆（Recall） POST/v1/default/banks/{bank_id}/memories/recall \n\n获取单条记忆 GET/v1/default/banks/{bank_id}/memories/{memory_id} \n\n更新记忆 PATCH/v1/default/banks/{bank_id}/memories/{memory_id} \n\n观察历史 GET/v1/default/banks/{bank_id}/memories/{memory_id}/history \n\n清除记忆观察 DELETE/v1/default/banks/{bank_id}/memories/{memory_id}/observations \n\n列出 observation scopes GET/v1/default/banks/{bank_id}/observations/scopes \n\n推理反思（Reflect） POST/v1/default/banks/{bank_id}/reflect \n\n列出 tags GET/v1/default/banks/{bank_id}/tags \n \n
\n
\nGET /v1/default/banks/{bank_id}/graph
\n获取用于可视化的图数据，可按 type（world/experience/observation）筛选。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n\ntypequery \nstring?否 \n类型。 \n \n\nlimitquery \ninteger否 \n默认值：1000；最小值：0 \n \n\nqquery \nstring?否 \n查询参数 q。 \n \n\ntagsquery \narray<string>?否 \n标签。 \n \n\ntags_matchquery \nstring否 \n默认值：\"all_strict\" \n \n\ndocument_idquery \nstring?否 \nDocument 的唯一 ID。 \n \n\nchunk_idquery \nstring?否 \nChunk 的唯一 ID。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n \n
\n\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nnodesarray<object>是 \n图中的节点列表。 \n \n\nedgesarray<object>是 \n图中的边列表。 \n \n\ntable_rowsarray<object>是 \n表格行列表。 \n \n\ntotal_unitsinteger是 \n单元总数。 \n \n\nlimitinteger是 \n返回数量上限。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"edges\" : [ \n3 { \n4 \"from\" : \"1\" , \n5 \"to\" : \"2\" , \n6 \"type\" : \"semantic\" , \n7 \"weight\" : 0.8 \n8 } \n9 ] , \n10 \"limit\" : 1000 , \n11 \"nodes\" : [ \n12 { \n13 \"id\" : \"1\" , \n14 \"label\" : \"Alice works at Google\" , \n15 \"type\" : \"world\" \n16 } , \n17 { \n18 \"id\" : \"2\" , \n19 \"label\" : \"Bob went hiking\" , \n20 \"type\" : \"world\" \n21 } \n22 ] , \n23 \"table_rows\" : [ \n24 { \n25 \"context\" : \"Work info\" , \n26 \"date\" : \"2024-01-15 10:30\" , \n27 \"entities\" : \"Alice (PERSON), Google (ORGANIZATION)\" , \n28 \"id\" : \"abc12345...\" , \n29 \"text\" : \"Alice works at Google\" \n30 } \n31 ] , \n32 \"total_units\" : 2 \n33 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=get_graph
\n
\nPOST /v1/default/banks/{bank_id}/memories
\n写入 memory items，并自动抽取 facts。
\n这是存储 memories 的主要接口。通过 async 参数同时支持同步和异步处理。
\n功能：
\n\n高效批处理 \n自动从自然语言中抽取事实 \n识别实体并建立链接 \n自动追踪 document，并在提供 document_id 时执行 upsert \n建立时序链接和语义链接 \n可选的异步处理 \n \n系统会自动：
\n\n从内容中抽取语义事实 \n生成 embedding \n对相似事实去重 \n创建时序、语义和实体链接 \n追踪 document 元数据 \n \n当 async=true 时： 加入队列后立即返回。可通过异步操作接口监控进度。
\n当 async=false（默认）时： 等待处理完成。
\n注意： 如果 memory item 的 document_id 已存在，系统会先删除旧 document 及其 memory unit，再创建新内容（upsert 行为）。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n\nContent-Typeheader \nstring是 \n固定application/json \n \n \n
\n\n格式：application/json \n必填：是 \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nitemsarray<MemoryItem>是 \n结果项目列表。 \n \n\nasyncboolean否 \n为 true 时在后台异步处理；为 false 时等待处理完成（默认值为 false）；默认值：false \n \n\noperation_idstring?否 \n客户端可选提供的 UUID，用作异步 Retain 异步操作的身份标识。使用相同 operation_id 重新提交时会返回原 operation，不会创建新工作；因此在确认丢失或超时后重试不会重复入队。复用属于其他 异步操作的 ID 会返回 HTTP 409。同步 Retain 会忽略此字段。 \n \n \n
\nitems[] · MemoryItem数据结构 MemoryItem：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ncontentstring是 \n资源的正文内容；对 directive/page 等资源含其可编辑文本。 \n \n\ntimestampstring(date-time) \\| string \\| null否 \n内容发生的时间。可传 ISO 8601 datetime 字符串（例如2024-01-15T10:30:00Z）、null/省略（默认为当前时间），或特殊值 unset，明确表示不保存时间戳（适用于虚构文档或静态参考资料等无时间内容）。 \n \n\ncontextstring?否 \n上下文信息。 \n \n\nmetadatamap<string, string>?否 \n附加元数据。 \n \n\ndocument_idstring?否 \n此 memory item 的可选 document ID。 \n \n\nentitiesarray<EntityInput>?否 \n可与自动抽取 entities 合并的可选 entities。 \n \n\ntagsarray<string>?否 \n用于可见性 scope 的可选 tags。带 tags 的 memories 可在 recall 时筛选。 \n \n\nobservation_scopes\"per_tag\" \\| \"combined\" \\| \"all_combinations\" \\| \"shared\" \\| array<array<string>> \\| null否 \nconsolidation 时 observation 的 scope 方式。per_tag 为每个独立 tag 运行一次 consolidation，并为每个 tag 创建独立 observations；combined（默认）将所有 tags 合并后运行一次；shared 在全局无标签 scope 上运行一次，使 memories 无论 tags 如何都合并在一起，适用于跨易变的调用来源 tags（如每会话 ID）去重，同时保留源 facts 上的 tags。传入 tag 列表的列表时，每个内层列表运行一次，可完全控制使用哪些组合。 \n \n\nstrategystring?否 \n此 item 使用的命名 Retain strategy。仅覆盖该 item 的 Bank 默认 strategy。Strategies 在 Bank 配置的 retain_strategies 中定义。 \n \n\nupdate_mode\"replace\" \\| \"append\"?否 \n如何处理 document_id 相同的已有 document。replace（默认）删除旧数据并从头重新处理；append 将新内容拼接到现有 document 文本后再处理。 \n \n \n
\nentities[] · EntityInput数据结构 EntityInput：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ntextstring是 \nEntity 名称或文本。 \n \n\ntypestring?否 \n可选的 entity type（例如 PERSON、ORG、CONCEPT）。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"async\" : false , \n3 \"items\" : [ \n4 { \n5 \"content\" : \"Alice works at Google\" , \n6 \"context\" : \"work\" , \n7 \"document_id\" : \"conversation_123\" \n8 } , \n9 { \n10 \"content\" : \"Bob went hiking yesterday\" , \n11 \"document_id\" : \"conversation_123\" , \n12 \"timestamp\" : \"2024-01-15T10:00:00Z\" \n13 } \n14 ] \n15 } \n
\n
\n
\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nsuccessboolean是 \n操作是否成功。 \n \n\nbank_idstring是 \n所属 Bank 的唯一标识符。 \n \n\nitems_countinteger是 \n项目数量。 \n \n\nasyncboolean是 \n该异步操作 是否以异步方式处理。 \n \n\noperation_idstring?否 \n用于跟踪异步操作的 ID。可通过GET /v1/default/banks/{bank_id}/operations 列出异步操作。仅在 async=true 时出现；item 使用不同 per-item strategies 时应改用 operation_ids。 \n \n\noperation_idsarray<string>?否 \n当 items 按多个 strategy group 提交时的 operation IDs（async=true 且 per-item strategies 混合）。为保持向后兼容，operation_id 会设置为第一项。 \n \n\nusageTokenUsage?否 \nFact 抽取期间 LLM 调用的 token 用量指标（仅同步 operation 返回）。 \n \n \n
\nusage · TokenUsage数据结构 TokenUsage：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ninput_tokensinteger否 \n消耗的输入／prompt token 数量；默认值：0 \n \n\noutput_tokensinteger否 \n生成的可见输出／completion token 数量（不含推理／思考 token）；默认值：0 \n \n\ntotal_tokensinteger否 \ntoken 总数（输入加输出，不含推理 token）；默认值：0 \n \n\ncached_tokensinteger否 \nprovider 报告的缓存命中／缓存读取 prompt token 数量；默认值：0 \n \n\nthoughts_tokensinteger否 \n模型生成的推理／思考 token 数量。部分 provider（如 Gemini 2.5+ 系列）按输出费率计费，但不会显示在可见响应中；默认值：0 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"async\" : false , \n3 \"bank_id\" : \"user123\" , \n4 \"items_count\" : 2 , \n5 \"success\" : true , \n6 \"usage\" : { \n7 \"input_tokens\" : 500 , \n8 \"output_tokens\" : 100 , \n9 \"total_tokens\" : 600 \n10 } \n11 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=retain_memories
\n
\nDELETE /v1/default/banks/{bank_id}/memories
\n删除 memory bank 中的 memory units。可按 type（world、experience、observation）筛选，仅删除指定类型。此操作无法撤销，但会保留 bank profile（disposition 和 background）。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n\ntypequery \nstring?否 \n可选的 fact type 筛选器（world、experience、observation）。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n \n
\n\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nsuccessboolean是 \n操作是否成功。 \n \n\nmessagestring?否 \n操作结果消息。 \n \n\ndeleted_countinteger?否 \n已删除数量。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"deleted_count\" : 10 , \n3 \"message\" : \"Deleted successfully\" , \n4 \"success\" : true \n5 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=clear_bank_memories
\n
\nPOST /v1/default/banks/{bank_id}/memories/dry-run-extract
\n预览 retain 将从文本中抽取的内容，不会修改 bank，也不会执行 entity resolution、links、embeddings 或持久化。返回候选 facts 和 LLM token 用量。所有会影响 prompt 的设置（retain mission、extraction mode、chunk size 等）都可在请求体中覆盖，用于将候选配置与 bank 当前配置进行 A/B 对比。此接口为只读操作，不会保存任何内容。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n\nContent-Typeheader \nstring是 \n固定application/json \n \n \n
\n\n格式：application/json \n必填：是 \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ncontentstring是 \n用于抽取 facts 的文本（例如 document 或单个 chunk）。 \n \n\ncontextstring否 \n关于内容的可选上下文；默认值：\"\" \n \n\ntimestampstring(date-time)?否 \n用于解析相对时间的参考时间戳（ISO 8601）。 \n \n\nretain_missionstring?否 \nRetain 使用的 mission。 \n \n\nretain_extraction_modestring?否 \nRetain 的 fact 抽取模式。 \n \n\nretain_custom_instructionsstring?否 \nRetain 的自定义抽取指令。 \n \n\nretain_extract_causal_linksboolean?否 \n是否抽取因果链接。 \n \n\nretain_chunk_sizeinteger?否 \nRetain 内容 chunk 的大小。 \n \n\nentity_labelsarray<LabelGroup-Input>?否 \nEntity label 受控词表；仅覆盖本次调用的 Bank 配置。 \n \n\nentities_allow_free_formboolean?否 \n是否允许自由格式 entity。 \n \n\nllm_output_languagestring?否 \nLLM 输出语言。 \n \n \n
\nentity_labels[] · LabelGroup-Input数据结构 LabelGroup-Input：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nkeystring是 \n字段键名。 \n \n\ndescriptionstring否 \n字段说明；默认值：\"\" \n \n\ntype\"value\" \\| \"multi-values\" \\| \"text\" \\| \"map\"否 \n字段类型；默认值：\"value\" \n \n\noptionalboolean否 \n是否为可选字段；默认值：true \n \n\ntagboolean否 \n是否将字段值用作 tag；默认值：false \n \n\nvaluesarray<LabelValue>否 \ncategory 类型允许的值；默认值：[] \n\nfieldsmap<string, MapField-Input>否 \n子字段定义；默认值：{} \n \n \n
\nvalues[] · LabelValue\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nvaluestring是 \nLabel 值。 \n \n\ndescriptionstring否 \nLabel 说明；默认值：\"\" \n \n \n
\n\n
\n \n
\n
1 { \n2 \"content\" : \"string\" , \n3 \"context\" : \"\" , \n4 \"timestamp\" : \"2026-01-01T00:00:00Z\" , \n5 \"retain_mission\" : \"string\" , \n6 \"retain_extraction_mode\" : \"string\" , \n7 \"retain_custom_instructions\" : \"string\" , \n8 \"retain_extract_causal_links\" : false , \n9 \"retain_chunk_size\" : 0 , \n10 \"entity_labels\" : [ ] , \n11 \"entities_allow_free_form\" : false , \n12 \"llm_output_language\" : \"string\" \n13 } \n
\n
\n
\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nfactsarray<ExtractedFact>否 \nRetain 步骤可能抽取的候选 facts。 \n \n\nusageTokenUsage否 \n所有抽取 LLM 调用汇总后的 token 用量。 \n \n \n
\nfacts[] · ExtractedFact数据结构 ExtractedFact：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ntextstring是 \n抽取出的 fact 文本。 \n \n\nfact_typestring是 \n视角分类：world 或 experience。 \n \n\noccurred_startstring?否 \nFact 事件开始时间的 ISO 时间戳（如果有日期）。 \n \n\noccurred_endstring?否 \nFact 事件结束时间的 ISO 时间戳（如果有日期）。 \n \n\nentitiesarray<string>否 \nFact 中提及的原始 entity 名称（尚未解析）。 \n \n \n
\nusage · TokenUsage数据结构 TokenUsage：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ninput_tokensinteger否 \n消耗的输入／prompt token 数量；默认值：0 \n \n\noutput_tokensinteger否 \n生成的可见输出／completion token 数量（不含推理／思考 token）；默认值：0 \n \n\ntotal_tokensinteger否 \ntoken 总数（输入加输出，不含推理 token）；默认值：0 \n \n\ncached_tokensinteger否 \nprovider 报告的缓存命中／缓存读取 prompt token 数量；默认值：0 \n \n\nthoughts_tokensinteger否 \n模型生成的推理／思考 token 数量。部分 provider（如 Gemini 2.5+ 系列）按输出费率计费，但不会显示在可见响应中；默认值：0 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"facts\" : [ \n3 { \n4 \"text\" : \"string\" , \n5 \"fact_type\" : \"string\" , \n6 \"occurred_start\" : \"string\" , \n7 \"occurred_end\" : \"string\" , \n8 \"entities\" : [ \n9 \"string\" \n10 ] \n11 } \n12 ] , \n13 \"usage\" : { \n14 \"input_tokens\" : 1500 , \n15 \"output_tokens\" : 500 , \n16 \"total_tokens\" : 2000 \n17 } \n18 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=dry_run_extract_memories
\n
\nGET /v1/default/banks/{bank_id}/memories/list
\n分页列出 memory unit，并可进行全文搜索。支持按类型、来源 document 和关联 entity ID 筛选。结果按最近时间优先排序（先按 mentioned_at DESC，再按 created_at DESC）。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n\ntypequery \nstring?否 \n类型。 \n \n\nqquery \nstring?否 \n查询参数 q。 \n \n\nconsolidation_statequery \nstring?否 \nConsolidation 状态。 \n \n\nstatequery \nstring?否 \n状态。 \n \n\ndocument_idquery \nstring?否 \nDocument 的唯一 ID。 \n \n\nentity_idquery \nstring?否 \nEntity 的唯一 ID。 \n \n\ntagsquery \narray<string>?否 \n标签。 \n \n\ntags_matchquery \n\"any\" \\| \"all\" \\| \"any_strict\" \\| \"all_strict\" \\| \"exact\"否 \n默认值：\"any\" \n \n\nlimitquery \ninteger否 \n默认值：100；最小值：0 \n \n\noffsetquery \ninteger否 \n默认值：0；最小值：0 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n \n
\n\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nitemsarray<object>是 \n结果项目列表。 \n \n\ntotalinteger是 \n总数量。 \n \n\nlimitinteger是 \n返回数量上限。 \n \n\noffsetinteger是 \n分页偏移量。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"items\" : [ \n3 { \n4 \"context\" : \"Work conversation\" , \n5 \"date\" : \"2024-01-15T10:30:00Z\" , \n6 \"entities\" : \"Alice (PERSON), Google (ORGANIZATION)\" , \n7 \"id\" : \"550e8400-e29b-41d4-a716-446655440000\" , \n8 \"metadata\" : { \n9 \"channel\" : \"engineering\" , \n10 \"source\" : \"slack\" \n11 } , \n12 \"text\" : \"Alice works at Google on the AI team\" , \n13 \"type\" : \"world\" \n14 } \n15 ] , \n16 \"limit\" : 100 , \n17 \"offset\" : 0 , \n18 \"total\" : 150 \n19 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=list_memories
\n
\nPOST /v1/default/banks/{bank_id}/memories/recall
\n使用语义相似度和 spreading activation Recall memories。
\ntype 参数可选，且必须是以下值之一：
\n\nworld: General knowledge about people, places, events, and things that happenexperience: Memories about experience, conversations, actions taken, and tasks performed \n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n\nContent-Typeheader \nstring是 \n固定application/json \n \n \n
\n\n格式：application/json \n必填：是 \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nquerystring是 \n查询文本。 \n \n\ntypesarray<string>?否 \nRecall 的 fact type 列表：world、experience、observation。未指定时默认为 world 和 experience。 \n \n\nprefer_observationsboolean否 \n同时召回原始 facts（world／experience）和 observation 时，如果结果中的 observation 由某条原始 fact consolidation 而来，则移除该 fact，由 observation 取代它，以避免重复内容。空出的结果位会由后续结果补齐，从而保持请求的结果数量。默认关闭；设为 true 可启用。仅当请求同时包含 observation 和至少一种原始 fact 类型时生效；默认值：false \n \n\nbudgetBudget否 \n默认值：\"mid\" \n \n\nmax_tokensinteger否 \n默认值：4096 \n \n\ntraceboolean否 \n默认值：false \n \n\nquery_timestampstring?否 \nISO 格式日期字符串（例如2023-05-30T23:40:00）。用作查询时间锚点，以解析相对时间表达式并计算新近度得分。 \n \n\nincludeIncludeOptions否 \n控制是否包含附加数据（默认包含 entities）；默认值：{} \n \n\ntagsarray<string>?否 \n按 tags 筛选 memories。未指定时返回所有 memories。tags_match=exact 且省略 tags（或传入 []）时，仅筛选无标签/全局 observations（即 observation_scopes=shared 写入的 scope）。 \n \n\ntags_match\"any\" \\| \"all\" \\| \"any_strict\" \\| \"all_strict\" \\| \"exact\"否 \ntag 的匹配方式: '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\" \n \n\ntag_groupsarray<TagGroupLeaf \\| TagGroupAnd-Input \\| TagGroupOr-Input \\| TagGroupNot-Input>?否 \n使用布尔分组的复合 tag 筛选器。列表中的 groups 按 AND 组合；每个 group 可以是叶节点 {tags, match}，也可以是复合结构 {and: [...]}、{or: [...]} 或 {not: ...}。 \n \n\nmin_scoresMinScores?否 \n各阶段可选的最低 score（均包含边界，并按 AND 组合）。semantic 和 keyword 是检索级 cutoff，会被推送到查询参数 q，用于覆盖本次请求的全局相似度／BM25 最低分；reranker 和 final 是对已评分结果执行的排序后过滤器。未设置的字段不施加最低分；完全省略 min_scores（默认行为）则不进行分数过滤。请谨慎使用：reranker 的绝对分数未在不同查询之间校准，即使结果排名第一，明显相关的匹配也可能只有约 0.001 分。 \n \n \n
\nbudget · Budget类型：Budget
\ninclude · IncludeOptions数据结构 IncludeOptions：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nentitiesEntityIncludeOptions?否 \n包含 entity observations。设为 null 可禁用 entity 包含；默认值：{\"max_tokens\": 500} \n \n\nchunksChunkIncludeOptions?否 \n是否包含原始 chunks。设置为 {} 启用，设置为 null 禁用（默认禁用）。 \n \n\nsource_factsSourceFactsIncludeOptions?否 \n是否为 observation 类型结果包含 source facts。设置为 {} 启用，设置为 null 禁用（默认禁用）。 \n \n \n
\nentities · EntityIncludeOptions数据结构 EntityIncludeOptions：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nmax_tokensinteger否 \nentity observations 的最大 token 数量；默认值：500 \n \n \n
\nchunks · ChunkIncludeOptions数据结构 ChunkIncludeOptions：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nmax_tokensinteger否 \nchunks 的最大 token 数量（可能截断 chunk）；默认值：8192 \n \n \n
\nsource_facts · SourceFactsIncludeOptions数据结构 SourceFactsIncludeOptions：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nmax_tokensinteger否 \nMaximum total tokens for source facts across all observations (-1 = unlimited)；默认值：4096 \n \n\nmax_tokens_per_observationinteger否 \n每条 observation 可使用的来源 facts 最大 token 数量 (-1 = unlimited)；默认值：-1 \n \n \n
\nmin_scores · MinScores数据结构 MinScores：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nsemanticnumber?否 \nRetrieval 层的最低向量相似度（0-1）。 \n \n\nkeywordnumber?否 \nRetrieval 层的最低 keyword/full-text（BM25）score。 \n \n\nrerankernumber?否 \n查询后处理的最低归一化 reranker score（0-1）。 \n \n\nfinalnumber?否 \n查询后处理的最低最终排名 score。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"budget\" : \"mid\" , \n3 \"include\" : { \n4 \"entities\" : { \n5 \"max_tokens\" : 500 \n6 } \n7 } , \n8 \"max_tokens\" : 4096 , \n9 \"query\" : \"What did Alice say about machine learning?\" , \n10 \"query_timestamp\" : \"2023-05-30T23:40:00\" , \n11 \"tags\" : [ \n12 \"user_a\" \n13 ] , \n14 \"tags_match\" : \"any\" , \n15 \"trace\" : true , \n16 \"types\" : [ \n17 \"world\" , \n18 \"experience\" \n19 ] \n20 } \n
\n
\n
\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nresultsarray<RecallResult>是 \n结果列表。 \n \n\ntraceobject?否 \n执行 trace。 \n \n\nentitiesmap<string, EntityStateResponse>?否 \n结果中提及 entities 的当前状态。 \n \n\nchunksmap<string, ChunkData>?否 \n按 chunk_id 索引的 fact chunks。 \n \n\nsource_factsmap<string, RecallResult>?否 \nobservation 类型结果的 source facts，按 fact ID 索引。 \n \n \n
\nresults[] · RecallResult数据结构 RecallResult：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nidstring是 \n资源的唯一标识符。 \n \n\ntextstring是 \n文本内容。 \n \n\ntypestring?否 \n对象或错误的类型。 \n \n\nentitiesarray<string>?否 \n相关 entities 列表。 \n \n\ncontextstring?否 \n上下文信息。 \n \n\noccurred_startstring?否 \n事件开始时间。 \n \n\noccurred_endstring?否 \n事件结束时间。 \n \n\nmentioned_atstring?否 \n被提及时间。 \n \n\ndocument_idstring?否 \nDocument 的唯一标识符。 \n \n\nmetadatamap<string, string>?否 \n附加元数据。 \n \n\nchunk_idstring?否 \nChunk 的唯一标识符。 \n \n\ntagsarray<string>?否 \n标签列表。 \n \n\nsource_fact_idsarray<string>?否 \n来源 fact 的 ID 列表。 \n \n\nscoresRecallScores?否 \n各检索阶段的 score。 \n \n \n
\nscores · RecallScores数据结构 RecallScores：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nfinalnumber是 \n最终排名 score（综合 reranker、时效/时间和 proof boosts）。 \n \n\nrerankernumber?否 \nCross-encoder 相关性，归一化范围为 0-1。reranker 直通时为 null（rrf/interleave 模式）。 \n \n\nsemanticnumber?否 \n向量余弦相似度（0-1）。结果不是由 semantic 检索召回时为 null。 \n \n\nkeywordnumber?否 \nKeyword/full-text（BM25）score（>= 0，无上限）。结果不是由 keyword 搜索召回时为 null。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"chunks\" : { \n3 \"456e7890-e12b-34d5-a678-901234567890\" : { \n4 \"chunk_index\" : 0 , \n5 \"id\" : \"456e7890-e12b-34d5-a678-901234567890\" , \n6 \"text\" : \"Alice works at Google on the AI team. She's been there for 3 years...\" \n7 } \n8 } , \n9 \"entities\" : { \n10 \"Alice\" : { \n11 \"canonical_name\" : \"Alice\" , \n12 \"entity_id\" : \"123e4567-e89b-12d3-a456-426614174001\" , \n13 \"observations\" : [ \n14 { \n15 \"mentioned_at\" : \"2024-01-15T10:30:00Z\" , \n16 \"text\" : \"Alice works at Google on the AI team\" \n17 } \n18 ] \n19 } \n20 } , \n21 \"results\" : [ \n22 { \n23 \"chunk_id\" : \"456e7890-e12b-34d5-a678-901234567890\" , \n24 \"context\" : \"work info\" , \n25 \"entities\" : [ \n26 \"Alice\" , \n27 \"Google\" \n28 ] , \n29 \"id\" : \"123e4567-e89b-12d3-a456-426614174000\" , \n30 \"occurred_end\" : \"2024-01-15T10:30:00Z\" , \n31 \"occurred_start\" : \"2024-01-15T10:30:00Z\" , \n32 \"text\" : \"Alice works at Google on the AI team\" , \n33 \"type\" : \"world\" \n34 } \n35 ] , \n36 \"trace\" : { \n37 \"num_results\" : 1 , \n38 \"query\" : \"What did Alice say about machine learning?\" , \n39 \"time_seconds\" : 0.123 \n40 } \n41 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=recall_memories
\n
\nGET /v1/default/banks/{bank_id}/memories/{memory_id}
\n按 ID 获取单个 memory unit 及其全部 metadata，包括 entities 和 tags。注意：history 字段已弃用且始终返回空列表，请改用 GET /memories/{memory_id}/history。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n\nmemory_idpath \nstring是 \nMemory 的唯一 ID。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n \n
\n\n状态码：200 — 成功响应 \n格式：application/json \n \n无展开字段（标量、自由 object 或未声明 properties）
\n\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=get_memory
\n
\nPATCH /v1/default/banks/{bank_id}/memories/{memory_id}
\n编辑 memory 文本和/或更改其整理状态（invalidate / revert）。已 invalidate 的 memories 会从 recall、consolidation 和图维护中排除，但会保留用于审计（可恢复）。只有 world/experience facts 可整理；observations 是派生数据。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n\nmemory_idpath \nstring是 \nMemory 的唯一 ID。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n\nContent-Typeheader \nstring是 \n固定application/json \n \n \n
\n\n格式：application/json \n必填：是 \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ntextstring?否 \n新的 fact 文本。系统会重新生成该 memory 的 embedding，删除其派生 observations 和链接，并触发重新 consolidation。 \n \n\ncontextstring?否 \nfact 的新 context。传入空字符串会清除；省略则保持不变。 \n \n\noccurred_startstring?否 \n新的发生时间范围起点（ISO 8601）。传入空字符串会清除；省略则保持不变。 \n \n\noccurred_endstring?否 \n新的发生时间范围终点（ISO 8601）。传入空字符串会清除；省略则保持不变。 \n \n\nfact_typestring?否 \n重新分类 fact：'world' 或 'experience'。省略则保持不变。 \n \n\nentitiesarray<string>?否 \n替换 fact 的 entities。名称按 Retain 相同的方式解析或查找/创建；传入 [] 会解绑所有 entities。省略则保持不变。 \n \n\nstatestring?否 \n整理状态：invalidated 将 memory 软停用（从 recall/consolidation 中排除，清理 links 和派生 observations，并移入 archive），valid 可恢复。此操作可逆。 \n \n\nreasonstring?否 \n使其失效时记录的可选自由文本原因。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"reason\" : \"superseded: server decommissioned 2026-06-01\" , \n3 \"state\" : \"invalidated\" \n4 } \n
\n
\n
\n状态码：200 — 成功响应 \n格式：application/json \n \n无展开字段（标量、自由 object 或未声明 properties）
\n\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=update_memory
\n
\nGET /v1/default/banks/{bank_id}/memories/{memory_id}/history
\n获取 observation 的完整历史，并将每次变更的源 facts 解析为对应文本。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n\nmemory_idpath \nstring是 \nMemory 的唯一 ID。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n \n
\n\n状态码：200 — 成功响应 \n格式：application/json \n \n无展开字段（标量、自由 object 或未声明 properties）
\n\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=get_observation_history
\n
\nDELETE /v1/default/banks/{bank_id}/memories/{memory_id}/observations
\n删除指定 memory 派生的所有 observations，并重置该 memory 以便重新 consolidation。memory 本身不会删除；系统会自动触发 consolidation，使其生成新的 observations。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n\nmemory_idpath \nstring是 \nMemory 的唯一 ID。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n \n
\n\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndeleted_countinteger是 \n已删除数量。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"deleted_count\" : 3 \n3 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=clear_memory_observations
\n
\nGET /v1/default/banks/{bank_id}/observations/scopes
\n枚举 Bank observations 中的不同 scope。每个 observation 属于一个 scope，即与其一起 consolidation 的完整 tags 集合。返回所有不同 scope（tags 顺序已规范化）及其中 observation 数量；空 tags 列表表示全局/无标签 scope。可将返回的 scope 与 graph 接口（tags=
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n \n
\n\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nscopesarray<ObservationScope>是 \n不同的 observation scopes，按数量最多优先。 \n \n \n
\nscopes[] · ObservationScope数据结构 ObservationScope：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ntagsarray<string>是 \n定义此 scope 的精确 tags 集合（顺序已规范化）。空列表表示全局/无标签 scope。 \n \n\ncountinteger是 \n此 scope 下的 observation 数量。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"scopes\" : [ \n3 { \n4 \"count\" : 12 , \n5 \"tags\" : [ \n6 \"user:alice\" \n7 ] \n8 } , \n9 { \n10 \"count\" : 4 , \n11 \"tags\" : [ \n12 \"user:alice\" , \n13 \"project:apollo\" \n14 ] \n15 } , \n16 { \n17 \"count\" : 2 , \n18 \"tags\" : [ ] \n19 } \n20 ] \n21 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=list_observation_scopes
\n
\nPOST /v1/default/banks/{bank_id}/reflect
\n使用 bank identity、world facts、observations 和 mental models 进行 Reflect 并组织回答。
\n此接口：
\n\n检索 experience（对话和事件） \n检索与查询相关的 world facts \n检索 observations 和 mental models（Bank 的综合视角） \n使用 LLM 生成符合上下文的回答 \n返回纯文本回答及所使用的事实 \n \n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n\nContent-Typeheader \nstring是 \n固定application/json \n \n \n
\n\n格式：application/json \n必填：是 \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nquerystring是 \n查询文本。 \n \n\nbudgetBudget否 \n默认值：\"low\" \n \n\nmax_tokensinteger否 \n响应的最大 token 数量；默认值：4096 \n \n\nincludeReflectIncludeOptions否 \n是否包含附加数据的选项（默认禁用）。 \n \n\nresponse_schemaobject?否 \n可选的结构化输出 JSON Schema。提供后，响应会包含 structured_output 字段，其中是按此 schema 解析的 LLM 响应。 \n \n\ntagsarray<string>?否 \nReflect 期间按 tags 筛选 memories。未指定时考虑所有 memories。 \n \n\ntags_match\"any\" \\| \"all\" \\| \"any_strict\" \\| \"all_strict\" \\| \"exact\"否 \ntag 的匹配方式: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged)；默认值：\"any\" \n \n\ntag_groupsarray<TagGroupLeaf \\| TagGroupAnd-Input \\| TagGroupOr-Input \\| TagGroupNot-Input>?否 \n使用布尔分组的复合 tag 筛选器。列表中的 groups 按 AND 组合；每个 group 可以是叶节点 {tags, match}，也可以是复合结构 {and: [...]}、{or: [...]} 或 {not: ...}。 \n \n\napply_all_directivesboolean否 \nApply 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 \n \n\nfact_typesarray<\"world\" \\| \"experience\" \\| \"observation\">?否 \n筛选 Reflect 时检索的 fact type。null 表示全部类型（world、experience、observation）。 \n \n\nexclude_mental_modelsboolean否 \n为 true 时，从 Reflect 循环中排除所有 mental models（跳过 search_mental_models 工具）；默认值：false \n \n\nexclude_mental_model_idsarray<string>?否 \n按 ID 从 Reflect 循环中排除指定 mental models。 \n \n \n
\nbudget · Budget类型：Budget
\ninclude · ReflectIncludeOptions数据结构 ReflectIncludeOptions：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nfactsFactsIncludeOptions?否 \n是否包含回答依据的 facts。设置为 {} 启用，null 禁用（默认禁用）。 \n \n\ntool_callsToolCallsIncludeOptions?否 \n是否包含 tool calls trace。设置为 {} 返回完整 trace（input+output），设置为 {output: false} 仅返回 inputs。 \n \n \n
\nfacts · FactsIncludeOptions类型：FactsIncludeOptions
\ntool_calls · ToolCallsIncludeOptions数据结构 ToolCallsIncludeOptions：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\noutputboolean否 \n在 trace 中包含工具输出。设为 false 时仅包含输入，可减小 payload；默认值：true \n \n \n
\n\n
\n \n
\n
1 { \n2 \"budget\" : \"low\" , \n3 \"include\" : { \n4 \"facts\" : { } \n5 } , \n6 \"max_tokens\" : 4096 , \n7 \"query\" : \"What do you think about artificial intelligence?\" , \n8 \"response_schema\" : { \n9 \"properties\" : { \n10 \"summary\" : { \n11 \"type\" : \"string\" \n12 } , \n13 \"key_points\" : { \n14 \"items\" : { \n15 \"type\" : \"string\" \n16 } , \n17 \"type\" : \"array\" \n18 } \n19 } , \n20 \"required\" : [ \n21 \"summary\" , \n22 \"key_points\" \n23 ] , \n24 \"type\" : \"object\" \n25 } , \n26 \"tags\" : [ \n27 \"user_a\" \n28 ] , \n29 \"tags_match\" : \"any\" \n30 } \n
\n
\n
\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ntextstring是 \nReflect 响应，采用格式规范的 Markdown（标题、列表、粗体/斜体、代码块等）。 \n \n\nbased_onReflectBasedOn?否 \n生成响应所依据的证据。仅在设置 include.facts 时出现。 \n \n\nstructured_outputobject?否 \n按请求 response_schema 解析的结构化输出。仅在请求提供 response_schema 时出现。 \n \n\nusageTokenUsage?否 \nReflect 期间 LLM 调用的 token 用量指标。 \n \n\ntraceReflectTrace?否 \nTool 和 LLM 调用的执行 trace。仅在设置 include.tool_calls 时出现。 \n \n \n
\nbased_on · ReflectBasedOn数据结构 ReflectBasedOn：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nmemoriesarray<ReflectFact>否 \n用于生成响应的 memory facts；默认值：[] \n \n\nmental_modelsarray<ReflectMentalModel>否 \nMental models used during reflection；默认值：[] \n \n\ndirectivesarray<ReflectDirective>否 \nDirectives applied during reflection；默认值：[] \n \n \n
\nmemories[] · ReflectFact数据结构 ReflectFact：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nidstring?否 \n对象的唯一标识符。 \n \n\ntextstring是 \nFact 文本。当 type=observation 时，此字段包含 Markdown 格式的 consolidation 知识。 \n \n\ntypestring?否 \n对象或错误的类型。 \n \n\ncontextstring?否 \n上下文信息。 \n \n\noccurred_startstring?否 \n事件开始时间。 \n \n\noccurred_endstring?否 \n事件结束时间。 \n \n \n
\nmental_models[] · ReflectMentalModel数据结构 ReflectMentalModel：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nidstring是 \nMental model 的唯一 ID。 \n \n\ntextstring是 \nMental model 内容。 \n \n\ncontextstring?否 \n附加 context。 \n \n \n
\ndirectives[] · ReflectDirective数据结构 ReflectDirective：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nidstring是 \nDirective 的唯一 ID。 \n \n\nnamestring是 \nDirective 名称。 \n \n\ncontentstring是 \nDirective 内容。 \n \n \n
\nusage · TokenUsage数据结构 TokenUsage：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ninput_tokensinteger否 \n消耗的输入／prompt token 数量；默认值：0 \n \n\noutput_tokensinteger否 \n生成的可见输出／completion token 数量（不含推理／思考 token）；默认值：0 \n \n\ntotal_tokensinteger否 \ntoken 总数（输入加输出，不含推理 token）；默认值：0 \n \n\ncached_tokensinteger否 \nprovider 报告的缓存命中／缓存读取 prompt token 数量；默认值：0 \n \n\nthoughts_tokensinteger否 \n模型生成的推理／思考 token 数量。部分 provider（如 Gemini 2.5+ 系列）按输出费率计费，但不会显示在可见响应中；默认值：0 \n \n \n
\ntrace · ReflectTrace数据结构 ReflectTrace：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ntool_callsarray<ReflectToolCall>否 \nTool calls made during reflection；默认值：[] \n \n\nllm_callsarray<ReflectLLMCall>否 \nLLM calls made during reflection；默认值：[] \n \n \n
\ntool_calls[] · ReflectToolCall数据结构 ReflectToolCall：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ntoolstring是 \nTool 名称：lookup、recall、learn、expand。 \n \n\ninputobject是 \nTool 输入参数。 \n \n\noutputobject?否 \nTool 输出（仅在 include.tool_calls.output 为 true 时包含）。 \n \n\nduration_msinteger是 \n执行耗时，单位为毫秒。 \n \n\niterationinteger否 \n调用此工具时的迭代轮次（从 1 开始）；默认值：0 \n \n \n
\nllm_calls[] · ReflectLLMCall数据结构 ReflectLLMCall：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nscopestring是 \n调用 scope：agent_1、agent_2、final 等。 \n \n\nduration_msinteger是 \n执行耗时，单位为毫秒。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"based_on\" : { \n3 \"memories\" : [ \n4 { \n5 \"id\" : \"123\" , \n6 \"text\" : \"AI is used in healthcare\" , \n7 \"type\" : \"world\" \n8 } , \n9 { \n10 \"id\" : \"456\" , \n11 \"text\" : \"I discussed AI applications last week\" , \n12 \"type\" : \"experience\" \n13 } \n14 ] \n15 } , \n16 \"structured_output\" : { \n17 \"key_points\" : [ \n18 \"Used in healthcare\" , \n19 \"Discussed recently\" \n20 ] , \n21 \"summary\" : \"AI 具有变革性\" \n22 } , \n23 \"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\" , \n24 \"trace\" : { \n25 \"llm_calls\" : [ \n26 { \n27 \"duration_ms\" : 1200 , \n28 \"scope\" : \"agent_1\" \n29 } \n30 ] , \n31 \"observations\" : [ \n32 { \n33 \"id\" : \"obs-1\" , \n34 \"name\" : \"AI Technology\" , \n35 \"subtype\" : \"structural\" , \n36 \"type\" : \"concept\" \n37 } \n38 ] , \n39 \"tool_calls\" : [ \n40 { \n41 \"duration_ms\" : 150 , \n42 \"input\" : { \n43 \"query\" : \"AI\" \n44 } , \n45 \"tool\" : \"recall\" \n46 } \n47 ] \n48 } , \n49 \"usage\" : { \n50 \"input_tokens\" : 1500 , \n51 \"output_tokens\" : 500 , \n52 \"total_tokens\" : 2000 \n53 } \n54 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=reflect
\n
\nGET /v1/default/banks/{bank_id}/tags
\n列出 memory bank 中所有不重复的 tags 及使用次数。支持使用通配符 * 搜索（例如 user:、 -fred、tag*-2），不区分大小写。使用 source=mental_models 可列出 mental models 使用的 tags，而不是 memories 使用的 tags。
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nbank_idpath \nstring是 \nBank 的唯一标识符。 \n \n\nqquery \nstring?否 \n用于筛选 tags 的通配模式（例如 user: 匹配 user:alice， -admin 匹配 role-admin）。使用 * 作为通配符，不区分大小写。 \n \n\nsourcequery \n\"memories\" \\| \"mental_models\"否 \nWhere to read tags from: 'memories' (memory_units, default) or 'mental_models'；默认值：\"memories\" \n \n\nlimitquery \ninteger否 \n返回 tag 的最大数量；默认值：100；最小值：0 \n \n\noffsetquery \ninteger否 \n分页偏移量；默认值：0；最小值：0 \n \n \n
\n\n\n\n名称 \nIn \n类型 \n必填 \n说明 \n \n \n\n\nAuthorizationheader \nstring是 \nBearer token。 \n \n \n
\n\n状态码：200 — 成功响应 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nitemsarray<TagItem>是 \n结果项目列表。 \n \n\ntotalinteger是 \n总数量。 \n \n\nlimitinteger是 \n返回数量上限。 \n \n\noffsetinteger是 \n分页偏移量。 \n \n \n
\nitems[] · TagItem数据结构 TagItem：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ntagstring是 \nTag 值。 \n \n\ncountinteger是 \n带有此 tag 的 memories 数量。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"items\" : [ \n3 { \n4 \"count\" : 42 , \n5 \"tag\" : \"user:alice\" \n6 } , \n7 { \n8 \"count\" : 15 , \n9 \"tag\" : \"user:bob\" \n10 } , \n11 { \n12 \"count\" : 8 , \n13 \"tag\" : \"session:abc123\" \n14 } \n15 ] , \n16 \"limit\" : 100 , \n17 \"offset\" : 0 , \n18 \"total\" : 25 \n19 } \n
\n
\n
\n状态码：422 — 校验错误 \n格式：application/json \n \n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\ndetailarray<ValidationError>否 \n详细信息或校验错误列表。 \n \n \n
\ndetail[] · ValidationError数据结构 ValidationError：
\n\n\n\n字段 \n类型 \n必填 \n说明 \n \n \n\n\nlocarray<string \\| integer>是 \n发生校验错误的位置路径；数组元素可以是字段名或索引。 \n \n\nmsgstring是 \n错误消息或状态消息。 \n \n\ntypestring是 \n对象或错误的类型。 \n \n\ninputany否 \n触发校验的原始输入值。 \n \n\nctxContext否 \n错误上下文信息。 \n \n \n
\n\n
\n \n
\n
1 { \n2 \"detail\" : [ \n3 { \n4 \"loc\" : [ ] , \n5 \"msg\" : \"string\" , \n6 \"type\" : \"string\" , \n7 \"input\" : null , \n8 \"ctx\" : { } \n9 } \n10 ] \n11 } \n
\n
\n
operationId=list_tags
","fields":{"slug":"amw04lci7","title":"Memory 模块","date":"2026-11-03","extractedHeadings":[]},"headings":[{"value":"记忆接口（Retain / Recall / Reflect）","depth":1},{"value":"调用说明","depth":2},{"value":"接口列表","depth":2},{"value":"获取记忆图","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"写入记忆（Retain）","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"请求体","depth":3},{"value":"请求示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"清空 bank 记忆","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"试运行抽取记忆","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"请求体","depth":3},{"value":"请求示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"列出记忆","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"检索记忆（Recall）","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"请求体","depth":3},{"value":"请求示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"获取单条记忆","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"响应","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"更新记忆","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"请求体","depth":3},{"value":"请求示例","depth":3},{"value":"响应","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"观察历史","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"响应","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"清除记忆观察","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"列出 observation scopes","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"推理反思（Reflect）","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"请求体","depth":3},{"value":"请求示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"列出 tags","depth":2},{"value":"参数","depth":3},{"value":"请求头","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3},{"value":"响应","depth":3},{"value":"响应示例","depth":3}]}},"pageContext":{"isCreatedByStatefulCreatePages":false,"slug":"amw04lci7","prev":{"id":"Imw04lc9x","name":"Bank Templates 模块","path":"Imw04lc9x","filePath":"Agent 记忆服务/API参考/Bank Templates 模块.md","seo":null,"parentIds":["fmpl4uat3","hmw010h6y"],"parents":[{"id":"fmpl4uat3","documentId":"89600c3e-96c9-4def-b9d8-08dad3b1f7fb","name":"Agent 记忆服务","repoName":"VDB","filePath":"Agent 记忆服务","disabled":false,"path":"fmpl4uat3","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":"","solutionTag":null,"solutionColor":null},{"id":"hmw010h6y","documentId":"a27b7eff-c280-45f6-947d-1e5f51790431","name":"API参考","repoName":"VDB","filePath":"Agent 记忆服务/API参考","disabled":false,"path":"hmw010h6y","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":"","solutionTag":null,"solutionColor":null}]},"next":{"id":"fmw04lch5","name":"Knowledge Base 模块","path":"fmw04lch5","filePath":"Agent 记忆服务/API参考/Knowledge Base 模块.md","seo":null,"parentIds":["fmpl4uat3","hmw010h6y"],"parents":[{"id":"fmpl4uat3","documentId":"89600c3e-96c9-4def-b9d8-08dad3b1f7fb","name":"Agent 记忆服务","repoName":"VDB","filePath":"Agent 记忆服务","disabled":false,"path":"fmpl4uat3","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":"","solutionTag":null,"solutionColor":null},{"id":"hmw010h6y","documentId":"a27b7eff-c280-45f6-947d-1e5f51790431","name":"API参考","repoName":"VDB","filePath":"Agent 记忆服务/API参考","disabled":false,"path":"hmw010h6y","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":"","solutionTag":null,"solutionColor":null}]},"parents":[{"id":"fmpl4uat3","documentId":"89600c3e-96c9-4def-b9d8-08dad3b1f7fb","name":"Agent 记忆服务","repoName":"VDB","filePath":"Agent 记忆服务","disabled":false,"path":"fmpl4uat3","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":"","solutionTag":null,"solutionColor":null},{"id":"hmw010h6y","documentId":"a27b7eff-c280-45f6-947d-1e5f51790431","name":"API参考","repoName":"VDB","filePath":"Agent 记忆服务/API参考","disabled":false,"path":"hmw010h6y","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":"","solutionTag":null,"solutionColor":null}],"specificSeo":null}}}