智能体记忆系统

GeniSpace 智能体采用分层记忆系统，能够在对话之间自动存储和检索相关信息，为用户提供更连贯、更个性化的体验。本指南将介绍记忆系统的架构、配置方法和最佳实践。

三层记忆架构

启用记忆后，系统始终按三层组织。这三层并不是需要从中二选一的隔离模式，而是同时生效：系统会自动决定新记忆存入哪一层，并在检索时对已存记忆进行排序。

会话记忆 (Session)

• 内容：当前会话的对话上下文、任务状态和决策节点
• 范围：当前会话
• 默认重要性阈值：约 0.3（重要性较低、生命周期较短的上下文存于此层）

用户记忆 (User)

• 内容：个人信息、偏好设置和个人背景
• 范围：在同一用户的所有会话间共享
• 默认重要性阈值：约 0.5

通用记忆 (Agent / General)

• 内容：专业知识、最佳实践和常见问答
• 范围：在同一智能体的所有用户和会话间共享（限于当前空间）
• 默认重要性阈值：约 0.7（只有重要性高、普遍适用的知识才会提升到此层）

除上述三个向量存储层外，智能体在单次运行期间还会维护短期对话状态。该短期状态由系统自动处理，无需单独配置。

记忆如何工作

存储（自动选择层级）

写入记忆时，您无需选择层级。系统会根据内容的重要性评分和记忆类型自动决定存储层级：

• 个人信息和偏好会被导向用户记忆。
• 重要性高的专业知识会被提升到通用记忆。
• 对话和任务上下文保存在会话记忆。
• 默认情况下，内容至少会保存在会话记忆中。

每一层都有一个由您配置的重要性阈值（见下文）。该阈值决定了内容需要达到多高的重要性，才会被存入对应层级。

检索（加权排序）

在每一轮对话开始时，智能体会并行搜索全部三层并合并结果。每条候选记忆都会被打分，得分最高的若干条会注入到智能体的上下文中。排序公式为：

最终得分 = 相似度 × 层级权重 × (1 + 重要性)

• 相似度：用户输入与已存记忆之间的语义匹配度（向量检索）
• 层级权重：该记忆所属层级的配置权重
• 重要性：该记忆存储时的重要性评分

检索还会受到每层限制的约束，因此每一层最多贡献设定数量的记忆。

配置记忆系统

在智能体配置页面打开记忆配置部分。配置分为两组：存储与检索。

1. 启用记忆

☑️ 启用记忆

开启后即激活完整的分层架构（会话记忆 + 用户记忆 + 通用记忆，以及短期会话状态）。关闭时，不会存储或检索任何记忆。

• 对话型智能体：通常启用，以在会话间维持上下文和个性化。
• 任务型智能体：通常关闭，因为任务型智能体专注于结构化输入输出。

2. 存储配置 —— 重要性阈值

为每一层设置重要性阈值。系统会结合这些阈值和内容类型，决定记忆存入哪一层。

层级	字段（importance_thresholds）	范围	默认值
会话	session	0–1	0.3
用户	user	0–1	0.5
通用	agent	0–1	0.7

• 会话阈值：对话上下文的存储阈值。
• 用户阈值：个人信息的存储阈值。
• 通用阈值：专业知识的存储阈值。

3. 检索配置

检索包含两项按层设置：限制数量与权重。

每层检索数量（layer_limits）—— 从每一层最多取出的记忆数量：

层级	字段	范围	默认值
会话	session	0–20	4
用户	user	0–20	3
通用	agent	0–20	3

层级权重（layer_weights）—— 排序结果时应用于每一层的权重（越高影响越大）：

层级	字段	范围	默认值
会话	session	0–1	0.4
用户	user	0–1	0.3
通用	agent	0–1	0.2

提示

默认值优先考虑近期对话上下文（会话），同时也会呈现相关的个人信息（用户）和共享知识（通用）。提高某一层的限制数量和权重，可让该层更具影响力。

memoryConfig 结构

该配置以 memoryConfig 对象的形式保存在智能体上：

{
  "memoryConfig": {
    "enabled": true,
    "retrieval": {
      "layer_limits": {
        "session": 4,
        "user": 3,
        "agent": 3
      },
      "layer_weights": {
        "session": 0.4,
        "user": 0.3,
        "agent": 0.2
      }
    },
    "storage": {
      "importance_thresholds": {
        "session": 0.3,
        "user": 0.5,
        "agent": 0.7
      }
    }
  }
}

最佳实践

针对不同场景调优

• 隐私敏感的对话（如客户咨询）：提高会话层的权重和限制数量，并降低通用记忆的影响，让回复更依赖当前对话而非共享知识。
• 个人助手：为用户记忆设置更高的权重和限制数量，使偏好和历史能够跨会话延续。
• 多名空间成员共用的共享知识助手：提高通用层的限制数量和权重，并降低其重要性阈值，从而让更多专业知识被提升和检索。

性能建议

1. 保持适度的每层限制：检索过多记忆会拖慢响应并稀释相关性。
2. 调整重要性阈值：通用层阈值越高，共享层中保留的就越是最有价值的知识。
3. 清理过时记忆：通过记忆管理界面或 API 删除过时或错误的条目。

记忆管理 API

可以通过智能体记忆接口（/agents/{agentId}/memory/*）管理智能体记忆，包括列出、创建、搜索、迁移和清除记忆。

列出记忆

const res = await fetch(
  `/agents/${agentId}/memory?page=1&limit=20&isolation_level=all`,
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
// isolation_level：all | session | user | agent
// 可选筛选：memory_type、session_id、search

创建记忆（手动）

手动创建记忆时必须指定 target_layers，且只允许 agent 或 user —— 会话层无法手动写入（它由对话自动填充）。

await fetch(`/agents/${agentId}/memory`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: '该客户偏好深色主题和简洁的界面。',
    memory_type: 'preference',
    importance_score: 0.6,
    tags: ['界面', '偏好'],
    target_layers: ['user'] // 仅支持 agent 或 user
  })
});

搜索记忆

const res = await fetch(`/agents/${agentId}/memory/search`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: '用户的界面偏好',
    isolation_levels: ['session', 'user', 'agent'],
    limit: 5,
    importance_threshold: 0.3
  })
});

在层级之间迁移记忆

await fetch(`/agents/${agentId}/memory/migrate`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    memory_id: 'mem_123',
    source_layer: 'session',
    target_layer: 'user'
  })
});

清除某一层

// 清除某一层的全部记忆（isolation_level：session、user 或 agent）
await fetch(`/agents/${agentId}/memory/clear`, {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ isolation_level: 'session' })
});

记忆统计

const res = await fetch(`/agents/${agentId}/memory/stats`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' }
});
const { data } = await res.json();
// data.stats.layer_breakdown -> { agent, user, session }

统计信息通过 layer_breakdown.{agent, user, session} 按层返回。

常见问题

Details

智能体如何决定记忆存入哪一层？

存储是自动的。系统会查看内容的重要性评分和记忆类型：个人信息和偏好倾向于存入用户记忆，重要性高的专业知识会提升到通用记忆，对话/任务上下文保留在会话记忆。默认情况下，内容至少会保存在会话记忆中。

Details

可以通过 API 直接写入会话层吗？

不可以。手动创建仅允许 agent 或 user 层。会话层由对话自动填充。

Details

检索到的记忆顺序是如何确定的？

每条候选记忆按 相似度 × 层级权重 × (1 + 重要性) 打分，然后将得分最高的结果（受每层限制约束）注入智能体上下文。可调整层级权重和限制数量来改变各层的影响力。

Details

记忆系统如何处理多模态内容？

记忆通过向量（语义）相似度进行检索，可跨语言工作，并支持匹配从文本和图片中提取的内容。

Details

如何优化记忆系统的性能？

保持适度的每层检索数量，调整重要性阈值使只有有价值的内容被提升到更高层级，并定期删除过时或错误的记忆。

下一步

探索更多智能体功能：

• 了解智能体概述中的完整功能介绍
• 在 MCP 工具调用系统中配置工具
• 掌握工具系统中的算子与数据源
• 探索API 集成将智能体集成到您的应用中

相关指南：

• 工作流引擎：了解智能体如何与工作流协同
• 数据与知识库：为智能体提供专业知识支持