{"componentChunkName":"component---src-templates-acg-portal-new-template-tsx","path":"/gmpl4ub1a","result":{"data":{"markdownRemark":{"html":"

在 REST API 模式下，您可以在自己的流程中主动决定什么时候读记忆、什么时候写记忆，以及如何使用记忆结果。所有接口通过 HTTPS 调用，使用 HTTP Bearer Token 认证。

\n

认证方式

\n

在请求头中携带 API Key：

\n\n
\n
\n
\n Plain Text\n \n
\n
\n 
1Authorization: Bearer <your-api-key>\n2Content-Type: application/json
\n
\n
\n
\n \n

文件上传接口使用 multipart/form-data。

\n

核心接口

\n

1. Bank 管理

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
方法接口路径用途
GET/banks列出当前 API Key 可访问的 Bank
POST/banks创建或初始化 Bank，请求体为 { bank_id }
\n

2. Retain 存储记忆

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
方法接口路径用途
POST/memories/retain同步写入文本内容，适合小批量或需要立即得到结果的场景
POST/memories/retain_async异步写入文本内容，适合较大文本或批量数据，返回后台操作信息
POST/files/retain上传一个或多个文件并异步写入记忆，表单字段 files 为文件列表，request 为 JSON 字符串
\n

Retain 请求字段

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
字段类型说明
bank_idstring目标 Bank，也兼容 agent_id
itemsarray要写入的内容列表，每项至少包含 content
items[].contentstring自然语言文本，建议保留完整上下文
items[].timestampstring事件发生时间，建议使用 ISO 8601 格式；传 \"unset\" 表示无时间信息
items[].contextstring内容来源或场景，如 support chat、code review、meeting notes
items[].document_idstring稳定文档 ID，便于更新而非重复写入
items[].update_modestring同名 document_id 的处理方式：replace（默认，删除旧内容后重新处理）或 append（追加新内容到已有文档）
items[].tagsstring[]范围标签，用于后续检索和多租户隔离
items[].metadataobject来源系统、外部 ID 等附加信息
items[].observation_scopesstring观察聚合粒度：combined（默认，按全部标签聚合）、per_tag（按每个标签独立聚合）、all_combinations（按所有标签组合聚合）、custom（自定义标签组合）
document_tagsstring[]应用到文档级别的标签
\n

文件上传字段

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
字段类型说明
filesfile[]一个或多个上传文件，字段名必须是 files
requeststringJSON 字符串，至少包含 bank_id，可包含 document_id、tags、context 等信息
\n

3. Recall 检索记忆

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
方法接口路径用途
POST/recall按自然语言查询检索相关记忆，适合 Agent 回复前注入上下文
\n

Recall 请求字段

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
字段类型说明
bank_idstring目标 Bank。未传时部分部署会使用 default，不建议依赖默认值
querystring自然语言查询（必填，最多 500 tokens）
budgetstring检索强度：low（快速查找）、mid（日常推荐）、high（深度检索），默认 mid
max_tokensnumber限制返回上下文大小，默认 4096
typesstring[]按事实类型过滤：world（客观事实）、experience（经验事实）、observation（观察）
tagsstring[]只检索匹配标签的记忆
tags_matchstring标签匹配方式：any（默认，含无标签）、any_strict（排除无标签）、all、all_strict
query_timestampstring把查询锚定到指定时间点，ISO 8601 格式
includeobject可包含 entities（默认开启）、chunks（返回原始分块）、source_facts（返回观察的来源事实）等扩展信息
traceboolean返回检索追踪信息，便于调试
\n

Recall 响应字段

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
字段类型说明
resultsarray按相关性排序的记忆列表，每项包含 id、text、type、context、tags、entities、occurred_start、occurred_end、mentioned_at、document_id 等
source_factsobject仅当 include.source_facts 开启时返回，以事实 ID 为键的来源事实字典
chunksobject仅当 include.chunks 开启时返回，以分块 ID 为键的原始文本字典
traceobject仅当 trace: true 时返回，包含每阶段的耗时和检索细节
\n

4. Reflect 智能推理

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
方法接口路径用途
POST/reflect基于记忆生成综合回答，适合总结、判断、画像和状态分析
\n

Reflect 请求字段

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
字段类型说明
bank_idstring目标 Bank
querystring需要推理回答的问题（必填）
budgetstring推理搜索强度：low（默认，浅层快速）、mid（多源核查）、high（深度探索），默认 low
max_tokensnumber限制回答长度，默认 4096
contextstring为推理提供情境信息，影响推理方向
response_schemaobjectJSON Schema 对象，传入后返回结构化输出（structured_output 字段），适用于程序化处理
include_factsboolean返回回答依据的事实（based_on 字段）
include_tool_callsboolean返回内部检索步骤，便于调试
tagsstring[]限定 Reflect 可访问的记忆范围
tags_matchstring标签匹配方式，与 Recall 一致
fact_typesstring[]限制事实类型：world、experience、observation
exclude_mental_modelsboolean跳过心智模型，强制从事实和观察推理
\n

Reflect 响应字段

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
字段类型说明
textstring综合回答文本（Markdown 格式）；使用 response_schema 时为空
structured_outputobject仅当传入 response_schema 时返回，按 Schema 解析的结构化结果
based_onobject仅当 include_facts: true 时返回，包含 memories、mental_models、directives 三个列表
usageobject本次推理的 Token 用量：input_tokens、output_tokens、total_tokens
traceobject仅当 include_tool_calls: true 时返回，包含完整的推理步骤日志
\n

5. 查询与管理数据

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
方法接口路径用途
GET/list?bank_id=...分页列出记忆，可按 type、q、limit、offset 过滤
GET/documents?bank_id=...列出导入文档
GET/entities?bank_id=...列出实体
GET/entities/graph?bank_id=...获取实体共现图
GET/operations/{bankId}查看异步任务，支持 status、type、limit、offset
DELETE/operations/{bankId}?operation_id=...取消待处理任务
\n

请求示例

\n

Retain 存储文本记忆

\n\n
\n
\n
\n Bash\n \n
\n
\n 
1curl \"$MEMORY_API_BASE_URL/memories/retain\" \\\n2  -H \"Authorization: Bearer $MEMORY_API_KEY\" \\\n3  -H \"Content-Type: application/json\" \\\n4  -d '{\n5    \"bank_id\": \"'\"$MEMORY_BANK_ID\"'\",\n6    \"items\": [\n7      {\n8        \"content\": \"用户偏好使用 TypeScript、React 和 Tailwind 构建前端页面。\",\n9        \"context\": \"project onboarding\",\n10        \"document_id\": \"onboarding-session-001\",\n11        \"timestamp\": \"2026-05-12T10:00:00+08:00\",\n12        \"tags\": [\"user:demo\", \"project:frontend\"]\n13      }\n14    ]\n15  }'
\n
\n
\n
\n \n

Retain 追加内容到已有文档

\n\n
\n
\n
\n Bash\n \n
\n
\n 
1curl \"$MEMORY_API_BASE_URL/memories/retain\" \\\n2  -H \"Authorization: Bearer $MEMORY_API_KEY\" \\\n3  -H \"Content-Type: application/json\" \\\n4  -d '{\n5    \"bank_id\": \"'\"$MEMORY_BANK_ID\"'\",\n6    \"items\": [\n7      {\n8        \"content\": \"新增讨论：团队决定将状态管理从 Redux 迁移到 Zustand。\",\n9        \"document_id\": \"onboarding-session-001\",\n10        \"update_mode\": \"append\",\n11        \"tags\": [\"user:demo\", \"project:frontend\"]\n12      }\n13    ]\n14  }'
\n
\n
\n
\n \n

Retain 上传文件写入记忆

\n\n
\n
\n
\n Bash\n \n
\n
\n 
1curl \"$MEMORY_API_BASE_URL/files/retain\" \\\n2  -H \"Authorization: Bearer $MEMORY_API_KEY\" \\\n3  -F 'request={\n4    \"bank_id\":\"'\"$MEMORY_BANK_ID\"'\",\n5    \"document_id\":\"product-guide-001\",\n6    \"tags\":[\"project:docs\"]\n7  }' \\\n8  -F \"files=@./product-guide.md;type=text/markdown\"
\n
\n
\n
\n \n

Recall 检索相关记忆

\n\n
\n
\n
\n Bash\n \n
\n
\n 
1curl \"$MEMORY_API_BASE_URL/recall\" \\\n2  -H \"Authorization: Bearer $MEMORY_API_KEY\" \\\n3  -H \"Content-Type: application/json\" \\\n4  -d '{\n5    \"bank_id\": \"'\"$MEMORY_BANK_ID\"'\",\n6    \"query\": \"这个用户偏好的前端技术栈是什么？\",\n7    \"budget\": \"mid\",\n8    \"tags\": [\"user:demo\"],\n9    \"tags_match\": \"all_strict\",\n10    \"max_tokens\": 1200,\n11    \"trace\": true\n12  }'
\n
\n
\n
\n \n

Recall JavaScript 示例

\n\n
\n
\n
\n Javascript\n \n
\n
\n 
1const apiBaseUrl = process.env.MEMORY_API_BASE_URL;\n2const memoryKey = process.env.MEMORY_API_KEY;\n3const bankId = process.env.MEMORY_BANK_ID;\n4\n5async function recallUserContext(userMessage) {\n6  const response = await fetch(`${apiBaseUrl}/recall`, {\n7    method: \"POST\",\n8    headers: {\n9      \"Authorization\": `Bearer ${memoryKey}`,\n10      \"Content-Type\": \"application/json\",\n11    },\n12    body: JSON.stringify({\n13      bank_id: bankId,\n14      query: userMessage,\n15      budget: \"mid\",\n16      tags: [\"user:demo\"],\n17      tags_match: \"all_strict\",\n18    }),\n19  });\n20\n21  if (!response.ok) {\n22    throw new Error(`Recall failed: ${response.status}`);\n23  }\n24\n25  return response.json();\n26}
\n
\n
\n
\n \n

Recall Python 示例

\n\n
\n
\n
\n Python\n \n
\n
\n 
1import os\n2import requests\n3\n4api_base_url = os.environ[\"MEMORY_API_BASE_URL\"]\n5api_key = os.environ[\"MEMORY_API_KEY\"]\n6bank_id = os.environ[\"MEMORY_BANK_ID\"]\n7\n8resp = requests.post(\n9    f\"{api_base_url}/recall\",\n10    headers={\n11        \"Authorization\": f\"Bearer {api_key}\",\n12        \"Content-Type\": \"application/json\",\n13    },\n14    json={\n15        \"bank_id\": bank_id,\n16        \"query\": \"这个用户最近在做什么项目？\",\n17        \"budget\": \"mid\",\n18        \"tags\": [\"user:demo\"],\n19        \"tags_match\": \"all_strict\",\n20    },\n21    timeout=30,\n22)\n23\n24resp.raise_for_status()\n25print(resp.json())
\n
\n
\n
\n \n

Reflect 智能推理

\n\n
\n
\n
\n Bash\n \n
\n
\n 
1curl \"$MEMORY_API_BASE_URL/reflect\" \\\n2  -H \"Authorization: Bearer $MEMORY_API_KEY\" \\\n3  -H \"Content-Type: application/json\" \\\n4  -d '{\n5    \"bank_id\": \"'\"$MEMORY_BANK_ID\"'\",\n6    \"query\": \"请总结这个用户的工程偏好，并给出接下来生成代码时应遵循的建议。\",\n7    \"budget\": \"mid\",\n8    \"include_facts\": true,\n9    \"tags\": [\"user:demo\"],\n10    \"tags_match\": \"all_strict\"\n11  }'
\n
\n
\n
\n \n

Reflect 结构化输出

\n\n
\n
\n
\n Bash\n \n
\n
\n 
1curl \"$MEMORY_API_BASE_URL/reflect\" \\\n2  -H \"Authorization: Bearer $MEMORY_API_KEY\" \\\n3  -H \"Content-Type: application/json\" \\\n4  -d '{\n5    \"bank_id\": \"'\"$MEMORY_BANK_ID\"'\",\n6    \"query\": \"这个用户适合使用什么前端框架？\",\n7    \"budget\": \"low\",\n8    \"response_schema\": {\n9      \"type\": \"object\",\n10      \"properties\": {\n11        \"recommendation\": {\"type\": \"string\"},\n12        \"confidence\": {\"type\": \"string\", \"enum\": [\"low\", \"medium\", \"high\"]},\n13        \"reasons\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n14      },\n15      \"required\": [\"recommendation\", \"confidence\", \"reasons\"]\n16    }\n17  }'
\n
\n
\n
\n ","fields":{"slug":"gmpl4ub1a","title":"API 接入","date":"2026-05-25","extractedHeadings":[]},"headings":[{"value":"认证方式","depth":1},{"value":"核心接口","depth":1},{"value":"1. Bank 管理","depth":2},{"value":"2. Retain 存储记忆","depth":2},{"value":"3. Recall 检索记忆","depth":2},{"value":"4. Reflect 智能推理","depth":2},{"value":"5. 查询与管理数据","depth":2},{"value":"请求示例","depth":1}]}},"pageContext":{"isCreatedByStatefulCreatePages":false,"slug":"gmpl4ub1a","prev":{"id":"ampl4uaua","name":"API Key 管理","path":"ampl4uaua","filePath":"Agent 记忆服务/接入方式/API Key 管理.md","seo":null,"parentIds":["fmpl4uat3","impl4uatp"],"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":""},{"id":"impl4uatp","documentId":"045943e2-0a50-4db3-9eca-e3aca899aa1e","name":"接入方式","repoName":"VDB","filePath":"Agent 记忆服务/接入方式","disabled":false,"path":"impl4uatp","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":""}]},"next":{"id":"cmpl4uayz","name":"接口速查表","path":"cmpl4uayz","filePath":"Agent 记忆服务/接入方式/接口速查表.md","seo":null,"parentIds":["fmpl4uat3","impl4uatp"],"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":""},{"id":"impl4uatp","documentId":"045943e2-0a50-4db3-9eca-e3aca899aa1e","name":"接入方式","repoName":"VDB","filePath":"Agent 记忆服务/接入方式","disabled":false,"path":"impl4uatp","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":""}]},"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":""},{"id":"impl4uatp","documentId":"045943e2-0a50-4db3-9eca-e3aca899aa1e","name":"接入方式","repoName":"VDB","filePath":"Agent 记忆服务/接入方式","disabled":false,"path":"impl4uatp","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":""}],"specificSeo":null}}}