AgentbaseDocs
文档目录

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

功能概述与核心场景

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

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


核心概念与架构

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

核心概念与治理属性表

属性维度参数字段可选枚举值详细语义与安全治理规则
可见范围scopeprivate、strict_private、user、group、project- strict_private / private:严格私有记忆,**禁用 sessionId 历史会话上下文补水**,防止跨轮次隐式关联;<br>- user:归属特定 userId(如 user_zhangwei_001),最常用的个人长期记忆范围;<br>- group:归属特定业务群组,必须同时传入 groupId,检索时校验调用者群组成员身份;<br>- project:项目级共享记忆,对项目内授权主体可见。
敏感度分级sensitivitynormal(默认)、confidential、restricted标识记忆数据的业务敏感等级。注意:若传入 secret 将被服务端直接拒绝(Fail-closed),切勿将密钥、口令或未脱敏隐私作为记忆写入。
模型处理策略handlingPolicystandard(默认)、no_embedding、no_model- standard:允许 Chat 模型推断与 Embedding 向量化;<br>- no_embedding:允许模型文本处理与关键词检索,但不生成向量投影;<br>- 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 融合;<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/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(删除)触发后台 Compactor 清理向量与图投影
批量写入与导入导出API / SDK 批处理入口POST /v1/memory/memories/batch、/imports、/exportsmemories.write / memories.export依赖内部 Artifact Broker 与对象存储

功能详解与操作指南

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

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

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

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

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

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)

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

// 使用官方服务端 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. 乐观锁更新、单条/批量删除与防重学保护


常见问题与排障(FAQ)

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

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

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


相关文档