Docs
文档目录

记忆总览与快速开始

功能概述与核心场景

记忆(Memory)为项目提供长期记忆能力,可将对话或业务事件中的信息保存下来,供后续交互按配置检索使用。它可用于跨会话保存用户偏好、历史事实和任务经验,实际效果取决于数据、模型及检索配置。

启用前需要确认项目表模式、权限及可用模型。下文中的项目名、模型名和用户 ID 均为示例,请使用当前环境中的实际配置。

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 时,数据面读写就绪,控制台开放记忆功能页签。
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记忆链路追踪、链路追踪

跨模块关联与互斥规则

  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)与上述两个记忆开关相互独立,可同时启用。


功能详解与操作指南

以下步骤说明如何准备项目和模型,并启用记忆。项目、模型和权限以实际环境为准。

步骤一:创建或确认项目

  1. 登录控制台并选择组织;需要新建组织时,参考组织与账号管理。

  2. 选择创建项目,填写名称;项目 ID 可以自定义或留空生成。数据库池标签按环境管理员的配置选择,然后提交。

  3. 在项目设置中确认表模式。记忆需要受支持的表模式;如不满足,请联系环境管理员确认可用资源池或评估迁移。

创建项目表单

图:2.12.0 环境中的创建项目表单。

步骤二:准备模型

在项目的模型页面配置可用供应商及向量模型,并确认模型支持的输出维度。对话模型、稀疏向量和重排模型按功能需要准备;模型是否可用与收费以供应商及环境配置为准。

步骤三:启用项目记忆

  1. 在项目左侧导航栏选择记忆。尚未启用时,页面显示启用 Memory。入口和按钮是否可用取决于项目权限及表模式。

记忆未启用状态

图:2.12.0 测试项目中尚未启用记忆。

  1. 选择启用 Memory,在弹窗中填写向量模型供应商、模型和维度,并按实际需求配置对话模型、稀疏向量和重排。模型及其维度必须与可用供应商匹配;初始化前应仔细核对,向量模型配置可能受到初始化后的不可变约束。模型测试可能产生费用。

启用记忆的模型配置

图:2.12.0 测试项目尚未配置模型时的启用弹窗。

  1. 核对配置后点击确认提交并启用。等待页面中的初始化状态更新,再根据状态与错误信息确认是否就绪;耗时取决于环境。下图中的独立测试项目已完成初始化。

测试项目中的记忆服务状态

图: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”?

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

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

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

5. Shared V2 库名含连字符时仍能使用 Memory 吗?

可以。更新后的服务支持已登记资源池使用 appbase-linkque-sharedv2 这类含连字符的物理库名;库名为 1–64 个 ASCII 字符,首字符为字母或数字,后续允许字母、数字、下划线和连字符。该兼容修复不取消项目隔离:签名路由仍须与资源池登记的库名及项目命名空间匹配。

业务用户无需在 Memory 表单、SDK 或请求体中填写物理库名,也不要为绕过初始化错误而重命名现有库或修改内部路由字段。如果含连字符资源池的项目仍初始化失败或被拒绝,记录项目 ID、时间和错误阶段,请管理员核对 Memory 服务部署版本及资源池登记;模型、权限或其他路由错误仍须分别处理。


相关文档