MemOS TreeTextMemory 树形明文记忆实战：基于 Neo4j 的结构化记忆抽取、检索与备份恢复

人工智能大模型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点击查看免费下载树形明文记忆TreeTextMemory是 MemOS 中一类基于图数据库的明文记忆实现它把 LLM 从原始文本中抽取出的记忆以节点node形式存储到图数据库中通过边edge将节点组织成层次结构与语义图并在检索时同时利用向量相似度与图遍历兼顾召回质量与可解释性。本文将以 docs/cn/open_source/modules/memories/tree_textual_memory.md 为主线结合src/memos/memories/textual/tree.py等源码实现与examples/data/config/下的真实配置带你从 0 到 1 完成 TreeTextMemory 的配置、记忆抽取、混合检索、互联网增强与备份恢复最终让你的 Agent 不仅能记住事实还能记住事实之间的联系。你将学到什么从原始文本或对话中提取结构化记忆TextualMemoryItem在图数据库中将记忆存储为节点将记忆链接成层次结构和语义图使用向量相似度 图遍历进行搜索。核心概念与工作流程记忆结构在TreeTextMemory中每个记忆节点都是一个TextualMemoryItem其数据结构定义于 src/memos/memories/textual/item.pyid: 唯一记忆 ID省略时自动生成 UUIDmemory: 记忆的主要文本内容metadata: 元数据包含层次结构信息、嵌入向量、标签、实体、来源与状态等。TextualMemoryItem还提供from_dict/to_dict用于与 JSON、图数据库记录互转id字段会被校验为合法 UUID。元数据字段TreeNodeTextualMemoryMetadataTreeNodeTextualMemoryMetadata继承自TextualMemoryMetadata在 src/memos/memories/textual/item.py 中扩展了树形记忆特有的生命周期与图谱字段字段类型描述memory_typeWorkingMemory,LongTermMemory,UserMemory等生命周期分类源码中还包括OuterMemory、RawFileMemory、SkillMemory、PreferenceMemory等statusactivated,resolving,archived,deleted节点状态visibilityprivate,public,session访问范围sourceslist[SourceMessage]来源列表文件、URL 等支持可追溯的 provenance 信息sourceconversation,retrieved,web,file,system原始来源类型confidencefloat (0-100)确定性得分entitieslist[str]提及的实体或概念tagslist[str]主题标签embeddinglist[float]向量嵌入用于相似性搜索created_atstr创建时间戳ISO 8601updated_atstr最近更新时间戳ISO 8601usagelist[str]使用历史backgroundstr附加上下文此外源码还定义了用于追踪记忆演化的字段version版本号更新时递增、history归档的历史版本列表由ArchivedTextualMemory记录conflict/duplicate/extract等更新类型、evolve_to记录节点在 LLM 抽取后演化出的新节点 ID以及working_binding快速模式记忆与工作记忆的绑定关系。最佳实践使用有意义的标签和background—— 它们有助于组织你的图进行多跳推理。核心工作流当运行 TreeTextMemory 示例时完整工作流为抽取Extract使用 LLM 从原始文本对话、文档、网页中提取结构化记忆嵌入Embed为相似性搜索生成向量嵌入存储与链接Store Link将带关系的节点添加到图数据库Neo4j中搜索Search通过向量相似度查询再通过图跳数hop展开结果。提示图链接有助于检索到纯向量搜索可能遗漏的上下文在源码层面TreeTextMemory.__init__见 src/memos/memories/textual/tree.py会依次装配抽取器 LLMextractor_llm、检索调度 LLMdispatcher_llm、嵌入器embedder、图数据库graph_store、重排器reranker默认cosine_local以及负责记忆组织与容量管理的MemoryManager。API 参考初始化TreeTextMemory(config: TreeTextMemoryConfig)核心方法方法描述add(memories)添加一个或多个记忆TextualMemoryItem或字典replace_working_memory()替换所有WorkingMemory节点get_working_memory()获取所有WorkingMemory节点按updated_at降序排列search(query, top_k)使用向量 图搜索检索 top-k 个记忆get(memory_id)通过 ID 获取单个记忆不存在时抛出ValueErrorget_by_ids(ids)通过多个 IDs 获取记忆get_all()将整个记忆图导出为字典update(memory_id, new)通过 ID 更新记忆delete(ids)通过 IDs 硬删除记忆连带删除边delete_all()删除所有记忆和关系dump(dir)在目录中将图序列化为 JSONload(dir)从保存的 JSON 文件加载图drop(keep_last_n)备份图并删除数据库保留最近 N 个备份除上述 API 外源码还提供了get_current_memory_size()查看各memory_type当前容量占用、get_relevant_subgraph(query, top_k, depth)提取 query 相关节点的局部邻域子图支持embedding与fulltext两种搜索方式以及soft_delete()软删除可将status置为deleted并记录evolve_to。这些方法在 src/memos/memories/textual/tree.py 中均有实现。文件存储当调用dump(dir)时MemOS 会将树形明文记忆导出为 JSON 文件dir/config.memory_filename其中memory_filename是TreeTextMemoryConfig的字段默认textual_memory.jsontree_config_shared_database.json中显式设为tree_textual_memories.json。该文件包含nodes与edges的 JSON 结构可通过load(dir)重新加载并调用graph_store.import_graph恢复进图数据库。动手实践从 0 到 1创建 TreeTextMemory 配置定义一个TreeTextMemoryConfig需要指定embedding 模型例如nomic-embed-text:latest由 Ollama 提供图数据库后端Neo4j记忆抽取器基于 LLM可选。TreeTextMemoryConfig的完整字段定义见 src/memos/configs/memory.py包括extractor_llm、dispatcher_llm、embedder、reranker、graph_db、internet_retriever、reorganize、memory_size、search_strategy、mode、include_embedding与memory_filename。仓库在 examples/data/config/tree_config.json 提供了一份可直接复用的本地化配置from memos.configs.memory import TreeTextMemoryConfig config TreeTextMemoryConfig.from_json_file(examples/data/config/tree_config.json)该 JSON 的完整内容为{ extractor_llm: { backend: ollama, config: { model_name_or_path: qwen3:0.6b, temperature: 0.0, remove_think_prefix: true, max_tokens: 8192 } }, dispatcher_llm: { backend: ollama, config: { model_name_or_path: qwen3:0.6b, temperature: 0.0, remove_think_prefix: true, max_tokens: 8192 } }, embedder: { backend: ollama, config: { model_name_or_path: nomic-embed-text:latest } }, graph_db: { backend: neo4j, config: { uri: bolt://localhost:7687, user: neo4j, password: 12345678, db_name: user08alice, auto_create: true, embedding_dimension: 768 } }, reorganize: false }仓库还提供了另外两份配置供不同场景使用examples/data/config/tree_config_shared_database.json基于 OpenAI 兼容接口gpt-4obge-m3embedding bge-reranker-v2-m3重排器的多租户共享数据库配置use_multi_db: true并显式设置memory_sizeWorkingMemory: 200、LongTermMemory: 20000、UserMemory: 30000与memory_filename: tree_textual_memories.jsonexamples/data/config/tree_config_community.json面向 Neo4j Community 版的配置backend: neo4j-community、use_multi_db: false并通过vec_config将向量索引外置到 Qdrantcollection_name: neo4j_vec_db、distance_metric: cosine同时开启reorganize: true。初始化 TreeTextMemoryfrom memos.memories.textual.tree import TreeTextMemory tree_memory TreeTextMemory(config)初始化过程会打印当前模式Tree mode is ...并装配抽取 LLM、调度 LLM、嵌入器、Neo4j 图存储、默认或自定义重排器以及按memory_size未配置时默认为WorkingMemory: 20 / LongTermMemory: 1500 / UserMemory: 480初始化的MemoryManager。若配置了internet_retriever还会一并创建互联网检索器。抽取结构化记忆使用记忆抽取器MemReader将对话、文件或文档解析为多个TextualMemoryItem。使用 SimpleStructMemReader基础from memos.mem_reader.simple_struct import SimpleStructMemReader reader SimpleStructMemReader.from_json_file(examples/data/config/simple_struct_reader_config.json) scene_data [[ {role: user, content: Tell me about your childhood.}, {role: assistant, content: I loved playing in the garden with my dog.} ]] memories reader.get_memory(scene_data, typechat, info{user_id: 1234}) for m_list in memories: tree_memory.add(m_list)其中 examples/data/config/simple_struct_reader_config.json 是一份真实可用的 reader 配置llm使用 OpenAI 兼容接口gpt-4o-minitemperature: 0.8、max_tokens: 1024embedder使用universal_apibge-m3chunker使用sentence分块器chunk_size: 2048、chunk_overlap: 128、min_sentences_per_chunk: 1。使用 MultiModalStructMemReader高级MultiModalStructMemReader支持处理多模态内容文本、图片、URL、文件等能够自动感知智能路由到不同的解析器。其实现位于 src/memos/mem_reader/multi_modal_struct.py底层通过FileContentParsersrc/memos/mem_reader/read_multi_modal/file_content_parser.py按direct_markdown_hostnames白名单直出 Markdownfrom memos.configs.mem_reader import MultiModalStructMemReaderConfig from memos.mem_reader.multi_modal_struct import MultiModalStructMemReader # 创建 MultiModal Reader 配置 multimodal_config MultiModalStructMemReaderConfig( llm{ backend: openai, config: { model_name_or_path: gpt-4o-mini, api_key: your-api-key } }, embedder{ backend: openai, config: { model_name_or_path: text-embedding-3-small, api_key: your-api-key } }, chunker{ backend: text_splitter, config: { chunk_size: 1000, chunk_overlap: 200 } }, extractor_llm{ backend: openai, config: { model_name_or_path: gpt-4o-mini, api_key: your-api-key } }, # 可选指定哪些域名直接返回 Markdown direct_markdown_hostnames[github.com, docs.python.org] ) # 初始化 MultiModal Reader multimodal_reader MultiModalStructMemReader(multimodal_config)示例 1处理包含图片的对话scene_with_image [[ { role: user, content: [ {type: text, text: 这是我家的花园}, {type: image_url, image_url: {url: https://example.com/garden.jpg}} ] }, { role: assistant, content: 你的花园很漂亮 } ]] memories multimodal_reader.get_memory( scene_with_image, typechat, info{user_id: 1234, session_id: session_001} ) for m_list in memories: tree_memory.add(m_list) print(f✓ 已添加 {len(memories)} 条多模态记忆)示例 2处理网页 URLscene_with_url [[ { role: user, content: 请分析这篇文章: https://example.com/article.html }, { role: assistant, content: 我会帮你分析这篇文章 } ]] url_memories multimodal_reader.get_memory( scene_with_url, typechat, info{user_id: 1234, session_id: session_002} ) for m_list in url_memories: tree_memory.add(m_list) print(f✓ 已从 URL 提取并添加 {len(url_memories)} 条记忆)示例 3处理本地文件# 支持的文件类型: PDF, DOCX, TXT, Markdown, HTML 等 file_paths [ ./documents/report.pdf, ./documents/notes.md, ./documents/data.txt ] file_memories multimodal_reader.get_memory( file_paths, typedoc, info{user_id: 1234, session_id: session_003} ) for m_list in file_memories: tree_memory.add(m_list) print(f✓ 已从文件提取并添加 {len(file_memories)} 条记忆)示例 4混合模式文本 图片 URLmixed_scene [[ { role: user, content: [ {type: text, text: 这是我的项目文档:}, {type: text, text: https://github.com/user/project/README.md}, {type: image_url, image_url: {url: https://example.com/diagram.png}} ] } ]] mixed_memories multimodal_reader.get_memory( mixed_scene, typechat, info{user_id: 1234, session_id: session_004} ) for m_list in mixed_memories: tree_memory.add(m_list) print(f✓ 已从混合内容提取并添加 {len(mixed_memories)} 条记忆)MultiModal Reader 优势智能路由自动识别内容类型图片/URL/文件并选择合适的解析器格式支持支持 PDF、DOCX、Markdown、HTML、图片等多种格式URL 解析自动提取网页内容包括 GitHub、文档站点等大文件处理自动分块处理超大文件避免 token 超限上下文保持使用滑动窗口保持分块间的上下文连续性。配置提示使用direct_markdown_hostnames参数可以指定哪些域名直接返回 Markdown 格式支持modefast和modefine两种提取模式fine 模式提取更详细可参考 examples/mem_reader 目录下的builders.py、samples.py、settings.py、utils.py等示例工具。搜索记忆同时尝试向量搜索 图搜索results tree_memory.search(Talk about the garden, top_k5) for i, node in enumerate(results): print(f{i}: {node.memory})search方法见 src/memos/memories/textual/tree.py的完整签名比文档 API 表更丰富实际检索流程为User query - TaskGoalParser - MemoryPathResolver - GraphMemoryRetriever - MemoryReranker - MemoryReasoner - Final output其关键参数包括modefast快速但精度略低或fine调用大模型多阶段检索精度更高但更慢memory_type检索范围限制可选All、WorkingMemory、LongTermMemory、UserMemorymanual_close_internet为True时本次搜索关闭互联网检索优先级高于配置search_filter可选的元数据精确过滤条件例如{user_id: 123, session_id: abc}top_k返回的 top-k 条记忆数量。该链路在 src/memos/memories/textual/tree_text_memory/retrieve/searcher.py 中由TaskGoalParser解析任务目标、GraphMemoryRetriever图 向量混合召回见 recall.py、重排器Reranker默认cosine_local可按background层级加权topic/concept/fact与MemoryReasoner协作完成。若配置了search_strategy还可开启 BM25 关键词召回{bm25: true}、CoT 推理{cot: true}或全文本搜索{fulltext: true}。从互联网检索记忆可选你也可以从 Google / Bing / Bocha博查/ Tavily / Xinyu 等搜索引擎实时获取网页内容并自动切分为记忆节点。MemOS 通过 src/memos/memories/textual/tree_text_memory/retrieve/internet_retriever_factory.py 提供统一工厂接口backend_to_class注册了google、bing、xinyu、bocha、tavily五种后端各后端的配置类定义见 src/memos/configs/internet_retriever.py。以下示例演示如何检索Alibaba 2024 ESG report相关网页并自动提取为结构化记忆# 创建embedder embedder EmbedderFactory.from_config( EmbedderConfigFactory.model_validate({ backend: ollama, config: {model_name_or_path: nomic-embed-text:latest}, }) ) # 配置检索器以 BochaAI 为例 retriever_config InternetRetrieverConfigFactory.model_validate({ backend: bocha, config: { api_key: sk-xxx, # 替换为你的 BochaAI API Key max_results: 5, reader: { # 自动分块的 Reader 配置 backend: simple_struct, config: ..., # 你的mem-reader config }, } }) # 实例化检索器 retriever InternetRetrieverFactory.from_config(retriever_config, embedder) # 执行网页检索 results retriever.retrieve_from_internet(Alibaba 2024 ESG report) # 添加到记忆图中 for m in results: tree_memory.add(m)你也可以直接在TreeTextMemoryConfig中配置internet_retriever字段{ internet_retriever: { backend: bocha, config: { api_key: sk-xxx, max_results: 5, reader: { backend: simple_struct, config: ... } } } }这样在调用tree_memory.search(query)时系统会自动调用互联网检索如 BochaAI / Google / Bing然后将结果与本地图中的节点一起排序返回无需手动调用retriever.retrieve_from_internet。替换工作记忆用一个新节点替换你当前的WorkingMemorytree_memory.replace_working_memory( [{ memory: User is discussing gardening tips., metadata: {memory_type: WorkingMemory} }] )备份与恢复支持树结构的持久化存储与随时重载tree_memory.dump(tmp/tree_memories) tree_memory.load(tmp/tree_memories)dump会调用graph_store.export_graph并将nodes/edges写入dir/memory_filenameload则从该文件读取 JSON 并调用import_graph恢复图。若需要先备份、后清库的完整生命周期管理可使用drop(keep_last_n30)它将图导出到系统临时目录memos_backups/memos_backup_时间戳清理仅保留最近keep_last_n个备份后再执行graph_store.drop_database()实现见 src/memos/memories/textual/tree.py。完整代码示例以下示例整合了上述所有步骤提供一个端到端的完整流程 —— 复制即可运行from memos.configs.embedder import EmbedderConfigFactory from memos.configs.memory import TreeTextMemoryConfig from memos.configs.mem_reader import SimpleStructMemReaderConfig from memos.embedders.factory import EmbedderFactory from memos.mem_reader.simple_struct import SimpleStructMemReader from memos.memories.textual.tree import TreeTextMemory # 嵌入设置 embedder_config EmbedderConfigFactory.model_validate({ backend: ollama, config: {model_name_or_path: nomic-embed-text:latest} }) embedder EmbedderFactory.from_config(embedder_config) # 创建TreeTextMemory tree_config TreeTextMemoryConfig.from_json_file(examples/data/config/tree_config.json) my_tree_textual_memory TreeTextMemory(tree_config) my_tree_textual_memory.delete_all() # 阅读器设置 reader_config SimpleStructMemReaderConfig.from_json_file( examples/data/config/simple_struct_reader_config.json ) reader SimpleStructMemReader(reader_config) # 从对话中抽取 scene_data [[ { role: user, content: Tell me about your childhood. }, { role: assistant, content: I loved playing in the garden with my dog. }, ]] memory reader.get_memory(scene_data, typechat, info{user_id: 1234, session_id: 2222}) for m_list in memory: my_tree_textual_memory.add(m_list) # 搜索 results my_tree_textual_memory.search( Talk about the users childhood story?, top_k10 ) for i, r in enumerate(results): print(f{i}th result: {r.memory}) # 从文档添加[可选项] doc_paths [./text1.txt, ./text2.txt] doc_memory reader.get_memory( doc_paths, doc, info{ user_id: your_user_id, session_id: your_session_id, } ) for m_list in doc_memory: my_tree_textual_memory.add(m_list) # 转储和丢弃[可选项] my_tree_textual_memory.dump(tmp/my_tree_textual_memory) my_tree_textual_memory.drop()更贴近真实场景的完整脚本可参考仓库中的 examples/core_memories/tree_textual_memory.py它演示了多轮长对话抽取、modefine精细检索、get_relevant_subgraph子图提取、get_current_memory_size容量查看以及memory_manager.wait_reorganizer()等待异步重组完成等进阶用法。深入源码TreeTextMemory 的组织与检索原理记忆组织MemoryManager 与图重组TreeTextMemory.add()委托给MemoryManager.add()见 src/memos/memories/textual/tree_text_memory/organize/manager.py。MemoryManager维护WorkingMemory、LongTermMemory、UserMemory、RawFileMemory四类桶的容量计数支持sync/async两种模式sync模式下添加后会立即执行_cleanup_working_memory清理临时工作记忆同时通过GraphStructureReorganizer实现图结构重组reorganizetrue时启用可在threshold默认 0.80与merged_threshold默认 0.92等相似度阈值下自动合并重复节点、建立交叉链接。混合检索向量 图遍历 重排GraphMemoryRetrieverrecall.py是混合检索的核心它对TaskGoalParser解析出的检索范围分别执行图路径查找与查询向量相似度搜索将两者结果合并后统一返回filter_weight等参数用于平衡过滤条件的权重。随后Searchersearcher.py调用重排器对候选记忆精排最后由MemoryReasoner结合 query 与记忆做答案合成判断。AdvancedSearcheradvanced_searcher.py进一步支持多阶段thinking_stages3检索扩展在当前记忆不足时由 LLM 生成新的检索短语继续召回直到可以作答。为什么选择 TreeTextMemory结构层次像思维导图一样组织记忆 —— 节点可以有父母、孩子和交叉链接图风格链接超越纯层次结构建立多跳推理链语义搜索 图扩展结合向量和图的优点可解释性追踪记忆是如何连接、合并或随时间演变的history、version、evolve_to字段记录了完整演化轨迹。尝试一下从文档或 web 内容中添加记忆节点手动链接它们或开启reorganize让系统自动合并相似节点下一步了解更多 Neo4jTreeTextMemory 由图数据库后端提供支持了解 Neo4j 图数据库文档 中节点、边和遍历的处理方式将帮助你设计更有效的记忆层次结构、多跳推理和上下文链接策略添加 Activation MemoryKV Cache使用运行时 KV-cache 来测试会话状态参见 kv_cache_memory.md探索图推理为多跳检索和答案合成构建工作流更进一步运行 examples 目录下的更多示例或结合general_textual_memory.md文档、preference_textual_memory.md文档了解其他记忆形态的取舍。现在你的 Agent 不仅能记住事实还能记住它们之间的联系赞分享人工智能大模型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点击查看免费下载相关推荐Wand-Enhancer 完整教程一次本地补丁解锁 Pro 功能、手机远程面板与脚本注入Wand Enhancer 完整教程一次本地补丁解锁 Pro 功能、手机远程面板与脚本注入 Wand Enhancer 是一款免费开源的本地补丁工具它对 W人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-pluginMemOS 创建你的第一个记忆用 SimpleStructMemReader 提取、TreeTextMemory 存储与检索的完整实战MemOS 创建你的第一个记忆用 SimpleStructMemReader 提取、TreeTextMemory 存储与检索的完整实战 导读 本文是 MemO人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-pluginMemOS 记忆结构设计最佳实践四种明文记忆选型与容量规划实战MemOS 记忆结构设计最佳实践四种明文记忆选型与容量规划实战 导读 本文面向在 MemOS面向 LLM 与 AI Agent 的自进化记忆操作系统中构建人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考