记忆管理
记忆写入、检索召回、记录管理与批量遗忘、导入导出、画像与蒸馏、技能/经验/上下文的各语言调用示例;概念、参数与一致性语义见记忆。
运行一遍写入到删除的完整流程
先按接入准备创建项目、启用 Memory、安装精确 SDK 版本并配置环境变量。以下为完整 memory-demo.mjs,仅在可信后端执行;打印的演示正文不应替换为真实敏感内容后直接记录到生产日志。
import assert from 'node:assert/strict';
import { Client, Memory } from 'agentbase-node-sdk';
const required = [
'APPBASE_ENDPOINT', 'APPBASE_PROJECT_ID', 'APPBASE_API_KEY',
'APPBASE_USER_ID', 'MEMORY_OPERATION_ID'
];
for (const name of required) {
if (!process.env[name]) throw new Error(`请先设置环境变量 ${name}`);
}
const endpoint = process.env.APPBASE_ENDPOINT.replace(/\/$/, '');
assert.ok(endpoint.endsWith('/v1'), 'SDK endpoint 必须包含 /v1');
const userId = process.env.APPBASE_USER_ID;
const originalContent = `用户喜欢拿铁咖啡。(SDK 演示 ${process.env.MEMORY_OPERATION_ID})`;
const updatedContent = `用户现在喜欢美式咖啡。(SDK 演示 ${process.env.MEMORY_OPERATION_ID})`;
const client = new Client()
.setEndpoint(endpoint)
.setProject(process.env.APPBASE_PROJECT_ID)
.setKey(process.env.APPBASE_API_KEY);
{
const prepareRequest = client.prepareRequest.bind(client);
client.prepareRequest = (...args) => {
const request = prepareRequest(...args);
request.options.redirect = 'error';
return request;
};
}
const memory = new Memory(client);
// 1. 原样保存一条新事实,避免把异步受理当作写入完成。
client.addHeader('Idempotency-Key', process.env.MEMORY_OPERATION_ID);
const created = await memory.create({
userId, scope: 'user', memoryType: 'preference', recordKind: 'fact',
content: originalContent, infer: false, async: false
});
assert.equal(created.status, 'completed');
const memoryId = created.memory?.memoryId;
assert.equal(typeof memoryId, 'string');
console.log('新建记忆 ID:', memoryId);
// 2. 通过 ID 精确读回;更新必须使用这里读取的版本。
const current = await memory.get({ memoryId });
assert.equal(current.memory.content, originalContent);
// 3. 打开用户的记忆列表;翻页时原样传回 nextCursor。
const listing = await memory.list({ userId, limit: 20 });
console.log('列表条数:', listing.memories.length);
// 4. 用自然语言查找相关记忆,结果可能因投影尚未就绪而为空。
const hits = await memory.search({
query: '用户喜欢喝什么咖啡?', userId, scope: 'user', limit: 5
});
for (const item of hits.items) {
console.log('检索:', item.memory.memoryId, item.memory.content);
}
console.log('检索降级:', hits.degraded);
// 5. 按预算召回,应用可将 context 加入自己的聊天模型请求。
const recalled = await memory.recallKnowledge({
query: '给用户推荐一杯咖啡', scope: 'user', userId,
kinds: ['memory', 'profile', 'skill', 'experience'],
limit: 5, tokenBudget: 1000
});
console.log('召回上下文:', recalled.context);
console.log('召回降级:', recalled.degraded);
// 6. 用户纠正偏好;并发冲突会抛错,不能用旧版本覆盖。
client.addHeader('Idempotency-Key', `${process.env.MEMORY_OPERATION_ID}-update`);
const updated = await memory.update({
memoryId, version: current.memory.version,
content: updatedContent
});
assert.ok(updated.memory.version > current.memory.version);
// 7. 主动删除这次脚本创建的记录;不会执行按用户范围的批量删除。
client.addHeader('Idempotency-Key', `${process.env.MEMORY_OPERATION_ID}-delete`);
const forgotten = await memory.delete({
memoryId, reason: 'demo_finished', source: 'sdk_demo'
});
assert.equal(forgotten.status, 'forgotten');
console.log('完成:已创建、查询、更新并遗忘本次演示记忆。');最后一行“完成”表示本次直接写入、精确读回、版本更新与主动删除均成功;不表示每条模型检索路线都已就绪。主动删除会清除记忆及检索数据,来源和审计仍可能保留。中途失败时可按已打印的 memoryId 到 Console 删除本次演示记录。应用上线时把这些步骤分别绑定到真实用户行为,不把整个演示脚本反复运行当作重试机制。
每次新演示使用新的 MEMORY_OPERATION_ID;正文包含该标记,避免再次写入上次已删除的同一内容。真实业务若需要重新学习相同内容,需明确使用 reRemember=true 和新的幂等键,这会创建新证据,不恢复原记录。
从多轮对话智能提取
新建 memory-async.mjs,从完整示例复制初始化部分(从 import 到 const memory = new Memory(client)),随后接下面代码,不包含上面的创建到删除流程。运行前设置新的 MEMORY_ASYNC_OPERATION_ID 作为本次提取幂等键。与上面的确定性直写不同,这段示例会使用模型,并保留提取出的记忆。
export MEMORY_ASYNC_OPERATION_ID="$(node -p 'require("node:crypto").randomUUID()')"
node memory-async.mjsif (!process.env.MEMORY_ASYNC_OPERATION_ID) {
throw new Error('请先设置 MEMORY_ASYNC_OPERATION_ID,标识本次提取。');
}
client.addHeader('Idempotency-Key', process.env.MEMORY_ASYNC_OPERATION_ID);
const accepted = await memory.create({
userId, scope: 'user', memoryType: 'long_term', recordKind: 'conversation',
sessionId: 'coffee-session-001',
messages: [{ role: 'user', content: '我最近开始喝不加糖的美式咖啡。' }],
infer: true, async: true
});
assert.equal(typeof accepted.jobId, 'string');
console.log('异步写入任务 ID:', accepted.jobId);
let job;
for (let attempt = 0; attempt < 30; attempt += 1) {
job = await memory.getJob({ jobId: accepted.jobId });
if (job.status === 'succeeded' || job.status === 'failed') break;
await new Promise(resolve => setTimeout(resolve, 2000));
}
if (job.status === 'queued' || job.status === 'running') {
throw new Error(`仍在处理,请保留任务 ${accepted.jobId},稍后继续 getJob,不要重新创建。`);
}
console.log('业务状态:', job.result?.status, '逐项结果:', job.result?.actions ?? []);
assert.equal(job.status, 'succeeded', job.reason ?? job.errorCode);
assert.equal(job.result?.status, 'completed');任务调度 succeeded 后还要检查 result.status;partial_failed 时逐项处理,不能宣称全部完成。actions 可能含 ADD、UPDATE、DELETE、NONE 或为空。同一会话的各轮复用 sessionId,新会话使用新的 ID,并先等待依赖的前一轮任务完成。私有范围不会加载历史消息。
job.errorCode、result.errorCode、actions[].errorCode 和 fallback.errorCode 都是可省略的字符串,例如 LLM_TIMEOUT;不是嵌套错误对象。reason 也是可省略的字符串。错误信息可能出现在重试中的任务或受控回退结果中;结合任务状态、result.status、retryable 和逐项结果决定后续处理。
部分失败的业务结果示意如下。成功动作与失败动作可能同时存在,不能将整个输入原样作为新操作重提;先核对已生效的动作,再按应用策略处理失败项。
{
"status": "partial_failed",
"mode": "inferred",
"actions": [
{ "index": 0, "action": "ADD", "status": "completed", "memoryId": "mem-example" },
{ "index": 1, "action": "NONE", "status": "failed", "errorCode": "VALIDATION_FAILED", "reason": "动作参数无效" }
]
}下面是各语言独立操作卡,沿用该语言的 Client 初始化,不顺序拼接成一个脚本。完整流程以本节 Node.js 示例为入口;重试写入时保持同一逻辑操作的幂等键,不同写入换新键。
各语言调用示例
写入
create 支持可选 sessionId(最长 128 UTF-8 字节;Node SDK 位置参数序在 runId 之后):infer=true 且 scope 为 user / group / project 时,服务加载同会话有界历史(最近 ≤12 个较早 source turn、约 4096 tokens 预算)辅助指代消解;private / strict_private 不补充历史消息,runId 不作 sessionId 回退。消息限制与失败处理见 API 参考。
- 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 prepareRequest = client.prepareRequest.bind(client);
client.prepareRequest = (...args) => {
const request = prepareRequest(...args);
request.options.redirect = 'error';
return request;
};
}
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, null, // agentId / runId / sessionId / sensitivity / handlingPolicy / metadata
true, // infer:从对话抽取事实并去重;直写已知事实用 false
null, null); // reRemember / async
// infer=true 默认异步入队;批量组合操作见 REST 页签 batch 端点from agentbase.services.memory import Memory
memory = Memory(client) # 同步调用;create 返回 JSON 对象
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 端点(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "$APPBASE_ENDPOINT/memory/memories" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
--header @- \
-d '{"userId":"user-123","scope":"user","memoryType":"conversation","recordKind":"conversation","messages":[{"role":"user","content":"我习惯每天早上十一点查看早餐店经营简报"}],"infer":true}'
# 默认返回 202;infer=true 异步入队时用 GET /memory/jobs/{jobId} 轮询
# 批量组合操作:POST /memory/memories/batch(items.create / items.delete / items.search 混合,scope 要求读写删并集)
)检索与召回
search 按记录检索(支持五路混合检索 hybrid|vector|keyword|graph|profile、模型生成稀疏向量 retrieval.sparse: true|false|"auto",以及 retrieval.strategy: "progressive" 分层渐进式召回 L3→L0);recallKnowledge 按统一 token 预算返回可直接拼进 Prompt 的记忆、画像、经验与技能上下文。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
// 1. 五路混合检索 + 模型生成稀疏向量(sparse: "auto")+ 渐进式分层召回(strategy: "progressive",L3 综述 -> L2 上下文 -> L1 事实 -> L0 证据)
const hits = await memory.search({
query: '早餐店经营简报',
searchMode: 'hybrid',
retrieval: {
sparse: 'auto',
strategy: 'progressive',
entryLevel: 'auto',
maxDepth: 2,
tokenBudget: 1200,
deadlineMs: 450,
expansionToken: '', // 展开下一层 L2/L1/L0 节点时传入上一轮返回的 expansionToken
},
userId: 'user-123',
limit: 10,
memoryType: 'long_term', // 时间衰减层:working / short_term / long_term
recordKind: 'fact'
});
// 2. 统一 Token 预算召回(联合召回 memory + profile + skill + experience,返回带 injectionId 的上下文)
const context = await memory.recallKnowledge({
query: '用户每天什么时候查看经营简报?',
scope: 'user',
userId: 'user-123',
sessionId: 'session-123', // 同一会话稳定复用同一 ID(关联最近 12 轮对话)
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 的上下文
});// retrieval 支持传入 Map.of("sparse", "auto", "strategy", "progressive", "entryLevel", "auto", "maxDepth", 2, "tokenBudget", 1200, "deadlineMs", 450)
Object hits = memory.search("早餐店经营简报",
io.agentbase.enums.SearchMode.HYBRID,
Map.of("sparse", "auto", "strategy", "progressive", "entryLevel", "auto", "maxDepth", 2, "tokenBudget", 1200, "deadlineMs", 450),
"user-123",
null, null, // agentId / runId
null, "long_term", "fact", // scope / memoryType (working|short_term|long_term) / recordKind
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,
search_mode='hybrid',
retrieval={'sparse': 'auto', 'strategy': 'progressive', 'entryLevel': 'auto', 'maxDepth': 2, 'tokenBudget': 1200, 'deadlineMs': 450},
memory_type='long_term', record_kind='fact') # memory_type: working / short_term / long_term
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.WithSearchSearchMode("hybrid"),
memory.WithSearchRetrieval(map[string]interface{}{
"sparse": "auto", "strategy": "progressive", "entryLevel": "auto",
"maxDepth": 2, "tokenBudget": 1200, "deadlineMs": 450,
}),
memory.WithSearchUserId("user-123"),
memory.WithSearchLimit(10),
memory.WithSearchMemoryType("long_term"), // working / short_term / long_term
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 的上下文(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "$APPBASE_ENDPOINT/memory/memories/search" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
--header @- \
-d '{"query":"早餐店经营简报","searchMode":"hybrid","retrieval":{"sparse":"auto","strategy":"progressive","entryLevel":"auto","maxDepth":2,"tokenBudget":1200,"deadlineMs":450},"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 });
await memory.update({
memoryId: one.memory.memoryId, version: one.memory.version,
content: '更新后的事实'
});
await memory.delete({ memoryId: one.memory.memoryId });
// 仅在业务已确认要遗忘该用户全部记忆时使用。
let res;
do {
res = await memory.deleteMany({ userId: 'user-123', limit: 100 });
if (res.failed > 0) throw new Error('存在失败项,请检查 res.items 后处理');
} while (res.hasMore); // 无 cursor,继续相同范围;不能忽略逐项失败。// 同一数据面子集:本人记忆的 get / list / update / delete
const one = await memory.get({ memoryId: '<memoryId>' });Map<?, ?> one = (Map<?, ?>) memory.get("<memoryId>");
Map<?, ?> record = (Map<?, ?>) one.get("memory");
long version = ((Number) record.get("version")).longValue();
Object page = memory.list(null, 25L, null, null, "user-123", null);
memory.update("<memoryId>", version, "更新后的事实", null, null);
memory.delete("<memoryId>", null, null);
// 仅在业务已确认要遗忘该用户全部记忆时使用。
io.agentbase.models.MemoryBulkDeleteResponse res;
do {
res = memory.deleteMany("user-123", 100L, null, null);
if (res.getFailed() > 0) throw new IllegalStateException("检查 res.getItems() 中的失败项");
} while (Boolean.TRUE.equals(res.getHasMore()));one = memory.get(memory_id='<memoryId>')
page = memory.list(user_id='user-123', limit=25)
memory.update(memory_id='<memoryId>', version=one['memory']['version'], content='更新后的事实')
memory.delete(memory_id='<memoryId>')
# 仅在业务已确认要遗忘该用户全部记忆时使用。delete_many 返回类型化模型。
while True:
res = memory.delete_many(user_id='user-123', limit=100)
if res.failed:
raise RuntimeError('检查 res.items 中的失败项')
if not res.hasmore:
breakone, err := memory.Get("<memoryId>")
if err != nil { panic(err) }
record := (*one).(map[string]interface{})["memory"].(map[string]interface{})
version := int(record["version"].(float64)) // JSON 解码后的数字
_, err = memory.Update("<memoryId>", version, memory.WithUpdateContent("更新后的事实"))
if err != nil { panic(err) }
_, err = memory.Delete("<memoryId>", memory.WithDeleteReason("user request"))
if err != nil { panic(err) }
// 仅在业务已确认要遗忘该用户全部记忆时使用。
for {
res, err := memory.DeleteMany(memory.WithDeleteManyUserId("user-123"), memory.WithDeleteManyLimit(100))
if err != nil { panic(err) }
if res.Failed > 0 { panic("检查 res.Items 中的失败项") }
if !res.HasMore { break }
}curl -sS --get "$APPBASE_ENDPOINT/memory/memories" \
--data-urlencode 'userId=user-123' --data-urlencode '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)导入导出
导入导出创建后按各自标识查询,不能把受理当作完成;下例导入使用 dryRun=true,只验证,不写入。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const exported = await memory.createExport({ userId: 'user-123', mode: 'async' });
const progress = await memory.getExportJob({ exportId: exported.exportId });
// 重复查询至 progress.job.status 终态,再检查 job.result / manifestUrl。
const imported = await memory.createImport({
userId: 'user-123', format: 'json', dryRun: true,
records: [{ userId: 'user-123', scope: 'user', memoryType: 'preference',
recordKind: 'fact', content: '用户喜欢拿铁咖啡。' }]
});
const importProgress = await memory.getImport({ importId: imported.importId });
// 检查 job.status 和逐项结果;正式导入前将 dryRun 改为 false,使用新的逻辑幂等键。// 导入导出属服务端能力(memories.export scope),Web Session 面不开放Map<?, ?> exported = (Map<?, ?>) memory.createExport("user-123",
io.agentbase.enums.Format.JSON, null, null, null, io.agentbase.enums.ExportJobMode.ASYNC);
Object progress = memory.getExportJob((String) exported.get("exportId"));
String data = "[{\"userId\":\"user-123\",\"scope\":\"user\",\"memoryType\":\"preference\",\"recordKind\":\"fact\",\"content\":\"用户喜欢拿铁咖啡。\"}]";
Map<?, ?> imported = (Map<?, ?>) memory.createImport("user-123",
io.agentbase.enums.Format.JSON, data, null, true);
Object importProgress = memory.getImport((String) imported.get("importId"));
// 继续查询并检查 job.status 和逐项结果;dryRun=true 不写入。exported = memory.create_export(user_id='user-123', mode='async')
progress = memory.get_export_job(export_id=exported['exportId'])
imported = memory.create_import(user_id='user-123', format='json', dry_run=True,
data='[{"userId":"user-123","scope":"user","memoryType":"preference","recordKind":"fact","content":"用户喜欢拿铁咖啡。"}]')
import_progress = memory.get_import(import_id=imported['importId'])
# 继续查询并检查 job.status 和逐项结果;dry_run=True 不写入。exported, err := memory.CreateExport("user-123", memory.WithCreateExportMode("async"))
if err != nil { panic(err) }
exportID := (*exported).(map[string]interface{})["exportId"].(string)
_, err = memory.GetExportJob(exportID)
if err != nil { panic(err) }
imported, err := memory.CreateImport("user-123",
memory.WithCreateImportFormat("json"),
memory.WithCreateImportData(`[{"userId":"user-123","scope":"user","memoryType":"preference","recordKind":"fact","content":"用户喜欢拿铁咖啡。"}]`),
memory.WithCreateImportDryRun(true))
if err != nil { panic(err) }
importID := (*imported).(map[string]interface{})["importId"].(string)
_, err = memory.GetImport(importID)
if err != nil { panic(err) }
// 继续查询并检查 job.status 和逐项结果;dryRun=true 不写入。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}画像与蒸馏
画像提取必须传新 messages,replace 也不例外;蒸馏须传有效来源或内联证据,下例使用内联对话。首次接入先提交画像提取;排队时等待完成再读取,画像尚未生成时 getProfile 可能返回 404。读取、来源查询和重建是独立操作,下面以注释给出,按需执行。设置 MEMORY_DISTILLATION_OPERATION_ID 标识一次蒸馏;重试保留该值。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
await memory.createProfileExtraction({
userId: 'user-123', mode: 'incremental',
messages: [{ role: 'user', content: '我喜欢简洁的技术说明。' }]
});
// 提取完成后独立执行:
// const profile = await memory.getProfile({ userId: 'user-123' });
// const sources = await memory.listProfileSources({ userId: 'user-123' });
// await memory.createProfileRebuild({ userId: 'user-123' });
const operationId = process.env.MEMORY_DISTILLATION_OPERATION_ID;
if (!operationId) throw new Error('请设置 MEMORY_DISTILLATION_OPERATION_ID');
client.addHeader('Idempotency-Key', operationId);
const submitted = await memory.submitDistillation({
scope: 'user', userId: 'user-123', mode: 'async',
messages: [{ role: 'assistant', content: '请求限流时读取 Retry-After,退避后用原幂等键重试。' },
{ role: 'user', content: '按此方法重试成功了。' }]
});
const dist = await memory.getDistillation({
distillationId: submitted.distillationId, scope: 'user', userId: 'user-123'
});
// 继续查询 dist.distillation.status,检查 counts、outputs 与人工确认状态。// 画像/蒸馏属服务端管理能力,Web Session 面不开放memory.createProfileExtraction("user-123", null,
List.of(new io.agentbase.models.MemoryMessage(io.agentbase.enums.MemoryMessageRole.USER, "我喜欢简洁的技术说明。")),
null, null, io.agentbase.enums.ProfileExtractionMode.INCREMENTAL);
// 提取完成后独立执行:
// memory.getProfile("user-123", null);
// memory.listProfileSources("user-123", null);
// memory.createProfileRebuild("user-123", null);
String operationId = java.util.Objects.requireNonNull(System.getenv("MEMORY_DISTILLATION_OPERATION_ID"));
client.addHeader("Idempotency-Key", operationId);
Map<?, ?> submitted = (Map<?, ?>) memory.submitDistillation(io.agentbase.enums.Scope.USER,
"user-123", null, null, null, null, null, null,
List.of(new io.agentbase.models.DistillationMessage(io.agentbase.enums.DistillationMessageRole.ASSISTANT,
"请求限流时读取 Retry-After,退避后用原幂等键重试。")),
null, io.agentbase.enums.DistillationMode.ASYNC, null);
memory.getDistillation((String) submitted.get("distillationId"), io.agentbase.enums.Scope.USER,
"user-123", null, null, null, null);
// 继续查询 distillation.status,检查 counts、outputs 与人工确认状态。import os
memory.create_profile_extraction(user_id='user-123', mode='incremental',
messages=[{'role': 'user', 'content': '我喜欢简洁的技术说明。'}])
# 提取完成后独立执行:
# memory.get_profile(user_id='user-123')
# memory.list_profile_sources(user_id='user-123')
# memory.create_profile_rebuild(user_id='user-123')
client.add_header('Idempotency-Key', os.environ['MEMORY_DISTILLATION_OPERATION_ID'])
submitted = memory.submit_distillation(scope='user', user_id='user-123', mode='async',
messages=[{'role': 'assistant', 'content': '请求限流时读取 Retry-After,退避后用原幂等键重试。'}])
dist = memory.get_distillation(distillation_id=submitted['distillationId'], scope='user', user_id='user-123')
# 继续查询 dist['distillation']['status'],检查 counts、outputs 与人工确认状态。_, err := memory.CreateProfileExtraction("user-123",
memory.WithCreateProfileExtractionMessages([]models.MemoryMessage{{Role: "user", Content: "我喜欢简洁的技术说明。"}}),
memory.WithCreateProfileExtractionMode("incremental"))
if err != nil { panic(err) }
// 提取完成后按需独立调用,并检查 error:
// memory.GetProfile("user-123")
// memory.ListProfileSources("user-123")
// memory.CreateProfileRebuild("user-123")
operationID := os.Getenv("MEMORY_DISTILLATION_OPERATION_ID") // 需 import "os"
if operationID == "" { panic("请设置 MEMORY_DISTILLATION_OPERATION_ID") }
cl.AddHeader("Idempotency-Key", operationID)
submitted, err := memory.SubmitDistillation(memory.WithSubmitDistillationScope("user"),
memory.WithSubmitDistillationUserId("user-123"), memory.WithSubmitDistillationMode("async"),
memory.WithSubmitDistillationMessages([]models.DistillationMessage{{Role: "assistant", Content: "请求限流时读取 Retry-After,退避后用原幂等键重试。"}}))
if err != nil { panic(err) }
distillationID := (*submitted).(map[string]interface{})["distillationId"].(string)
_, err = memory.GetDistillation(distillationID, memory.WithGetDistillationScope("user"), memory.WithGetDistillationUserId("user-123"))
if err != nil { panic(err) }
// 继续查询 distillation.status,检查 counts、outputs 与人工确认状态。(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 画像:GET /memory/memories/users/{userId}/profile
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS "$APPBASE_ENDPOINT/memory/memories/users/user-123/profile" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" --header @-
# 增量/替换抽取:POST .../profile/extractions
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "$APPBASE_ENDPOINT/memory/memories/users/user-123/profile/extractions" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" --header @- \
-d '{"mode":"incremental","messages":[{"role":"user","content":"我喜欢简洁的技术说明。"}]}'
# 全量重建:POST .../profile/rebuild;证据源:GET .../profile/sources
# 蒸馏:POST /memory/memories/distillations(范围参数同 Node 面);详情 GET /memory/memories/distillations/{distillationId};
# 重放 POST /memory/memories/distillations/{distillationId}/replay
)技能 / 经验 / 上下文做梦(Dreaming)与自进化审批
技能与经验使用 knowledgeId;上下文管理分层聚合(Dreaming:createContextRun、confirmContext、rebuildContext、rollbackContext)。蒸馏产出的候选经验/技能通过 /v1/memory/memories/knowledge/reviews/{reviewId} 审批(approve / reject)或按修订比对回滚(/revisions、/diff、/rollback);艾宾浩斯遗忘流水线通过 POST /v1/memory/pipelines/{id}/validate(dryRun: true)预览单用户遗忘结果。下例管理调用须具备管理访问能力。
- 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' });
// 1. 触发分层上下文做梦(Dreaming)并读取状态
await memory.createContextRun({ scope: 'user', userId: 'user-123' });
const ctxStatus = await memory.getContextStatus({ scope: 'user', userId: 'user-123' });
const ctx = await memory.getContext({ contextId: '<contextId>', scope: 'user', userId: 'user-123' });
// 下列独立动作按需要选择;targetRevision 是业务核对后选中的历史修订。
// await memory.confirmContext({ contextId: '<contextId>', expectedVersion: ctx.context.version, reason: '已核对来源', scope: 'user', userId: 'user-123' });
// await memory.rollbackContext({ contextId: '<contextId>', expectedVersion: ctx.context.version, targetRevision, reason: '回滚到已验证修订', scope: 'user', userId: 'user-123' });
// await memory.rebuildContext({ contextId: '<contextId>', reason: '重新聚合', scope: 'user', userId: 'user-123' });
// 2. 自进化审批(approve / reject)、知识修订回滚与艾宾浩斯遗忘流水线单用户 Dry-run 校验(经底层 client.call 访问管理面端点)
// await client.call('post', new URL(`${endpoint}/memory/memories/knowledge/reviews/<reviewId>/approve`), { 'content-type': 'application/json' }, { expectedVersion: 1, reason: 'SRE 复核通过' });
// await client.call('post', new URL(`${endpoint}/memory/memories/knowledge/<knowledgeId>/rollback`), { 'content-type': 'application/json' }, { scope: 'user', userId: 'user-123', expectedVersion: 5, targetRevision: 3, reason: '回滚至稳定修订' });
// 流水线验证属于管理操作,请使用具备权限的 Console 会话;参见记忆 API 文档。// 技能/经验只读检索可按需开放(本人 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 运行
Map<?, ?> detail = (Map<?, ?>) memory.getContext("<contextId>", io.agentbase.enums.Scope.USER, "user-123", null, null, null, null);
long version = ((Number) ((Map<?, ?>) detail.get("context")).get("version")).longValue();
// 下列独立动作按需选择;targetRevision 从已核对的 history 选择。
// memory.confirmContext("<contextId>", version, "已核对来源", io.agentbase.enums.Scope.USER, "user-123", null, null, null, null);
// memory.rollbackContext("<contextId>", version, targetRevision, "回滚到已验证修订", io.agentbase.enums.Scope.USER, "user-123", null, null, null, null);
// memory.rebuildContext("<contextId>", "重新聚合", io.agentbase.enums.Scope.USER, "user-123", 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(scope='user', user_id='user-123')
ctx = memory.get_context('<contextId>', scope='user', user_id='user-123')
# 下列独立动作按需选择;target_revision 从已核对的 history 选择。
# memory.confirm_context('<contextId>', expected_version=ctx['context']['version'], reason='已核对来源', scope='user', user_id='user-123')
# memory.rollback_context('<contextId>', expected_version=ctx['context']['version'], target_revision=target_revision, reason='回滚到已验证修订', scope='user', user_id='user-123')
# memory.rebuild_context('<contextId>', reason='重新聚合', scope='user', user_id='user-123')memory.ListSkills(memory.WithListSkillsUserId("user-123"))
memory.SearchSkills("周报排版", memory.WithSearchSkillsUserId("user-123"))
memory.ListExperiences(memory.WithListExperiencesUserId("user-123"))
memory.SearchExperiences("投放复盘", memory.WithSearchExperiencesUserId("user-123"))
_, err := memory.CreateContextRun(memory.WithCreateContextRunScope("user"), memory.WithCreateContextRunUserId("user-123"))
if err != nil { panic(err) }
ctx, err := memory.GetContext("<contextId>", memory.WithGetContextScope("user"), memory.WithGetContextUserId("user-123"))
if err != nil { panic(err) }
version := int((*ctx).(map[string]interface{})["context"].(map[string]interface{})["version"].(float64))
_ = version
// 下列独立动作按需选择;targetRevision 从已核对的 history 选择,并处理每次返回的 error。
// memory.ConfirmContext("<contextId>", version, "已核对来源", memory.WithConfirmContextScope("user"), memory.WithConfirmContextUserId("user-123"))
// memory.RollbackContext("<contextId>", version, targetRevision, "回滚到已验证修订", memory.WithRollbackContextScope("user"), memory.WithRollbackContextUserId("user-123"))
// memory.RebuildContext("<contextId>", "重新聚合", memory.WithRebuildContextScope("user"), memory.WithRebuildContextUserId("user-123"))(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 技能:GET /memory/memories/skills;检索 POST /memory/memories/skills/search;详情/证据源 GET .../skills/{knowledgeId}[/sources]
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS -X POST "$APPBASE_ENDPOINT/memory/memories/skills/search" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"query":"周报排版","userId":"user-123"}'
# 经验:GET /memory/memories/experiences;检索 POST .../experiences/search
# 上下文做梦(Dreaming):GET /memory/memories/contexts;调度 POST /memory/memories/contexts/runs;
# 确认 POST .../contexts/{contextId}/confirm;回滚 .../rollback;重建 .../rebuild;状态 GET .../contexts/status
# 自进化审批与回滚:GET/PATCH /memory/memories/knowledge/reviews/{reviewId};POST .../approve | .../reject;GET .../knowledge/{knowledgeId}/revisions | .../diff;POST .../rollback
# 流水线验证属于管理操作,使用具备权限的 Console 会话;请求体包含 versionId 与 data.userId。
)适用版本
完整 Node.js 流程使用 agentbase-node-sdk@2.12.0,服务端流程适用于 Agentbase 2.12.0。其他语言沿用各操作卡的 SDK 接入方式;安装与版本选择见SDK 接入。
2.12.0 — 来源时间与时间检索
写入的 sourceContext.conversationTime 支持日期或带偏移 RFC3339,timeZone 使用 IANA 名称。缺少来源对话时间保持未知,不用导入或事件时间冒充。检索 temporal.mode 可为 current、asOf 或 history;asOf 需要带时区时间戳,不确定事实单独返回。不同时间模式得到不同范围,展示时保留时间与不确定性,不能把历史结果当作当前有效事实。
import { Client, Memory } from 'agentbase-node-sdk';
const client = new Client().setEndpoint(process.env.AGENTBASE_ENDPOINT)
.setProject(process.env.AGENTBASE_PROJECT_ID).setKey(process.env.AGENTBASE_API_KEY);
{
const prepareRequest = client.prepareRequest.bind(client);
client.prepareRequest = (...args) => {
const request = prepareRequest(...args);
request.options.redirect = 'error';
return request;
};
}
const memory = new Memory(client);
const result = await memory.search({ query: 'preferred delivery region',
userId: process.env.AGENTBASE_USER_ID,
temporal: { mode: 'current' }, limit: 10 });
console.log(result);