记忆服务
AG-Kit 的记忆服务为 AI Agent 提供全面的记忆管理,支持短期对话历史和长期知识持久化。该服务为不同的部署场景提供多种实现,从开发到企业生产环境。
记忆服务由两个主要组件组成:
- 短期记忆: 管理对话历史、上下文窗口和会话状态
- 长期记忆: 存储持久化知识、用户偏好和提取的见解
这两个组件都支持智能上下文管理、自动令牌优化,以及与 AI Agent 框架的无缝集成。
记忆实现
AG-Kit 为不同的用例和部署场景提供多种短期记忆实现。每种实现都支持统一的分支和摘要架构以及上下文工程能力。
可用的实现
InMemoryMemory
用于开发和测试的易失性内存存储
TDAIMemory
基于 TDAI 服务的云端持久化存储
TypeORMMemory
支持多种数据库的灵活 ORM 存储
MySQLMemory
优化的 MySQL 实现,具有性能特性
MongoDBMemory
具有灵活模式的 NoSQL 文档存储
CloudBaseMemory
腾讯 CloudBase 无服务器集成
快速比较
| 实现 | 存储类型 | 持久化 | 可扩展性 | 用例 |
|---|
| InMemoryMemory | 易失性 | ❌ | 单实例 | 开发、测试 |
| TDAIMemory | 云端 | ✅ | 高 | 生产、企业 |
| TypeORMMemory | 数据库 | ✅ | 中高 | 自定义模式、企业 |
| MySQLMemory | MySQL | ✅ | 高 | MySQL 优化应用 |
| MongoDBMemory | NoSQL | ✅ | 非常高 | 灵活模式、分析 |
| CloudBaseMemory | 无服务器 | ✅ | 自动 | 中国市场、无服务器 |
基本用法示例
import { InMemoryMemory, TDAIMemory, TypeORMMemory } from '@ag-kit/agents/storage';
// 根据需求选择实现
const memory = new InMemoryMemory(); // 用于开发
// const memory = new TDAIMemory({ ... }); // 用于生产
// const memory = new TypeORMMemory({ ... }); // 用于自定义数据库
// 所有实现共享相同的接口
await memory.add({
message: {
id: 'msg-1',
role: 'user',
content: 'Hello, I need help with my project',
timestamp: new Date()
},
state: { userId: 'user-123', context: 'project-help' }
});
// 跨所有实现的常用操作
const events = await memory.list({ limit: 10, maxTokens: 4000 });
const results = await memory.retrieve('project help');
const count = await memory.getCount();
核心数据结构
Message
role
'user' | 'assistant' | 'system' | 'tool'
必填
消息角色类型
IMemoryEvent
上下文工程
内置的自动上下文管理,用于在长对话中实现最佳性能。
配置类型
ContextThresholds
在 preRotThreshold 的此百分比时触发压缩
在 preRotThreshold 的此百分比时触发摘要
StructuredSummary
通用功能
所有记忆实现共享以下核心能力:
上下文工程
具有智能压缩和摘要的自动上下文管理:
// 配置上下文阈值以进行自动管理
const memory = new SomeMemory({
enableContextManagement: true,
thresholds: {
preRotThreshold: 8000, // 在 8000 个令牌时开始管理
compactionTrigger: 0.8, // 在阈值的 80% 时压缩
summarizationTrigger: 0.95, // 在阈值的 95% 时摘要
recentToKeep: 10 // 始终保留最后 10 条消息
}
});
// 在操作期间自动管理上下文
await memory.add(event); // 如果需要,自动触发压缩
令牌管理
内置令牌计数和修剪,支持多种策略:
import { TokenTrimmer, TiktokenTokenizer } from '@ag-kit/agents/storage';
// 创建分词器和修剪器
const tokenizer = new TiktokenTokenizer('gpt-4');
const trimmer = new TokenTrimmer(tokenizer);
// 计数令牌
const tokenCount = tokenizer.countTokens('Hello, world!');
// 修剪消息以适应上下文窗口
const events = await memory.list();
const trimmed = trimmer.trimMessages(events, 4000, 'newest_first');
基于内容的搜索
跨所有实现的相似性搜索和相关性评分:
// 语义搜索相关记忆
const results = await memory.retrieve('project help', {
limit: 5,
threshold: 0.7,
sessionId: 'user-session'
});
// 结果包含相关性分数
results.forEach(event => {
console.log(`Score: ${event.score}, Content: ${event.message.content}`);
});
会话管理
多会话支持,具有隔离的对话上下文:
// 使用不同的会话
await memory.add(event1, { sessionId: 'session-A' });
await memory.add(event2, { sessionId: 'session-B' });
// 会话实用程序
const sessionIds = memory.getSessionIds?.() || [];
const count = await memory.getCount({ sessionId: 'session-A' });
await memory.clear({ sessionId: 'session-A' });
会话分支
会话分支启用类 Git 的对话实验和时间旅行功能。创建实验性对话路径,测试不同的响应,并回滚到以前的状态。
关键特性
- 对话实验: 在不丢失原始对话的情况下尝试不同的路径
- 时间旅行: 检出到任何先前的事件并从那里继续
- A/B 测试: 在并行分支中比较不同的 Agent 响应
- 撤销/回滚: 轻松恢复不需要的更改
基本操作
// 创建并切换到新分支
await memory.branch('experiment-1');
await memory.checkout('experiment-1');
// 列出所有分支
const branches = await memory.listBranches();
// 时间旅行到特定事件
await memory.checkout('msg-5', { type: 'event' });
// 清理未使用的分支
await memory.cleanupBranches();
实现支持
| 实现 | 分支支持 |
|---|
| InMemoryMemory | ✅ 完全支持 |
| TDAIMemory | ❌ 不可用 |
| TypeORMMemory | ✅ 完全支持 |
| MySQLMemory | ✅ 完全支持 |
| MongoDBMemory | ✅ 完全支持 |
| CloudBaseMemory | ✅ 完全支持 |
令牌管理
AG-Kit 提供全面的令牌管理实用程序,用于处理 LLM 上下文窗口和优化内存使用。
关键特性
- 精确分词: TiktokenTokenizer 用于精确的 OpenAI 模型令牌计数
- 智能修剪: 具有多种策略的自动消息修剪
- 上下文管理: 与所有记忆实现的内置集成
- 性能优化: 具有资源管理的高效令牌操作
基本用法
import { TokenTrimmer, TiktokenTokenizer } from '@ag-kit/agents/storage';
// 创建分词器和修剪器
const tokenizer = new TiktokenTokenizer('gpt-4');
const trimmer = new TokenTrimmer(tokenizer);
// 计数令牌
const tokenCount = tokenizer.countTokens('Hello, world!');
// 修剪消息以适应上下文窗口
const events = await memory.list();
const trimmed = trimmer.trimMessages(events, 4000, 'newest_first');
长期记忆
长期记忆智能地从对话中提取和存储重要信息,以构建持久的用户档案、偏好和知识库。
关键特性
- 智能提取: 自动识别重要信息
- 语义搜索: 基于高级相似性的检索
- 记忆合并: 去重和关系映射
- 基于策略的组织: 按类型和用途对记忆进行分类
可用的实现
Mem0LongTermMemory
具有自动提取的 AI 驱动记忆(推荐)
TDAILongTermMemory
具有 TDAI 集成的企业级记忆
基本用法
import { Mem0LongTermMemory } from '@ag-kit/agents/storage';
const longTermMemory = new Mem0LongTermMemory({
apiKey: 'your-mem0-api-key',
userId: 'user-123'
});
// 记录记忆
await longTermMemory.record({
id: 'mem-1',
strategy: 'user_preferences',
content: 'User prefers dark mode and minimal UI',
metadata: { confidence: 0.9 },
createdAt: new Date()
});
// 语义搜索
const results = await longTermMemory.semanticSearch('UI preferences');
核心数据结构
interface MemoryEntity {
id: string;
strategy: string; // 用于组织的记忆策略/类别
role?: 'user' | 'assistant'; // 可选角色信息
content: string; // 记忆内容文本
metadata: Record<string, any>; // 额外的上下文和元数据
createdAt: Date; // 创建时间戳
updatedAt?: Date; // 最后更新时间戳
}
interface MemoryQuery {
query?: string; // 用于搜索的语义查询文本
strategy?: string | string[]; // 策略过滤器
limit?: number; // 返回的最大结果数
offset?: number; // 分页偏移量
threshold?: number; // 相似性阈值 (0-1)
filters?: Record<string, any>; // 额外过滤器
orderBy?: Record<string, 'asc' | 'desc'>; // 排序选项
[key: string]: any; // 可扩展以用于特定实现的选项
}
基础接口
abstract class BaseLongTermMemory {
// 核心 CRUD 操作
abstract record(memory: MemoryEntity): Promise<void>;
abstract recordBatch(memories: MemoryEntity[]): Promise<void>;
abstract retrieve(query: MemoryQuery): Promise<MemoryEntity[]>;
abstract delete(memoryId: string | MemoryQuery): Promise<void>;
abstract update(memoryId: string, updates: Partial<MemoryEntity>): Promise<void>;
abstract clear(strategy?: string): Promise<void>;
// 高级功能
abstract extractAndRecord(messages: Message[], context: Record<string, any>): Promise<MemoryEntity[]>;
abstract semanticSearch(query: string, options?: MemoryQuery): Promise<MemoryEntity[]>;
abstract getRelatedMemories(memoryId: string, depth?: number): Promise<MemoryEntity[]>;
abstract consolidate(): Promise<void>;
}
API 参考
BaseMemory (抽象类)
所有记忆实现的基础类,具有内置的上下文工程。所有记忆实现都继承自此类并提供一致的接口方法。
构造函数
记忆和上下文工程的配置
令牌计算器(默认为 TiktokenTokenizer)
thresholds
Partial<ContextThresholds>
上下文管理阈值
summarizer
(events: IMemoryEvent[]) => Promise<StructuredSummary>
自定义摘要函数
核心接口方法
所有记忆实现都从 BaseMemory 继承这些方法,以实现跨不同存储后端的一致记忆管理。
基本操作
list(options?): Promise<IMemoryEvent[]>
使用过滤和分页支持检索事件。
Promise<IMemoryEvent[]>
Promise<IMemoryEvent[]>
必填
符合条件的记忆事件数组
add(event, options?): Promise<void>
将单个事件添加到记忆存储。
addList(events, options?): Promise<void>
在批量操作中高效地添加多个事件。
delete(idOrIndex, options?): Promise<void>
从记忆中删除特定事件。
retrieve(query, options?): Promise<IMemoryEvent[]>
使用相似性匹配按内容搜索事件。
Promise<IMemoryEvent[]>
Promise<IMemoryEvent[]>
必填
具有相关性分数的匹配事件数组
clear(options?): Promise<void>
使用可选过滤从存储中清除事件。
getCount(options?): Promise<number>
获取存储中的事件总数。
isEmpty(options?): Promise<boolean>
检查记忆存储是否为空。
分支方法(在支持的地方)
在支持对话分支的实现中可用 (InMemoryMemory、TypeORMMemory、MySQLMemory、MongoDBMemory、CloudBaseMemory)。
branch(name, fromEventId?): Promise<void>
创建一个新的对话分支以进行实验。
checkout(target, options?): Promise<void>
切换到不同的分支或检出特定事件。
可选的检出参数
type
'branch' | 'event'
默认值:"branch"
正在检出的目标类型
listBranches(): Promise<string[]>
列出记忆存储中的所有可用分支。
deleteBranch(name): Promise<void>
删除特定分支及其所有事件。
cleanupBranches(keep?): Promise<void>
删除未使用的分支以优化存储。
上下文工程方法
isCompacted(event: IMemoryEvent): boolean
检查事件是否已压缩。
decompressEvent(event: IMemoryEvent): IMemoryEvent
解压缩已压缩的事件以恢复原始内容。
decompressEvents(events: IMemoryEvent[]): IMemoryEvent[]
解压缩多个已压缩的事件。
getMetrics(): object
获取上下文管理操作的性能指标。
长期记忆 API
Mem0LongTermMemory
构造函数
constructor(config: Mem0LongTermMemoryConfig)
config
Mem0LongTermMemoryConfig
必填
方法
record(memory: MemoryEntity): Promise<void>
使用智能处理将新的记忆实体记录到 Mem0 服务。
semanticSearch(query: string, options?: MemoryQuery): Promise<MemoryEntity[]>
使用 Mem0 的 AI 驱动相似性匹配执行高级语义搜索。
Promise<MemoryEntity[]>
Promise<MemoryEntity[]>
必填
具有相关性分数的匹配记忆数组
extractAndRecord(messages: Message[], context: Record<string, any>): Promise<MemoryEntity[]>
使用 AI 自动从对话消息中提取和记录重要记忆。
要分析的对话消息数组
role
'user' | 'assistant' | 'system'
必填
对话中的消息角色
Promise<MemoryEntity[]>
Promise<MemoryEntity[]>
必填
提取和记录的记忆数组
令牌管理 API
TiktokenTokenizer
构造函数
constructor(encodingName?: TiktokenEncoding)
encodingName
TiktokenEncoding
默认值:"o200k_base"
Tiktoken 编码名称。支持的编码: 'o200k_base', 'cl100k_base', 'p50k_base', 'r50k_base', 'gpt2'
方法
encode(text: string): Uint32Array
使用 tiktoken 将文本编码为令牌数组。
decode(tokens: Uint32Array): string
将令牌解码回文本。
countTokens(text: string): number
计算文本中的令牌数。
free(): void
释放编码资源。
TokenTrimmer
构造函数
constructor(tokenizer?: ITokenizer)
方法
countMessageTokens(message: { role: string; content: string }): number
计算消息的令牌数,包括格式化开销。
参数:
message
{ role: string; content: string }
必填
要计数令牌的消息对象
消息角色 (user、assistant、system 等)
trimMessages<T>(events: T[], maxTokens: number, strategy?: 'newest_first' | 'oldest_first'): T[]
使用指定策略修剪消息列表以适应令牌限制。
参数:
strategy
'newest_first' | 'oldest_first'
默认值:"newest_first"
修剪策略 - 超出限制时保留哪些消息
newest_first: 保留最新消息,修剪较旧的消息oldest_first: 保留最早消息,修剪较新的消息- 超出限制的单个消息将使用 ”…” 后缀截断
- 考虑 ChatML 格式化开销(每条消息 4 个令牌)
free(): void
释放分词器资源。
返回:
SimpleTokenizer
构造函数
constructor(tokensPerChar?: number)
方法
encode(text: string): Uint32Array
简单的基于字符的编码(每个字符成为一个令牌)。
参数:
返回:
decode(tokens: Uint32Array): string
将基于字符的令牌解码回文本。
参数:
返回:
countTokens(text: string): number
基于字符长度和比率估计令牌数。
参数:
返回:
完整用法示例
多会话聊天应用
import { InMemoryMemory, Mem0LongTermMemory } from '@ag-kit/agents/storage';
class ChatApplication {
private shortTermMemory: InMemoryMemory;
private longTermMemory: Mem0LongTermMemory;
constructor() {
this.shortTermMemory = new InMemoryMemory();
this.longTermMemory = new Mem0LongTermMemory({
apiKey: process.env.MEM0_API_KEY!,
userId: 'default-user'
});
}
async handleMessage(sessionId: string, userId: string, message: string) {
// 存储在短期记忆中
await this.shortTermMemory.add({
message: {
id: `msg-${Date.now()}`,
role: 'user',
content: message,
timestamp: new Date()
},
state: { userId, sessionId, context: 'chat' }
}, { sessionId });
// 获取对话上下文(最后 10 条消息,最多 4000 个令牌)
const context = await this.shortTermMemory.list({
sessionId,
limit: 10,
order: 'desc',
maxTokens: 4000
});
// 搜索长期记忆以获取相关信息
const relevantMemories = await this.longTermMemory.semanticSearch(message, {
threshold: 0.7,
limit: 5
});
return context;
}
}
基本操作
// 创建并切换到新分支
await memory.branch('experiment-1');
await memory.checkout('experiment-1');
// 列出所有分支
const branches = await memory.listBranches();
// 时间旅行到特定事件
await memory.checkout('msg-5', { type: 'event' });
// 清理未使用的分支
await memory.cleanupBranches();
下一步
