记忆
这是什么 / 何时用
Memory 为项目内的用户/Agent 提供长期记忆:把对话与事实写入项目隔离的记忆库,之后按语义检索、按 token 预算召回,或维护用户画像(profile)、技能(skill)、经验(experience)与蒸馏(distillation)。适合需要跨会话记住用户偏好、事实与历史行为的 Agent/助手应用。
资源分两层:数据面(记忆记录、检索、画像、蒸馏等)与控制面(项目级 Memory 配置:启用、命名空间配置、历史与回滚)。逻辑资源(Memory Resource)与项目绑定由部署/控制台配置管理(REST 管理接口),SDK 不直接暴露。
前置
- 实例启用 Memory(
_APP_MEMORY_ENABLED=enabled)、存在可路由的健康集群、项目 Memory API 未禁用;provider 命名空间配置 embedding / chat / rerank 三条路由,embeddingDims必须与目标集群一致。 - API Key scopes:数据面
memories.read/memories.write/memories.delete/memories.export;项目配置属控制面(projects.read/projects.write)。按最小授权发放。 - Web SDK 只使用当前用户 Session,不能带 API Key,也不能指定其他用户。
- 依赖 LLM Gateway 的模型路由(Provider 引用形如
dashscope:{providerId},只存引用不存明文密钥)。
使用骨架
- 写入:
memory.create({ messages | content, userId, scope, memoryType, recordKind, infer })——infer必须显式传:普通事实直写用infer: false;需要抽取/去重/归纳用infer: true(仅 user 角色消息参与抽取;messages与content同传时messages是事实抽取的权威输入)。批量写用createBatch。 - 检索:
memory.search({ query, userId, limit, memoryType, recordKind, scope, filter })按记录检索;memory.recallKnowledge({ query, scope, userId, sessionId, kinds, limit, tokenBudget })按 token 预算返回可直接拼进 Prompt 的上下文。 - 记录管理:
get/list/update/delete/deleteMany;范围导出/导入用createExport/createImport系列并轮询getExportJob/getJob。 - 派生资产:画像
getProfile/createProfileExtraction/createProfileRebuild;蒸馏submitDistillation/getDistillation;技能与经验listSkills/searchSkills/listExperiences/searchExperiences;上下文运行createContextRun/getContext/confirmContext/rollbackContext/rebuildContext。 - 项目控制面(Console SDK):
memory.getProject/enableProject/deleteProject;命名空间配置getProjectConfig/listProjectConfigs/deleteProjectConfig;配置历史与回滚listProjectConfigHistory/getProjectConfigHistory/getProjectConfigHistoryDiff/createProjectConfigRollback;审计listAudits。更新配置必须单个 namespace + value,并携带当前expectedConfigVersion(REST 对应If-Match;首次创建 REST 显式If-None-Match: *)。
关键参数与返回
create:scope标识记忆归属(如用户级);userId为项目内用户;返回记忆记录(含 sourceId / provenance,用于区分原始对话与派生记录——去重不是全局唯一约束,需结合 provenance 判断)。search/recallKnowledge:limit与tokenBudget控制返回规模(示例:limit: 10, tokenBudget: 2000);检索路由支持 dense / sparse / full-text / graph,融合策略由项目 runtime 配置决定。- 遗忘策略默认值(retention 配置):
decay_rate=1.5,阶段乘数 working=1 / short_term=7 / long_term=60,working_threshold=0.3,minimum_protection_hours=168;参数越大衰减越慢、阈值越高越早归档;expiresAt是独立硬过期,关闭自适应遗忘仍会处理。 deleteMany返回有界分页:hasMore=true必须继续分页并逐项检查失败项,单次 HTTP 成功不等于整范围已删。
错误与边界(2.6.0 一致性语义)
- 有界重试:项目初始化只对标记 retryable 的依赖失败重试,最多 3 次有界退避;鉴权依赖短暂不可用返回 503 +
auth_dependency_unavailable+retryable=true,无效 HMAC 仍是非重试 401。create/batch 写入的幂等键在可重试 503 后必须复用,不要换新键造成重复业务记录。 - 串行写入:写入与范围删除按同一 scope(project / user / substore)串行执行;2.6.0 起删除登记与后续写入共享同一 scope 门闩,避免"删除完成后并发写入又留下数据"。项目删除/重建或 revision 变化后,旧的后台任务不得写回新生命周期。
- quota 条件更新:Memory 数量与存储配额在业务事务内条件更新,并发写入不会各自通过旧计数后共同越过上限——超限请求失败而不是静默超额。
- 配置更新报 409 / precondition required:先读 configVersion(ETag)再带
expectedConfigVersion/If-Match重试。 - 删除语义三分:项目级解绑(仅停路由不删数据)、单条删除(逻辑删除 + 后续物理压缩)、资源删除(项目级数据删除,破坏性)。
permanent_forgetting_enabled只控制遗忘结果是否进入物理压缩,不等于资源删除开关。
SDK 类别差异
- Server SDK(server-sdk/nodejs.md):数据面全集(含批量、导入导出、画像/蒸馏、上下文)。
- 客户端 SDK(client-sdk/web.md):同一数据面子集(用户 Session 限定本人记忆)。
- Console SDK(console-sdk/nodejs.md):数据面 + 项目控制面(启用/配置/历史/回滚/审计)。
- 逻辑资源与项目绑定的认领(claim)仅用于迁移历史资源,不属于初始化流程。
各语言调用示例
控制面(启用 / 配置)示例保留在本页;写入、召回、管理等数据面示例见记忆管理。
控制面(启用 / 配置 / 历史回滚 / 审计)
控制面走 **Console SDK 或 REST(projects.write):绑定逻辑资源到项目、按 namespace 读写配置。配置更新必须单个 namespace + value**,首次创建 REST 显式 If-None-Match: *,更新带 expectedConfigVersion / If-Match;冲突 409 时重读 configVersion 再重试。
- Console(Node)
- REST(curl)
// consoleClient 为 Console SDK Client(Session / 短期 JWT),见 console-sdk/nodejs.md
const memory = new Memory(consoleClient);
// 资源与项目绑定(一次性初始化)
await memory.createResource({ /* 配额等资源参数 */ });
await memory.createProjectBinding({ projectId, resourceId /*, ...绑定参数 */ });
// 配置读改写(namespace ∈ runtime / prompt / policy / retention / provider / evolution)
const current = await memory.getProjectConfig({ projectId, namespace: 'policy' });
await memory.updateProjectConfig({
projectId,
namespace: 'policy',
value: {
...current.editableValue,
forgetting: { ...current.editableValue.forgetting, enabled: true }
},
expectedConfigVersion: current.configVersion, // 冲突 409 → 重读后重试
schemaVersion: current.schemaVersion,
reason: 'Update Memory forgetting policy'
});
// 历史与回滚、审计
await memory.listProjectConfigHistory({ projectId, namespace: 'policy' });
await memory.createProjectConfigRollback({ projectId, namespace: 'policy' /*, 目标版本 */ });
await memory.listAudits({ projectId });# 项目绑定:POST /v1/projects/{projectId}/memory;配置:/v1/projects/{projectId}/memory/config/{namespace}
curl -sS -X PUT "$APPBASE_ENDPOINT/projects/$APPBASE_PROJECT_ID/memory/config/policy" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H 'If-None-Match: *' \
-d '{"value":{"forgetting":{"enabled":true}}}'
# 更新已有配置改带 If-Match: "<configVersion 的 ETag>";历史/回滚在同名 namespace 子路径下示例指引
- JavaScript(Node 写入/检索,Console 项目配置):examples/javascript.md
- Java:examples/java.md
事实源
skills/ob-agentbase/references/memory.md- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
packages/sdks/*/src/services/memory.ts方法面)