记忆管理(新建、检索与删除记忆)
功能概述与核心场景
记忆管理(Memories)是 Agentbase Memory(v2.10.0)的核心数据面操作中心,负责单条与批量记忆的写入、多模态文档/图片解析入库、会话历史上下文推断、五路混合检索(Hybrid / Vector / Sparse / Keyword / Graph)、带 Token 预算的统一召回(Recall)、数据导入导出以及合规遗忘删除。
在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的 **企业智能客服与知识中台**(enterprise-ai-hub-210)项目中,智能客服系统通过记忆管理能力分别服务不同层级的企业客户:
- 针对核心账务架构师
user_zhangwei_001,系统不仅通过**直接写入(infer=false)**同步记录其集群拓扑参数与 SLA 等级,还支持将其上传至agent_multimedia_bucket存储桶的集群架构图(PNG)与排障报告(PDF)解析转化为长期记忆; - 针对一线运维工程师
user_lina_002,系统在多轮工单对话中开启**按流程智能提取(infer=true)**并传入sessionId,结合最近 12 轮历史对话自动抽取出自包含的技术事实,智能执行新增(ADD)、更新(UPDATE)、冲突删除(DELETE)或忽略重复(NONE),确保记忆库始终准确反映最新系统状态。
核心概念与架构
Memory 的写入与检索链路采用“同步确定性直写 + 异步模型推断管线”与“多路索引投影 + 重排融合”的双引擎架构。
flowchart LR
subgraph WritePath["记忆写入与多模态处理链路 (POST /v1/memory/memories)"]
Input["输入载荷\ncontent / messages / media({bucketId, fileId})"]
MediaParser["多模态解析器 (Vision LLM: qwen-vl-max)\nPNG/JPEG/WebP (≤16MP) & PDF (≤10页, ≤8MiB)"]
ModeSwitch{"写入模式判断\ninfer & handlingPolicy"}
DirectWrite["直接写入 (infer=false)\n同步生成记忆记录与版本 v1"]
SessionHydrate["会话上下文补水 (sessionId)\n加载同会话最近 ≤12 turns / ≤4096 tokens"]
PipelineExec["新增记忆 Pipeline (infer=true, 异步 Job)\n事实抽取 (qwen-plus) -> 冲突候选召回 -> ADD/UPDATE/DELETE/NONE"]
end
subgraph IndexStore["OceanBase Shared V2 多维投影存储"]
PrimaryTable[("主记忆表与不可变 Source 表\n乐观锁 version & 治理策略")]
DenseIdx[("稠密向量索引 (Dense)\ntext-embedding-v3 (1024维)")]
SparseIdx[("稀疏向量索引 (Sparse)\nDashScope Sparse 权重")]
FulltextIdx[("全文关键词索引 (Keyword)\n精准子串兜底")]
GraphIdx[("实体关系图谱投影 (Graph)\n模型抽取有向边 (最多 2 跳)")]
end
subgraph ReadPath["多路检索与统一召回链路 (search / recall)"]
QueryInput["查询请求\n文本 query 或图片 media + 过滤条件"]
Rewrite["画像查询改写 (可选)\nprofileRewriteEnabled"]
Fusion["多路召回与 RRF 融合\nhybrid / vector / sparse / keyword / graph"]
Rerank["语义重排 (可选)\nqwen3.7-text-rerank"]
Progressive["渐进式检索 / 统一 Recall\nL3 Overview -> L2 Context -> L1 Fact -> L0 Evidence"]
end
Input --> MediaParser
MediaParser --> ModeSwitch
Input --> ModeSwitch
ModeSwitch -->|"infer=false (默认同步)"| DirectWrite
ModeSwitch -->|"infer=true (默认异步 202)"| SessionHydrate
SessionHydrate --> PipelineExec
DirectWrite --> PrimaryTable
PipelineExec --> PrimaryTable
PrimaryTable --> DenseIdx
PrimaryTable --> SparseIdx
PrimaryTable --> FulltextIdx
PrimaryTable --> GraphIdx
QueryInput --> Rewrite
Rewrite --> Fusion
DenseIdx --> Fusion
SparseIdx --> Fusion
FulltextIdx --> Fusion
GraphIdx --> Fusion
Fusion --> Rerank
Rerank --> Progressive核心概念与治理属性表
| 属性维度 | 参数字段 | 可选枚举值 | 详细语义与安全治理规则 |
|---|---|---|---|
| 可见范围 | scope | private、strict_private、user、group、project | - strict_private / private:严格私有记忆,**禁用 sessionId 历史会话上下文补水**,防止跨轮次隐式关联;<br>- user:归属特定 userId(如 user_zhangwei_001),最常用的个人长期记忆范围;<br>- group:归属特定业务群组,必须同时传入 groupId,检索时校验调用者群组成员身份;<br>- project:项目级共享记忆,对项目内授权主体可见。 |
| 敏感度分级 | sensitivity | normal(默认)、confidential、restricted | 标识记忆数据的业务敏感等级。注意:若传入 secret 将被服务端直接拒绝(Fail-closed),切勿将密钥、口令或未脱敏隐私作为记忆写入。 |
| 模型处理策略 | handlingPolicy | standard(默认)、no_embedding、no_model | - standard:允许 Chat 模型推断与 Embedding 向量化;<br>- no_embedding:允许模型文本处理与关键词检索,但不生成向量投影;<br>- no_model:严禁任何大模型接触该条数据,要求必须显式设置 infer=false,且拒绝多模态媒体解析。 |
| 记录种类 | recordKind | fact、conversation、action | 区分提炼后的客观事实(fact)、原始对话片段(conversation)与智能体工具执行动作(action),分别适用 retention 命名空间下的不同保留天数策略。 |
| 记忆类型 | memoryType | preference、fact、long_term、short_term、working、conversation、action 或自定义字符串 | 业务分类标签。在 infer=false 直接写入时由调用方指定;在 infer=true 按流程处理时由新增记忆 Pipeline 自动分类生成。 |
| 检索模式 | searchMode | hybrid(默认)、vector、sparse、keyword、graph | - hybrid:综合稠密向量、稀疏向量与全文索引进行 RRF 融合;<br>- vector:纯稠密语义向量检索;<br>- sparse:基于 DashScope 稀疏向量的高维词项权重检索;<br>- keyword:全文检索(对 1~2 字短词如“锁表”自动启用参数化精确子串兜底);<br>- graph:基于模型抽取的“实体—关系—实体”有向边执行最多 2 跳图遍历召回。 |
功能入口与权限矩阵
操作入口与角色权限矩阵
控制台入口位于:**项目 enterprise-ai-hub-210 → 记忆(Memory) → 记忆** 页签。
| 操作场景 | 控制台操作入口 | REST API 端点 | 所需 API Key Scope | 关联模块与依赖 |
|---|---|---|---|---|
| 创建单条/对话记忆 | 添加记忆 按钮 | POST /v1/memory/memories | memories.write(多模态需额外具备 files.read) | 关联 配置中心 的新增记忆 Pipeline 与 存储(Storage) |
| 查询异步写入任务 | 提交回执弹窗自动轮询 | GET /v1/memory/jobs/{jobId} | memories.write 或 memories.read | 关联 记忆审计 与 链路追踪 |
| 列表与来源溯源 | 记忆列表 查询 | GET /v1/memory/memories、GET /v1/memory/memories/{memoryId}/sources | memories.read | 为 用户画像 与 上下文治理 提供底层证据 |
| 多路检索与渐进召回 | 搜索框 + 检索模式下拉框 | POST /v1/memory/memories/search、POST /v1/memory/memories/recall | memories.read | 为 Agent Workbench(智能体工作台) 提供实时上下文注入 |
| 更新与单条/批量删除 | 记忆列表行尾 删除 按钮 | PATCH /v1/memory/memories/{memoryId}、DELETE /v1/memory/memories/{memoryId}、DELETE /v1/memory/memories | memories.write(更新) / memories.delete(删除) | 触发后台 Compactor 清理向量与图投影 |
| 批量写入与导入导出 | API / SDK 批处理入口 | POST /v1/memory/memories/batch、/imports、/exports | memories.write / memories.export | 依赖内部 Artifact Broker 与对象存储 |
功能详解与操作指南
1. 在控制台直接写入确定性事实(infer=false)
当业务应用已经明确整理好用户偏好或系统环境事实,无需大模型二次改写时,使用直接写入模式(同步落库):
- 进入项目
enterprise-ai-hub-210的 记忆 → 记忆 页签,单击右上角 添加记忆。 - 在弹窗中按下表填写参数:
- **用户 ID(
userId)**:输入user_zhangwei_001(或演示账号demo-user)。 - **可见范围(
scope)**:选择user。 - 处理方式:选择 直接写入(对应 API
infer: false, async: false)。 - **记忆类型(
memoryType)**:输入或选择preference。 - **记录种类(
recordKind):选择 事实(fact)**。 - **正文(
content)**:输入非空文本(UTF-8 编码最大 20,000 字节),例如用户张伟(核心账务架构师)偏好直接查看 OceanBase V4 分布式死锁排查 SQL 与向量索引 HNSW 参数说明。。 - **元数据(
metadata)**:输入合法 JSON 对象,例如{"ticketId": "TK-20261022-001", "env": "production"}。
- **用户 ID(
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
- 单击 保存,页面弹出执行回执详情,显示状态
completed、处理模式simple、生成的memoryId以及动作ADD。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
2. 从多轮对话异步智能提取记忆(infer=true 与会话历史补水)
在实际客服会话中,用户的关键信息往往分布在多轮问答中(例如上一轮客服给出选项 A/B,下一轮用户仅回复“我选 A”)。此时应使用**按流程处理(infer=true)**:
- 在 添加记忆 弹窗中,将 处理方式 切换为 按流程处理。
- 选择 使用默认 Pipeline 或指定已发布的新增记忆流水线(草稿状态流水线不可用于正式写入)。此时无需手动填写
memoryType,由 Pipeline 内的事实抽取节点(调用qwen-plus)自动判定。 - 输入对话内容并提交。智能提取默认采用异步执行(HTTP 202),返回
status: "queued"、jobId与sourceId。 - **会话上下文推断(
sessionId历史补水)**: - 当通过 API/SDK 调用且同时满足
infer=true、sessionId非空(最长 128 字符)、scope为user/group/project时,Memory 会在同一项目、同一用户、同一agentId和治理边界内,自动往前读取同会话最近 12 个历史 turn(总预算约 4,096 tokens)作为推断背景。 - 历史消息仅辅助模型理解当前轮指代(如将“我选 A”还原为“用户选择开启 OceanBase 向量索引异步重建策略”),不会篡改当前 Source 原文。
- 后台任务完成事实提取后,会召回已有相似记忆并由模型执行冲突判定:
- **
ADD**:新增独立事实; - **
UPDATE**:合并或修正既有事实(自动递增目标记忆的version); - **
DELETE**:当新事实明确推翻旧事实时,自动遗忘冲突的旧记忆; - **
NONE**:判定为寒暄或完全重复信息,跳过写入(此时任务成功完成但新增条数为 0,属正常现象)。
- **
- 当通过 API/SDK 调用且同时满足
3. 多模态图片与 PDF 记忆入库与检索
在技术支持工单中,客户常上传报错截图或架构 PDF。应用可先将文件上传至同项目 Storage 存储桶(如 agent_multimedia_bucket),再将文件引用 {bucketId, fileId} 传给 Memory 接口:
# 提交 Storage 中的架构图或 PDF 手册进行异步视觉解析入库
curl -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Idempotency-Key: multimodal-ticket-001" \
-H "Content-Type: application/json" \
--data '{
"userId": "user_zhangwei_001",
"scope": "user",
"memoryType": "long_term",
"recordKind": "fact",
"media": {
"bucketId": "agent_multimedia_bucket",
"fileId": "ob_cluster_topology_2026.pdf"
},
"content": "客户核心账务 OceanBase 集群三中心拓扑与 OBProxy 路由表配置文档",
"infer": true
}' | jq .多模态输入技术边界与约束:
- 支持格式与体积:支持单个
PNG、JPEG、WebP或PDF文件,文件大小1 byte至 **8 MiB;图片分辨率上限16,000,000像素(16 MP);PDF 页数上限1~10页**。 - 执行机制:多模态写入固定为异步模式(返回 HTTP 202 及
jobId,若显式传async: false将返回 400)。后台通过内部 Documents Parser 与项目配置的视觉模型qwen-vl-max将媒体解析为结构化文本(与附加content合计不超过 20,000 UTF-8 字节),并冻结在不可变 Source 的_appbaseMemoryMedia元数据中(包含 SHA-256、页边界与字符偏移)。 - 权限与策略约束:调用凭据须同时具备
memories.write与 Storagefiles.read权限;handlingPolicy=no_model时拒绝媒体输入;图片辅助检索(POST /v1/memory/memories/search传入media)仅支持图片格式,不支持直接用 PDF 发起搜索。
4. 多路混合检索、渐进式检索与统一召回(Recall)
- 在控制台 记忆 → 记忆 页签顶部,输入目标用户 ID(如
user_zhangwei_001或demo-user)。 - 在搜索框中输入自然语言问题(例如
用户负责哪个集群,排障偏好是什么?),在检索模式下拉框中选择 **混合检索(hybrid)、向量(vector)、稀疏向量(sparse)、关键词(keyword) 或 图检索(graph),单击 查询**。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
- **在业务服务端使用
agentbase-node-sdk@2.10.0执行渐进式检索与统一召回: 当智能体需要在单次推理前同时组装用户的普通记忆、用户画像、经验(Experience)与技能(Skill)**,并严格控制注入 Prompt 的 Token 数量时,推荐使用统一召回接口POST /v1/memory/memories/recall或渐进式检索策略:
// 使用官方服务端 SDK: agentbase-node-sdk@2.10.0
import { Client, Memory } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint('https://appbuild.oceanbase.com/v1')
.setProject('enterprise-ai-hub-210')
.setKey(process.env.APPBASE_API_KEY);
const memory = new Memory(client);
// 1. 渐进式多路检索 (L3 Overview -> L2 Context -> L1 Fact)
const searchResult = await memory.searchMemories({
userId: 'user_zhangwei_001',
scope: 'user',
query: 'OceanBase 分布式事务锁冲突与向量索引排障偏好',
searchMode: 'hybrid',
limit: 10,
retrieval: {
strategy: 'progressive',
entryLevel: 'auto',
maxDepth: 2,
tokenBudget: 1200,
deadlineMs: 450
}
});
// 2. 带 Token 预算的统一召回(整合记忆、画像、经验与技能)
const recallBundle = await memory.recall({
userId: 'user_zhangwei_001',
agentId: 'enterprise-support-agent',
query: '如何处理 TK-20261022-001 工单中的向量索引重建超时问题?',
tokenBudget: 2000
});5. 乐观锁更新、单条/批量删除与防重学保护
- **乐观锁更新(
PATCH /v1/memory/memories/{memoryId})**: 先通过GET获取目标记忆当前的version(如1),在PATCH请求体中携带{"version": 1, "content": "...", "metadata": {...}}。若并发修改导致版本不匹配,服务端返回409 Conflict,需重新读取最新版本后再提交。 - **单条与有界批量删除(
DELETE)**: - 在控制台记忆列表行尾单击 删除 并确认,或调用
DELETE /v1/memory/memories/{memoryId},记忆状态立即变为forgotten并停止被任何检索召回,后台 Compactor 异步清理物理向量与图索引。**主动删除不受“永久遗忘(permanent_forgetting_enabled)”开关限制,始终立即生效**,但不会删除同项目 Storage 中的原始文件。 - 调用
DELETE /v1/memory/memories按用户批量清理时,每次请求执行一个有界批次(limit取值1~500,默认100)。应用必须检查响应中的hasMore布尔值,循环调用直至hasMore: false,并核查failed计数是否为0。
- 在控制台记忆列表行尾单击 删除 并确认,或调用
- **防意外重学保护与显式
reRemember**: 被用户主动删除的记忆内容会记录删除墓碑指纹。若应用仅更换Idempotency-Key再次提交相同内容,系统默认会拦截重写以保护用户隐私删除意愿;仅当用户明确要求“重新记住该事实”时,可在创建请求中显式传入"reRemember": true。
常见问题与排障(FAQ)
1. 为什么提交“按流程处理(infer=true)”后,任务状态显示 succeeded,但在记忆列表中查不到新记录?
- 原因分析:
infer=true交由大模型(qwen-plus)判断输入内容是否包含值得长期保存的事实,并与该用户已有记忆进行比对。若输入仅包含无实质事实的寒暄(如“你好,谢谢”),或输入事实与既有记忆完全重复,模型会输出NONE动作。此外,若查看过早,任务可能仍处于queued或running状态。 - 解决措施:在提交回执或 记忆审计 中查看对应
jobId的result.actions数组。若动作为NONE属于正常的去重行为;若需不论内容原样落库,请改用 **直接写入(infer=false)**。
2. 刚刚写入成功的记忆,为什么在列表中能看到,但使用向量检索(vector)或图检索(graph)却搜不到?
- 原因分析:记忆主记录落库后,稠密/稀疏向量投影与实体关系图谱(Graph)投影可能仍在异步构建中;或者该条记忆在写入时被设置了
handlingPolicy: "no_embedding"/"no_model",系统按治理要求跳过了向量化。另外,若未配置 Chat 模型,Graph 投影将保持为空。 - 解决措施:核对该记忆的
handlingPolicy是否为standard,并检查搜索响应中的degraded字段(如degraded.embedding、degraded.rerank)。若需检查投影完整性,可调用GET /v1/memory/memories/projections/verification核验。
3. 调用多模态图片/PDF 记忆写入时返回 400 或异步任务失败(failed)如何排查?
- 原因分析:常见原因包括:① 显式传入了
async: false(多模态写入强制异步);② 项目未在 Memory → 模型 或对应 Pipeline 中同时配置成对的visionProviderRef与visionModel(如qwen-vl-max);③ 调用 API Key 缺少 Storage 的files.read权限;④ 文件超过 8 MiB、图片超过 16,000,000 像素、PDF 超过 10 页,或解析后总文本超过 20,000 UTF-8 字节。 - 解决措施:通过
GET /v1/memory/jobs/{jobId}查看errorCode与reason,确认视觉模型路由已启用且 Storage 文件满足尺寸与权限要求。