记忆与上下文

记忆类别

记忆存储在四个类别中：

• 事实：永久性知识：用户偏好、个人信息、背景。示例："用户是一名热爱泰国菜的软件工程师。"
• 事件：共同经历的情节性记忆。示例："上周我们聊了他们去日本的旅行。"
• 承诺：智能体做出的承诺和计划。示例："承诺下次询问他们的工作面试情况。"
• 摘要：对话的综合摘要。会话之间自动生成。

记忆的工作原理

记忆完全自动化——你无需管理它。平台分析每段对话并提取事实、事件和承诺。在每次响应之前，最相关的记忆会自动组装并包含在上下文中。

自我改进的记忆

记忆不是静态存储。在每次 chat 调用的背后，几个闭合反馈循环会自动运行，以保持记忆随时间的准确性、组织性和相关性。所有这些都不需要你方面的代码。

• 重要性反馈 — 智能体在响应中实际使用的事实会被强化；被加载但被忽略的事实会逐渐淡化。
• 置信度强化 — 当一个事实被回忆并在对话中得到确认时，它的置信度会稳步朝着确定性攀升。
• 自然的遗忘 — 事实随时间逐渐衰减，但永远不会低于底线。情感重要的和定义身份的事实比中性事实衰减得慢得多。
• 用户级检索策略 — 平台从会话反馈中学习每个智能体–用户对的检索偏好。几周后，检索就会针对该用户的模式进行调整。
• 记忆关联 — 一起被访问的记忆会加强它们之间的链接。记忆图中频繁遍历的路径会随时间变得更快。
• 自适应检索预算 — 检索在自调节的时间预算下运行。质量保持一致；用户始终感觉响应迅速。
• 下一会话预测 — 在会话结束时，平台预测用户下次可能提出的话题，并为它们预热上下文。

有关每个机制的完整说明——包括整合、聚类、去重、话题转换检测、叙事弧、突破和部署安全系统——请参阅智能体如何随时间变得更聪明。

自动整合、去重和清理

平台在后台主动重塑记忆，使其在增长时保持紧凑且易于导航。你不需要调用任何这些——它们默认按正确的周期运行。

主题聚类

新事实会自动分组到语义聚类中。当聚类变得过于异构时会分裂，当它们相互漂近时会合并，当为空时会退役——在没有调整的情况下保持聚类集平衡。

可逆的去重

当两个事实被发现是同一件事时，平台会合并它们并附有完整的审计跟踪记录。如果后续信号与之相矛盾，每次合并都可以逆转。记忆从不被破坏——它被重组，每个重组都被追踪。

冲突解决

当新信息与现有记忆相矛盾（"我上个月搬到柏林"覆盖"我住在巴黎"），平台会推理冲突并选择正确的行动——将两者保留为新信息、合并它们、取代旧事实，或丢弃严格重复。当矛盾尚不能干净地解决时，两个版本都会被保留，所以没有什么会过早丢失。

来源锚定的事实

无法追溯到对话中实际引用的事实在进入存储之前就会被拒绝。智能体不能凭空想象记忆——每个存储的事实都被验证锚定于来自真实说话者的真实消息。

修剪

置信度、重要性和最近性组合分数低的分支会被修剪。平台从不删除高价值的记忆，但它会停止呈现没有贡献的分支。

树自组织

分层记忆树会随时间重塑自身。频繁访问的分支逐渐向根靠近，以便更快检索。过载的节点拆分成平衡的子树。记忆的形状最终反映了它的实际使用方式。

叙事弧压缩

跨多个会话重复出现的实体和主题被压缩成命名的叙事弧。一条长期运行的线索（例如"用户的创业"）变成一个弧，而不是二十个独立的事实——长期对话保持连贯，而不会让上下文窗口爆炸。

话题转换检测和情节

对话没有整齐的分隔——有时用户会说"无论如何，换个完全不同的话题..."，有时他们会在段落中途转向。平台自动检测这些转换，并将其用于将记忆组织成连贯的情节。

两阶段检查首先运行轻量级信号，仅在信号模糊时才升级到更深的语义检查。信号权重在每个智能体–用户对的会话结束审计中校准，因此情节检测随使用而改进。

当智能体检索记忆时，它可以拉取"这个情节中的所有记忆"，而不仅仅是关键字匹配的片段——为其回复提供叙事连续性。

预填记忆

使用 memory.seed() 在用户第一次对话之前预加载智能体对用户的了解。

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: "sk-..." });

await client.agents.memory.seed("agent-id", {
userId: "user-123",
memories: [
  { text: "User's name is Jane Smith", factType: "fact" },
  { text: "Jane is a senior product manager at Acme Corp", factType: "fact" },
  { text: "Jane lives in San Francisco and enjoys hiking", factType: "fact" },
],
});

搜索记忆

按关键字或语义查询搜索用户-智能体对的记忆。

const results = await client.agents.memory.search("agent-id", {
userId: "user-123",
query: "hiking trip",
limit: 10,
});

for (const mem of results.memories) {
console.log(mem.content, mem.type, mem.createdAt);
}

列表与浏览

列出所有记忆或按类别浏览。

// 列出所有记忆（分页）
const memories = await client.agents.memory.list("agent-id", {
userId: "user-123",
type: "fact",   // "fact" | "event" | "commitment" | "summary"
limit: 20,
offset: 0,
});

// 按类别浏览
const facts = await client.agents.memory.listFacts("agent-id", {
userId: "user-123",
});

记忆时间线

获取用户记忆历史的时间顺序视图。

const timeline = await client.agents.memory.timeline("agent-id", {
userId: "user-123",
from: "2026-01-01",
to:   "2026-03-31",
});

for (const entry of timeline.entries) {
console.log(entry.date, entry.summary);
}

浏览记忆树

导航用户的层级记忆结构。

// 在指定路径浏览记忆树
const nodes = await client.agents.memory.browse("agent-id", {
userId: "user-123",
path: "/facts",   // 可选：按路径过滤
});

重置记忆

清除用户-智能体对的所有记忆——适用于测试或用户想重新开始的情况。

await client.agents.memory.reset("agent-id", {
userId: "user-123",
});

实际应用

记忆对每种使用场景都至关重要，但不同的构建目标，实际操作方式也不同。请选择你的方向。

const timeline = await client.agents.memory.timeline("agent-id", {
  userId: "user-123",
  limit: 30,
});

for (const entry of timeline.entries) {
  // 将每个情节渲染为伴侣 UI 中的一个时刻
  render(entry.date, entry.summary, entry.moodBefore, entry.moodAfter);
}