MemOS GeneralTextMemory 通用明文记忆：基于向量语义检索的智能记忆模块实战指南

人工智能大模型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点击查看免费下载GeneralTextMemory 是 MemOS 中一个灵活的、基于向量的明文记忆模块用于存储、搜索和管理非结构化知识。如果说 NaiveTextMemory 是关键词匹配那么 GeneralTextMemory 就是理解意思的智能索引——它适用于会话代理、个人助理和任何需要语义记忆检索的系统。读完本文你将掌握其记忆数据结构、配置初始化方式、全部核心 API、文件持久化机制以及如何将其与互联网检索、MultiModal Reader 等能力组合使用。记忆结构在 MemOS 的文本记忆体系中每条记忆都被统一表达为一个TextualMemoryItem。它由三个字段构成字段类型描述idstrUUID如果省略则自动生成memorystr记忆内容主体必填metadataTextualMemoryMetadata元数据用于搜索/过滤从源码看item.py 中TextualMemoryItem基于 PydanticBaseModel实现id字段通过default_factorylambda: str(uuid.uuid4())自动生成 UUID且带field_validator强制校验 ID 必须是合法 UUIDmemory为必填字段metadata缺省时自动创建空的TextualMemoryMetadata。所有值都会经过 Pydantic 校验无效值将直接抛出异常。元数据域TextualMemoryMetadataTextualMemoryMetadata是记忆的索引卡用于支撑搜索与过滤。文档定义的核心字段如下字段类型描述typeprocedure,fact,event,opinion记忆类型memory_timestr (YYYY-MM-DD)记忆所指的日期/时间sourceconversation,retrieved,web,file记忆源confidencefloat (0-100)确定性/可信度评分entitieslist[str]主要实体/概念tagslist[str]主题标签visibilityprivate,public,session访问范围updated_atstr最近更新时间戳ISO 8601需要说明的是在实际源码 item.py 中TextualMemoryMetadata还扩展了文档表中未列出的丰富字段包括user_id/session_id标记记忆归属的用户与会话支撑多用户系统与对话上下文追踪status记忆状态activated/resolving/archived/deleted默认activatedversion记忆版本号更新时递增与history字段ArchivedTextualMemory列表配合实现记忆的历史归档与回滚key记忆的键或标题extract()提取时会自动填充info/internal_info任意附加键值对与系统内部算法元数据模型配置为extraallow允许携带任意自定义扩展字段。所有字段都经过 Pydantic 校验无效值将引发错误。搜索机制向量语义搜索 vs 关键词匹配与前文提到的 NaiveTextMemory 使用关键词匹配算法不同GeneralTextMemory使用向量语义搜索。从实现上看两者的检索路径差异明显NaiveTextMemory 直接在内存字典中做子串/关键词扫描而 GeneralTextMemory 每次search()都会调用self._embed_one_sentence(query)将查询文本转为向量再交给向量数据库做相似度检索见 general.py。与 NaiveTextMemory 的算法特点对比特性关键词匹配向量语义搜索理解语义❌ 不理解同义词✅ 理解相似概念资源占用✅ 极低⚠️ 需要嵌入模型和向量数据库执行速度✅ 快速O(n)⚠️ 较慢索引构建 查询适用规模 1K 条记忆10K - 100K 条记忆可预测性✅ 结果直观⚠️ 黑盒模型一句话总结选型思路如果你的记忆量小千条以内、检索要求可解释选 Naive如果记忆量大、需要理解意思的语义召回选 General。官方文档 记忆模块总览 也将 GeneralTextMemory 定位为记住聊天内容或大量文档并能根据语义搜索的通用文本记忆方案。配置与初始化GeneralTextMemory的构造函数签名如下GeneralTextMemory(config: GeneralTextMemoryConfig)GeneralTextMemoryConfig在 memory.py 中定义继承自BaseTextMemoryConfig除继承的memory_filename默认textual_memory.json与cube_id外包含三个必填配置项配置项类型说明extractor_llmLLMConfigFactory记忆提取器 LLM 配置支持 Ollama / OpenAI / Azure 等vector_dbVectorDBConfigFactory向量数据库配置支持 Qdrant / MilvusembedderEmbedderConfigFactory嵌入模型配置支持 Ollama / Ark 等从构造函数源码general.py可以看到初始化时通过三个工厂将配置转为实际实例LLMFactory.from_config(config.extractor_llm)→ 提取器 LLMVecDBFactory.from_config(config.vector_db)→ 向量数据库默认 QdrantEmbedderFactory.from_config(config.embedder)→ 嵌入模型。其中向量数据库的底层配置 QdrantVecDBConfig 支持host/port/path/url/api_key等参数当不提供任何远程地址时会自动回退到本地路径MEMOS_DIR/qdrant嵌入式模式。这意味着你可以零配置启动也可以对接 Qdrant Cloud。推荐使用工厂方式初始化这样无需关心具体后端差异import os from memos.configs.memory import MemoryConfigFactory from memos.memories.factory import MemoryFactory config MemoryConfigFactory( backendgeneral_text, config{ extractor_llm: { ... }, vector_db: { ... }, embedder: { ... }, }, ) m MemoryFactory.from_config(config)这条调用链背后的逻辑是MemoryConfigFactory在backendgeneral_text时会将config字段实例化为GeneralTextMemoryConfig见 memory.py随后MemoryFactory.from_config()依据backend_to_class映射找到GeneralTextMemory类并实例化见 factory.py。核心方法GeneralTextMemory实现了 BaseTextMemory 定义的全部抽象方法API 总结如下方法描述extract(messages)从消息列表中提取记忆基于 LLMadd(memories)添加一个或多个记忆条目或字典search(query, top_k)使用向量相似度检索 top-k 记忆get(memory_id)通过 ID 获取单个记忆get_by_ids(ids)通过 ID 获取多个记忆get_all()返回所有记忆update(memory_id, new)通过 ID 更新一个记忆delete(ids)通过 ID 删除记忆delete_all()删除所有记忆dump(dir)将所有记忆序列化到目录中的 JSON 文件load(dir)从存储的文件中加载记忆下面结合源码说明几个关键方法的内部流程extractLLM 提取。将消息列表拼成role:content字符串替换进SIMPLE_STRUCT_MEM_READER_PROMPT模板调用extractor_llm.generate()让 LLM 返回 JSON再解析为TextualMemoryItem列表并自动填充sourceconversation、tags与updated_atgeneral.py。该过程带tenacity重试装饰器LLM 输出不是合法 JSON 时最多重试 3 次。add添加。先把每个条目统一转为TextualMemoryItem用embedder.embed()批量生成向量再包装成VecDBItemidpayloaditem.model_dump()vector交给vector_db.add()general.py。search语义检索。将查询语句嵌入为向量调用vector_db.search(query_vector, top_k)按score降序排序后把 payload 还原为TextualMemoryItem返回general.py。delete_all清空。实现为删除集合后重新创建保证后续 add 依然可用general.py。文件存储当调用dump(dir)时系统会将记忆保存到dir/config.memory_filename其中memory_filename默认值为textual_memory.json可在GeneralTextMemoryConfig中覆盖。该文件包含所有记忆条目的 JSON 列表每条含id/vector/payload可以使用load(dir)重新加载。源码实现中general.pydump()先vector_db.get_all()取回全部VecDBItem转成 dict 后以ensure_asciiFalse、缩进 4 格的格式写入os.path.join(dir, config.memory_filename)目录不存在会自动创建load()则读取该文件用VecDBItem.from_dict()还原并批量写回向量库general.py。文件不存在时只记录 warning 并安全返回不会中断程序。示例用法完整的最小可运行示例来自文档并补充注释import os from memos.configs.memory import MemoryConfigFactory from memos.memories.factory import MemoryFactory config MemoryConfigFactory( backendgeneral_text, config{ extractor_llm: { ... }, # 例如 {backend: ollama, config: {model_name_or_path: qwen2.5}} vector_db: { ... }, # 例如 {backend: qdrant, config: {collection_name: my_memories}} embedder: { ... }, # 例如 {backend: ollama, config: {model_name_or_path: bge-m3}} }, ) m MemoryFactory.from_config(config) # 提取并添加记忆LLM 自动从对话中抽取结构化记忆 memories m.extract([ {role: user, content: I love tomatoes.}, {role: assistant, content: Great! Tomatoes are delicious.}, ]) m.add(memories) # 通过 id 手动创建并添加一个记忆 memory_id xxx m.add( [ { id: memory_id, memory: User is Chinese., ... } ] ) # 检索记忆语义相似度而非关键词匹配 results m.search(Tell me more about the user, top_k2) # 更新记忆 m.update(memory_id, {memory: User is Canadian., ...}) # 删除记忆 m.delete([memory_id]) # 将所有记忆序列化到目录中的 JSON 文件 / 从存储的文件中加载记忆 m.dump(tmp/mem) m.load(tmp/mem)几点实战注意手动传入id时必须为合法 UUID 字符串否则TextualMemoryItem的校验器会抛错search的top_k控制返回条数结果按相似度分数从高到低排序集成测试覆盖了上述全部方法见 test_general.py可作为 API 用法的权威参照。扩展与进阶互联网检索GeneralTextMemory可以与互联网检索结合使用从网页提取内容并添加到记忆库。其思路是先通过互联网检索模块抓取网页文本再用extract或手动构造TextualMemoryItem的方式入库从而让 Agent 的长期记忆包含实时网络知识。完整示例可参考 TreeTextMemory 文档从互联网检索记忆可选。MultiModal Reader如果需要处理图片、URL、文件等多模态内容可以使用MultiModalStructMemReader它能够将多模态输入解析为结构化文本后再写入记忆库弥补GeneralTextMemory本身只接受纯文本输入的局限。完整示例见 TreeTextMemory 文档使用 MultiModalStructMemReader高级。开发者注意事项使用 Qdrant或兼容向量数据库进行快速相似度搜索vector_db配置支持 Qdrant本地嵌入式、独立服务、Cloud 三种模式后端枚举见 vec_db.py嵌入和提取模型均可配置支持 Ollama / OpenAI / Azure / Ark 等后端分别通过LLMConfigFactory与EmbedderConfigFactory注入测试验证/tests中的集成测试覆盖了所有方法。单元测试 test_general.py 通过 mock 三个工厂LLM / VecDB / Embedder验证了初始化与全方法调用链配置层的校验测试见 test_memory.py。小结GeneralTextMemory是 MemOS 在轻量关键词记忆Naive与复杂图结构记忆Tree之间提供的折中方案它保留简单的列表式数据模型却通过嵌入模型 向量数据库获得了真正的语义检索能力。对于会话代理、个人助理、知识管理系统等记聊天、搜文档、按语义召回的场景它是开箱即用的最佳起点。赞分享人工智能大模型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点击查看免费下载相关推荐MemOS 第一篇记忆实战用 GeneralTextMemory 完成文本记忆的提取、向量化与语义检索MemOS 第一篇记忆实战用 GeneralTextMemory 完成文本记忆的提取、向量化与语义检索 本篇是 MemOS 开源仓库快速入门系列的核心一讲从人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-pluginMemOS GeneralTextMemory 通用文本记忆模块详解基于向量检索的非结构化知识存储与语义召回MemOS GeneralTextMemory 通用文本记忆模块详解基于向量检索的非结构化知识存储与语义召回 GeneralTextMemory gener人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-pluginMemOS TreeTextMemory 树形明文记忆实战基于 Neo4j 的结构化记忆抽取、检索与备份恢复MemOS TreeTextMemory 树形明文记忆实战基于 Neo4j 的结构化记忆抽取、检索与备份恢复 树形明文记忆TreeTextMemory是人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考