Docs
文档目录

记忆总览与快速开始

功能概述与核心场景

AI 记忆(Memory)是 Agentbase(v2.10.0)提供的项目级企业长期记忆能力。在多轮对话、智能客服、技术支持工单与复杂任务编排场景中,大语言模型受限于单次推理上下文窗口(Context Window),无法跨会话持久记住用户的个人偏好、历史事实、架构环境配置与排障操作经验。Agentbase Memory 通过统一的控制面与高性能数据面,帮助应用从对话和业务事件中提取、去重、冲突消解并持久化记忆,在后续交互中按语义、稀疏词项、关键词或实体关系图谱精准召回。

在 Agentbase 企业智能中台(组织 ID:69c6d1aa00062e6bb60)的标杆项目 企业智能客服与知识中台(项目 ID:enterprise-ai-hub-210)中,Memory 运行于 OceanBase Shared V2 存储模式之上,打通了 DashScope 模型提供方(dashscope-prod)的稠密向量模型 text-embedding-v3(1024 维)、稀疏向量路由、对话模型 qwen-plus、重排模型 qwen3.7-text-rerank 以及多模态视觉模型 qwen-vl-max。客服智能体不仅能够记住 VIP 架构师 user_zhangwei_001 与一线工程师 user_lina_002 的技术栈偏好和集群拓扑事实,还能自动汇总用户画像、通过后台 Dreaming 构建分层上下文,并将排障轨迹蒸馏为可复用的经验(Experience)与技能(Skill)。

Memory 提供以下核心能力边界:


核心概念与架构

Agentbase 采用一套逻辑 Memory 服务承载多租户、多项目的架构设计。外部客户端或服务端 SDK 统一通过 Agentbase /v1/memory/* 门面(Facade)发起调用,由平台完成项目鉴权、API Key Scope 校验、生命周期状态检查与动态数据源路由,再签发短期可信上下文交由 Memory 数据面执行。

记忆总览与快速开始:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

核心概念说明

核心概念标识与示例架构职责与关键技术约束
Project Memory(项目记忆实例)项目 enterprise-ai-hub-210项目级配额、模型路由、数据库路由版本(databaseRouteVersion)与生命周期版本号(revision)的承载单元。必须运行在 OceanBase Shared V2 表模式项目中。
Memory(记忆记录)mem_8f92a1c4...单条可检索的记忆单元,包含正文(content)、记忆类型(memoryType)、记录种类(recordKind:事实 fact、对话 conversation、动作 action)、可见范围(scope)与乐观锁版本号(version)。
Source(不可变来源)src_7b31e0d2...触发记忆写入、画像更新或知识蒸馏的原始对话、文本或多模态文件引用。用于溯源解释、会话历史补水与幂等检查点恢复。
Profile(用户画像)用户 user_zhangwei_001基于同一用户的有效记忆来源提炼而成的全景描述,支持正文(content)与主题(topics)两种视图,支持增量合并与全量替换。
Context & Dreaming(分层上下文)L2 Topic / Episode / State、L3 Overview后台 Dreaming 任务异步扫描变化记忆,聚合成 L2 主题/事件/状态与 L3 全局概览,支持渐进式检索(Progressive Retrieval)与人工确认。
Experience & Skill(经验与技能)dst_3e5b09f456c5d5c332507ec1dbe3eb6d从客服排障对话或工具调用轨迹中蒸馏出的可复用排障经验(Experience)与标准化操作步骤(Skill),支持 shadow -> active 状态跃迁与二次确认。
Pipeline(业务处理流水线)新增记忆 / 画像 / 经验与技能 / 遗忘固化处理步骤顺序的可版本化流程配置,支持节点级 Prompt 与模型路由覆盖、草稿保存、Dry-run 样例测试与一键发布。

项目 Memory 生命周期状态机

项目 Memory 通过控制面接口 /v1/projects/{projectId}/memory 管理状态流转,严格遵循乐观并发控制(expectedRevision):

状态值控制台展示名称状态说明与允许的操作
null(未启用)未启用 Memory项目尚未初始化 Memory,接口返回 HTTP 200 及 project: null。项目管理员可单击 启用 Memory 启动配置向导。
initializing初始化中(Provisioning)已提交启用请求(HTTP 202),后台 Worker 正在项目所属的 Shared V2 数据库中幂等创建 _<projectSequence> 独占表组并校验向量索引。页面每 1.5 秒自动轮询;若最终失败会展示 lastError 错误码与阶段,修复模型配置后可重新启用。
active可用(Active)当 project.status=active 且 project.schema.status=ready、serviceHealth.status=healthy 时,数据面读写全面就绪,控制台开放全部 8 个功能页签。
disabled已禁用 / 已暂停(Disabled / Suspended)管理员执行暂停禁用(PATCH 传入 enabled: false)后进入该状态。立即停止数据面读写访问,但完整保留底层物理表数据与配置。可通过重新调用启用流程(POST)恢复至 active,或执行永久删除。
deleting删除中(Deleting)管理员确认永久删除(DELETE)后进入该状态。后台建立删除栅栏(Fence)并清理该项目 Memory 物理表组与产物,保留项目配置草稿供日后重新启用。删除不可撤销。

功能入口与权限矩阵

控制台入口与 8 大功能页签

登录 Agentbase 控制台,进入组织 Agentbase 企业智能中台(69c6d1aa00062e6bb60)下的项目 企业智能客服与知识中台(enterprise-ai-hub-210),在左侧导航栏单击 记忆(Memory)(路由:/console/project-{region}-enterprise-ai-hub-210/memory)。当项目 Memory 处于 active 状态时,控制台顶部展示 3 张健康摘要卡(生命周期状态 Revision、表结构状态 Route version、服务健康状态 Fixed service endpoint)以及 8 个核心页签:

页签名称内部视图标识核心功能定位所需权限 / Scope详细文档入口
记忆memories直接写入事实、从对话异步提取记忆、按五种模式检索记忆及单条删除。memories.read / memories.write / memories.delete记忆管理、多层记忆划分
画像profiles查询用户画像(content / topics)、触发增量更新、按证据重新生成或删除画像。memories.read / memories.write / memories.delete用户画像
经验与技能evolution按 user/agent/project 范围提交执行证据蒸馏,查看、编辑、批准或回滚经验与技能版本。memories.read / memories.write / projects.write(审批)经验与技能知识蒸馏、经验与技能演进
模型models集中查看与维护 provider 命名空间的默认模型路由(Embedding、Sparse、Chat、Rerank、Vision)。projects.read / projects.write记忆模型路由
上下文governance查看 Dreaming 水位与任务状态,按 L2/L3 过滤分层上下文,执行确认、重建与版本回滚。memories.read / memories.write / projects.write上下文治理、多层记忆划分
配置configuration管理四类业务 Pipeline(新增记忆、画像、经验与技能、遗忘)及 5 大系统配置命名空间。projects.read / projects.write记忆配置中心、记忆遗忘机制
审计audit按请求 ID、任务 ID、用户 ID 或操作名核对写入、检索、治理等请求的执行回执与耗时。memories.read记忆审计日志
Tracetraces(跳转链接)一键跳转至 智能体运维 → 链路(Traces) 页面,并自动附带 ?tag=capability%3Amemory 过滤条件。observability.traces.read记忆链路追踪、链路追踪

跨模块关联与互斥规则

  1. 存储表模式硬性要求(Shared V2): Memory 强依赖 OceanBase Shared V2 表模式的动态项目表组与向量索引能力。Collection、Shared V1 与 JsonTable 模式的存量项目不支持启用 Memory。若在控制台中看到表模式不支持告警,请前往 项目设置 核对表模式或创建新的 Shared V2 项目。

  2. 与模型管理(LLM Gateway)的依赖关系: 启用 Memory 前,必须先在项目的 模型网关(LLM Gateway) 中配置好模型提供方(如 dashscope-prod)。Memory 初始化完成后,基础配置中的稠密向量提供方(embeddingProviderRef)、模型名称(embeddingModel)和向量维度(embeddingDims)将永久锁定,防止同一物理表内向量空间混杂。

  3. 智能体工作台(Agent Runtime)中 Memory 与 PowerContext 的互斥规则: 在项目的 Agent Workbench(智能体工作台)(配置接口 /v1/agent-runtime/project/config)中,长期记忆提供 独立 Memory(memory_enabled) 与 托管 PowerContext(powercontext_enabled) 两种方案,二者严格互斥,不能同时开启(但允许同时关闭):

    • 当在智能体工作台开启 Memory 时,系统在保存配置时会自动将 powercontext_enabled 原子切换为 false;

    • 当开启 PowerContext 时,系统会自动将 memory_enabled 原子切换为 false;

    • 若通过 API 请求同时传入 memory_enabled: true 和 powercontext_enabled: true,服务端将直接拒绝并返回 400 general_argument_invalid 参数错误,保护现有配置不被破坏。

    • 知识库检索(Knowledge Search,如绑定 kb_enterprise_support 与词典 lex_enterprise_synonyms)与上述两个记忆开关相互独立,可同时启用。


功能详解与操作指南

以下以标杆项目 企业智能客服与知识中台(enterprise-ai-hub-210)为例,完整演示从确认项目环境、配置 DashScope 模型路由、启用 Memory 到写入第一条企业级用户记忆的全流程。

步骤一:创建或确认 Shared V2 项目

  1. 登录 Agentbase 控制台,进入组织 Agentbase 企业智能中台(69c6d1aa00062e6bb60);若首次使用,请先参考 组织与账号管理 完成组织创建。

  2. 单击右上角 创建项目,输入项目名称 企业智能客服与知识中台,自定义项目 ID 为 enterprise-ai-hub-210,选择默认 Shared V2 数据库资源池后提交。

  3. 进入项目后,可在左侧导航栏 设置(Settings) 中确认当前项目存储模式为 Shared V2。

创建项目(沿用已登记截图)

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

步骤二:在模型网关准备 DashScope 模型

  1. 在左侧导航栏打开 模型(Models / LLM Gateway),添加 DashScope 提供方 dashscope-prod(兼容端点 https://dashscope.aliyuncs.com/compatible-mode/v1,凭据填入 <DASHSCOPE_API_KEY>)。

  2. 登记并启用以下五类核心模型能力,供 Memory 各阶段调用:

    • 稠密向量模型(Embedding):text-embedding-v3(向量维度 1024)

    • 稀疏向量路由(Sparse Embedding):DashScope Sparse 路由(用于混合检索中的精确词项权重匹配)

    • 对话生成模型(Chat LLM):qwen-plus(主路由)与 qwen-turbo(备用)

    • 重排模型(Rerank):qwen3.7-text-rerank

    • 视觉多模态模型(Vision LLM):qwen-vl-max(用于解析 Storage 中的架构图与 PDF 手册)

步骤三:通过向导启用项目 Memory

  1. 在项目左侧导航栏单击 记忆(Memory)。首次进入时页面处于未启用态,展示能力介绍与 启用 Memory 按钮。

Memory 未启用态(沿用已登记截图)

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

  1. 单击 启用 Memory 打开模型路由与配额配置弹窗,按以下参数表完成配置:

配置分组字段名称标杆项目配置值约束与说明
向量索引(必填)Embedding 提供方 (embeddingProviderRef)project:dashscope-prod初始化后锁定,不可更改
向量索引(必填)Embedding 模型 (embeddingModel)text-embedding-v3初始化后锁定,不可更改
向量索引(必填)向量维度 (embeddingDims)1024必须与模型实际输出维度严格一致,初始化后锁定
稀疏向量(默认开启)开启稀疏向量 (sparseEmbeddingEnabled)开启 (true)新启用向导默认开启,绑定 DashScope Sparse 路由;若不使用可手动关闭
智能处理(必填)Chat 提供方与模型 (llmProviderRef / chatModel)project:dashscope-prod / qwen-plus用于 infer=true 事实提取、冲突消解、画像生成与经验蒸馏
重排(默认开启)开启重排与模型 (rerankEnabled / rerankModel)开启 (true) / qwen3.7-text-rerank新项目向导默认开启重排;若未准备 Rerank 模型请先关闭开关
配额限制(可选)最大记忆条数 (maxMemories)00 表示不额外限制,按实例物理容量运行
配额限制(可选)最大存储容量 (storageBytes)00 表示不额外限制
配额限制(可选)每分钟请求上限 (requestsPerMinute)00 表示不额外设置项目级特殊限流

Memory 模型路由配置弹窗(沿用已登记截图)

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

  1. 单击 下一步 进入启用前确认弹窗,仔细核对 Embedding 提供方、模型名称与维度(确认无误后再提交,避免初始化后因维度不匹配需要重建实例)。

Memory 启用前确认弹窗(沿用已登记截图)

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

  1. 单击 确认启用。此时状态变为 initializing,等待约 3~5 秒后台建表完成后,页面自动刷新为 active 状态,顶部三张健康卡片全部显示绿色就绪徽标(Active、Ready、Healthy)。

Memory 就绪工作台(沿用已登记截图)

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

步骤四:通过 API / SDK 验证生命周期与写入第一条记忆

在 项目总览 → 集成 → API keys 中创建服务端 API Key(授权 memories.read、memories.write、memories.delete、memories.export),即可在业务后端通过 REST API 或 agentbase-node-sdk@2.10.0 接入:

export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
export APPBASE_API_KEY="<APPBASE_API_KEY>"

# 1. 核对 Memory 数据面健康与统计信息
curl -fsS "${APPBASE_ENDPOINT}/memory/memories/stats" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" | jq .

# 2. 为 VIP 架构师 user_zhangwei_001 写入第一条架构偏好记忆
curl -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Idempotency-Key: init-mem-zhangwei-001" \
  -H "Content-Type: application/json" \
  --data '{
    "userId": "user_zhangwei_001",
    "scope": "user",
    "memoryType": "preference",
    "recordKind": "fact",
    "content": "张伟架构师负责核心账务集群,偏好直接给出 OceanBase 分布式事务与向量索引 SQL 排障命令,不需要基础概念解释。",
    "metadata": {
      "department": "core-banking-arch",
      "slaTier": "P0-VIP"
    },
    "infer": false
  }' | jq .

返回 status: "completed" 及生成的 memoryId,代表项目 Memory 已完成端到端生产就绪验证。


常见问题与排障(FAQ)

1. 为什么在控制台进入 Memory 页面时提示“当前项目表模式不支持启用 Memory”?

2. Memory 卡在 initializing 状态或显示 lastError 初始化失败怎么办?

3. 在智能体工作台(Agent Workbench)中开启 Memory 后,为什么原本开启的 PowerContext 自动关闭了?

4. 暂停禁用(Disable)与永久删除(Delete)项目 Memory 有什么区别?


相关文档