AgentbaseDocs
文档目录

记忆管理

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

运行一遍写入到删除的完整流程

先按接入准备创建项目、启用 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 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.mjs
if (!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 参考。

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 按记录检索(支持五路混合检索 hybrid|vector|keyword|graph|profile、模型生成稀疏向量 retrieval.sparse: true|false|"auto",以及 retrieval.strategy: "progressive" 分层渐进式召回 L3→L0);recallKnowledge 按统一 token 预算返回可直接拼进 Prompt 的记忆、画像、经验与技能上下文。

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

记录管理与批量遗忘

单条 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 });
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,继续相同范围;不能忽略逐项失败。

导入导出

导入导出创建后按各自标识查询,不能把受理当作完成;下例导入使用 dryRun=true,只验证,不写入。

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,使用新的逻辑幂等键。

画像与蒸馏

画像提取必须传新 messages,replace 也不例外;蒸馏须传有效来源或内联证据,下例使用内联对话。首次接入先提交画像提取;排队时等待完成再读取,画像尚未生成时 getProfile 可能返回 404。读取、来源查询和重建是独立操作,下面以注释给出,按需执行。设置 MEMORY_DISTILLATION_OPERATION_ID 标识一次蒸馏;重试保留该值。

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 与人工确认状态。

技能 / 经验 / 上下文做梦(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)预览单用户遗忘结果。下例管理调用须具备管理访问能力。

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: '回滚至稳定修订' });
// await client.call('post', new URL(`${endpoint}/memory/pipelines/pipe_forgetting_01/validate`), { 'content-type': 'application/json' }, { dryRun: true, sampleUserId: 'user_zhangwei_001', simulatedDays: 14 });

适用版本

完整 Node.js 流程使用 agentbase-node-sdk@2.9.0,服务端流程适用于 Agentbase 2.10.0。其他语言沿用各操作卡的 SDK 接入方式;安装与版本选择见SDK 接入。