记忆总览与快速开始
功能概述与核心场景
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 提供以下核心能力边界:
- 项目级独立隔离与生命周期管理:支持按项目一键启用、状态巡检、配额治理、暂停禁用与永久清理,底层使用项目专属的
_<projectSequence>物理表组隔离业务数据。 - 双模式记忆写入与多模态接入:支持确定性直接写入(
infer=false)与基于 Pipeline 的异步智能推断(infer=true),并支持解析同项目 Storage(如agent_multimedia_bucket)中的 PNG、JPEG、WebP 图片与 PDF 文档。 - 多路混合检索与统一召回:融合 OceanBase 稠密向量(Dense)、DashScope 稀疏向量(Sparse)、全文关键词(Keyword)与实体关系图谱(Graph),提供带 Token 预算控制的统一召回(Recall)。
- 全生命周期自进化与可观测:涵盖用户画像(Profiles)、分层上下文治理(Contexts & Dreaming)、经验与技能蒸馏(Evolution)、自定义处理流水线(Pipelines)、请求审计(Audit)与端到端链路追踪(Trace)。
核心概念与架构
Agentbase 采用一套逻辑 Memory 服务承载多租户、多项目的架构设计。外部客户端或服务端 SDK 统一通过 Agentbase /v1/memory/* 门面(Facade)发起调用,由平台完成项目鉴权、API Key Scope 校验、生命周期状态检查与动态数据源路由,再签发短期可信上下文交由 Memory 数据面执行。
flowchart TB
subgraph ClientLayer["客户端与业务接入层"]
Console["Agentbase Console 控制台"]
ServerSDK["服务端 SDK (agentbase-node-sdk@2.10.0)"]
Workbench["智能体工作台 (Agent Runtime)"]
end
subgraph FacadeLayer["Agentbase 统一门面与控制面 (/v1)"]
Auth["项目鉴权与 Scope 校验\n(memories.read/write/delete/export)"]
Lifecycle["项目生命周期与表模式守卫\n(强制校验 Shared V2 & status=active)"]
ConfigCenter["版本化配置中心与 Pipeline 引擎\n(provider / policy / prompt / retention / evolution)"]
end
subgraph DataPlane["Memory 统一数据面与后台 Worker"]
Ingest["记忆写入与多模态解析\n(infer=false 直写 / infer=true 事实抽取与冲突消解)"]
Retrieval["多路混合检索引擎\n(Dense + Sparse + Keyword + Graph + Rerank)"]
EvolutionEngine["高阶演进引擎\n(用户画像 / Dreaming 上下文 / 经验与技能蒸馏)"]
Forgetting["自适应遗忘与生命周期清理 Worker"]
end
subgraph InfraLayer["基础设施与模型底座"]
OB[("OceanBase Shared V2\n项目独占表组 _<projectSequence>")]
Gateway["Models / LLM Gateway (dashscope-prod)\ntext-embedding-v3 / qwen-plus / qwen3.7-text-rerank / qwen-vl-max"]
Storage[("Storage 存储桶\nagent_multimedia_bucket")]
Obs["智能体运维 (Observability)\nTrace (capability:memory) & Audit"]
end
Console --> Auth
ServerSDK --> Auth
Workbench --> Auth
Auth --> Lifecycle
Lifecycle --> ConfigCenter
ConfigCenter --> Ingest
ConfigCenter --> Retrieval
ConfigCenter --> EvolutionEngine
Ingest --> OB
Ingest --> Gateway
Ingest --> Storage
Retrieval --> OB
Retrieval --> Gateway
EvolutionEngine --> OB
EvolutionEngine --> Gateway
Forgetting --> OB
DataPlane --> Obs核心概念说明
| 核心概念 | 标识与示例 | 架构职责与关键技术约束 |
|---|---|---|
| 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 | 记忆审计日志 |
| Trace | traces(跳转链接) | 一键跳转至 智能体运维 → 链路(Traces) 页面,并自动附带 ?tag=capability%3Amemory 过滤条件。 | observability.traces.read | 记忆链路追踪、链路追踪 |
跨模块关联与互斥规则
- **存储表模式硬性要求(
Shared V2)**: Memory 强依赖 OceanBaseShared V2表模式的动态项目表组与向量索引能力。Collection、Shared V1与JsonTable模式的存量项目不支持启用 Memory。若在控制台中看到表模式不支持告警,请前往 项目设置 核对表模式或创建新的Shared V2项目。 - 与模型管理(LLM Gateway)的依赖关系: 启用 Memory 前,必须先在项目的 模型网关(LLM Gateway) 中配置好模型提供方(如
dashscope-prod)。Memory 初始化完成后,基础配置中的稠密向量提供方(embeddingProviderRef)、模型名称(embeddingModel)和向量维度(embeddingDims)将永久锁定,防止同一物理表内向量空间混杂。 - 智能体工作台(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)与上述两个记忆开关相互独立,可同时启用。
- 当在智能体工作台开启 Memory 时,系统在保存配置时会自动将
功能详解与操作指南
以下以标杆项目 **企业智能客服与知识中台**(enterprise-ai-hub-210)为例,完整演示从确认项目环境、配置 DashScope 模型路由、启用 Memory 到写入第一条企业级用户记忆的全流程。
步骤一:创建或确认 Shared V2 项目
- 登录 Agentbase 控制台,进入组织
Agentbase 企业智能中台(69c6d1aa00062e6bb60);若首次使用,请先参考 组织与账号管理 完成组织创建。 - 单击右上角 创建项目,输入项目名称
企业智能客服与知识中台,自定义项目 ID 为enterprise-ai-hub-210,选择默认Shared V2数据库资源池后提交。 - 进入项目后,可在左侧导航栏 设置(Settings) 中确认当前项目存储模式为
Shared V2。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
步骤二:在模型网关准备 DashScope 模型
- 在左侧导航栏打开 模型(Models / LLM Gateway),添加 DashScope 提供方
dashscope-prod(兼容端点https://dashscope.aliyuncs.com/compatible-mode/v1,凭据填入<DASHSCOPE_API_KEY>)。 - 登记并启用以下五类核心模型能力,供 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 手册)
- 稠密向量模型(Embedding):
步骤三:通过向导启用项目 Memory
- 在项目左侧导航栏单击 记忆(Memory)。首次进入时页面处于未启用态,展示能力介绍与 启用 Memory 按钮。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
- 单击 启用 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) | 0 | 0 表示不额外限制,按实例物理容量运行 |
| 配额限制(可选) | 最大存储容量 (storageBytes) | 0 | 0 表示不额外限制 |
| 配额限制(可选) | 每分钟请求上限 (requestsPerMinute) | 0 | 0 表示不额外设置项目级特殊限流 |
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
- 单击 下一步 进入启用前确认弹窗,仔细核对 Embedding 提供方、模型名称与维度(确认无误后再提交,避免初始化后因维度不匹配需要重建实例)。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
- 单击 确认启用。此时状态变为
initializing,等待约 3~5 秒后台建表完成后,页面自动刷新为active状态,顶部三张健康卡片全部显示绿色就绪徽标(Active、Ready、Healthy)。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
步骤四:通过 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”?
- 原因分析:Memory 底层需要在项目的独立表命名空间中创建包含向量索引、全文索引和事务栅栏的 9 张关系与向量表,目前仅支持 **OceanBase
Shared V2** 存储模式。若项目创建时属于Collection、Shared V1或JsonTable模式,控制面守卫会拦截启用请求。 - 解决措施:前往 项目设置 查看当前项目的
sourceTableMode。若为非Shared V2项目,建议新建一个基于Shared V2资源池的项目(如enterprise-ai-hub-210),或联系平台管理员评估表模式转换。
2. Memory 卡在 initializing 状态或显示 lastError 初始化失败怎么办?
- 原因分析:初始化过程会验证模型路由连通性(如向
text-embedding-v3发送维度探测请求)并在数据库中创建表结构。如果dashscope-prod的 API Key 无效、填写的embeddingDims(如误填为1536而实际模型返回1024)不匹配,或数据库连接池瞬时繁忙,会导致初始化失败并记录lastError.code与lastError.stage。 - 解决措施:不要删除或重建整个项目。先根据页面红色错误横幅中的
stage与message前往 模型网关 修正 Provider 凭据或维度参数,然后回到 Memory 页面单击右上角 重新启用(Retry Enable),系统会递增revision并幂等完成剩余初始化步骤。
3. 在智能体工作台(Agent Workbench)中开启 Memory 后,为什么原本开启的 PowerContext 自动关闭了?
- 原因分析:Agent Runtime 的长期记忆提供方采用单活互斥设计(
memory_enabled与powercontext_enabled互斥),以避免同一次 Agent Run 同时向两套长期记忆引擎重复写入与召回冲突上下文。 - 解决措施:这是预期设计行为。若业务使用 Agentbase 原生 Memory(包含本文档介绍的记忆、画像、Dreaming 上下文与经验蒸馏),请保持
memory_enabled: true且powercontext_enabled: false。
4. 暂停禁用(Disable)与永久删除(Delete)项目 Memory 有什么区别?
- 原因分析:部分运维人员担心禁用操作会丢失已积累的客户记忆与画像。
- 解决措施:禁用(Disable) 仅关闭
/v1/memory/*数据面访问入口(状态变为disabled),所有物理表、向量索引、画像和知识版本均安全保留,随时可重新启用恢复业务;而 永久删除(Delete)(状态变为deleting)会异步销毁该项目下的所有 Memory 物理表组与已生成产物,不可逆转。执行永久删除前请务必先通过导出接口备份核心数据。