AI 智能体记忆系统 - MemoryOS 入门指南
GrissomFI约 9 分钟1. 概述
MemoryOS 是一个智能记忆管理系统，采用模块化架构设计，通过可插拔的存储后端和分层记忆管理机制，为 AI 助手提供持久化的记忆能力。本文档深入分析 MemoryOS 主入口类的架构设计与配置机制。
> 地址：https://github.com/BAI-LAB/MemoryOS
2. 快速开始
2.1 安装 MemoryOS
# 使用 pip 安装
pip install memoryos# 或从源码安装
git clone https://github.com/memoryos/memoryos.git
cd memoryos
pip install -e .
2.2 基础使用示例
2.2.1 初始化 MemoryOS
from memoryos import Memoryos# 创建 MemoryOS 实例
memo = Memoryos(
user_id="user123", # 用户唯一标识
openai_api_key="your-api-key", # OpenAI API 密钥
data_storage_path="./memoryos_data", # 数据存储路径
assistant_id="assistant", # 助手标识
llm_model="gpt-4o-mini"# LLM 模型
)
2.2.2 添加记忆和获取响应
# 添加对话记忆
memo.add_memory(
user_message="我喜欢喝咖啡，特别是拿铁",
assistant_message="好的，我记住了您喜欢拿铁咖啡。"
)# 获取智能响应
response = memo.get_response(
user_message="推荐一些咖啡给我",
assistant_message_context="根据用户的喜好推荐咖啡"
)
print(response)
2.3 进阶配置
2.3.1 自定义容量参数
# 高级配置示例
memo = Memoryos(
user_id="user123",
openai_api_key="your-api-key",
data_storage_path="./memoryos_data",
assistant_id="specialized_assistant",
llm_model="gpt-4",
short_term_capacity=20, # 短期记忆容量（默认 10）
mid_term_heat_threshold=3, # 热度更新阈值（默认 5）
long_term_knowledge_capacity=500, # 长期知识容量（默认 100）
embedding_model_name="text-embedding-3-large"# 嵌入模型
)2.3.2 参数调优建议
容量参数：
• short_term_capacity：5-20，适合对话频率• mid_term_heat_threshold：3-10，控制知识更新频率• long_term_knowledge_capacity：100-1000，根据应用场景调整
模型选择：
• 开发测试： gpt-4o-mini+text-embedding-3-small• 生产环境： gpt-4+text-embedding-3-large
3. 架构演进分析
3.1 存储架构演进
MemoryOS 在不同版本中采用了不同的存储策略：
3.1.1 传统文件存储版本（memoryos-pypi & memoryos-mcp）
• 存储方式：JSON 文件 + Faiss 索引 • 数据组织：基于文件系统的目录结构 • 特点：简单直接，适合小规模数据
3.1.2 ChromaDB 版本（memoryos-chromadb）
• 存储方式：ChromaDB 向量数据库 • 数据组织：统一的向量存储和检索 • 特点：高性能向量检索，支持大规模数据
3.2 可插拔存储架构设计
MemoryOS 采用依赖注入模式实现可插拔存储架构：
# ChromaDB 版本的存储提供者注入
classMemoryos:
def__init__(self, ...):
# 初始化存储提供者
self.storage_provider = ChromaStorageProvider(
path=data_storage_path,
user_id=user_id,
assistant_id=assistant_id,
distance_function=distance_function
)
# 将存储提供者注入到各个记忆模块
self.short_term_memory = ShortTermMemory(
storage_provider=self.storage_provider,
max_capacity=short_term_capacity
)4. 主入口类设计分析
4.1 类结构概览
基于对 memoryos.py 的分析，Memoryos 类作为系统的核心入口点，采用以下设计模式：
• 门面模式：为复杂的记忆管理子系统提供统一接口 • 依赖注入：通过构造函数注入各种配置参数和依赖组件 • 模块化设计：将不同类型的记忆管理功能分离到独立模块
4.2 构造函数参数分析
Memoryos 类的构造函数包含 13 个参数，可分为以下几类：
身份标识参数：
user_id: str# 用户唯一标识
assistant_id: str = "default_assistant_profile"# 助手唯一标识API 配置参数：
openai_api_key: str# OpenAI API 密钥
openai_base_url: str = None# OpenAI API 基础 URL（可选）
llm_model: str = "gpt-4o-mini"# 大语言模型名称存储配置参数：
data_storage_path: str# 数据存储路径
embedding_model_name: str = "all-MiniLM-L6-v2"# 嵌入模型名称
embedding_model_kwargs: dict = None# 嵌入模型参数记忆容量参数：
short_term_capacity: int = 10# 短期记忆容量
mid_term_capacity: int = 2000# 中期记忆容量
long_term_knowledge_capacity: int = 100# 长期知识容量
retrieval_queue_capacity: int = 7# 检索队列容量智能触发参数：
mid_term_heat_threshold: float = 5.0# 中期记忆热度阈值
mid_term_similarity_threshold: float = 0.6# 中期记忆相似度阈值4.3 智能配置机制
4.3.1 自适应嵌入模型配置
系统根据嵌入模型类型自动配置优化参数：
# 智能检测 BGE-M3 模型并自动配置 FP16 优化
if embedding_model_kwargs isNone:
if'bge-m3'inself.embedding_model_name.lower():
print("INFO: Detected bge-m3 model, defaulting embedding_model_kwargs to {'use_fp16': True}")
self.embedding_model_kwargs = {'use_fp16': True}
else:
self.embedding_model_kwargs = {}
else:
self.embedding_model_kwargs = embedding_model_kwargs4.3.2 自动目录创建
系统自动创建用户和助手的数据存储目录：
# 定义用户和助手的数据存储路径
self.user_data_dir = os.path.join(self.data_storage_path, "users", self.user_id)
self.assistant_data_dir = os.path.join(self.data_storage_path, "assistants", self.assistant_id)# 确保目录存在（通过 ensure_directory_exists 函数）
ensure_directory_exists(user_short_term_path)
ensure_directory_exists(user_mid_term_path)
ensure_directory_exists(user_long_term_path)
ensure_directory_exists(assistant_long_term_path)
5. 模块化架构设计
5.1 记忆模块层次结构
5.1.1 短期记忆（ShortTermMemory）
• 功能：存储最近的对话历史 • 特点：FIFO 队列，容量有限 • 实现：使用 deque数据结构
self.short_term_memory = ShortTermMemory(
file_path=os.path.join(user_data_dir, "memory.json"),
max_capacity=short_term_capacity
)5.1.2 中期记忆（MidTermMemory）
• 功能：存储经过处理的对话片段 • 特点：基于热度的智能管理 • 实现：向量化存储和检索
self.mid_term_memory = MidTermMemory(
file_path=os.path.join(user_data_dir, "mid_term_memory"),
embedding_model_name=embedding_model_name
)5.1.3 长期记忆（LongTermMemory）
• 用户知识库：存储用户相关的长期知识 • 助手知识库：存储助手学习到的知识
# 用户长期记忆
self.user_long_term_memory = LongTermMemory(
file_path=os.path.join(user_data_dir, "user_profiles"),
embedding_model_name=embedding_model_name,
max_capacity=long_term_knowledge_capacity
)# 助手长期记忆
self.assistant_long_term_memory = LongTermMemory(
file_path=os.path.join(assistant_data_dir, "assistant_knowledge"),
embedding_model_name=embedding_model_name,
max_capacity=long_term_knowledge_capacity
)
5.2 编排模块设计
5.2.1 更新器（Updater）
• 职责：管理记忆的更新和转移 • 依赖：短期、中期、用户长期记忆
self.updater = Updater(
short_term_memory=self.short_term_memory,
mid_term_memory=self.mid_term_memory,
user_long_term_memory=self.user_long_term_memory,
openai_client=self.openai_client
)5.2.2 检索器（Retriever）
• 职责：从各层记忆中检索相关信息 • 依赖：中期、用户长期、助手长期记忆
self.retriever = Retriever(
mid_term_memory=self.mid_term_memory,
user_long_term_memory=self.user_long_term_memory,
assistant_long_term_memory=self.assistant_long_term_memory,
retrieval_queue_capacity=retrieval_queue_capacity
)6. 核心功能接口设计
6.1 记忆添加接口
add_memory() 方法实现了智能的记忆添加机制：
defadd_memory(self, user_input: str, assistant_response: str):
"""添加记忆的核心流程"""
# 1. 添加到短期记忆
self.short_term_memory.add_qa_pair(user_input, assistant_response)
# 2. 检查短期记忆是否已满
ifself.short_term_memory.is_full():
# 3. 处理到中期记忆
self.updater.process_short_to_mid_term()
# 4. 触发智能更新
self._trigger_profile_and_knowledge_update_if_needed()6.2 响应生成接口
get_response 方法实现了基于记忆的智能响应生成：
defget_response(self, user_input: str) -> str:
"""基于记忆生成响应的核心流程"""
# 1. 检索相关记忆
retrieved_info = self.retriever.retrieve_memory(user_input)
# 2. 获取短期历史
short_term_history = self.short_term_memory.get_history()
# 3. 格式化上下文
formatted_context = self._format_context(
retrieved_info, short_term_history, user_input
)
# 4. 生成响应
response = self.openai_client.generate_response(formatted_context)
# 5. 添加到记忆
self.add_memory(user_input, response)
return response7. 智能触发与容量管理机制
7.1 热度驱动的更新机制
_trigger_profile_and_knowledge_update_if_needed 方法实现了基于中期记忆热度的智能更新，采用并行 LLM 处理优化性能：
def_trigger_profile_and_knowledge_update_if_needed(self):
"""基于热度阈值的智能更新机制"""
ifnotself.mid_term_memory.heap:
return
# 获取最热的会话段
neg_heat, sid = self.mid_term_memory.heap[0]
current_heat = -neg_heat
if current_heat >= self.mid_term_heat_threshold:
session = self.mid_term_memory.sessions.get(sid)
unanalyzed_pages = [p for p in session.get("details", [])
ifnot p.get("analyzed", False)]
if unanalyzed_pages:
# 并行执行用户画像分析和知识提取
with ThreadPoolExecutor(max_workers=2) as executor:
future_profile = executor.submit(task_user_profile_analysis)
future_knowledge = executor.submit(task_knowledge_extraction)
updated_user_profile = future_profile.result()
knowledge_result = future_knowledge.result()
# 更新用户画像和知识库
self._update_profile_and_knowledge(updated_user_profile, knowledge_result)
# 重置会话热度
self._reset_session_heat(session, sid)7.2 多层次容量管理
系统通过分层的容量管理策略确保性能和存储效率：
短期记忆容量管理：
• 固定容量限制（默认 10 条） • FIFO 策略，满容量时自动转移到中期记忆 • 实时检查容量状态触发处理流程
中期记忆容量管理：
• 大容量存储（默认 2000 条） • 基于热度的动态管理和优先级排序 • 热度阈值触发长期记忆更新
长期记忆容量管理：
• 知识容量限制（默认 100 条） • 基于重要性和时间的淘汰策略 • 向量化存储支持高效检索
8. 架构设计总结
MemoryOS 主入口架构设计遵循了现代软件工程的最佳实践，体现了以下核心设计原则：
8.1 设计原则
• 职责分离：各记忆模块职责明确，ShortTermMemory 负责临时存储，MidTermMemory 负责会话管理，LongTermMemory 负责知识沉淀 • 依赖注入：通过构造函数注入依赖，提高模块间的解耦性和可测试性 • 门面模式：Memoryos 类作为统一入口，简化客户端调用复杂度
8.2 技术优势
• 可扩展性：模块化设计支持独立扩展，插件化存储适应不同场景需求 • 性能优化：分层存储策略、智能触发机制、并行 LLM 处理提升系统响应速度 • 数据隔离：用户级和助手级的数据隔离确保数据安全性 • 智能管理：基于热度的动态更新和容量管理实现资源的高效利用
8.3 架构价值
通过精心设计的主入口架构，MemoryOS 实现了高性能、可扩展、易维护的智能记忆系统，为 AI 应用提供了强大的上下文记忆能力，支持长期对话和知识积累，显著提升了 AI 助手的智能化水平。这种设计使得 MemoryOS 既能满足简单的个人助手需求，也能扩展到复杂的企业级应用场景。