Banks 模块

更新时间：2026-11-03

Bank 管理接口

本文介绍 Bank 管理相关的 12 个接口。创建、查询、更新和删除 Bank，管理 Bank 配置，触发或恢复 Consolidation，并查看 Bank 统计。

调用说明

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

接口列表

接口	方法	路径
列出 Banks	`GET`	`/v1/default/banks`
创建或更新 Bank	`PUT`	`/v1/default/banks/{bank_id}`
更新 Bank	`PATCH`	`/v1/default/banks/{bank_id}`
删除 Bank	`DELETE`	`/v1/default/banks/{bank_id}`
获取 Bank 配置	`GET`	`/v1/default/banks/{bank_id}/config`
更新 Bank 配置	`PATCH`	`/v1/default/banks/{bank_id}/config`
重置 Bank 配置	`DELETE`	`/v1/default/banks/{bank_id}/config`
触发 Consolidation	`POST`	`/v1/default/banks/{bank_id}/consolidate`
恢复 Consolidation	`POST`	`/v1/default/banks/{bank_id}/consolidation/recover`
清除 Observations	`DELETE`	`/v1/default/banks/{bank_id}/observations`
Agent 统计	`GET`	`/v1/default/banks/{bank_id}/stats`
记忆时序统计	`GET`	`/v1/default/banks/{bank_id}/stats/memories-timeseries`

列出 Banks

GET /v1/default/banks

获取所有 agent 及其 profile 列表

请求头

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

响应

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

字段	类型	必填	说明
`banks`	`array<BankListItem>`	是	Bank 列表。

banks[] · BankListItem

数据结构 BankListItem：

字段	类型	必填	说明
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`name`	`string?`	否	名称。
`disposition`	`DispositionTraits`	是	Bank 的 disposition 特征配置。
`mission`	`string?`	否	Bank 或 agent 的 mission。
`created_at`	`string?`	否	创建时间。
`updated_at`	`string?`	否	最后更新时间。
`fact_count`	`integer`	否	默认值：`0`
`last_document_at`	`string?`	否	最近一个 document 的时间。
`last_write_at`	`string?`	否	最近一次向此 Bank 写入内容的时间，包括 Retain 新 document、追加现有 document，以及创建或更新 mental model、knowledge page 或 directive。

disposition · DispositionTraits

数据结构 DispositionTraits：

字段	类型	必填	说明
`skepticism`	`integer`	是	对信息持怀疑还是信任的程度（1=信任，5=怀疑）；取值范围：`1`–`5`
`literalism`	`integer`	是	对信息进行字面解读的程度（1=灵活，5=字面）；取值范围：`1`–`5`
`empathy`	`integer`	是	考虑情绪背景的程度（1=疏离，5=共情）；取值范围：`1`–`5`

响应示例

                JSON
                
            

                {
  "banks": [
    {
      "bank_id": "user123",
      "created_at": "2024-01-15T10:30:00Z",
      "disposition": {
        "empathy": 3,
        "literalism": 3,
        "skepticism": 3
      },
      "fact_count": 156,
      "last_document_at": "2024-01-16T14:20:00Z",
      "mission": "I am a software engineer helping my team ship quality code",
      "name": "Alice",
      "updated_at": "2024-01-16T14:20:00Z"
    }
  ]
}
            

响应

状态码：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_banks

创建或更新 Bank

PUT /v1/default/banks/{bank_id}

创建 agent，或更新已有 agent 的 disposition 与 mission；缺失字段会自动填充默认值。

参数

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

请求头

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

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`name`	`string?`	否	已弃用：仅用于显示标签，不对外宣传
`disposition`	`DispositionTraits?`	否	已弃用：请改用 update_bank_config
`disposition_skepticism`	`integer?`	否	已弃用：请改用 update_bank_config；取值范围：`1`–`5`
`disposition_literalism`	`integer?`	否	已弃用：请改用 update_bank_config；取值范围：`1`–`5`
`disposition_empathy`	`integer?`	否	已弃用：请改用 update_bank_config；取值范围：`1`–`5`
`mission`	`string?`	否	已弃用：请改用带 reflect_mission 的 update_bank_config
`background`	`string?`	否	已弃用：请改用带 reflect_mission 的 update_bank_config
`reflect_mission`	`string?`	否	Reflect 异步操作的 mission/context；指导 Reflect 如何理解和使用 memories。
`retain_mission`	`string?`	否	控制 retain() 抽取的内容；会与内置抽取规则一起注入。
`retain_extraction_mode`	`string?`	否	Fact 抽取模式：'concise'（默认）、'verbose'、'custom'、'verbatim' 或 'chunks'。
`retain_custom_instructions`	`string?`	否	自定义抽取 prompt。仅当 retain_extraction_mode 为 'custom' 时生效。
`retain_chunk_size`	`integer?`	否	Retain 期间每个内容 chunk 的目标最大字符数。
`retain_structured_chunk_size`	`integer?`	否	Retain 期间单条 JSONL 行或单轮对话保持完整时允许的最大字符数。未设置时默认为 retain_chunk_size。
`enable_observations`	`boolean?`	否	是否在 retain() 后自动进行 observation consolidation。
`enable_temporal_retrieval`	`boolean?`	否	是否在 Recall 中启用时序检索及日期感知查询。
`enable_graph_retrieval`	`boolean?`	否	是否在 Recall 中启用图检索。
`enable_reranking`	`boolean?`	否	是否在 Recall 中启用 reranker。
`observations_mission`	`string?`	否	控制合成到 observations 中的内容；会完全替代内置 consolidation 规则。

disposition · DispositionTraits

数据结构 DispositionTraits：

字段	类型	必填	说明
`skepticism`	`integer`	是	对信息持怀疑还是信任的程度（1=信任，5=怀疑）；取值范围：`1`–`5`
`literalism`	`integer`	是	对信息进行字面解读的程度（1=灵活，5=字面）；取值范围：`1`–`5`
`empathy`	`integer`	是	考虑情绪背景的程度（1=疏离，5=共情）；取值范围：`1`–`5`

请求示例

                JSON
                
                {
  "observations_mission": "Observations are stable facts about people and projects. Always include preferences and skills.",
  "retain_mission": "Always include technical decisions and architectural trade-offs. Ignore meeting logistics."
}

响应

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

字段	类型	必填	说明
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`name`	`string`	是	名称。
`disposition`	`DispositionTraits`	是	Bank 的 disposition 特征配置。
`mission`	`string`	是	agent 的 mission：agent 是谁以及要完成什么目标
`background`	`string?`	否	已弃用：请改用 mission

disposition · DispositionTraits

数据结构 DispositionTraits：

字段	类型	必填	说明
`skepticism`	`integer`	是	对信息持怀疑还是信任的程度（1=信任，5=怀疑）；取值范围：`1`–`5`
`literalism`	`integer`	是	对信息进行字面解读的程度（1=灵活，5=字面）；取值范围：`1`–`5`
`empathy`	`integer`	是	考虑情绪背景的程度（1=疏离，5=共情）；取值范围：`1`–`5`

响应示例

                JSON
                
            

                {
  "bank_id": "user123",
  "disposition": {
    "empathy": 3,
    "literalism": 3,
    "skepticism": 3
  },
  "mission": "I am a software engineer helping my team stay organized and ship quality code",
  "name": "Alice"
}
            

响应

状态码：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=create_or_update_bank

更新 Bank

PATCH /v1/default/banks/{bank_id}

部分更新 agent profile；只会更新请求中提供的字段。

参数

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

请求头

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

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`name`	`string?`	否	已弃用：仅用于显示标签，不对外宣传
`disposition`	`DispositionTraits?`	否	已弃用：请改用 update_bank_config
`disposition_skepticism`	`integer?`	否	已弃用：请改用 update_bank_config；取值范围：`1`–`5`
`disposition_literalism`	`integer?`	否	已弃用：请改用 update_bank_config；取值范围：`1`–`5`
`disposition_empathy`	`integer?`	否	已弃用：请改用 update_bank_config；取值范围：`1`–`5`
`mission`	`string?`	否	已弃用：请改用带 reflect_mission 的 update_bank_config
`background`	`string?`	否	已弃用：请改用带 reflect_mission 的 update_bank_config
`reflect_mission`	`string?`	否	Reflect 异步操作的 mission/context；指导 Reflect 如何理解和使用 memories。
`retain_mission`	`string?`	否	控制 retain() 抽取的内容；会与内置抽取规则一起注入。
`retain_extraction_mode`	`string?`	否	Fact 抽取模式：'concise'（默认）、'verbose'、'custom'、'verbatim' 或 'chunks'。
`retain_custom_instructions`	`string?`	否	自定义抽取 prompt。仅当 retain_extraction_mode 为 'custom' 时生效。
`retain_chunk_size`	`integer?`	否	Retain 期间每个内容 chunk 的目标最大字符数。
`retain_structured_chunk_size`	`integer?`	否	Retain 期间单条 JSONL 行或单轮对话保持完整时允许的最大字符数。未设置时默认为 retain_chunk_size。
`enable_observations`	`boolean?`	否	是否在 retain() 后自动进行 observation consolidation。
`enable_temporal_retrieval`	`boolean?`	否	是否在 Recall 中启用时序检索及日期感知查询。
`enable_graph_retrieval`	`boolean?`	否	是否在 Recall 中启用图检索。
`enable_reranking`	`boolean?`	否	是否在 Recall 中启用 reranker。
`observations_mission`	`string?`	否	控制合成到 observations 中的内容；会完全替代内置 consolidation 规则。

disposition · DispositionTraits

数据结构 DispositionTraits：

字段	类型	必填	说明
`skepticism`	`integer`	是	对信息持怀疑还是信任的程度（1=信任，5=怀疑）；取值范围：`1`–`5`
`literalism`	`integer`	是	对信息进行字面解读的程度（1=灵活，5=字面）；取值范围：`1`–`5`
`empathy`	`integer`	是	考虑情绪背景的程度（1=疏离，5=共情）；取值范围：`1`–`5`

请求示例

                JSON
                
                {
  "observations_mission": "Observations are stable facts about people and projects. Always include preferences and skills.",
  "retain_mission": "Always include technical decisions and architectural trade-offs. Ignore meeting logistics."
}

响应

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

字段	类型	必填	说明
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`name`	`string`	是	名称。
`disposition`	`DispositionTraits`	是	Bank 的 disposition 特征配置。
`mission`	`string`	是	agent 的 mission：agent 是谁以及要完成什么目标
`background`	`string?`	否	已弃用：请改用 mission

disposition · DispositionTraits

数据结构 DispositionTraits：

字段	类型	必填	说明
`skepticism`	`integer`	是	对信息持怀疑还是信任的程度（1=信任，5=怀疑）；取值范围：`1`–`5`
`literalism`	`integer`	是	对信息进行字面解读的程度（1=灵活，5=字面）；取值范围：`1`–`5`
`empathy`	`integer`	是	考虑情绪背景的程度（1=疏离，5=共情）；取值范围：`1`–`5`

响应示例

                JSON
                
            

                {
  "bank_id": "user123",
  "disposition": {
    "empathy": 3,
    "literalism": 3,
    "skepticism": 3
  },
  "mission": "I am a software engineer helping my team stay organized and ship quality code",
  "name": "Alice"
}
            

响应

状态码：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_bank

删除 Bank

DELETE /v1/default/banks/{bank_id}

删除整个 memory bank，包括所有 memories、entities、documents 以及 bank profile。此操作具有破坏性且无法撤销。

参数

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

请求头

名称	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=delete_bank

获取 Bank 配置

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

获取 Bank 的完整解析配置，包括所有层级覆盖（global → tenant → bank）。config 字段包含解析后的全部配置值；overrides 字段仅显示 Bank 专属覆盖项。

参数

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

请求头

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

响应

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

字段	类型	必填	说明
`bank_id`	`string`	是	Bank 标识符
`config`	`object`	是	应用所有层级覆盖后的完整配置（Python 字段名）
`overrides`	`object`	是	仅包含 Bank 专属的配置覆盖项（Python 字段名）

响应示例

                JSON
                
            

                {
  "bank_id": "my-bank",
  "config": {
    "llm_model": "gpt-4",
    "llm_provider": "openai",
    "retain_extraction_mode": "verbose"
  },
  "overrides": {
    "retain_chunk_size": 1200,
    "retain_extraction_mode": "verbose"
  }
}
            

响应

状态码：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_bank_config

更新 Bank 配置

PATCH /v1/default/banks/{bank_id}/config

更新 Bank 的配置覆盖项。支持按 Bank 覆盖的字段如下：

访问与审计：mcp_enabled_tools、audit_log_enabled
数据保留：store_document_text
Retain：retain_chunk_size、retain_structured_chunk_size、retain_extraction_mode、retain_mission、retain_custom_instructions、retain_default_strategy、retain_strategies、retain_chunk_batch_size
Entity：entity_labels、entities_allow_free_form
Recall 开关：enable_temporal_retrieval、enable_graph_retrieval、enable_reranking
Consolidation：enable_observations、enable_auto_consolidation、consolidation_llm_batch_size、consolidation_llm_parallelism、consolidation_max_memories_per_round、consolidation_source_facts_max_tokens、consolidation_source_facts_max_tokens_per_observation、observations_mission、max_observations_per_scope、observation_scope_limits
Reflect：reflect_mission、reflect_source_facts_max_tokens
Recall 细节：recall_include_chunks、recall_max_tokens、recall_chunks_max_tokens
Recall budget：recall_budget_function、recall_budget_fixed_low、recall_budget_fixed_mid、recall_budget_fixed_high、recall_budget_adaptive_low、recall_budget_adaptive_mid、recall_budget_adaptive_high、recall_budget_min、recall_budget_max
Disposition：disposition_skepticism、disposition_literalism、disposition_empathy
Gemini 安全策略：llm_gemini_safety_settings
Memory Defense：memory_defense

参数

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

请求头

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

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`updates`	`object`	是	配置覆盖项，仅支持上文列出的字段。

请求示例

                JSON
                
            

                {
  "updates": {
    "retain_chunk_size": 1200,
    "retain_custom_instructions": "请仔细抽取技术细节",
    "retain_extraction_mode": "verbose"
  }
}
            

响应

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

字段	类型	必填	说明
`bank_id`	`string`	是	Bank 标识符
`config`	`object`	是	应用所有层级覆盖后的完整配置（Python 字段名）
`overrides`	`object`	是	仅包含 Bank 专属的配置覆盖项（Python 字段名）

响应示例

                JSON
                
            

                {
  "bank_id": "my-bank",
  "config": {
    "llm_model": "gpt-4",
    "llm_provider": "openai",
    "retain_extraction_mode": "verbose"
  },
  "overrides": {
    "retain_chunk_size": 1200,
    "retain_extraction_mode": "verbose"
  }
}
            

响应

状态码：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_bank_config

重置 Bank 配置

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

移除 Bank 的全部专属覆盖项，将配置重置为默认值。之后该 Bank 仅使用全局和租户级配置。

参数

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

请求头

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

响应

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

字段	类型	必填	说明
`bank_id`	`string`	是	Bank 标识符
`config`	`object`	是	应用所有层级覆盖后的完整配置（Python 字段名）
`overrides`	`object`	是	仅包含 Bank 专属的配置覆盖项（Python 字段名）

响应示例

                JSON
                
            

                {
  "bank_id": "my-bank",
  "config": {
    "llm_model": "gpt-4",
    "llm_provider": "openai",
    "retain_extraction_mode": "verbose"
  },
  "overrides": {
    "retain_chunk_size": 1200,
    "retain_extraction_mode": "verbose"
  }
}
            

响应

状态码：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=reset_bank_config

触发 Consolidation

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

运行 memory consolidation，根据近期 memories 创建或更新 observations。

参数

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

请求头

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

请求体

格式：application/json
必填：否

字段	类型	必填	说明
`observation_scopes`	`array<array<string>>?`	否	可选的待 consolidation 标签 scope 列表。每个 scope 是一个标签列表；只有标签包含至少一个 scope 中全部标签、且尚未 consolidation 的 memory 才会处理。省略时处理所有尚未 consolidation 的 memory。

请求示例

                JSON
                
            

                {
  "observation_scopes": [
    [
      "string"
    ]
  ]
}
            

响应

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

字段	类型	必填	说明
`operation_id`	`string`	是	异步 consolidation 异步操作的 ID
`deduplicated`	`boolean`	否	如果复用了已有的待处理任务则为 true；默认值：`false`

响应示例

                JSON
                
                {
  "operation_id": "string",
  "deduplicated": false
}

响应

状态码：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=trigger_consolidation

恢复 Consolidation

POST /v1/default/banks/{bank_id}/consolidation/recover

重置 consolidation 期间被永久标记为失败的 memories（已耗尽所有 LLM 重试并完成自适应批次拆分），使其在下一次 consolidation 时重新处理。不会删除任何 observations。

参数

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

请求头

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

响应

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

字段	类型	必填	说明
`retried_count`	`integer`	是	已重试数量。

响应示例

                JSON
                
                {
  "retried_count": 42
}

响应

状态码：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=recover_consolidation

清除 Observations

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

删除 memory bank 的所有 observations，用于重置已 consolidation 的知识。

参数

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

请求头

名称	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_observations

Agent 统计

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

获取指定 agent 的节点和链接统计信息

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`refresh`	query	`boolean`	否	强制重新计算，跳过缓存值（并刷新缓存）；默认值：`false`

请求头

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

响应

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

字段	类型	必填	说明
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`total_nodes`	`integer`	是	节点总数。
`total_links`	`integer`	是	链接总数。
`total_documents`	`integer`	是	document 总数。
`nodes_by_fact_type`	`map<string, integer>`	是	按 fact type 分组的节点数量。
`links_by_link_type`	`map<string, integer>`	是	按 link type 分组的链接数量。
`links_by_fact_type`	`map<string, integer>`	是	按 fact type 分组的链接数量。
`links_breakdown`	`map<string, map<string, integer>>`	是	链接分类统计明细。
`pending_operations`	`integer`	是	待处理 operation 数量。
`failed_operations`	`integer`	是	失败 operation 数量。
`operations_by_status`	`map<string, integer>`	否	按状态分组的异步操作数量（pending、processing、completed、failed、cancelled）。
`last_consolidated_at`	`string?`	否	上次运行 consolidation 的时间（ISO 格式）。
`pending_consolidation`	`integer`	否	尚未处理为 observations 的 memories 数量；默认值：`0`
`failed_consolidation`	`integer`	否	consolidation 永久失败、可通过 consolidation recovery 接口重试的源 memories（world/experience）数量；默认值：`0`
`last_memory_write_at`	`string?`	否	最近一次 memory 写入完成的时间。
`total_observations`	`integer`	否	observations 总数；默认值：`0`

响应示例

                JSON
                
            

                {
  "bank_id": "user123",
  "failed_consolidation": 0,
  "failed_operations": 0,
  "last_consolidated_at": "2024-01-15T10:30:00Z",
  "links_breakdown": {
    "fact": {
      "entity": 40,
      "semantic": 60,
      "temporal": 100
    }
  },
  "links_by_fact_type": {
    "fact": 200,
    "observation": 40,
    "preference": 60
  },
  "links_by_link_type": {
    "entity": 50,
    "semantic": 100,
    "temporal": 150
  },
  "nodes_by_fact_type": {
    "fact": 100,
    "observation": 20,
    "preference": 30
  },
  "pending_consolidation": 0,
  "pending_operations": 2,
  "total_documents": 10,
  "total_links": 300,
  "total_nodes": 150,
  "total_observations": 45
}
            

响应

状态码：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_agent_stats

记忆时序统计

GET /v1/default/banks/{bank_id}/stats/memories-timeseries

指定时间段内写入的 memories，按时间分桶并按 fact type 拆分。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`period`	query	`string`	否	默认值：`"7d"`
`time_field`	query	`string`	否	用于分桶的时间字段。`created_at`（默认）表示写入时间；`mentioned_at`／`occurred_start` 表示事件时间，适用于写入时间集中于单个时间点、无法反映实际知识时间线的迁移数据。未知值回退为 `created_at`；默认值：`"created_at"`

请求头

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

响应

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

字段	类型	必填	说明
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`period`	`string`	是	可选值：1h、12h、1d、7d、30d、90d。
`trunc`	`string`	是	时间桶粒度：minute、hour、day。
`time_field`	`string`	否	用于将每行分配到时间桶的时间戳列。`created_at` 表示写入时间；`mentioned_at` / `occurred_start` 表示事件时间（为空时逐行回退到 `created_at`）；默认值：`"created_at"`
`buckets`	`array<MemoryTimeseriesBucket>`	否	每个时间桶的计数；按请求时间段补齐后始终完整返回。

buckets[] · MemoryTimeseriesBucket

数据结构 MemoryTimeseriesBucket：

字段	类型	必填	说明
`time`	`string`	是	时间桶起始时间戳（ISO-8601，UTC）。
`world`	`integer`	否	此时间桶写入的 world fact memories；默认值：`0`
`experience`	`integer`	否	此时间桶写入的 experience memories；默认值：`0`
`observation`	`integer`	否	此时间桶记录的 observations；默认值：`0`

响应示例

                JSON
                
            

                {
  "bank_id": "string",
  "period": "string",
  "trunc": "string",
  "time_field": "created_at",
  "buckets": [
    {
      "time": "string",
      "world": 0,
      "experience": 0,
      "observation": 0
    }
  ]
}
            

响应

状态码：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_memories_timeseries

评价此篇文章

有帮助没帮助

API 简介

Bank Templates 模块

上下文数据服务

Banks 模块

Bank 管理接口

调用说明

接口列表

列出 Banks

请求头

响应

响应示例

响应

响应示例

创建或更新 Bank

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

更新 Bank

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

删除 Bank

参数

请求头

响应

响应示例

响应

响应示例

获取 Bank 配置

参数

请求头

响应

响应示例

响应

响应示例

更新 Bank 配置

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

重置 Bank 配置

参数

请求头

响应

响应示例

响应

响应示例

触发 Consolidation

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

恢复 Consolidation

参数

请求头

响应

响应示例

响应

响应示例

清除 Observations

参数

请求头

响应

响应示例