MemOS MemReader 深度指南：把原始输入翻译成结构化记忆块的“记忆翻译官“-北京尧图网络

人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin【免费下载链接】MemOSSelf-evolving memory OS for LLM AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址https://gitcode.com/gh_mirrors/memos/MemOS点击查看免费下载MemReader 是 MemOS 开源项目中负责信息消化的核心模块它把聊天记录、文档、图片等任意原始输入Raw Data归一化、切片并精炼成带 Embedding 和元数据的标准记忆块TextualMemoryItem为长时记忆写入、文档分析、多模态理解和跨任务技能复用提供统一入口。读完本文你将掌握 MemReader 的 Fast/Fine 双模式原理、三种后端实现的选型方法、工厂化调用方式以及从配置到源码的完整实战方案。1. 它到底解决什么问题在构建 AI 应用时用户输入千奇百怪随口一句聊天、一份 PDF 文档、一张图表截图甚至一串 Tool 调用轨迹。如果把这些原始文本直接塞进记忆库检索质量会急剧下降。MemReader 的作用就是充当记忆翻译官——把杂乱输入统一嚼碎、消化产出带 Embedding 和元数据的标准记忆块供后续的记忆入库、检索召回使用。从 mem_reader/base.py 中可以看到所有 Reader 都遵循统一的BaseMemReader抽象接口核心契约只有两个方法get_memory(scene_data, type, info, mode, **kwargs) - list[list[TextualMemoryItem]]从场景数据中提取记忆fine_transfer_simple_mem(input_memories, type) - list[list[TextualMemoryItem]]调用 LLM 把已有的通常是 Fast 模式产出的记忆项进一步精炼为更高质量的记忆。接口还预留了set_graph_db()与set_searcher()两个钩子用于在提取阶段接入图数据库语义去重、冲突检测和检索器Searcher这为后续的渐进式记忆优化埋下了伏笔。简单来说MemReader 处理一份输入只做三件事归一化Normalize不管你发来的是字符串、OpenAI 格式的对话消息、还是文件路径列表先统一转换成系统可处理的标准消息格式切片Chunking把长对话或长文档切成合适的小块滑窗/分块避免超出 LLM 的 Token 限制精炼Extraction调用 LLM 把非结构化信息提取成结构化知识点Fine 模式或者直接生成快照Fast 模式。2. 两种核心模式Fast 与 FineMemReader 设计了两种工作模式分别对应快和准两种诉求。⚡ Fast 模式唯快不破特点不调用 LLM只做切片、窗口聚合和 Embedding。适用场景用户发消息飞快系统需要毫秒级响应只需保留对话的快照不需要深度理解。产物原始文本片段向量索引来源追踪Sources。从 simple_struct.py 的_process_chat_data实现看Fast 模式把滑窗切出的每个窗口原样包装成记忆项仅当窗口内角色全部是user时标记为UserMemory否则标记为LongTermMemory并统一打上[mode:fast]标签随后用 8 线程的ContextThreadPoolExecutor并发完成 Embedding。整个过程零 LLM 调用速度可达到毫秒级。 Fine 模式精雕细琢特点调用 LLM进行深度分析。适用场景长时记忆写入需要提取关键事实文档分析需要总结核心观点多模态理解需要看懂图片里的内容。产物结构化的事实关键信息提取Key 背景Background 向量索引来源追踪Sources 多模态细节。Fine 模式会先把滑窗文本交给 LLM让模型返回memory list每条包含value、key、tags、memory_type和summary摘要。值得注意的一个实现细节LLM 返回的中文记忆类型会被显式归一化——长期记忆 → LongTermMemory、用户记忆 → UserMemory见 simple_struct.py_process_chat_data这保证了无论模型输出哪种语言落库的记忆类型始终是系统枚举值。mode参数强烈建议显式指定。从get_memory的签名看它的默认值是fine但同一段代码中_process_chat_data又按kwargs.get(mode, fine)取默认值——显式传参可以避免版本升级带来的默认行为漂移。3. 代码结构三种后端实现MemReader 的代码位于 src/memos/mem_reader/结构清晰base.py定义所有 Reader 必须遵守的BaseMemReader接口规范。simple_struct.py最常用的实现专攻纯文本对话和本地文档轻量高效。multi_modal_struct.py全能型选手能处理图片、文件 URL、Tool 调用等复杂输入继承自SimpleStructMemReader。strategy_struct.py策略化切片实现支持按content_length或会话轮数两种聊天切片策略。read_multi_modal/存放各种具体的解析器Parser——ImageParser图片、FileContentParser文件、ToolParserTool 调用、UserParser/AssistantParser/SystemParser各角色消息等。factory.py统一工厂负责按配置创建对应 Reader。read_pref_memory/ 与 read_skill_memory/偏好记忆与技能记忆的专项处理Fine 模式下由多模态 Reader 并行触发。3.1 工厂如何路由后端MemReaderFactory内部维护了一张后端映射表factory.pybackend_to_class { simple_struct: SimpleStructMemReader, strategy_struct: StrategyStructMemReader, multimodal_struct: MultiModalStructMemReader, }from_config()是一个被singleton_factory()装饰的类方法意味着同一配置只创建一次 Reader 实例单例复用避免在长生命周期服务中反复初始化 LLM/Embedder 造成资源浪费。工厂还支持在创建时直接注入graph_db与searcher也可以通过reader.set_graph_db()后续补充。3.2 多模态解析器的路由机制MultiModalStructMemReader在初始化时构建了一个MultiModalParsermulti_modal_parser.py它按消息特征把不同类型的消息分发到对应的专用解析器按type字段路由text、file、image/image_url、tool_description/tool_input/tool_output、audio预留按role字段路由system、user、assistant、tool纯字符串消息则由StringParser兜底。每个解析器都同时实现parse_fast无 LLM与parse_fine调 LLM两个方法并由统一的parse()按模式分发。4. 如何选择 Reader你的需求推荐选择理由只处理纯文本对话SimpleStructMemReader简单、直接、性能好。需要处理图片、文件链接MultiModalStructMemReader内置了多模态解析能力。聊天内容超长、需要自定义切片策略StrategyStructMemReader支持按字符长度或会话轮数两种滑窗策略。需要从 Fast 升级到 Fine任意 Reader 的fine_transfer_simple_mem方法支持先存后优的渐进式策略。StrategyStructMemReader的切片策略由配置中的chat_chunker决定strategy_struct.pychunk_type: content_length按字符数累加切窗超阈值时以上一条消息作为 overlap 继续否则按chunk_session窗口大小与chunk_overlap重叠轮数切分。5. API 概览5.1 统一工厂MemReaderFactory不要自己去new对象使用工厂模式是最佳实践from memos.configs.mem_reader import MemReaderConfigFactory from memos.mem_reader.factory import MemReaderFactory # 从配置创建 Reader cfg MemReaderConfigFactory.model_validate({ backend: simple_struct, config: { llm: {...}, embedder: {...}, chunker: {...}, }, }) reader MemReaderFactory.from_config(cfg)MemReaderConfigFactory会先校验backend是否合法再根据backend把config字典反序列化为对应的配置类SimpleStructMemReaderConfig/MultiModalStructMemReaderConfig/StrategyStructMemReaderConfig详见 configs/mem_reader.py。5.2 核心方法get_memory()这是最常调用的方法。memories reader.get_memory( scene_data, # 你的输入数据 typechat, # 类型chat 或 doc infouser_info, # 用户信息user_id, session_id modefine # 模式fast 或 fine强烈建议显式指定 )返回结果list[list[TextualMemoryItem]]为什么是双层列表因为一个长对话可能会被切成多个窗口Window外层列表代表窗口内层列表代表该窗口提取出的记忆项。这一设计在源码层面贯穿始终_read_memory用线程池并发处理每个窗口再把各窗口结果聚合成外层列表。info字典有硬性校验必须包含字符串类型的user_id和session_id否则get_memory会直接抛出ValueErrorsimple_struct.py。此外还支持可选字段topic_chunk_size、topic_chunk_overlap、chunk_size、chunk_overlap以及custom_tags自定义标签会被注入提取 Prompt。5.3 记忆项的字段结构产出的TextualMemoryItem定义于 memories/textual/item.py包含memory记忆文本内容metadata.memory_type记忆生命周期类型如LongTermMemory、UserMemory、WorkingMemory、SkillMemory、PreferenceMemory、RawFileMemory等metadata.embedding向量索引metadata.sources来源追踪SourceMessage记录 role、chat_time、内容或文档路径保证记忆可溯源metadata.tags、metadata.key关键信息、metadata.backgroundLLM 生成的摘要背景。6. 开发实战场景一处理简单的聊天记录这是最基础的用法使用SimpleStructMemReader。# 1. 准备输入标准的 OpenAI 格式对话 conversation [ [ {role: user, content: 我明天下午 3 点有个会}, {role: assistant, content: 会议主题是什么}, {role: user, content: 讨论 Q4 项目截止日期}, ] ] # 2. 提取记忆 (Fine 模式) memories reader.get_memory( conversation, typechat, modefine, info{user_id: u1, session_id: s1} ) # 3. 结果 # memories 里会包含提取出的事实例如用户明天下午3点有关于Q4项目的会议在这条链路的底层coerce_scene_data()read_multi_modal/utils.py会先把输入归一化为每条消息自动注入chat_time时间戳格式如01:19 PM on 23 September, 2026随后_iter_chat_windows按 Token 数做滑窗。默认滑窗大小为chat_window_max_tokens1024 Token窗口间保留 200 Token 的重叠以保证语境连续。场景二处理多模态输入当用户发来图片或文件链接时切换到MultiModalStructMemReader。# 1. 准备输入包含文件和图片的复杂消息 scene_data [ [ { role: user, content: [ {type: text, text: 看看这个文件和图片}, # 文件支持 URL 自动下载解析 {type: file, file: {file_data: https://example.com/readme.md}}, # 图片支持 URL {type: image_url, image_url: {url: https://example.com/chart.png}}, ] } ] ] # 2. 提取记忆 memories multimodal_reader.get_memory( scene_data, typechat, modefine, # 只有 Fine 模式才会调用视觉模型解析图片 info{user_id: u1, session_id: s1} )处理流程multi_modal_struct.py_expand_multimodal_messages()把content列表拆成独立的子消息每个模态路由到各自的解析器文本 →TextContentParser文件 →FileContentParser图片 →ImageParserFast 阶段 30 线程并行解析_concat_multi_modal_memories()用与聊天滑窗一致的滑动窗口逻辑聚合记忆项超长超过chat_window_max_tokens的单项会先用 chunker 拆分成多个子项Fine 阶段启用四路并行 LLM字符串精炼_process_string_fine、Tool 轨迹经验提取_process_tool_trajectory_fine、技能记忆process_skill_memory_fine、偏好记忆process_preference_fine各走独立的 Prompt 模板与可配置的独立 LLM 实例。图片解析依赖视觉模型配置中image_parser_llm可单独指定未配置时回退到general_llm再回退到主llm文档解析则有独立的document_parser_llm。另外只有 Fine 模式才调用视觉模型解析图片Fast 模式只做文件 URL 的元数据快照。场景三渐进式优化Fine Transfer为了用户体验你可以先用 Fast 模式快速存下对话等系统空闲时再把它精炼成 Fine 记忆。# 1. 先快速存毫秒级 fast_memories reader.get_memory(conversation, modefast, ...) # ... 存入数据库 ... # 2. 后台异步精炼 refined_memories reader.fine_transfer_simple_mem( fast_memories_flat_list, # 注意这里传入的是展平后的 Item 列表 typechat ) # 3. 用 refined_memories 替换掉原来的 fast_memoriesfine_transfer_simple_mem的实现simple_struct.py_process_transfer_chat_data会取出 Fast 记忆项的原始文本重新走一遍 LLM 提取并把原记忆项中的user_id、session_id、sources完整继承到新记忆项上确保精炼前后记忆来源不丢失。多模态版本multi_modal_struct.py_process_transfer_multi_modal_data则更进一步按SourceMessage逐一重建原始消息再交给对应 Parser 做 Fine 解析实现先存后优的渐进式记忆沉淀。7. 配置项说明在.env或配置文件中你可以调整以下关键参数chat_window_max_tokens滑窗大小。默认 1024。决定了多少上下文会被打包在一起处理。设得太小容易丢失语境设得太大容易超出 LLM 的 Token 限制。remove_prompt_example是否移除 Prompt 里的示例。True 省 Token 但可能降低提取质量False 保留 Few-shot 示例提高准确度但消耗更多 Token。默认False。direct_markdown_hostnames仅多模态域名白名单。列表中的域名如raw.githubusercontent.com会被直接当作 Markdown 文本处理跳过 OCR/格式转换步骤加速处理。若未配置则读取FILE_PARSER_DIRECT_MARKDOWN_HOSTNAMES环境变量。此外BaseMemReaderConfig还支持一组可独立定制的 LLM 槽位configs/mem_reader.py用于让不同任务使用各自擅长的模型配置项职责回退链llm主 LLM负责标准文本/聊天记忆提取建议使用微调过的抽取模型必填general_llm通用 LLM负责幻觉过滤、记忆重写、记忆合并、Tool 轨迹、技能记忆回退到llmimage_parser_llm视觉 LLM负责图片解析回退到general_llmdocument_parser_llm文档内容提取专用 LLM未配置时使用文件解析器默认路径preference_extractor_llm偏好提取专用 LLM回退到general_llmembedder向量化模型必填chunker文档分块策略必填chat_chunker聊天切片策略StrategyStruct 专用可选MultiModalStructMemReaderConfig额外支持oss_configOSS 存储配置、skills_dir_config技能目录与memory_version_switch记忆版本管线开关on/off默认off。7.1 完整配置示例仓库中 examples/data/config/mem_scheduler/memos_config_w_optimized_scheduler.yaml 给出了一份可直接参考的simple_struct完整配置mem_reader: backend: simple_struct config: llm: backend: openai config: model_name_or_path: gpt-4o-mini temperature: 0.8 max_tokens: 4096 top_p: 0.9 top_k: 50 remove_think_prefix: true api_key: sk-xxxxxx api_base: https://api.openai.com/v1 embedder: backend: ollama config: model_name_or_path: nomic-embed-text:latest chunker: backend: sentence config: tokenizer_or_token_counter: gpt2 chunk_size: 512 chunk_overlap: 128 min_sentences_per_chunk: 1生产环境建议抽取用微调过的专用模型temperature 可略高如 0.8而幻觉过滤、重写、合并等决策型任务交给general_llm可选用更稳的通用模型向量化模型按语言场景选择中文场景可考虑中英双语 Embedding 模型。8. 源码级深度解析8.1 聊天滑窗算法_iter_chat_windowssimple_struct.py用 Token 计数器实现滑动窗口逐条累加消息当当前窗口文本下一条消息超过chat_window_max_tokens时切出一个窗口然后从窗口头部弹出消息直到剩余 Token 不超过 overlap默认 200形成有重叠的滑动窗口。每条消息在滑窗时同时构造SourceMessage记录type、index、role、chat_time、content保证后续每个记忆项都能精确溯源到原始消息。这是整个 MemReader 记忆可追溯性的基石。8.2 doc 输入的智能归一化coerce_scene_data()对typedoc的list[str]输入会自动分流read_multi_modal/utils.py本地文件路径os.path.exists为真调用 MarkItDown 解析器解析成文本包装为{type: file, file: {...}}URL 或远程路径识别http/https/oss/s3/gs/cosscheme 或含路径分隔符保留原值作为file_data留待多模态解析器异步下载纯文本包装为{type: text, text: s}。Doc 的 Fine 处理在_process_doc_data中先由 chunker 分块逐块按语言中/英选择 Prompt 模板再用 50 线程池并发调用 LLM 提取进度条由tqdm展示。Fast 模式对 doc 输入暂不支持会抛NotImplementedError因为文档必须经 LLM 提炼才有意义。8.3 幻觉过滤与记忆重写当环境变量SIMPLE_STRUCT_ADD_FILTERtrue时_read_memory会在提取完成后追加两道质检工序filter_hallucination_in_memories让general_llm对照原始对话逐条判定提取出的记忆是否被对话支撑不支撑的幻觉直接丢弃rewrite_memories让general_llm重写表述不准确的记忆支持user_only模式仅依据用户消息重写。这两道工序默认关闭SIMPLE_STRUCT_ADD_FILTER默认false需要显式开启以换取更高的记忆质量。8.4 失败兜底LLM 挂了也不丢数据_get_llm_response中有一处关键兜底逻辑当 LLM 返回为空或 JSON 解析失败时会把整段文本包装成一条UserMemory原样保存并附上keymem_str[:10]。注释特别提醒兜底响应的 key 必须是带空格的memory list而非memory_list因为下游_process_chat_data/_process_transfer_chat_data通过resp.get(memory list, [])读取——键名拼写错误会导致兜底项被静默丢弃出现接口返回 200 但 Neo4j 零写入的诡异 bug。这提醒集成方记忆提取的失败降级路径同样重要。8.5 测试覆盖仓库在 tests/mem_reader/ 提供了较完整的测试支撑可作为阅读源码的辅助线索test_factory.py验证工厂按 backend 正确创建对应 Readertest_coarse_memory_type.py验证 chat/doc 各种输入形态本地文件、远程 URL、纯文本、混合输入的归一化与兜底行为test_document_parser_llm.py验证文档解析走独立 LLM、Markdown 直通域名、标题上下文传递等行为test_preference_extractor_llm_config.py验证偏好提取 LLM 的配置接线与回退逻辑。9. 小结MemReader 是 MemOS 记忆流水线的第一公里SimpleStructMemReader负责轻量文本MultiModalStructMemReader负责图片/文件/Tool 等复杂输入StrategyStructMemReader提供自定义切片策略Fast/Fine 双模式让快照入库与深度精炼可以解耦配合fine_transfer_simple_mem实现先存后优的渐进式记忆优化。源码中的滑窗算法、来源追踪、失败兜底、幻觉过滤等设计共同保证了记忆在写入即结构化、处处可溯源、异常不丢失的前提下被高效沉淀为后续的混合检索与跨任务技能复用打下坚实基础。赞分享人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin【免费下载链接】MemOSSelf-evolving memory OS for LLM AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址https://gitcode.com/gh_mirrors/memos/MemOS点击查看免费下载相关推荐openinterpreter 记忆写入管线解剖Stage-One 输入消息模板如何把 Rollout 变成结构化原始记忆openinterpreter 记忆写入管线解剖Stage One 输入消息模板如何把 Rollout 变成结构化原始记忆本篇以 stage_one_inp人工智能大模型AI Agent代码智能体AI 应用CLIgh_mirrors/la/lang翻译记忆库提高翻译效率gh_mirrors/la/lang翻译记忆库提高翻译效率你是否还在为多语言项目中的重复翻译工作而烦恼是否经常遇到相同的短语需要在不同文件中反复翻译的情况后端GoGoGo无需ROOT的Android虚拟定位工具完整指南GoGoGo无需ROOT的Android虚拟定位工具完整指南 GoGoGo是一款基于Android调试API和百度地图SDK开发的免费虚拟定位工具无需ROO移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

MemOS MemReader 深度指南：把原始输入翻译成结构化记忆块的“记忆翻译官“

相关推荐

Docker部署XXL-JOB：从调度中心到执行器的完整实战指南

DAB双有源桥变换器：移相控制与软开关的工程实践指南

NLP-情感分析项目（三）：RNN模型搭建

更多资讯

ESP32-S3-BOX-3实战：智能语音与物联网联动开发指南

EMQX 升级 gen_rpc 3.5.1：根治节点不可达时的 Crash 日志长尾与 `failed_to_connect_server` 刷屏

YOLOv11实时人体行为识别与异常事件预警：安防监控新范式

Skia 的 clang_ubuntu_noble 工具链资产：Linux 自研 Clang 编译器的构建、分发与 Bazel/GN 集成指南

Kornia 点云 PLY 加载器重构解析：基于 header 的 `load_pointcloud_ply` 与 `load_pointcloud_ply_binary`

Formily Vue 自定义组件开发：useField Hook 读取与操作字段状态完全指南

今日更新

Play Framework 迁移指南：移除 GlobalSettings，全面转向依赖注入（Scala 与 Java）

Numba 类型推断机制详解：从 Numba IR 到编译期类型重建的完整原理与实践

企业级项目dragonballz_e159-1的技术架构与实现方案

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？