记忆管理
记忆写入、检索召回、记录管理与批量遗忘、导入导出、画像与蒸馏、技能/经验/上下文的各语言调用示例;概念、参数与一致性语义见记忆。
各语言调用示例
写入
2.7.0 起 create 支持可选 sessionId(最长 128 字符;Node SDK 位置参数序在 runId 之后):infer=true 且 scope 为 user / group / project 时,服务加载同会话有界历史(最近 ≤12 个较早 source turn、约 4096 tokens 预算)辅助指代消解;private / strict_private 永不补水,runId 不作 sessionId 回退。完整围栏与失败语义见 API 参考 POST /memory/memories。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
import { Client, Memory, MemoryScope } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 必须包含 /v1
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!); // memories.write 最小 scope
const memory = new Memory(client);
await memory.create({
messages: [{ role: 'user', content: '我习惯每天早上十一点查看早餐店经营简报' }],
userId: 'user-123',
scope: MemoryScope.User,
memoryType: 'conversation',
recordKind: 'conversation',
infer: true // 从对话抽取事实并去重;直写已知事实用 false
});
// infer=true 默认异步入队;批量组合操作见 REST 页签 batch 端点import { Client, Memory } from 'agentbase-web-sdk'; // 前提:用户已登录
const memory = new Memory(client);
await memory.create({
messages: [{ role: 'user', content: '我习惯每天早上十一点查看早餐店经营简报' }],
userId: '<当前登录用户 ID>', // Session 限定本人,不能指定其他用户
scope: 'user',
memoryType: 'conversation',
recordKind: 'conversation',
infer: true // 从对话抽取事实并去重
});import io.agentbase.enums.MemoryMessageRole;
import io.agentbase.enums.MemoryScope;
import io.agentbase.enums.RecordKind;
import io.agentbase.models.MemoryMessage;
import io.agentbase.services.Memory;
Memory memory = new Memory(client); // client 初始化见 server-sdk/java.md
memory.create("user-123", MemoryScope.USER, "conversation", RecordKind.CONVERSATION,
null, // content:与 messages 二选一(同传时 messages 是事实抽取的权威输入)
List.of(new MemoryMessage(MemoryMessageRole.USER, "我习惯每天早上十一点查看早餐店经营简报")),
null, null, null, null, null, // agentId / runId / sensitivity / handlingPolicy / metadata
true, // infer:从对话抽取事实并去重;直写已知事实用 false
null, null); // reRemember / async
// infer=true 默认异步入队;批量组合操作见 REST 页签 batch 端点from agentbase.services.memory import Memory
memory = Memory(client) # 同步调用,返回 pydantic 模型
memory.create(
user_id='user-123', scope='user',
memory_type='conversation', record_kind='conversation',
messages=[{'role': 'user', 'content': '我习惯每天早上十一点查看早餐店经营简报'}],
infer=True) # 从对话抽取事实并去重;直写已知事实用 infer=False
# infer=True 默认异步入队;批量组合操作见 REST 页签 batch 端点import "agentbase-go-sdk/models"
memory := agentbase.NewMemory(cl) // facade 构造器;cl 为已装载 API Key 的 Client
memory.Create("user-123", "user", "conversation", "conversation",
memory.WithCreateMessages([]models.MemoryMessage{{Role: "user", Content: "我习惯每天早上十一点查看早餐店经营简报"}}),
memory.WithCreateInfer(true)) // 从对话抽取事实并去重;直写已知事实用 WithCreateInfer(false)
// infer=true 默认异步入队;批量组合操作见 REST 页签 batch 端点curl -sS -X POST "$APPBASE_ENDPOINT/memory/memories" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"userId":"user-123","scope":"user","memoryType":"conversation","recordKind":"conversation","messages":[{"role":"user","content":"我习惯每天早上十一点查看早餐店经营简报"}],"infer":true}'
# 返回 200;infer=true 异步入队时用 GET /memory/jobs/{jobId} 轮询
# 批量组合操作:POST /memory/memories/batch(items.create / items.delete / items.search 混合,scope 要求读写删并集)检索与召回
search 按记录检索;recallKnowledge 按 token 预算返回可直接拼进 Prompt 的上下文(两者都走 dense / sparse / full-text / graph 融合路由)。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const hits = await memory.search({
query: '早餐店经营简报',
userId: 'user-123',
limit: 10,
memoryType: 'long_term', // 可选:按类型/记录种类/scope/filter 过滤
recordKind: 'fact'
});
const context = await memory.recallKnowledge({
query: '用户每天什么时候查看经营简报?',
scope: 'user',
userId: 'user-123',
sessionId: 'session-123', // 同一会话稳定复用同一 ID
kinds: ['memory', 'profile', 'skill', 'experience'],
limit: 10,
tokenBudget: 2000
});const hits = await memory.search({ query: '我的偏好', userId: '<当前登录用户 ID>', limit: 10 });
const context = await memory.recallKnowledge({
query: '我的偏好',
scope: 'user',
userId: '<当前登录用户 ID>',
limit: 10,
tokenBudget: 2000 // 按 token 预算返回可直接拼进 Prompt 的上下文
});Object hits = memory.search("早餐店经营简报",
null, null, // searchMode / retrieval
"user-123",
null, null, // agentId / runId
null, "long_term", "fact", // scope / memoryType / recordKind(可选:按类型/记录种类/scope/filter 过滤)
null, 10L, null, null, null, null, null, null); // filter / limit / cursor / sort / memorySubStoreId / sessionId / groupId / accessMode
Object context = memory.recallKnowledge("用户每天什么时候查看经营简报?",
io.agentbase.enums.Scope.USER, "user-123",
null, "session-123", // agentId / sessionId(同一会话稳定复用同一 ID)
null, null, // runId / memorySubStoreId
List.of(io.agentbase.enums.Kinds.MEMORY, io.agentbase.enums.Kinds.PROFILE,
io.agentbase.enums.Kinds.SKILL, io.agentbase.enums.Kinds.EXPERIENCE),
10L, 2000L, null, null); // limit / tokenBudget(按 token 预算返回可拼进 Prompt 的上下文)/ retrieval / accessModehits = memory.search(
query='早餐店经营简报', user_id='user-123', limit=10,
memory_type='long_term', record_kind='fact') # 可选:按类型/记录种类过滤
context = memory.recall_knowledge(
query='用户每天什么时候查看经营简报?', scope='user',
user_id='user-123', session_id='session-123', # 同一会话稳定复用同一 ID
kinds=['memory', 'profile', 'skill', 'experience'],
limit=10, token_budget=2000) # 按 token 预算返回可直接拼进 Prompt 的上下文memory.Search("早餐店经营简报",
memory.WithSearchUserId("user-123"),
memory.WithSearchLimit(10),
memory.WithSearchMemoryType("long_term"), // 可选:按类型/记录种类/scope/filter 过滤
memory.WithSearchRecordKind("fact"))
memory.RecallKnowledge("用户每天什么时候查看经营简报?",
memory.WithRecallKnowledgeScope("user"),
memory.WithRecallKnowledgeUserId("user-123"),
memory.WithRecallKnowledgeSessionId("session-123"), // 同一会话稳定复用同一 ID
memory.WithRecallKnowledgeKinds([]string{"memory", "profile", "skill", "experience"}),
memory.WithRecallKnowledgeLimit(10),
memory.WithRecallKnowledgeTokenBudget(2000)) // 按 token 预算返回可直接拼进 Prompt 的上下文curl -sS -X POST "$APPBASE_ENDPOINT/memory/memories/search" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"query":"早餐店经营简报","userId":"user-123","limit":10,"memoryType":"long_term","recordKind":"fact"}'
# recallKnowledge 按 token 预算召回(scope/userId/sessionId/kinds/limit/tokenBudget),返回可直接拼进 Prompt 的上下文记录管理与批量遗忘
单条 get / list / update / delete;范围删除 deleteMany 有界分页——hasMore=true 必须继续分页并逐项检查失败项,单次 HTTP 成功不等于整范围已删。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const one = await memory.get({ memoryId: '<memoryId>' });
const page = await memory.list({ userId: 'user-123', limit: 25 }); // 字段同 REST 查询参数
await memory.update({ memoryId: '<memoryId>', content: '更新后的事实' });
await memory.delete({ memoryId: '<memoryId>' });
let res = await memory.deleteMany({ userId: 'user-123' });
while (res.hasMore) { // 有界分页:继续翻页直至 hasMore=false
res = await memory.deleteMany({ userId: 'user-123' /*, cursor 续传 */ });
// 逐项检查失败列表,不能只看 HTTP 成功
}// 同一数据面子集:本人记忆的 get / list / update / delete
const one = await memory.get({ memoryId: '<memoryId>' });Object one = memory.get("<memoryId>");
Object page = memory.list(null, 25L, null, null, "user-123", null); // 字段同 REST 查询参数
memory.update("<memoryId>", 1L, "更新后的事实", null, null); // version 为 CAS 乐观锁版本
memory.delete("<memoryId>", null, null);
io.agentbase.models.MemoryBulkDeleteResponse res = memory.deleteMany("user-123", null, null, null);
while (Boolean.TRUE.equals(res.getHasMore())) { // 有界分页:继续翻页直至 hasMore=false,逐项检查失败列表
res = memory.deleteMany("user-123", null, null, null);
}one = memory.get(memory_id='<memoryId>')
page = memory.list(user_id='user-123', limit=25) # 字段同 REST 查询参数
memory.update(memory_id='<memoryId>', version=1, content='更新后的事实') # version 为 CAS 乐观锁版本
memory.delete(memory_id='<memoryId>')
res = memory.delete_many(user_id='user-123')
while res['hasMore']: # 有界分页:继续翻页直至 False,逐项检查失败列表
res = memory.delete_many(user_id='user-123')one, _ := memory.Get("<memoryId>")
page, _ := memory.List(memory.WithListUserId("user-123"), memory.WithListLimit(25)) // 字段同 REST 查询参数
memory.Update("<memoryId>", 1, memory.WithUpdateContent("更新后的事实")) // Version 为 CAS 乐观锁版本
memory.Delete("<memoryId>", memory.WithDeleteReason("user request"))
res, _ := memory.DeleteMany(memory.WithDeleteManyUserId("user-123"))
for (*res).(map[string]any)["hasMore"] == true { // 有界分页:继续翻页直至 hasMore=false,逐项检查失败列表
res, _ = memory.DeleteMany(memory.WithDeleteManyUserId("user-123"))
}curl -sS "$APPBASE_ENDPOINT/memory/memories?queries[]=limit(25)" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 单条:GET /memory/memories/{memoryId};更新:PATCH /memory/memories/{memoryId}(CAS 版本)
# 单条删除:DELETE /memory/memories/{memoryId};有界批量遗忘:DELETE /memory/memories(body 传 userId/limit)导入导出
范围导出/导入均为异步任务:创建后轮询任务详情直至完成。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const job = await memory.createExport({ userId: 'user-123' }); // scope 需 memories.export
const done = await memory.getExportJob(job.jobId); // 轮询直至 done
const imp = await memory.createImport({ /* 导入负载 */ });
await memory.getImport(imp.importId); // 轮询任务详情// 导入导出属服务端能力(memories.export scope),Web Session 面不开放Object job = memory.createExport("user-123",
io.agentbase.enums.Format.JSON, null, null, null, null); // scope 需 memories.export
memory.getExportJob((String) ((Map<?, ?>) job).get("jobId")); // 轮询直至完成
Object imp = memory.createImport("user-123",
io.agentbase.enums.Format.JSON, "{ ... }", null, false); // 或 records 传 MemoryRecordInput 列表
memory.getImport((String) ((Map<?, ?>) imp).get("importId")); // 轮询任务详情job = memory.create_export(user_id='user-123') # scope 需 memories.export
# 用返回的 jobId 轮询 get_export_job 直至完成
imp = memory.create_import() # 导入负载字段同 Node 面
# 用返回的 importId 轮询 get_import 任务详情job, _ := memory.CreateExport("user-123") // scope 需 memories.export;可选 WithCreateExportFormat/Include* 等
_ = memory.GetExportJob("<exportId>") // 用返回的 jobId 轮询直至完成
_, _ = memory.CreateImport("user-123",
memory.WithCreateImportFormat("json"),
memory.WithCreateImportData("{ ... }"), // 或 WithCreateImportRecords([]models.MemoryRecordInput{...})
memory.WithCreateImportDryRun(false))
_, _ = memory.GetImport("<importId>") // 用返回的 importId 轮询任务详情curl -sS -X POST "$APPBASE_ENDPOINT/memory/memories/exports" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"userId":"user-123"}'
# 任务详情:GET /memory/memories/exports/{exportId};同步导出:GET /memory/memories/export
# 导入:POST /memory/memories/imports,任务详情 GET /memory/memories/imports/{importId}画像与蒸馏
画像按用户聚合长期事实;蒸馏把记忆沉淀为结构化任务产物,二者都是异步/派生流程。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const profile = await memory.getProfile({ userId: 'user-123' });
await memory.createProfileExtraction({ userId: 'user-123' }); // 增量/替换抽取
await memory.createProfileRebuild({ userId: 'user-123' }); // 全量重建(更重)
const sources = await memory.listProfileSources({ userId: 'user-123' }); // 画像证据源
await memory.submitDistillation({ userId: 'user-123' /* 蒸馏范围参数 */ });
const dist = await memory.getDistillation('<distillationId>'); // 轮询直至完成// 画像/蒸馏属服务端管理能力,Web Session 面不开放memory.getProfile("user-123", null);
memory.createProfileExtraction("user-123", null, null, null, null); // 增量/替换抽取
memory.createProfileRebuild("user-123", null); // 全量重建(更重)
memory.listProfileSources("user-123", null); // 画像证据源
memory.submitDistillation(null, "user-123", null, null, null, null,
null, null, null, null, null, null); // 蒸馏范围参数同 Node 面
memory.getDistillation("<distillationId>", null, null, null, null, null, null); // 轮询直至完成memory.get_profile(user_id='user-123')
memory.create_profile_extraction(user_id='user-123') # 增量/替换抽取
memory.create_profile_rebuild(user_id='user-123') # 全量重建(更重)
memory.list_profile_sources(user_id='user-123') # 画像证据源
memory.submit_distillation(user_id='user-123') # 蒸馏范围参数同 Node 面
memory.get_distillation('<distillationId>') # 轮询直至完成memory.GetProfile("user-123") // 可选 WithGetProfileProfileType
memory.CreateProfileExtraction("user-123") // 增量/替换抽取;可选 WithCreateProfileExtraction*
memory.CreateProfileRebuild("user-123") // 全量重建(更重)
memory.ListProfileSources("user-123") // 画像证据源
memory.SubmitDistillation(memory.WithSubmitDistillationUserId("user-123"),
memory.WithSubmitDistillationMode("auto")) // 蒸馏范围参数同 Node 面
memory.GetDistillation("<distillationId>") // 轮询直至完成# 画像:GET /memory/memories/users/{userId}/profile
curl -sS "$APPBASE_ENDPOINT/memory/memories/users/user-123/profile" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 增量/替换抽取:POST .../profile/extractions
curl -sS -X POST "$APPBASE_ENDPOINT/memory/memories/users/user-123/profile/extractions" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"userId":"user-123"}'
# 全量重建:POST .../profile/rebuild;证据源:GET .../profile/sources
# 蒸馏:POST /memory/memories/distillations(范围参数同 Node 面);详情 GET /memory/memories/distillations/{distillationId};
# 重放 POST /memory/memories/distillations/{distillationId}/replay技能 / 经验 / 上下文
技能与经验是沉淀的可复用知识与操作记录(knowledgeId 为稳定 ID);上下文(Dreaming)按项目治理记忆生命周期:调度运行 → 确认 shadow → 回滚/重建。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const skills = await memory.listSkills({ userId: 'user-123' });
const found = await memory.searchSkills({ query: '周报排版', userId: 'user-123' });
const exps = await memory.listExperiences({ userId: 'user-123' });
const expHits = await memory.searchExperiences({ query: '投放复盘', userId: 'user-123' });
await memory.createContextRun({ /* 调度参数 */ }); // 调度一次 Dreaming 运行
const ctx = await memory.getContext('<contextId>');
await memory.confirmContext('<contextId>'); // 确认 shadow 上下文
await memory.rollbackContext('<contextId>'); // 回滚活跃上下文
await memory.rebuildContext('<contextId>'); // 重建// 技能/经验只读检索可按需开放(本人 scope);上下文治理属服务端能力,Web 面不开放memory.listSkills(null, "user-123", null, null, null, null, null, null);
memory.searchSkills("周报排版", null, "user-123", null, null, null, null, null, null, null);
memory.listExperiences(null, "user-123", null, null, null, null, null, null);
memory.searchExperiences("投放复盘", null, "user-123", null, null, null, null, null, null, null);
memory.createContextRun(io.agentbase.enums.Scope.USER, "user-123",
null, null, null, null); // 调度一次 Dreaming 运行
memory.getContext("<contextId>", null, null, null, null, null, null);
memory.confirmContext("<contextId>", 1L, "confirm shadow",
null, null, null, null, null, null, null); // 确认 shadow 上下文(expectedVersion + reason)
memory.rollbackContext("<contextId>", 1L, 0L, "rollback",
null, null, null, null, null, null); // 回滚活跃上下文(expectedVersion + targetRevision + reason)
memory.rebuildContext("<contextId>", "rebuild",
null, null, null, null, null, null, null); // 重建memory.list_skills(user_id='user-123')
memory.search_skills(query='周报排版', user_id='user-123')
memory.list_experiences(user_id='user-123')
memory.search_experiences(query='投放复盘', user_id='user-123')
memory.create_context_run() # 调度参数同 Node 面;调度一次 Dreaming 运行
memory.get_context('<contextId>')
memory.confirm_context('<contextId>', expected_version=1, reason='confirm shadow') # 确认 shadow 上下文
memory.rollback_context('<contextId>', expected_version=1, target_revision=0, reason='rollback') # 回滚活跃上下文
memory.rebuild_context('<contextId>', reason='rebuild') # 重建memory.ListSkills(memory.WithListSkillsUserId("user-123"))
memory.SearchSkills("周报排版", memory.WithSearchSkillsUserId("user-123"))
memory.ListExperiences(memory.WithListExperiencesUserId("user-123"))
memory.SearchExperiences("投放复盘", memory.WithSearchExperiencesUserId("user-123"))
memory.CreateContextRun(memory.WithCreateContextRunScope("user"),
memory.WithCreateContextRunUserId("user-123")) // 调度一次 Dreaming 运行
memory.GetContext("<contextId>")
memory.ConfirmContext("<contextId>", 1, "confirm shadow") // 确认 shadow 上下文(ExpectedVersion + Reason)
memory.RollbackContext("<contextId>", 1, 0, "rollback") // 回滚活跃上下文(ExpectedVersion + TargetRevision + Reason)
memory.RebuildContext("<contextId>", "rebuild") // 重建# 技能:GET /memory/memories/skills;检索 POST /memory/memories/skills/search;详情/证据源 GET .../skills/{knowledgeId}[/sources]
curl -sS -X POST "$APPBASE_ENDPOINT/memory/memories/skills/search" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"query":"周报排版","userId":"user-123"}'
# 经验:GET /memory/memories/experiences;检索 POST .../experiences/search
# 上下文:GET /memory/memories/contexts;调度 POST /memory/memories/contexts/runs;
# 确认 POST .../contexts/{contextId}/confirm;回滚 .../rollback;重建 .../rebuild;状态 GET .../contexts/status事实源
skills/ob-agentbase/references/memory.md- appbase v2.7.0(tag v2.7.0);release-2.7.0 分支 PR 542/552/553(
sessionId有界会话上下文推断) - agentbase-sdks v2.7.0 specs(
packages/sdks/server-nodejs/src/services/memory.ts:create的sessionId参数与位置参数序实读)