AgentbaseDocs
文档目录

记忆总览与快速开始

功能概述与核心场景

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 数据面执行。

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记忆审计日志
Tracetraces(跳转链接)一键跳转至 智能体运维 → 链路(Traces) 页面,并自动附带 ?tag=capability%3Amemory 过滤条件。observability.traces.read记忆链路追踪、链路追踪

跨模块关联与互斥规则


功能详解与操作指南

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

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

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

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

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

步骤三:通过向导启用项目 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 表示不额外设置项目级特殊限流

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

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

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

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

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

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

步骤四:通过 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 有什么区别?


相关文档