让智能体记住用户偏好和历史信息 — 自动提取、手动管理和上下文注入。

智能体记忆

记忆系统使智能体能够跨对话保留用户的关键信息，在后续交互中自动注入相关上下文，从而提供更具个性化的体验。

记忆类型

每条记忆有一个 memoryType，决定其语义用途：

类型	说明	示例
`core`	用户的核心身份信息，始终注入上下文	"用户是外贸公司的采购经理"
`fact`	从对话中提取的事实性信息	"用户常用 ERP 系统是金蝶"
`preference`	用户偏好和习惯	"用户喜欢中文回复，偏好简洁风格"
`summary`	对话摘要或阶段性总结	"上周讨论了 Q2 季度的采购计划"
`note`	管理员手动添加的备注	"VIP 客户，优先响应"

记忆来源

每条记忆的 source 字段标识其创建方式：

来源	说明
`auto`	系统从对话中自动提取
`agent`	智能体在运行过程中主动写入
`admin`	管理员通过 API 或管理面板手动创建

自动提取

当用户与智能体对话时，系统会在后台异步分析对话内容，自动提取值得长期记忆的信息。

提取流程

用户发送消息 → 智能体回复
       ↓
  后台异步触发记忆提取
       ↓
  LLM 分析对话，提取事实和偏好
       ↓
  生成文本向量（text-embedding-v3, 1024 维）
       ↓
  向量去重检查（余弦相似度 >= 0.92 视为重复）
       ↓
  重复 → 更新已有记忆 / 新增 → 写入数据库

提取规则

仅提取事实性信息（身份、职业、偏好、需求），不做推测
每条记忆是一个简洁的陈述句
过滤掉仅与当前对话相关的临时信息
用户消息长度 < 10 字符时跳过提取
每条记忆包含 0.0 ~ 1.0 的置信度评分

向量去重

系统使用 pgvector 存储记忆向量，新记忆入库前会与已有记忆做余弦相似度比较：

相似度 >= 0.92：视为重复或更新，合并到已有记忆
相似度 < 0.92：视为全新记忆，独立写入

记忆检索与上下文注入

每次对话时，系统通过两层机制将相关记忆注入到智能体的上下文中：

第一层：核心记忆（始终注入）

所有 memoryType = 'core' 的记忆
所有 pinned = true 的记忆
不经过相关性检索，直接注入

第二层：相关记忆（按需检索）

基于用户当前问题，通过混合检索（向量 + 关键词）召回最相关的记忆：

参数	默认值	说明
`topK`	8	最大召回条数
`maxTokens`	1000	Token 预算上限
向量权重	0.7	向量相似度在综合评分中的权重
关键词权重	0.3	关键词匹配在综合评分中的权重

检索过程：

将用户问题编码为向量
并行执行向量搜索和关键词搜索
按加权综合分排序
按 Token 预算截断
异步更新被召回记忆的 accessCount 和 lastAccessedAt

REST API

所有记忆接口均需认证，且按 orgId 隔离。

列出记忆

GET /api/agents/:agentId/memories?userId=xxx

返回指定智能体下的所有记忆。可选传入 userId 过滤特定用户的记忆。

响应示例：

[
  {
    "id": "mem-1713100000-abc123",
    "orgId": "org-1",
    "agentId": "agent-1",
    "userId": "user-1",
    "memoryType": "fact",
    "source": "auto",
    "content": "用户是一家外贸公司的采购经理",
    "tags": [],
    "confidence": 0.85,
    "accessCount": 3,
    "lastAccessedAt": "2026-04-10T08:00:00.000Z",
    "pinned": false,
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-01T10:00:00.000Z"
  }
]

创建记忆

POST /api/agents/:agentId/memories

请求体：

字段	类型	必填	说明
`userId`	string	是	关联的用户 ID
`memoryType`	string	否	类型，默认 `fact`
`content`	string	是	记忆内容
`tags`	string[]	否	标签，默认 `[]`
`pinned`	boolean	否	是否置顶，默认 `false`

通过 API 创建的记忆 source 固定为 admin，confidence 为 1.0。

更新记忆

PATCH /api/agents/:agentId/memories/:memoryId

请求体（所有字段可选）：

字段	类型	说明
`content`	string	更新记忆内容
`memoryType`	string	更新类型
`tags`	string[]	更新标签
`pinned`	boolean	更新置顶状态

删除单条记忆

DELETE /api/agents/:agentId/memories/:memoryId

返回 { "ok": true }，记忆不存在时返回 404。

删除用户全部记忆

DELETE /api/agents/:agentId/memories?userId=xxx

删除指定用户在该智能体下的所有记忆。userId 查询参数必填。

返回 { "ok": true, "deleted": 5 }。

记忆统计

GET /api/agents/:agentId/memories/stats

响应示例：

{
  "total": 42,
  "byType": {
    "fact": 25,
    "preference": 10,
    "core": 5,
    "note": 2
  },
  "bySource": {
    "auto": 30,
    "admin": 12
  },
  "userCount": 8
}

数据模型

interface Memory {
  id: string;
  orgId: string;
  agentId: string;
  userId: string;
  memoryType: 'core' | 'fact' | 'preference' | 'summary' | 'note';
  source: 'auto' | 'agent' | 'admin';
  content: string;
  tags: string[];
  confidence: number;       // 0.0 ~ 1.0
  sourceMessageId?: string; // 自动提取时关联的消息 ID
  accessCount: number;      // 被召回次数
  lastAccessedAt?: Date;
  pinned: boolean;
  createdAt: Date;
  updatedAt: Date;
}

智能体记忆

目录