Docs
文档目录

记忆管理(新建、检索与删除记忆)

功能概述与核心场景

记忆管理(Memories)是 Agentbase Memory 的核心数据面操作中心,负责单条与批量记忆的写入、多模态文档/图片解析入库、会话历史上下文推断、五路混合检索(Hybrid / Vector / Sparse / Keyword / Graph)、带 Token 预算的统一召回(Recall)、数据导入导出以及合规遗忘删除。

在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的 企业智能客服与知识中台(enterprise-ai-hub-210)项目中,智能客服系统通过记忆管理能力分别服务不同层级的企业客户:


核心概念与架构

Memory 的写入与检索链路采用“同步确定性直写 + 异步模型推断管线”与“多路索引投影 + 重排融合”的双引擎架构。

核心概念与治理属性表

属性维度参数字段可选枚举值详细语义与安全治理规则
可见范围scopeprivate、strict_private、user、group、project- strict_private / private:严格私有记忆,禁用 sessionId 历史会话上下文补水,防止跨轮次隐式关联;
- user:归属特定 userId(如 user_zhangwei_001),最常用的个人长期记忆范围;
- group:归属特定业务群组,必须同时传入 groupId,检索时校验调用者群组成员身份;
- project:项目级共享记忆,对项目内授权主体可见。
敏感度分级sensitivitynormal(默认)、confidential、restricted标识记忆数据的业务敏感等级。注意:若传入 secret 将被服务端直接拒绝(Fail-closed),切勿将密钥、口令或未脱敏隐私作为记忆写入。
模型处理策略handlingPolicystandard(默认)、no_embedding、no_model- standard:允许 Chat 模型推断与 Embedding 向量化;
- no_embedding:允许模型文本处理与关键词检索,但不生成向量投影;
- no_model:严禁任何大模型接触该条数据,要求必须显式设置 infer=false,且拒绝多模态媒体解析。
记录种类recordKindfact、conversation、action区分提炼后的客观事实(fact)、原始对话片段(conversation)与智能体工具执行动作(action),分别适用 retention 命名空间下的不同保留天数策略。
记忆类型memoryTypepreference、fact、long_term、short_term、working、conversation、action 或自定义字符串业务分类标签。在 infer=false 直接写入时由调用方指定;在 infer=true 按流程处理时由新增记忆 Pipeline 自动分类生成。
检索模式searchModehybrid(默认)、vector、sparse、keyword、graph- hybrid:综合稠密向量、稀疏向量与全文索引进行 RRF 融合;
- vector:纯稠密语义向量检索;
- sparse:基于 DashScope 稀疏向量的高维词项权重检索;
- keyword:全文检索(对 1~2 字短词如“锁表”自动启用参数化精确子串兜底);
- graph:基于模型抽取的“实体—关系—实体”有向边执行最多 2 跳图遍历召回。

功能入口与权限矩阵

操作入口与角色权限矩阵

控制台入口位于:项目 enterprise-ai-hub-210 → 记忆(Memory) → 记忆 页签。

操作场景控制台操作入口REST API 端点所需 API Key Scope关联模块与依赖
创建单条/对话记忆添加记忆 按钮POST /v1/memory/memoriesmemories.write(多模态需额外具备 files.read)关联 配置中心 的新增记忆 Pipeline 与 存储(Storage)
查询异步写入任务提交回执弹窗自动轮询GET /v1/memory/jobs/{jobId}memories.write 或 memories.read关联 记忆审计 与 链路追踪
列表与来源溯源记忆列表 查询GET /v1/memory/memories、GET /v1/memory/memories/{memoryId}/sourcesmemories.read为 用户画像 与 上下文治理 提供底层证据
多路检索与渐进召回搜索框 + 检索模式下拉框POST /v1/memory/memories/search、POST /v1/memory/memories/recallmemories.read为 Agent Workbench(智能体工作台) 提供实时上下文注入
更新与单条/批量删除记忆列表行尾 删除 按钮PATCH /v1/memory/memories/{memoryId}、DELETE /v1/memory/memories/{memoryId}、DELETE /v1/memory/memoriesmemories.write(更新) / memories.delete(删除)单条删除在事务内移除主记录和召回投影,相关知识来源随后处理
批量写入与导入导出API / SDK 批处理入口POST /v1/memory/memories/batch、/imports、/exportsmemories.write / memories.export依赖内部 Artifact Broker 与对象存储

功能详解与操作指南

1. 在控制台直接写入确定性事实(infer=false)

当业务应用已经明确整理好用户偏好或系统环境事实,无需大模型二次改写时,使用直接写入模式(同步落库):

  1. 进入目标项目的 记忆 → 记忆列表 页签,单击 创建记忆。

  2. 在弹窗中按下表填写参数:

    • 用户 ID(userId):输入 user_zhangwei_001(或演示账号 demo-user)。

    • 可见范围(scope):选择 user。

    • 处理方式:选择 直接写入(对应 API infer: false, async: false)。

    • 记忆类型(memoryType):输入或选择 preference。

    • 记录种类(recordKind):选择 事实(fact)。

    • 正文(content):输入非空文本(控制台限制长度为 20,000),例如 用户张伟(核心账务架构师)偏好直接查看 OceanBase V4 分布式死锁排查 SQL 与向量索引 HNSW 参数说明。。

    • 元数据(metadata):在键值字段中添加 ticketId 和 env 等条目;通过 API 调用时使用 JSON 对象。

创建记忆弹窗

图:2.12.0 测试项目的创建记忆表单。

  1. 单击 确认,查看执行回执及其实际状态。如果返回任务 ID,等待任务进入终态;失败时查看错误信息。

记忆写入结果详情

图:2.12.0 测试项目中的直接写入回执,测试标识已遮罩。

2. 从多轮对话异步智能提取记忆(infer=true 与会话历史补水)

在实际客服会话中,用户的关键信息往往分布在多轮问答中(例如上一轮客服给出选项 A/B,下一轮用户仅回复“我选 A”)。此时应使用按流程处理(infer=true):

  1. 在 创建记忆 弹窗中,将 处理方式 切换为 按流程处理。

  2. 选择 使用默认 Pipeline 或指定已发布的新增记忆流水线(草稿状态流水线不可用于正式写入)。此时无需手动填写 memoryType,由所选流水线处理,实际使用的模型取决于项目配置。

  3. 输入对话内容并提交。文本智能提取默认异步执行;查看回执中的任务状态和 jobId,等待处理完成后再检查结果。

  4. 会话上下文推断(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,属正常现象)。

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 .

多模态输入技术边界与约束:

4. 多路混合检索、渐进式检索与统一召回(Recall)

  1. 在控制台选择 记忆 → 记忆列表。如需按用户过滤,填写目标用户 ID;不填写时不按用户 ID 限定。

  2. 在搜索框中输入问题,选择检索方式后按 Enter 或单击搜索图标。混合检索中的包含稀疏检索需要相应模型;未配置时可关闭该选项。可用方式和结果取决于实际配置。

记忆检索列表

图:2.12.0 测试项目的合成记忆检索结果。

  1. 在业务服务端使用 agentbase-node-sdk@2.12.0 执行渐进式检索与统一召回: 当智能体需要在单次推理前组装用户的普通记忆、用户画像、经验(Experience)与技能(Skill),并控制上下文预算时,可使用统一召回接口 POST /v1/memory/memories/recall 或渐进式检索策略:

运行前将 <APPBASE_ENDPOINT_WITH_V1> 和 <APPBASE_PROJECT_ID> 替换为已确认的目标 API 地址和项目 ID。未替换时 SDK 会拒绝无效地址,不会发送请求。

// 使用官方服务端 SDK: agentbase-node-sdk@2.12.0
import { Client, Memory } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
    .setProject('<APPBASE_PROJECT_ID>')
    .setKey(process.env.APPBASE_API_KEY);

const memory = new Memory(client);

// 1. 渐进式多路检索 (L3 Overview -> L2 Context -> L1 Fact)
const searchResult = await memory.search({
    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.recallKnowledge({
    userId: 'user_zhangwei_001',
    scope: 'user',
    query: '如何处理 TK-20261022-001 工单中的向量索引重建超时问题?',
    tokenBudget: 2000
});

5. 乐观锁更新、单条/批量删除与防重学保护


常见问题与排障(FAQ)

1. 为什么提交“按流程处理(infer=true)”后,任务状态显示 succeeded,但在记忆列表中查不到新记录?

2. 刚刚写入成功的记忆,为什么在列表中能看到,但使用向量检索(vector)或图检索(graph)却搜不到?

3. 调用多模态图片/PDF 记忆写入时返回 400 或异步任务失败(failed)如何排查?


相关文档