从新建项目到用 SDK 操作记忆
本页按实际接入顺序准备项目,下一页提供可运行的 SDK 示例。适用于 Agentbase 2.10.0;Node.js 示例使用 agentbase-node-sdk@2.9.0。
先完成一个演示项目
登录 Console,进入组织;没有组织时先创建组织。
单击创建项目,填写名称,例如“咖啡助手”,按页面提供的区域与数据库资源池标签提交。记下项目 ID,在 Memory 页面确认支持启用;Shared V2 由项目使用的资源池决定,不是创建表单中的独立选项。
进入项目模型管理(LLM Gateway),配置 Embedding 与 Chat 提供方、模型。暂不使用重排或 sparse 时在启用向导关闭对应可选项。
回到 Memory 启用向导,选好模型、实际向量维度及配额,提交后等待项目 active、数据 ready。
打开 记忆 → 添加记忆,用户 ID 填
demo-user,范围选用户(user),处理方式选直接写入,记忆类型填 preference、记录种类选事实(fact),保存“用户喜欢拿铁咖啡。”。按该用户 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、get | memories / 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,主动删除记录与检索数据;来源证据和审计仍可能保留。 |
搜索和召回不等于向聊天模型提问,也不会自动替应用生成最终回答。写入完成后,向量等投影可能仍在后台准备;语义结果为空时先检查用户、范围和索引状态,不立即重复写入。
继续接入
记忆操作与异步提取示例:完整 Node.js 流程及现有多语言操作卡。
REST API 参考:参数、真实响应结构、错误与边界。
新增 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 接口不作为新项目初始化步骤。
六大配置命名空间(
GET/PUT /v1/projects/{projectId}/memory/config/{namespace}):涵盖runtime(五路融合与渐进式召回)、prompt(抽取/做梦/蒸馏提示词)、policy(访问隔离与过滤白名单)、retention(工作/短期记忆留存与遗忘周期)、provider(LLM Gateway 模型绑定与sparseMode: "auto")及evolution(自进化蒸馏与人工审批门禁)。每次更新必须携带expectedConfigVersion与If-Match头防止覆盖并发修改。四类记忆流水线(
/v1/memory/pipelines):覆盖add_memory、profile、distillation与forgetting(艾宾浩斯遗忘流水线)。其中forgetting流水线支持通过POST /v1/memory/pipelines/{id}/validate(传入dryRun: true与sampleUserId)执行单用户艾宾浩斯遗忘曲线预览,确认无误后再publish并通过PUT /v1/memory/pipelines/default设为默认流水线。画像与自进化审批:画像替换(
mode: "replace")需要新messages,sourceMemoryIds仅作补充证据;删除画像保留原始记忆。蒸馏产出的候选经验和技能通过/v1/memory/memories/knowledge/reviews/{reviewId}审批(approve/reject)或按修订版本对比与回滚(/revisions、/diff、/rollback),人工批准要求真实管理用户,普通项目 API Key 不能充当批准人。
适用版本
服务端流程适用于 Agentbase 2.10.0;Node.js 示例使用 agentbase-node-sdk@2.9.0。完整安装方式见SDK 接入,本次新增 HTTP 字段不会自动出现在该版本 SDK 的请求中。