agentbase-docs

记忆管理

记忆写入、检索召回、记录管理与批量遗忘、导入导出、画像与蒸馏、技能/经验/上下文的各语言调用示例;概念、参数与一致性语义见记忆。

各语言调用示例

写入

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。

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 端点

检索与召回

search 按记录检索;recallKnowledge 按 token 预算返回可直接拼进 Prompt 的上下文(两者都走 dense / sparse / full-text / graph 融合路由)。

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
});

记录管理与批量遗忘

单条 get / list / update / delete;范围删除 deleteMany 有界分页——hasMore=true 必须继续分页并逐项检查失败项,单次 HTTP 成功不等于整范围已删。

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 成功
}

导入导出

范围导出/导入均为异步任务:创建后轮询任务详情直至完成。

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);                             // 轮询任务详情

画像与蒸馏

画像按用户聚合长期事实;蒸馏把记忆沉淀为结构化任务产物,二者都是异步/派生流程。

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>');  // 轮询直至完成

技能 / 经验 / 上下文

技能与经验是沉淀的可复用知识与操作记录(knowledgeId 为稳定 ID);上下文(Dreaming)按项目治理记忆生命周期:调度运行 → 确认 shadow → 回滚/重建。

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>');                  // 重建

事实源