1. 项目概述告别重启失忆的Agent记忆革命最近在折腾AI Agent特别是像Hermes Agent这类需要长期运行、处理复杂任务的智能体时最头疼的问题是什么我猜很多开发者都遇到过重启即失忆。你花了好几个小时通过多轮对话让Agent学习了一个复杂的项目结构、理解了你的编码规范、甚至记住了你常用的API密钥格式结果服务器一重启或者进程一崩溃Agent瞬间“大脑一片空白”一切又得从头再来。这种体验就像你辛苦训练了一个得力的数字助手但它却患上了严重的健忘症。这正是“Hermes Agent 持久化内存”这个项目要解决的核心痛点。它不是一个简单的“保存对话记录”功能而是一套旨在为Agent赋予**长期、稳定、可检索的“工作记忆”**的系统。根据其标题“2 文件、3 级扫描1,300 tokens 告别重启失忆”我们可以窥见其设计思路的精炼与务实。2个文件可能定义了记忆的存储结构和索引机制3级扫描则暗示了记忆的写入、整理和检索策略而1,300 tokens这个具体的数字很可能指向其核心的上下文管理或记忆压缩算法旨在用极小的开销承载关键信息。简单来说这个项目让Hermes Agent从一个“金鱼脑”的临时工变成了一个拥有“笔记本”和“资料库”的专业顾问。无论是因为部署更新、资源调度还是意外故障导致的进程重启Agent都能从上次中断的地方无缝衔接记得之前的任务上下文、用户偏好、已学到的知识片段甚至是未完成的待办事项。这对于构建真正可用的、7x24小时在线的自动化服务如智能客服、自动化运维、个人知识管理助手至关重要。2. 核心设计思路从易失到持久的内存架构演进要理解持久化内存的价值我们得先看看典型Agent的“标准”内存模型。大多数基于大语言模型LLM的Agent其“记忆”严重依赖于上下文窗口Context Window。所有的对话历史、工具调用结果、系统指令都被塞进这个有限的窗口里作为下一次模型推理的输入。这种模式有几个致命伤容量限制上下文窗口大小是硬性天花板如4K、8K、128K tokens。长程任务很容易“挤爆”窗口导致最早的、可能很重要的记忆被丢弃。完全易失进程结束内存清空。所有在上下文窗口里的“记忆”烟消云散。检索效率低虽然上下文窗口内的信息对模型是“全量可见”的但对人类开发者或外部系统而言想要精准找到某条特定记忆如“用户昨天提到的API密钥是什么”只能靠模糊搜索或重新问一遍Agent效率低下。Hermes Agent的持久化内存方案正是为了突破这些限制。其设计思路可以概括为“分级存储、智能索引、按需加载”。2.1 内存的“分层”与“固化”传统的Agent内存是“扁平”且“流动”的。持久化方案首先将其“分层”工作记忆Working Memory相当于Agent当前的“思考白板”存放正在处理的对话轮次、临时变量和即时工具调用结果。这部分通常仍在传统的上下文窗口中速度快但容量小且易失。长期记忆Long-term Memory这就是持久化内存的核心。它将那些需要被记住的信息从易失的工作记忆中“固化”下来写入到外部存储如数据库、文件系统。“固化”不是简单的文本转储。它涉及一个关键步骤记忆向量化Embedding。将一段文本例如“用户偏好使用Python的requests库进行HTTP请求”通过嵌入模型转化为一个高维向量。这个向量捕获了语义信息使得我们后续可以进行语义相似度搜索而不仅仅是关键词匹配。2.2 “2文件”的职责猜想标题中的“2文件”很可能对应着持久化内存系统的两个核心数据载体记忆库文件Memory Bank File这是一个结构化的存储文件可能是SQLite数据库、JSONL或自定义二进制格式用于保存所有被“固化”的记忆条目。每条记忆可能包含唯一ID、原始文本内容、对应的向量嵌入、时间戳、记忆类型如“用户偏好”、“事实知识”、“任务步骤”、关联的元数据如来源会话ID等。索引文件Index File为了实现对海量记忆的快速语义检索单纯的线性扫描是不可行的。因此需要一个高效的索引文件。这很可能是一个向量索引如使用FAISS、HNSWlib、Chroma等库构建。这个索引文件将记忆向量组织起来使得在查询时能以亚秒级的速度找到与查询语句语义最相关的N条记忆。这两个文件相辅相成索引文件负责“找得快”记忆库文件负责“存得全”、“读得细”。它们共同构成了Agent持久化记忆的物理基础。2.3 “3级扫描”的工作流程解析“3级扫描”生动地描述了记忆从产生到被利用的生命周期管理策略。这三级扫描构成了一个完整的流水线第一级扫描记忆捕获与过滤Capture FilterAgent在运行过程中会产生大量中间信息并非所有都值得长期记忆。第一级扫描实时监控Agent的“思维流”可能是内部状态、工具输出、最终回复根据预设规则如重要性评分、信息类型、去重判断进行过滤。只有被判定为“有价值”的信息片段才会被送入记忆固化流水线。这防止了记忆库被垃圾信息填满。第二级扫描记忆固化与向量化Persist Embed通过第一级扫描的信息会进入本阶段。系统将其原始文本进行清洗、格式化然后调用嵌入模型将其转化为向量最后将“文本-向量”对作为一个记忆条目原子化地写入记忆库文件并同步更新向量索引文件。这个过程可能是异步的以避免阻塞Agent的主推理线程。第三级扫描记忆检索与注入Retrieve Inject当Agent需要处理新请求时系统会根据当前查询或上下文自动从记忆库中进行语义搜索第三级扫描。检索到的相关记忆条目会被格式化例如加上“这是你之前记住的信息”的前缀然后作为系统提示的一部分“注入”到本次请求的上下文窗口中供大模型参考。这就是实现“记忆重现”的关键。这个“扫描”体系确保了记忆的选择性存储和相关性召回而不是无差别的全量备份和盲目的全文检索。3. 核心细节解析1,300 Tokens的智慧与安全扫描的考量3.1 1,300 Tokens的精妙平衡“1,300 tokens”这个数字非常值得玩味。它不太可能是记忆库的总容量更可能指的是每次注入到上下文窗口中的记忆内容的总token预算。为什么是这个数字这体现了一种深刻的工程权衡成本控制大模型的API调用成本与输入/输出的tokens数量直接相关。无限制地注入所有相关记忆会急剧增加每次交互的成本。效用递减对于当前问题最相关的记忆可能只有几条。注入过多的陈旧或弱相关记忆不仅浪费tokens还可能“稀释”关键信息甚至干扰模型判断称为“记忆干扰”。上下文窗口预留上下文窗口需要为当前的用户问题、工具调用结果、系统指令和模型回复预留空间。1,300 tokens是一个经过测算的、既能携带足够多关键记忆又不至于挤占其他必要空间的“甜点”值。实现上系统在第三级扫描检索到相关记忆后会按相关性分数排序然后从高到低依次选取直到累计tokens接近1,300的上限。这要求记忆条目本身也需要被设计得相对紧凑可能需要对原始信息进行摘要Summarization这也是记忆固化阶段可能做的工作之一。例如将一段冗长的错误日志总结为“某服务在UTC时间XX曾因网络超时失败重试策略为3次间隔5秒”。3.2 与“安全扫描”热词的关联记忆的安全与隐私热搜词中出现了“安全扫描”这提示我们在设计持久化内存时绝不能忽视安全与隐私。记忆库中可能保存着敏感信息用户隐私数据、内部系统配置、API密钥片段等。因此一个健壮的持久化内存系统必须内置“安全扫描”机制写入前扫描Ingress Scan在第一级或第二级扫描阶段集成内容过滤模块。对即将被固化的文本进行敏感信息检测如使用正则表达式匹配信用卡号、手机号模式或调用内部的关键词过滤服务。对于检测到的高风险信息可以选择1) 完全拒绝写入2) 进行脱敏处理后再写入如将api_keysk-12345替换为api_key3) 打上特殊标签隔离存储。存储加密Storage Encryption记忆库文件和索引文件在磁盘上应以加密形式存储。密钥由外部密钥管理系统管理确保即使文件被非法访问内容也无法被直接读取。访问控制Access Control记忆应被隔离。不同用户、不同会话、不同项目的记忆应严格分开防止记忆越权访问。检索时必须带上身份或会话上下文系统只返回该上下文有权访问的记忆。读取时审计Egress Audit记录哪些记忆在何时被谁哪个Agent实例/用户检索。这对于追溯问题、满足合规性要求至关重要。将安全扫描作为记忆流水线的一个有机环节而不是事后补救是构建可信Agent系统的基石。4. 实操部署与核心环节实现假设我们要为Hermes Agent或一个类似的自研Agent框架集成这样一套持久化内存系统。以下是基于常见实践的核心实现步骤。4.1 环境与依赖准备首先需要引入关键库。以Python环境为例# 核心依赖 pip install chromadb # 或 faiss-cpu 用于向量存储与检索 pip install sentence-transformers # 用于本地嵌入模型可选也可用OpenAI等API pip install sqlalchemy # 用于记忆元数据的关系型存储可选Chromadb自带存储 pip install pydantic # 用于定义严谨的记忆数据模型如果追求极致性能且数据量大可以选择faissFacebook AI Similarity Search作为向量索引后端如果希望开箱即用包含持久化、元数据管理和多租户隔离Chromadb是一个更全面的选择。这里以Chromadb为例因为它集成了存储、索引和检索。4.2 定义记忆数据模型使用Pydantic定义清晰的数据结构这是保证数据质量的第一步。from pydantic import BaseModel, Field from datetime import datetime from typing import Optional, Dict, Any from uuid import uuid4, UUID class MemoryItem(BaseModel): id: UUID Field(default_factoryuuid4) content: str # 记忆的原始文本内容 embedding: Optional[List[float]] None # 向量嵌入由系统填充 metadata: Dict[str, Any] Field(default_factorydict) # 元数据来源、类型、时间、重要性等 # 例如metadata {session_id: sess_001, type: user_preference, timestamp: 2023-10-27..., importance: 0.8} created_at: datetime Field(default_factorydatetime.utcnow)这个模型对应了“记忆库文件”中的一条记录。元数据字段至关重要它是后续进行高级过滤如“只检索某个会话的类型为‘事实’的记忆”的基础。4.3 实现三级扫描流水线接下来我们构建一个MemoryManager类来封装整个流程。import chromadb from chromadb.config import Settings from sentence_transformers import SentenceTransformer import logging class MemoryManager: def __init__(self, persist_directory: str ./agent_memory): # 初始化Chroma客户端数据持久化到指定目录 self.client chromadb.PersistentClient(pathpersist_directory) # 获取或创建一个集合Collection相当于一个命名空间的记忆库 self.collection self.client.get_or_create_collection(nameagent_long_term_memory) # 加载本地嵌入模型例如 all-MiniLM-L6-v2 平衡速度与质量 self.embedder SentenceTransformer(all-MiniLM-L6-v2) self.logger logging.getLogger(__name__) # --- 第一级扫描捕获与过滤 --- def _capture_and_filter(self, text: str, metadata: dict) - Optional[MemoryItem]: 判断一段文本是否值得长期记忆。 # 规则1去重。检查近期或同会话内是否有高度相似的内容已存储。 # 规则2重要性评分。可以根据文本长度、来源用户输入 vs 工具输出 vs 模型思考、关键词等进行简单评分。 importance_score self._calculate_importance(text, metadata) if importance_score 0.5: # 假设阈值是0.5 self.logger.debug(f信息重要性({importance_score})不足跳过记忆: {text[:50]}...) return None # 规则3敏感信息过滤安全扫描。 if self._contains_sensitive_info(text): self.logger.warning(检测到敏感信息进行脱敏处理或跳过。) # 这里可以实现脱敏逻辑例如 text self._redact_sensitive_info(text) # 本例中直接跳过 return None memory_item MemoryItem(contenttext, metadatametadata) memory_item.metadata[importance] importance_score return memory_item def _calculate_importance(self, text: str, metadata: dict) - float: 简单的启发式重要性评分。 score 0.0 # 来自用户明确指令或总结性陈述的分数高 if metadata.get(source) user_directive: score 0.7 # 文本长度适中既不是太短无信息也不是太长日志的分数高 if 50 len(text) 500: score 0.2 # 包含特定关键词如“记住”、“偏好”、“总是”的分数高 important_keywords [prefer, always, never, remember, important] if any(keyword in text.lower() for keyword in important_keywords): score 0.3 return min(score, 1.0) # 归一化到0-1 def _contains_sensitive_info(self, text: str) - bool: 简单的敏感信息检测。 import re patterns [ r\b\d{3}[-.]?\d{3}[-.]?\d{4}\b, # 类手机号 r\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b, # 类信用卡号 r\b(?:sk-|AKIA|GCM)[a-zA-Z0-9]{20,}\b, # 类API密钥 ] for pattern in patterns: if re.search(pattern, text): return True return False # --- 第二级扫描固化与向量化 --- def persist_memory(self, text: str, metadata: dict): 外部调用的主要接口尝试将一段文本存入长期记忆。 memory_item self._capture_and_filter(text, metadata) if not memory_item: return # 生成向量嵌入 embedding self.embedder.encode(memory_item.content).tolist() memory_item.embedding embedding # 准备存入ChromaDB的数据 # ChromaDB 需要 id, embedding, metadata, document doc_id str(memory_item.id) doc_embedding memory_item.embedding doc_metadata memory_item.metadata doc_content memory_item.content # 原始文本也存储一份便于调试和直接读取 # 异步或同步添加到集合 self.collection.add( documents[doc_content], embeddings[doc_embedding], metadatas[doc_metadata], ids[doc_id] ) self.logger.info(f记忆已持久化ID: {doc_id}, 内容摘要: {memory_item.content[:80]}...) # --- 第三级扫描检索与注入 --- def retrieve_memories(self, query: str, n_results: int 5, filter_dict: Optional[dict] None) - List[MemoryItem]: 根据查询检索相关记忆。 # 将查询文本也向量化 query_embedding self.embedder.encode(query).tolist() # 调用ChromaDB查询可以附加元数据过滤 results self.collection.query( query_embeddings[query_embedding], n_resultsn_results, wherefilter_dict # 例如 {session_id: sess_001} 实现记忆隔离 ) retrieved_memories [] # results的结构{ids: [[...]], documents: [[...]], metadatas: [[...]], ...} if results[ids][0]: for doc_id, doc_content, metadata in zip(results[ids][0], results[documents][0], results[metadatas][0]): memory_item MemoryItem( idUUID(doc_id), contentdoc_content, metadatametadata ) retrieved_memories.append(memory_item) return retrieved_memories def format_memories_for_context(self, memories: List[MemoryItem], token_budget: int 1300) - str: 将检索到的记忆格式化为一段文本准备注入上下文并严格遵守token预算。 formatted_texts [] current_tokens 0 # 这里需要一个简单的token估算函数可以用tiktoken库针对OpenAI模型或近似按字符/单词估算 for memory in memories: # 简单估算英文大致1 token ~ 4字符中文1 token ~ 2字符。此处为示例使用字符数/3的粗略估计。 memory_text f[记忆] {memory.content}\n estimated_tokens len(memory_text) // 3 if current_tokens estimated_tokens token_budget: break formatted_texts.append(memory_text) current_tokens estimated_tokens header f以下是与你当前任务相关的历史记忆共{len(formatted_texts)}条\n return header .join(formatted_texts)4.4 与Agent主循环集成最后我们需要在Agent的主逻辑中调用这个MemoryManager。# 在Agent初始化时 memory_manager MemoryManager(persist_directory./data/agent_memory) # 在Agent处理完一轮交互生成有价值的信息后尝试固化记忆 def on_agent_cycle_complete(self, final_response: str, context_metadata: dict): 假设在一个对话轮次结束后调用。 # context_metadata 应包含 session_id, turn_id, source 等信息 self.memory_manager.persist_memory(final_response, context_metadata) # 在Agent开始处理一个新用户请求时检索相关记忆并注入提示词 def prepare_context_for_new_query(self, user_query: str, session_id: str) - str: 准备包含历史记忆的上下文。 # 1. 检索相关记忆 filter_by_session {session_id: session_id} # 实现会话隔离 relevant_memories self.memory_manager.retrieve_memories( queryuser_query, n_results10, # 多检索一些供后续token预算筛选 filter_dictfilter_by_session ) # 2. 格式化记忆遵守1300 tokens预算 memory_context self.memory_manager.format_memories_for_context(relevant_memories, token_budget1300) # 3. 组合成最终的提示词 system_prompt f你是一个拥有长期记忆的助手。{memory_context} 请基于以上记忆如果存在和当前对话回答用户问题。 full_prompt system_prompt f\n\n用户: {user_query}\n助手: return full_prompt通过以上步骤我们就将一个具备“2文件”ChromaDB的持久化存储文件及其索引、“3级扫描”捕获过滤、固化向量化、检索注入和“~1,300 tokens”预算管理的持久化内存系统集成到了Agent框架中。Agent重启后MemoryManager会从./data/agent_memory目录加载已有的记忆库和索引实现记忆的延续。5. 常见问题与排查技巧实录在实际部署和运行这套系统时你肯定会遇到各种问题。以下是我在类似项目中踩过的坑和总结的技巧。5.1 记忆检索不准或无关记忆被注入问题现象Agent的回答开始变得奇怪引用了完全不相关的历史信息。排查思路检查嵌入模型你使用的嵌入模型是否与你的任务领域匹配通用模型如all-MiniLM-L6-v2在通用语义上不错但对于特定领域如医疗、法律、代码使用领域微调过的嵌入模型效果会大幅提升。可以尝试在少量数据上测试不同模型的检索准确率。审视元数据过滤检索时是否正确地使用了元数据过滤如果没有加session_id过滤那么用户A的记忆可能会被注入到用户B的会话中造成混乱。确保filter_dict被正确设置。调整检索数量n_results一开始不要检索太多如50条这会让很多弱相关记忆进入候选池。先从5-10条开始观察召回的关键记忆是否足够。查看记忆内容质量通过memory_manager.collection.get()方法查看记忆库里实际存了什么。很可能第一级扫描的过滤规则太松存入了大量无意义的中间过程文本如“我正在思考...”。需要收紧过滤规则或引入基于LLM的摘要/重要性评估。实操技巧为记忆条目增加一个embedding_model_version的元数据字段。当你升级嵌入模型时旧向量和新向量不在同一个语义空间无法直接比较。要么全部重新生成向量重建索引要么将不同版本的记忆分开存储和检索。5.2 记忆库膨胀导致性能下降问题现象随着时间推移Agent响应变慢尤其是检索环节。排查思路检查索引类型ChromaDB或FAISS默认的平面索引Flat Index在数据量很大时如超过10万条查询速度会线性下降。需要切换到更高效的索引如HNSWHierarchical Navigable Small World。在ChromaDB中创建集合时可以指定hnsw:space等参数。实施记忆清理策略不是所有记忆都需要永久保存。实现一个后台清理任务定期如每天扫描记忆库根据metadata中的created_at时间和importance重要性评分删除过于陈旧或重要性极低的记忆。可以设定策略如“保留最近30天的重要记忆importance0.7保留最近7天的所有记忆”。记忆压缩与摘要对于非常重要的长期记忆可以定期使用LLM对其进行摘要将多条详细记忆合并成一条高度凝练的概要记忆然后归档或删除原始详细记忆。这能大幅减少存储和检索压力。实操技巧将记忆库按时间分片Sharding。例如每个月的数据存在一个独立的集合或目录中。当前活跃会话只查询最近1-2个月的记忆库。历史记忆库可以离线存档仅在需要深度回溯时才加载。这能极大提升热数据的检索性能。5.3 Token预算1300总是很快用尽关键记忆被截断问题现象format_memories_for_context函数总是只能放入前2-3条记忆后面的高相关记忆因为token超限被丢弃。排查思路优化记忆文本长度在第二级扫描固化阶段就对过长的文本进行智能摘要。例如工具返回的1000字错误日志可以总结成“模块X在时间Y因Z原因失败建议措施A”。摘要本身可以作为一个新的、更紧凑的记忆条目存入。实现更精细的Token估算使用准确的tokenizer如tiktoken对应OpenAI模型transformers库的tokenizer对应本地模型来精确计算token数避免基于字符数的粗糙估算导致预算浪费或低估。动态调整检索策略不要一次性检索固定数量如10条再筛选。可以尝试两阶段检索第一阶段用宽松条件检索出较多记忆如20条然后用一个快速的、轻量级的模型或规则对这些记忆进行针对当前查询的“精排序”和“重要性重评估”只选取Top N条最关键的再计算token。这比单纯按向量相似度排序更智能。实操技巧在记忆的元数据中增加一个summary或key_points字段。在固化时就用LLM生成一个简短摘要例如限制在50个tokens内存进去。在format_memories_for_context函数中优先使用这个摘要字段而不是完整的content。只有当token预算非常充裕时才考虑注入完整内容。这相当于为每条记忆准备了一个“压缩版”专门用于上下文注入。5.4 安全扫描的误报与漏报问题现象要么太多正常信息被误判为敏感误报影响记忆功能要么真正的敏感信息没检测出来漏报造成风险。排查思路误报率高检查正则表达式模式是否过于宽泛。例如检测手机号的模式可能把一些版本号如v1.2.3-456也匹配了。需要优化正则表达式增加上下文判断或者引入一个允许列表Allow List。漏报率高单纯的正则表达式难以应对格式多变的敏感信息。考虑集成更专业的敏感信息检测库如微软的Presidio或使用微调过的NER命名实体识别模型。对于API密钥等可以检查其是否出现在一个已知的密钥模式前缀列表中。建立分级处理机制不要一刀切地“发现即丢弃”。可以建立分级策略高风险信息如明文密码必须脱敏或阻断中风险信息如内部IP可以打标签并记录日志低风险信息如泛化的错误类型可以放过。实操技巧将安全扫描模块设计成可插拔的管道Pipeline。你可以配置多个扫描器RegexScanner,PresidioScanner,CustomKeywordScanner每个扫描器返回一个风险分数和类型。最后由一个聚合器RiskAggregator根据预定义的策略决定最终动作通过、脱敏、阻断、告警。这样便于后续迭代和调整规则而不用修改核心的记忆管理代码。这套持久化内存系统将Agent从“瞬时智能”提升到了“持续智能”的层面。它不仅仅是技术的叠加更是对Agent作为“数字员工”这一角色认知的深化。一个不会遗忘、善于总结、且安全可靠的助手才是我们真正期待在生产和生活中并肩作战的伙伴。 1. 项目概述告别重启失忆的Agent记忆革命最近在折腾AI Agent特别是像Hermes Agent这类需要长期运行、处理复杂任务的智能体时最头疼的问题是什么我猜很多开发者都遇到过重启即失忆。你花了好几个小时通过多轮对话让Agent学习了一个复杂的项目结构、理解了你的编码规范、甚至记住了你常用的API密钥格式结果服务器一重启或者进程一崩溃Agent瞬间“大脑一片空白”一切又得从头再来。这种体验就像你辛苦训练了一个得力的数字助手但它却患上了严重的健忘症。这正是“Hermes Agent 持久化内存”这个项目要解决的核心痛点。它不是一个简单的“保存对话记录”功能而是一套旨在为Agent赋予**长期、稳定、可检索的“工作记忆”**的系统。根据其标题“2 文件、3 级扫描1,300 tokens 告别重启失忆”我们可以窥见其设计思路的精炼与务实。2个文件可能定义了记忆的存储结构和索引机制3级扫描则暗示了记忆的写入、整理和检索策略而1,300 tokens这个具体的数字很可能指向其核心的上下文管理或记忆压缩算法旨在用极小的开销承载关键信息。简单来说这个项目让Hermes Agent从一个“金鱼脑”的临时工变成了一个拥有“笔记本”和“资料库”的专业顾问。无论是因为部署更新、资源调度还是意外故障导致的进程重启Agent都能从上次中断的地方无缝衔接记得之前的任务上下文、用户偏好、已学到的知识片段甚至是未完成的待办事项。这对于构建真正可用的、7x24小时在线的自动化服务如智能客服、自动化运维、个人知识管理助手至关重要。2. 核心设计思路从易失到持久的内存架构演进要理解持久化内存的价值我们得先看看典型Agent的“标准”内存模型。大多数基于大语言模型LLM的Agent其“记忆”严重依赖于上下文窗口Context Window。所有的对话历史、工具调用结果、系统指令都被塞进这个有限的窗口里作为下一次模型推理的输入。这种模式有几个致命伤容量限制上下文窗口大小是硬性天花板如4K、8K、128K tokens。长程任务很容易“挤爆”窗口导致最早的、可能很重要的记忆被丢弃。完全易失进程结束内存清空。所有在上下文窗口里的“记忆”烟消云散。检索效率低虽然上下文窗口内的信息对模型是“全量可见”的但对人类开发者或外部系统而言想要精准找到某条特定记忆如“用户昨天提到的API密钥是什么”只能靠模糊搜索或重新问一遍Agent效率低下。Hermes Agent的持久化内存方案正是为了突破这些限制。其设计思路可以概括为“分级存储、智能索引、按需加载”。2.1 内存的“分层”与“固化”传统的Agent内存是“扁平”且“流动”的。持久化方案首先将其“分层”工作记忆Working Memory相当于Agent当前的“思考白板”存放正在处理的对话轮次、临时变量和即时工具调用结果。这部分通常仍在传统的上下文窗口中速度快但容量小且易失。长期记忆Long-term Memory这就是持久化内存的核心。它将那些需要被记住的信息从易失的工作记忆中“固化”下来写入到外部存储如数据库、文件系统。“固化”不是简单的文本转储。它涉及一个关键步骤记忆向量化Embedding。将一段文本例如“用户偏好使用Python的requests库进行HTTP请求”通过嵌入模型转化为一个高维向量。这个向量捕获了语义信息使得我们后续可以进行语义相似度搜索而不仅仅是关键词匹配。2.2 “2文件”的职责猜想标题中的“2文件”很可能对应着持久化内存系统的两个核心数据载体记忆库文件Memory Bank File这是一个结构化的存储文件可能是SQLite数据库、JSONL或自定义二进制格式用于保存所有被“固化”的记忆条目。每条记忆可能包含唯一ID、原始文本内容、对应的向量嵌入、时间戳、记忆类型如“用户偏好”、“事实知识”、“任务步骤”、关联的元数据如来源会话ID等。索引文件Index File为了实现对海量记忆的快速语义检索单纯的线性扫描是不可行的。因此需要一个高效的索引文件。这很可能是一个向量索引如使用FAISS、HNSWlib、Chroma等库构建。这个索引文件将记忆向量组织起来使得在查询时能以亚秒级的速度找到与查询语句语义最相关的N条记忆。这两个文件相辅相成索引文件负责“找得快”记忆库文件负责“存得全”、“读得细”。它们共同构成了Agent持久化记忆的物理基础。2.3 “3级扫描”的工作流程解析“3级扫描”生动地描述了记忆从产生到被利用的生命周期管理策略。这三级扫描构成了一个完整的流水线第一级扫描记忆捕获与过滤Capture FilterAgent在运行过程中会产生大量中间信息并非所有都值得长期记忆。第一级扫描实时监控Agent的“思维流”可能是内部状态、工具输出、最终回复根据预设规则如重要性评分、信息类型、去重判断进行过滤。只有被判定为“有价值”的信息片段才会被送入记忆固化流水线。这防止了记忆库被垃圾信息填满。第二级扫描记忆固化与向量化Persist Embed通过第一级扫描的信息会进入本阶段。系统将其原始文本进行清洗、格式化然后调用嵌入模型将其转化为向量最后将“文本-向量”对作为一个记忆条目原子化地写入记忆库文件并同步更新向量索引文件。这个过程可能是异步的以避免阻塞Agent的主推理线程。第三级扫描记忆检索与注入Retrieve Inject当Agent需要处理新请求时系统会根据当前查询或上下文自动从记忆库中进行语义搜索第三级扫描。检索到的相关记忆条目会被格式化例如加上“这是你之前记住的信息”的前缀然后作为系统提示的一部分“注入”到本次请求的上下文窗口中供大模型参考。这就是实现“记忆重现”的关键。这个“扫描”体系确保了记忆的选择性存储和相关性召回而不是无差别的全量备份和盲目的全文检索。3. 核心细节解析1,300 Tokens的智慧与安全扫描的考量3.1 1,300 Tokens的精妙平衡“1,300 tokens”这个数字非常值得玩味。它不太可能是记忆库的总容量更可能指的是每次注入到上下文窗口中的记忆内容的总token预算。为什么是这个数字这体现了一种深刻的工程权衡成本控制大模型的API调用成本与输入/输出的tokens数量直接相关。无限制地注入所有相关记忆会急剧增加每次交互的成本。效用递减对于当前问题最相关的记忆可能只有几条。注入过多的陈旧或弱相关记忆不仅浪费tokens还可能“稀释”关键信息甚至干扰模型判断称为“记忆干扰”。上下文窗口预留上下文窗口需要为当前的用户问题、工具调用结果、系统指令和模型回复预留空间。1,300 tokens是一个经过测算的、既能携带足够多关键记忆又不至于挤占其他必要空间的“甜点”值。实现上系统在第三级扫描检索到相关记忆后会按相关性分数排序然后从高到低依次选取直到累计tokens接近1,300的上限。这要求记忆条目本身也需要被设计得相对紧凑可能需要对原始信息进行摘要Summarization这也是记忆固化阶段可能做的工作之一。例如将一段冗长的错误日志总结为“某服务在UTC时间XX曾因网络超时失败重试策略为3次间隔5秒”。3.2 与“安全扫描”热词的关联记忆的安全与隐私热搜词中出现了“安全扫描”这提示我们在设计持久化内存时绝不能忽视安全与隐私。记忆库中可能保存着敏感信息用户隐私数据、内部系统配置、API密钥片段等。因此一个健壮的持久化内存系统必须内置“安全扫描”机制写入前扫描Ingress Scan在第一级或第二级扫描阶段集成内容过滤模块。对即将被固化的文本进行敏感信息检测如使用正则表达式匹配信用卡号、手机号模式或调用内部的关键词过滤服务。对于检测到的高风险信息可以选择1) 完全拒绝写入2) 进行脱敏处理后再写入如将api_keysk-12345替换为api_key3) 打上特殊标签隔离存储。存储加密Storage Encryption记忆库文件和索引文件在磁盘上应以加密形式存储。密钥由外部密钥管理系统管理确保即使文件被非法访问内容也无法被直接读取。访问控制Access Control记忆应被隔离。不同用户、不同会话、不同项目的记忆应严格分开防止记忆越权访问。检索时必须带上身份或会话上下文系统只返回该上下文有权访问的记忆。读取时审计Egress Audit记录哪些记忆在何时被谁哪个Agent实例/用户检索。这对于追溯问题、满足合规性要求至关重要。将安全扫描作为记忆流水线的一个有机环节而不是事后补救是构建可信Agent系统的基石。4. 实操部署与核心环节实现假设我们要为Hermes Agent或一个类似的自研Agent框架集成这样一套持久化内存系统。以下是基于常见实践的核心实现步骤。4.1 环境与依赖准备首先需要引入关键库。以Python环境为例# 核心依赖 pip install chromadb # 或 faiss-cpu 用于向量存储与检索 pip install sentence-transformers # 用于本地嵌入模型可选也可用OpenAI等API pip install sqlalchemy # 用于记忆元数据的关系型存储可选Chromadb自带存储 pip install pydantic # 用于定义严谨的记忆数据模型如果追求极致性能且数据量大可以选择faissFacebook AI Similarity Search作为向量索引后端如果希望开箱即用包含持久化、元数据管理和多租户隔离Chromadb是一个更全面的选择。这里以Chromadb为例因为它集成了存储、索引和检索。4.2 定义记忆数据模型使用Pydantic定义清晰的数据结构这是保证数据质量的第一步。from pydantic import BaseModel, Field from datetime import datetime from typing import Optional, Dict, Any from uuid import uuid4, UUID class MemoryItem(BaseModel): id: UUID Field(default_factoryuuid4) content: str # 记忆的原始文本内容 embedding: Optional[List[float]] None # 向量嵌入由系统填充 metadata: Dict[str, Any] Field(default_factorydict) # 元数据来源、类型、时间、重要性等 # 例如metadata {session_id: sess_001, type: user_preference, timestamp: 2023-10-27..., importance: 0.8} created_at: datetime Field(default_factorydatetime.utcnow)这个模型对应了“记忆库文件”中的一条记录。元数据字段至关重要它是后续进行高级过滤如“只检索某个会话的类型为‘事实’的记忆”的基础。4.3 实现三级扫描流水线接下来我们构建一个MemoryManager类来封装整个流程。import chromadb from chromadb.config import Settings from sentence_transformers import SentenceTransformer import logging class MemoryManager: def __init__(self, persist_directory: str ./agent_memory): # 初始化Chroma客户端数据持久化到指定目录 self.client chromadb.PersistentClient(pathpersist_directory) # 获取或创建一个集合Collection相当于一个命名空间的记忆库 self.collection self.client.get_or_create_collection(nameagent_long_term_memory) # 加载本地嵌入模型例如 all-MiniLM-L6-v2 平衡速度与质量 self.embedder SentenceTransformer(all-MiniLM-L6-v2) self.logger logging.getLogger(__name__) # --- 第一级扫描捕获与过滤 --- def _capture_and_filter(self, text: str, metadata: dict) - Optional[MemoryItem]: 判断一段文本是否值得长期记忆。 # 规则1去重。检查近期或同会话内是否有高度相似的内容已存储。 # 规则2重要性评分。可以根据文本长度、来源用户输入 vs 工具输出 vs 模型思考、关键词等进行简单评分。 importance_score self._calculate_importance(text, metadata) if importance_score 0.5: # 假设阈值是0.5 self.logger.debug(f信息重要性({importance_score})不足跳过记忆: {text[:50]}...) return None # 规则3敏感信息过滤安全扫描。 if self._contains_sensitive_info(text): self.logger.warning(检测到敏感信息进行脱敏处理或跳过。) # 这里可以实现脱敏逻辑例如 text self._redact_sensitive_info(text) # 本例中直接跳过 return None memory_item MemoryItem(contenttext, metadatametadata) memory_item.metadata[importance] importance_score return memory_item def _calculate_importance(self, text: str, metadata: dict) - float: 简单的启发式重要性评分。 score 0.0 # 来自用户明确指令或总结性陈述的分数高 if metadata.get(source) user_directive: score 0.7 # 文本长度适中既不是太短无信息也不是太长日志的分数高 if 50 len(text) 500: score 0.2 # 包含特定关键词如“记住”、“偏好”、“总是”的分数高 important_keywords [prefer, always, never, remember, important] if any(keyword in text.lower() for keyword in important_keywords): score 0.3 return min(score, 1.0) # 归一化到0-1 def _contains_sensitive_info(self, text: str) - bool: 简单的敏感信息检测。 import re patterns [ r\b\d{3}[-.]?\d{3}[-.]?\d{4}\b, # 类手机号 r\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b, # 类信用卡号 r\b(?:sk-|AKIA|GCM)[a-zA-Z0-9]{20,}\b, # 类API密钥 ] for pattern in patterns: if re.search(pattern, text): return True return False # --- 第二级扫描固化与向量化 --- def persist_memory(self, text: str, metadata: dict): 外部调用的主要接口尝试将一段文本存入长期记忆。 memory_item self._capture_and_filter(text, metadata) if not memory_item: return # 生成向量嵌入 embedding self.embedder.encode(memory_item.content).tolist() memory_item.embedding embedding # 准备存入ChromaDB的数据 # ChromaDB 需要 id, embedding, metadata, document doc_id str(memory_item.id) doc_embedding memory_item.embedding doc_metadata memory_item.metadata doc_content memory_item.content # 原始文本也存储一份便于调试和直接读取 # 异步或同步添加到集合 self.collection.add( documents[doc_content], embeddings[doc_embedding], metadatas[doc_metadata], ids[doc_id] ) self.logger.info(f记忆已持久化ID: {doc_id}, 内容摘要: {memory_item.content[:80]}...) # --- 第三级扫描检索与注入 --- def retrieve_memories(self, query: str, n_results: int 5, filter_dict: Optional[dict] None) - List[MemoryItem]: 根据查询检索相关记忆。 # 将查询文本也向量化 query_embedding self.embedder.encode(query).tolist() # 调用ChromaDB查询可以附加元数据过滤 results self.collection.query( query_embeddings[query_embedding], n_resultsn_results, wherefilter_dict # 例如 {session_id: sess_001} 实现记忆隔离 ) retrieved_memories [] # results的结构{ids: [[...]], documents: [[...]], metadatas: [[...]], ...} if results[ids][0]: for doc_id, doc_content, metadata in zip(results[ids][0], results[documents][0], results[metadatas][0]): memory_item MemoryItem( idUUID(doc_id), contentdoc_content, metadatametadata ) retrieved_memories.append(memory_item) return retrieved_memories def format_memories_for_context(self, memories: List[MemoryItem], token_budget: int 1300) - str: 将检索到的记忆格式化为一段文本准备注入上下文并严格遵守token预算。 formatted_texts [] current_tokens 0 # 这里需要一个简单的token估算函数可以用tiktoken库针对OpenAI模型或近似按字符/单词估算 for memory in memories: # 简单估算英文大致1 token ~ 4字符中文1 token ~ 2字符。此处为示例使用字符数/3的粗略估计。 memory_text f[记忆] {memory.content}\n estimated_tokens len(memory_text) // 3 if current_tokens estimated_tokens token_budget: break formatted_texts.append(memory_text) current_tokens estimated_tokens header f以下是与你当前任务相关的历史记忆共{len(formatted_texts)}条\n return header .join(formatted_texts)4.4 与Agent主循环集成最后我们需要在Agent的主逻辑中调用这个MemoryManager。# 在Agent初始化时 memory_manager MemoryManager(persist_directory./data/agent_memory) # 在Agent处理完一轮交互生成有价值的信息后尝试固化记忆 def on_agent_cycle_complete(self, final_response: str, context_metadata: dict): 假设在一个对话轮次结束后调用。 # context_metadata 应包含 session_id, turn_id, source 等信息 self.memory_manager.persist_memory(final_response, context_metadata) # 在Agent开始处理一个新用户请求时检索相关记忆并注入提示词 def prepare_context_for_new_query(self, user_query: str, session_id: str) - str: 准备包含历史记忆的上下文。 # 1. 检索相关记忆 filter_by_session {session_id: session_id} # 实现会话隔离 relevant_memories self.memory_manager.retrieve_memories( queryuser_query, n_results10, # 多检索一些供后续token预算筛选 filter_dictfilter_by_session ) # 2. 格式化记忆遵守1300 tokens预算 memory_context self.memory_manager.format_memories_for_context(relevant_memories, token_budget1300) # 3. 组合成最终的提示词 system_prompt f你是一个拥有长期记忆的助手。{memory_context} 请基于以上记忆如果存在和当前对话回答用户问题。 full_prompt system_prompt f\n\n用户: {user_query}\n助手: return full_prompt通过以上步骤我们就将一个具备“2文件”ChromaDB的持久化存储文件及其索引、“3级扫描”捕获过滤、固化向量化、检索注入和“~1,300 tokens”预算管理的持久化内存系统集成到了Agent框架中。Agent重启后MemoryManager会从./data/agent_memory目录加载已有的记忆库和索引实现记忆的延续。5. 常见问题与排查技巧实录在实际部署和运行这套系统时你肯定会遇到各种问题。以下是我在类似项目中踩过的坑和总结的技巧。5.1 记忆检索不准或无关记忆被注入问题现象Agent的回答开始变得奇怪引用了完全不相关的历史信息。排查思路检查嵌入模型你使用的嵌入模型是否与你的任务领域匹配通用模型如all-MiniLM-L6-v2在通用语义上不错但对于特定领域如医疗、法律、代码使用领域微调过的嵌入模型效果会大幅提升。可以尝试在少量数据上测试不同模型的检索准确率。审视元数据过滤检索时是否正确地使用了元数据过滤如果没有加session_id过滤那么用户A的记忆可能会被注入到用户B的会话中造成混乱。确保filter_dict被正确设置。调整检索数量n_results一开始不要检索太多如50条这会让很多弱相关记忆进入候选池。先从5-10条开始观察召回的关键记忆是否足够。查看记忆内容质量通过memory_manager.collection.get()方法查看记忆库里实际存了什么。很可能第一级扫描的过滤规则太松存入了大量无意义的中间过程文本如“我正在思考...”。需要收紧过滤规则或引入基于LLM的摘要/重要性评估。实操技巧为记忆条目增加一个embedding_model_version的元数据字段。当你升级嵌入模型时旧向量和新向量不在同一个语义空间无法直接比较。要么全部重新生成向量重建索引要么将不同版本的记忆分开存储和检索。5.2 记忆库膨胀导致性能下降问题现象随着时间推移Agent响应变慢尤其是检索环节。排查思路检查索引类型ChromaDB或FAISS默认的平面索引Flat Index在数据量很大时如超过10万条查询速度会线性下降。需要切换到更高效的索引如HNSWHierarchical Navigable Small World。在ChromaDB中创建集合时可以指定hnsw:space等参数。实施记忆清理策略不是所有记忆都需要永久保存。实现一个后台清理任务定期如每天扫描记忆库根据metadata中的created_at时间和importance重要性评分删除过于陈旧或重要性极低的记忆。可以设定策略如“保留最近30天的重要记忆importance0.7保留最近7天的所有记忆”。记忆压缩与摘要对于非常重要的长期记忆可以定期使用LLM对其进行摘要将多条详细记忆合并成一条高度凝练的概要记忆然后归档或删除原始详细记忆。这能大幅减少存储和检索压力。实操技巧将记忆库按时间分片Sharding。例如每个月的数据存在一个独立的集合或目录中。当前活跃会话只查询最近1-2个月的记忆库。历史记忆库可以离线存档仅在需要深度回溯时才加载。这能极大提升热数据的检索性能。5.3 Token预算1300总是很快用尽关键记忆被截断问题现象format_memories_for_context函数总是只能放入前2-3条记忆后面的高相关记忆因为token超限被丢弃。排查思路优化记忆文本长度在第二级扫描固化阶段就对过长的文本进行智能摘要。例如工具返回的1000字错误日志可以总结成“模块X在时间Y因Z原因失败建议措施A”。摘要本身可以作为一个新的、更紧凑的记忆条目存入。实现更精细的Token估算使用准确的tokenizer如tiktoken对应OpenAI模型transformers库的tokenizer对应本地模型来精确计算token数避免基于字符数的粗糙估算导致预算浪费或低估。动态调整检索策略不要一次性检索固定数量如10条再筛选。可以尝试两阶段检索第一阶段用宽松条件检索出较多记忆如20条然后用一个快速的、轻量级的模型或规则对这些记忆进行针对当前查询的“精排序”和“重要性重评估”只选取Top N条最关键的再计算token。这比单纯按向量相似度排序更智能。实操技巧在记忆的元数据中增加一个summary或key_points字段。在固化时就用LLM生成一个简短摘要例如限制在50个tokens内存进去。在format_memories_for_context函数中优先使用这个摘要字段而不是完整的content。只有当token预算非常充裕时才考虑注入完整内容。这相当于为每条记忆准备了一个“压缩版”专门用于上下文注入。5.4 安全扫描的误报与漏报问题现象要么太多正常信息被误判为敏感误报影响记忆功能要么真正的敏感信息没检测出来漏报造成风险。排查思路误报率高检查正则表达式模式是否过于宽泛。例如检测手机号的模式可能把一些版本号如v1.2.3-456也匹配了。需要优化正则表达式增加上下文判断或者引入一个允许列表Allow List。漏报率高单纯的正则表达式难以应对格式多变的敏感信息。考虑集成更专业的敏感信息检测库如微软的Presidio或使用微调过的NER命名实体识别模型。对于API密钥等可以检查其是否出现在一个已知的密钥模式前缀列表中。建立分级处理机制不要一刀切地“发现即丢弃”。可以建立分级策略高风险信息如明文密码必须脱敏或阻断中风险信息如内部IP可以打标签并记录日志低风险信息如泛化的错误类型可以放过。实操技巧将安全扫描模块设计成可插拔的管道Pipeline。你可以配置多个扫描器RegexScanner,PresidioScanner,CustomKeywordScanner每个扫描器返回一个风险分数和类型。最后由一个聚合器RiskAggregator根据预定义的策略决定最终动作通过、脱敏、阻断、告警。这样便于后续迭代和调整规则而不用修改核心的记忆管理代码。这套持久化内存系统将Agent从“瞬时智能”提升到了“持续智能”的层面。它不仅仅是技术的叠加更是对Agent作为“数字员工”这一角色认知的深化。一个不会遗忘、善于总结、且安全可靠的助手才是我们真正期待在生产和生活中并肩作战的伙伴。 
