记忆总览与快速开始
功能概述与核心场景
记忆(Memory)为项目提供长期记忆能力,可将对话或业务事件中的信息保存下来,供后续交互按配置检索使用。它可用于跨会话保存用户偏好、历史事实和任务经验,实际效果取决于数据、模型及检索配置。
启用前需要确认项目表模式、权限及可用模型。下文中的项目名、模型名和用户 ID 均为示例,请使用当前环境中的实际配置。
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 数据面执行。
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
核心概念说明
| 核心概念 | 标识与示例 | 架构职责与关键技术约束 |
|---|---|---|
| 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 时,数据面读写就绪,控制台开放记忆功能页签。 |
disabled | 已禁用 / 已暂停(Disabled / Suspended) | 管理员执行暂停禁用(PATCH 传入 enabled: false)后进入该状态。立即停止数据面读写访问,但完整保留底层物理表数据与配置。可通过重新调用启用流程(POST)恢复至 active,或执行永久删除。 |
deleting | 删除中(Deleting) | 管理员确认永久删除(DELETE)后进入该状态。后台建立删除栅栏(Fence)并清理该项目 Memory 物理表组与产物,保留项目配置草稿供日后重新启用。删除不可撤销。 |
功能入口与权限矩阵
控制台入口与功能导航
登录 Agentbase 控制台,选择目标项目,在左侧导航栏单击 记忆(路由:/console/project-{region}-{projectId}/memory)。当项目 Memory 处于 active 状态时,页面展示 7 个功能页签以及独立的 记忆链路追踪入口:
| 页签名称 | 内部视图标识 | 核心功能定位 | 所需权限 / 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 | 记忆审计日志 |
| 记忆链路追踪(独立入口) | traces(跳转链接) | 跳转至 智能体运维 → 链路 页面,并附带 ?tag=memory 筛选条件。 | 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)与上述两个记忆开关相互独立,可同时启用。
功能详解与操作指南
以下步骤说明如何准备项目和模型,并启用记忆。项目、模型和权限以实际环境为准。
步骤一:创建或确认项目
登录控制台并选择组织;需要新建组织时,参考组织与账号管理。
选择创建项目,填写名称;项目 ID 可以自定义或留空生成。数据库池标签按环境管理员的配置选择,然后提交。
在项目设置中确认表模式。记忆需要受支持的表模式;如不满足,请联系环境管理员确认可用资源池或评估迁移。
图:2.12.0 环境中的创建项目表单。
步骤二:准备模型
在项目的模型页面配置可用供应商及向量模型,并确认模型支持的输出维度。对话模型、稀疏向量和重排模型按功能需要准备;模型是否可用与收费以供应商及环境配置为准。
步骤三:启用项目记忆
在项目左侧导航栏选择记忆。尚未启用时,页面显示启用 Memory。入口和按钮是否可用取决于项目权限及表模式。
图:2.12.0 测试项目中尚未启用记忆。
选择启用 Memory,在弹窗中填写向量模型供应商、模型和维度,并按实际需求配置对话模型、稀疏向量和重排。模型及其维度必须与可用供应商匹配;初始化前应仔细核对,向量模型配置可能受到初始化后的不可变约束。模型测试可能产生费用。
图:2.12.0 测试项目尚未配置模型时的启用弹窗。
核对配置后点击确认提交并启用。等待页面中的初始化状态更新,再根据状态与错误信息确认是否就绪;耗时取决于环境。下图中的独立测试项目已完成初始化。
图:2.12.0 测试项目中的记忆服务已启用,项目表结构已就绪。
步骤四:通过 API / SDK 验证生命周期与写入第一条记忆
创建项目级服务端 API Key。以下两个请求分别需要 memories.read 和 memories.write;请替换为实际端点与项目 ID,避免将密钥放入命令历史或请求参数:
每次新写入前设置独立的 MEMORY_IDEMPOTENCY_KEY;仅在重试同一次写入时沿用原键和相同请求内容。
APPBASE_ENDPOINT="https://your-agentbase.example.com/v1"
APPBASE_PROJECT_ID="your-project-id"
read -r -s -p 'API key: ' APPBASE_API_KEY
printf '\n'
(
set +x
set -e -o pipefail
: "${MEMORY_IDEMPOTENCY_KEY:?Set a unique key for this new write}"
# 1. 核对 Memory 数据面健康与统计信息
HEALTH_RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | \
curl --disable --header @- -fsS -w '\n%{http_code}' \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
"${APPBASE_ENDPOINT}/memory/memories/stats")"
case "${HEALTH_RESPONSE##*$'\n'}" in
2??) builtin printf '%s\n' "${HEALTH_RESPONSE%$'\n'*}" ;;
*) builtin printf 'Memory health check returned a non-2xx response\n' >&2; exit 1 ;;
esac
# 2. 为 VIP 架构师 user_zhangwei_001 写入第一条架构偏好记忆
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | \
curl --disable --header @- -fsS -w '\nHTTP %{http_code}\n' -X POST "${APPBASE_ENDPOINT}/memory/memories" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "Idempotency-Key: ${MEMORY_IDEMPOTENCY_KEY}" \
-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
}'
)
APPBASE_RESULT=$?
unset APPBASE_API_KEY
(exit "$APPBASE_RESULT")根据 HTTP 状态码和响应核对写入结果。单次请求成功只说明该次操作完成,仍需分别验证读取、权限和实际业务流程。
常见问题与排障(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 物理表组与已生成产物,不可逆转。执行永久删除前请务必先通过导出接口备份核心数据。
5. Shared V2 库名含连字符时仍能使用 Memory 吗?
可以。更新后的服务支持已登记资源池使用 appbase-linkque-sharedv2 这类含连字符的物理库名;库名为 1–64 个 ASCII 字符,首字符为字母或数字,后续允许字母、数字、下划线和连字符。该兼容修复不取消项目隔离:签名路由仍须与资源池登记的库名及项目命名空间匹配。
业务用户无需在 Memory 表单、SDK 或请求体中填写物理库名,也不要为绕过初始化错误而重命名现有库或修改内部路由字段。如果含连字符资源池的项目仍初始化失败或被拒绝,记录项目 ID、时间和错误阶段,请管理员核对 Memory 服务部署版本及资源池登记;模型、权限或其他路由错误仍须分别处理。




