Docs
文档目录

从新建项目到用 SDK 操作记忆

本页按实际接入顺序准备项目,下一页提供可运行的 SDK 示例。适用于 Agentbase 2.10.0;Node.js 示例使用 agentbase-node-sdk@2.9.0。

先完成一个演示项目

  1. 登录 Console,进入组织;没有组织时先创建组织。

  2. 单击创建项目,填写名称,例如“咖啡助手”,按页面提供的区域与数据库资源池标签提交。记下项目 ID,在 Memory 页面确认支持启用;Shared V2 由项目使用的资源池决定,不是创建表单中的独立选项。

  3. 进入项目模型管理(LLM Gateway),配置 Embedding 与 Chat 提供方、模型。暂不使用重排或 sparse 时在启用向导关闭对应可选项。

  4. 回到 Memory 启用向导,选好模型、实际向量维度及配额,提交后等待项目 active、数据 ready。

  5. 打开 记忆 → 添加记忆,用户 ID 填 demo-user,范围选用户(user),处理方式选直接写入,记忆类型填 preference、记录种类选事实(fact),保存“用户喜欢拿铁咖啡。”。

  6. 按该用户 ID 筛选列表,核对记录正文与 ID。SDK 后续使用相同项目和目标用户。

详细 Console 操作见从创建项目开始使用记忆。项目启用不再需要创建 Memory Resource 或绑定资源。

为服务端创建 API Key

项目 Overview → Integrations → API keys,选择创建 API Key:

计划操作需要的 scope
读回、列表、搜索、统一召回、读画像与蒸馏状态memories.read
写入、更新、查询异步写入任务、提取画像和蒸馏memories.write
遗忘本次演示记忆memories.delete
导出memories.export

复制区域 endpoint、项目 ID 与密钥。SDK 的 endpoint 包含 /v1,例如 https://<agentbase-host>/v1;不要复制 Console 页面 URL。密钥来自目标项目的 API keys,Console 登录账号与业务 userId 是不同概念;本演示使用业务用户标识 demo-user。

密钥只在后端环境变量或密钥管理设施中保存。浏览器用用户 Session,不能把项目 API Key 放入前端代码。跨用户读取或写入由业务后端鉴权。

安装并运行

准备 Node.js 20 或更高版本,在新的本地演示目录执行:

mkdir memory-demo
cd memory-demo
npm init -y
npm install --save-exact agentbase-node-sdk@2.9.0

然后配置环境变量:

export APPBASE_ENDPOINT="https://<agentbase-host>/v1"
export APPBASE_PROJECT_ID="<project-id>"
export APPBASE_API_KEY="<project-api-key>"
export APPBASE_USER_ID="demo-user"
export MEMORY_OPERATION_ID="$(node -p 'require("node:crypto").randomUUID()')"

将完整 SDK 示例保存为 memory-demo.mjs,执行:

node memory-demo.mjs

示例依次创建一条带本次操作标记的新记忆、读回、按用户列出、语义检索、统一召回、携带版本更新,最后主动删除它自己新建的那条记忆。运行前给演示 Key 授予 memories.read、memories.write、memories.delete 三类权限。示例不会删除前面在 Console 手工创建的记忆;主动删除不可撤销。

MEMORY_OPERATION_ID 是一次逻辑创建的幂等标识。超时重试同一创建时保留原值;开始另一条写入时换新值。完整脚本包含最终删除,不应在删除后把整个脚本原样当作同一次创建重放。

示例把本次操作标记放进演示正文,是为了让新一轮演示与上次已删除的内容区分开。真实应用应保留业务正文原意;确需重新学习已遗忘的相同内容时,显式使用 reRemember=true 和新的幂等键创建新证据。仅更换幂等键不能绕过内容保护。

应用里如何使用

用户行为SDK 操作读取结果
用户明确告诉应用一条事实create,infer=false,按衰减周期指定 memoryType(working / short_term / long_term)与可见范围 scope(strict_private / private / user / group / project)status=completed 后取 memory.memoryId。
对话结束后提取值得长期保留的信息(或多模态图片/PDF 抽取)create,infer=true、sessionId(自动关联最近 12 轮上下文)、handlingPolicy(standard / no_embedding / no_model)、media: {bucketId, fileId}、或重学已遗忘记忆 reRemember: true通常返回 jobId,轮询 getJob;检查 result.status 和 actions(ADD / UPDATE / DELETE / NONE)。
打开该用户的记忆管理页list、getmemories / memory;列表翻页原样传 nextCursor。
发送新问题,走五路混合检索、模型生成稀疏向量或渐进式召回search(mode: hybrid|vector|keyword|graph|profile、retrieval.sparse: true|false|"auto"、retrieval.strategy: "progressive"、deadlineMs: 450)普通命中读 items[].memory;渐进式召回读 progressive.items(L3 领域综述 → L2 上下文主题 → L1 原子事实 → L0 原始证据)并用 expansionToken 展开下一层;检查 degraded。
组装用户画像、经验、技能和记忆上下文recallKnowledge(统一 Token 预算内联合召回 memory + profile + experience + skill)context、items、usedTokens、injectionId、degraded;应用再把需要的上下文送入自己的模型调用,并可用 injectionId 调 createKnowledgeFeedback / createKnowledgeObservation 归因。
从多轮对话与工具轨迹蒸馏经验/技能,并做上下文做梦(Dreaming)submitDistillation(mode: "async" | "wait"、messages、toolEvents)、createContextRun、confirmContext / rebuildContext / rollbackContext轮询 getDistillation 检查候选产出,经自进化审批单(/v1/memory/memories/knowledge/reviews/{reviewId}/approve|reject)晋升上线。
用户纠正了某条事实get 后 update传当前 memory.version,保存新的返回版本。
用户要求删除某条信息delete / deleteMany返回 status=forgotten,主动删除记录与检索数据;来源证据和审计仍可能保留。

搜索和召回不等于向聊天模型提问,也不会自动替应用生成最终回答。写入完成后,向量等投影可能仍在后台准备;语义结果为空时先检查用户、范围和索引状态,不立即重复写入。

继续接入

新增 pipelineId、媒体输入等字段以服务端 REST 契约为准。已发布 2.9.0 SDK 的 create/search 未包含 media,create、createImport、createProfileExtraction、submitDistillation 未包含 pipelineId;把额外属性塞进对象不会让 SDK 发送它们。这些能力先使用 REST 或经验证已具备相应签名的 SDK。

管理边界与流水线/配置命名空间

启用、永久删除项目 Memory、六大配置命名空间与四类记忆流水线在 Console 或受控管理端管理;这些操作不使用本页演示的普通项目 API Key。管理面 PATCH /v1/projects/{projectId}/memory 的 enabled=false 禁用项目 Memory 并保留数据;项目 Settings 的 Services 开关只控制客户端访问,不能代替整个 Memory 的禁用。DELETE /v1/projects/{projectId}/memory 是永久删除,不是解绑。旧 Resource/claim 接口不作为新项目初始化步骤。

适用版本

服务端流程适用于 Agentbase 2.10.0;Node.js 示例使用 agentbase-node-sdk@2.9.0。完整安装方式见SDK 接入,本次新增 HTTP 字段不会自动出现在该版本 SDK 的请求中。