MemOS 是什么 · 全景与阅读地图

30 秒导读： MemOS（Memory Operating System）是一套面向 LLM 和 Agent 的"记忆操作系统"。它把"给大模型加长期记忆"这件事，统一成一组 add / search / chat 的 API：你把对话或文档丢进去，它抽取成结构化记忆、落进图谱、需要时检索出来拼回 prompt——让模型跨会话记住你是谁、你说过什么、你偏好什么。

1. 这是什么（零基础也能懂）

一句话定义。 MemOS 是一个长期记忆的中间层：坐在你的应用和 LLM 之间，负责把记忆的存（store）、取（retrieve）、管（manage） 收敛成一套统一 API。

README 开头把它定位成 Memory Operating System for LLMs and AI agents，强调"unifies store / retrieve / manage for long-term memory"（README.md:58-60）。

它解决什么问题。 裸的 LLM 是"失忆"的——一旦超出上下文窗口，之前的对话就丢了。业界常见做法是把历史塞进一个黑盒向量库，检索时算相似度捞回来。MemOS 想做得更进一步：

记忆不是黑盒 embedding，而是可检查、可编辑的图结构（README.md:65 Unified Memory API）。
支持多模态记忆：文本、图片、工具调用轨迹、人物画像（README.md:66 Multi-Modal Memory）。
多个知识库当成可组合的记忆立方（MemCube），在用户/项目/Agent 之间隔离与共享（README.md:67）。
摄取走异步调度（MemScheduler），高并发下也稳（README.md:68）。

给谁用。 给要做"有记忆的 Agent / 个性化对话 / 企业知识库"的工程师。它的 PyPI 包名叫 MemoryOS，slogan 是 Intelligence Begins with Memory（pyproject.toml:6-8）；对外暴露命令行入口 memos（pyproject.toml:62-63）和一个 REST 服务。

一句话直觉/类比。 把它当操作系统的内存管理器来想：上下文窗口 = 有限的"内存条"，MemOS 管的图数据库 = 大容量"磁盘"；它负责在两者之间换页——需要哪段记忆，就把哪段"调度进"当前 prompt。这个类比正是项目取名 "OS" 的由来。

本节只讲"是什么"，不碰实现。想直接看代码怎么组织，从 §2 开始。

2. 顶层全景（一条记忆怎么流动）

理解 MemOS 的最快路径，是跟着一条记忆走完一整趟：从一句对话进来，到最终影响模型回答。

2.1 端到端主线（怎么读这张图）

从左到右是一条记忆的生命周期；上半行是写入路径（add），下半行是读取路径（chat/search）。异步的部分由 MemScheduler 在后台接手。

                     ┌─────────────────────────────────────────────┐
   写入 add ─────►   │ ① MemReader 抽取                             │
  (messages/docs)    │   把原始对话/文档 → 结构化记忆条目            │
                     └───────────────────┬─────────────────────────┘
                                         ▼
                     ┌─────────────────────────────────────────────┐
                     │ ② 图谱组织并落库                             │
                     │   TreeTextMemory 去重/连边 → Neo4j 图数据库  │
                     └───────────────────┬─────────────────────────┘
                                         ▼   （磁盘：长期记忆）
   ─────────────────────────────────────────────────────────────────
                                         ▲
   读取 chat ────►  ┌────────────────────┴─────────────────────────┐
    (query)         │ ③ 检索召回 search                            │
                    │   向量/全文命中 → 取子图 → 重排               │
                    └───────────────────┬─────────────────────────┘
                                        ▼
                    ┌─────────────────────────────────────────────┐
                    │ ④ 拼进 prompt → LLM 生成回答                 │
                    │   _build_system_prompt(memories) → chat_llm  │
                    └─────────────────────────────────────────────┘

   后台：MemScheduler（异步）——async 模式下 ①②由它在队列里跑，
        并负责激活记忆(KV-cache)刷新，不阻塞主请求。

这条主线对应的真实入口：

写入：MOSCore.add() 判断 backend 是 tree_text 时，先 self.mem_reader.get_memory(...) 抽取，再 text_mem.add(memories_flatten) 落库（core.py:759-766）。
组织落库：TreeTextMemory.add() 把条目写进 self.graph_store（一个 Neo4jGraphDB）（tree.py:56、tree.py:103）。
读取：MOSCore.search() 调 cube.text_mem.search(query, mode=...)（core.py:618）；TreeTextMemory.search() 走向量/全文 + 取子图（tree.py:157、tree.py:272-314）。
拼 prompt 生成：MOSCore.chat() 搜到记忆后 _build_system_prompt(memories_all)，再 self.chat_llm.generate(...)（core.py:303、core.py:330-332）。

2.2 顶层模块职责表

MemOS 的代码全部在 src/memos/ 下。这张表是"谁负责哪一段主线"的总索引：

顶层模块	干什么	对应主线	关键符号 / 文件
`mem_os/`	内核。对外的 `MOS` / `MOSCore`，管 add/search/chat、用户与 cube 权限	全程编排	`MOSCore` (mem_os/core.py:38)、`MOS` (mem_os/main.py:24)
`mem_cube/`	记忆容器 MemCube：一个 cube 里装四种记忆槽位	承载①②③	`GeneralMemCube` (mem_cube/general.py:21)
`memories/`	记忆的三大形态实现：明文/激活/参数	②落库、③召回	`textual/` `activation/` `parametric/`
`mem_reader/`	抽取器：把 messages/文档读成结构化记忆条目	①抽取	`SimpleStructMemReader` (mem_reader/simple_struct.py:167)
`mem_scheduler/`	异步调度：队列消费、后台摄取、激活记忆刷新	后台	`GeneralScheduler` (mem_scheduler/general_scheduler.py:16)
`graph_dbs/`	图数据库适配层：Neo4j / PolarDB / Postgres	②③的存储后端	`Neo4jGraphDB` (graph_dbs/neo4j.py)、`GraphStoreFactory`
`api/`	REST/MCP 服务层，暴露 `/product/*` 端点	对外接口	前缀 `/product` (api/routers/server_router.py:68)

注：MemCube 有四个槽位 text_mem / act_mem / para_mem / pref_mem（mem_cube/general.py:28-46）。"三类记忆形态"指明文(textual)、激活(activation)、参数(parametric)三大类；偏好记忆 pref_mem 是明文记忆的一个变体槽位。详见 01 章。

3. 核心心智模型（记住这四个词）

看懂 MemOS 的源码，只要先把四个概念立起来。它们两两对应"容器 / 内容 / 内核 / 后台"。

3.1 MemCube = 记忆容器

MemCube 是装记忆的盒子。一个 cube 内部并排放着四种记忆槽位，每个槽位可独立启用或留空（uninitialized 时就是 None）：

槽位	属性	装什么
`text_mem`	`_text_mem`	明文记忆（对话/文档抽取出的事实，图谱组织）
`act_mem`	`_act_mem`	激活记忆（KV-cache，加速生成）
`para_mem`	`_para_mem`	参数记忆（LoRA 等权重形态）
`pref_mem`	`_pref_mem`	偏好记忆（用户偏好，明文变体）

四个槽位由 MemoryFactory.from_config(...) 按配置实例化（mem_cube/general.py:28-46）；dump/load 也是按这四类分别落盘（mem_cube/general.py:74-88）。多个 cube 之间可隔离、可共享，这就是 README 说的 "Multi-Cube KB"。

3.2 三类记忆形态

MemOS 的一个核心观点：记忆不只有"明文"一种形态。memories/ 下并列三大类实现：

明文记忆（textual） —— 最主线的一类，抽取成图谱、可读可编辑（memories/textual/tree.py）。
激活记忆（activation） —— 存成 KV-cache，直接喂给模型的注意力缓存（memories/activation/kv.py）。
参数记忆（parametric） —— 存成 LoRA 之类的权重（memories/parametric/lora.py）。

这三者的取舍与 MemCube 的关系，在 01 章展开。

3.3 MOSCore = 内核

MOSCore 是"记忆操作系统"的内核：管着一堆已注册的 MemCube、用户权限（user_manager）、聊天历史，对外提供 add / search / get / update / delete / chat 全套操作（mem_os/core.py:38 起，方法见 core.py:251/546/684 等）。

对外类 MOS 只是 MOSCore 的向后兼容外壳，额外加了 CoT（思维链）分解增强，并提供最简入口 MOS.simple()（mem_os/main.py:24、mem_os/main.py:80）。

3.4 MemScheduler = 异步后台

GeneralScheduler 是跑在后台的调度器（mem_scheduler/general_scheduler.py:16）。当记忆以 async 模式写入时，主请求只往调度器提交一条消息（submit_messages）就立即返回，真正的抽取/落库在后台队列里消费（core.py:734-794）。它基于 Redis 队列 + dispatcher 分发（mem_scheduler/base_scheduler.py:41-149），这样高并发下 add 不会卡住用户。详见 06 章。

4. 最小使用示例（用起来什么样）

MemOS 有两种典型用法：REST 服务（生产部署）和 Python 直连（快速上手）。

4.1 REST：/product/add 与 /product/search

部署后（Docker 或 uvicorn），最基础的两步是"写一条记忆"和"查一条记忆"。下面是 README 给的最小示例（README.md:223-263）：

import requests, json

# ① 写入一条用户记忆
add_data = {
    "user_id": "8736b16e-1d20-4163-980b-a5063c3facdc",
    "mem_cube_id": "b32d0977-435d-4828-a86f-4f47f8b55bca",
    "messages": [{"role": "user", "content": "I like strawberry"}],
    "async_mode": "sync",
}
requests.post("http://localhost:8000/product/add",
              headers={"Content-Type": "application/json"},
              data=json.dumps(add_data))

# ② 检索："我喜欢什么"
search_data = {
    "query": "What do I like",
    "user_id": "8736b16e-1d20-4163-980b-a5063c3facdc",
    "mem_cube_id": "b32d0977-435d-4828-a86f-4f47f8b55bca",
}
res = requests.post("http://localhost:8000/product/search",
                    headers={"Content-Type": "application/json"},
                    data=json.dumps(search_data))
print(res.json())

这两个端点在源码里挂在 /product 前缀下：search_memories（server_router.py:111-112）和 add_memories（server_router.py:127-128），同一路由还提供 /product/chat/complete、/product/feedback 等（server_router.py:270、408）。

4.2 Python：MOS.simple() 一行起步

不想起服务，可以直接在 Python 里用内核。MOS.simple() 从环境变量自动配置（读 OPENAI_API_KEY 等），返回一个已注册默认 cube 的实例（mem_os/main.py:80-106）：

from memos import MOS          # src/memos/__init__.py 导出 MOS

memory = MOS.simple()          # 从环境变量自动配置 + 注册默认 cube
memory.add(memory_content="Hello world!")        # 写入一条记忆
response = memory.chat("What did I just say?")    # 检索记忆后回答

simple() 内部就是无参 cls()，走 _auto_configure() 读环境变量、get_default(...) 造配置与默认 cube（mem_os/main.py:57-77）。这是"上手 MemOS 最简单的方式"（该方法 docstring 原话）。

注：MOS.simple() 的 docstring 里写的是 memory.add_memory("...")（mem_os/main.py:102），但内核里并没有 add_memory 这个方法——真实入口是 MOSCore.add(...)（core.py:684，参数 messages / memory_content / doc_path）与 MOS.chat(...)（main.py:108）。上面示例用的是真实方法名。

5. 阅读地图（建议顺序）

本套文档把 MemOS 拆成七章，由浅入深。建议按下面顺序读；每章边界互不重叠：

顺序	章节	讲什么	什么时候读
0	index.md（本章）	顶层导览 + 心智模型 + 阅读地图	先读，建立全局观
1	01-memory-types-and-memcube.md	三类记忆形态 + MemCube 容器如何组织它们	想懂"记忆长什么样"先读这章
2	02-mos-core-kernel.md	MOSCore 内核：add/search/chat 主循环、用户与 cube 权限校验	想读主流程代码从这里进
3	03-mem-reader-extraction.md	MemReader 如何把对话/文档抽成结构化记忆	关心"写入端"抽取逻辑
4	04-tree-graph-organize.md	图谱明文记忆（上）：组织、去重、冲突、重构	关心记忆怎么落进图、怎么维护一致性
5	05-retrieval-pipeline.md	图谱明文记忆（下）：检索召回、重排、推理	关心"读取端"召回质量
6	06-mem-scheduler.md	MemScheduler 异步摄取 + 激活记忆刷新	关心高并发、异步、后台机制

两条推荐路线：

想快速会用 → 读本章 §4 + 02 章的 add/search/chat 三个方法即可。
想读懂原理 → 按 0→1→2→3→4→5→6 顺序全程走一遍。

6. 全局代码地图（导航索引）

想直接跳进源码时，从这张表按符号名 grep 定位（比行号抗漂移）。所有路径相对克隆根 aiRef/repos/memos/。

主题	文件路径	符号名
包版本与对外导出	`src/memos/__init__.py`	`__version__`、`MOS`、`GeneralMemCube`
最简入口 / 兼容外壳	`src/memos/mem_os/main.py`	`MOS`、`MOS.simple`、`MOS.cot_decompose`
内核（主循环）	`src/memos/mem_os/core.py`	`MOSCore`、`MOSCore.add`、`MOSCore.search`、`MOSCore.chat`
记忆容器	`src/memos/mem_cube/general.py`	`GeneralMemCube`
明文/图谱记忆	`src/memos/memories/textual/tree.py`	`TreeTextMemory`、`TreeTextMemory.add`、`TreeTextMemory.search`
激活记忆（KV-cache）	`src/memos/memories/activation/kv.py`	（见 01 章）
参数记忆（LoRA）	`src/memos/memories/parametric/lora.py`	（见 01 章）
抽取器	`src/memos/mem_reader/simple_struct.py`	`SimpleStructMemReader`、`get_memory`
异步调度	`src/memos/mem_scheduler/general_scheduler.py`	`GeneralScheduler`
图数据库适配	`src/memos/graph_dbs/neo4j.py`、`src/memos/graph_dbs/factory.py`	`Neo4jGraphDB`、`GraphStoreFactory`
REST 服务路由	`src/memos/api/routers/server_router.py`	`add_memories`、`search_memories`（前缀 `/product`）
CLI 入口	`src/memos/cli.py`	`main`（`pyproject.toml:62` `memos = "memos.cli:main"`）

本章边界： 本章只做 Layer 0（是什么）+ Layer 1（顶层全景）+ 阅读地图，不深入任何单一子系统的实现。四种记忆槽位的内部机制看 01 章；add/search/chat 的逐行走读看 02 章；抽取/组织/检索/调度分别在 03–06 章展开。需要交叉引用时用相对链接跳转，避免重复。

1. 这是什么（零基础也能懂）​

2. 顶层全景（一条记忆怎么流动）​

2.1 端到端主线（怎么读这张图）​

2.2 顶层模块职责表​

3. 核心心智模型（记住这四个词）​

3.1 MemCube = 记忆容器​

3.2 三类记忆形态​

3.3 MOSCore = 内核​

3.4 MemScheduler = 异步后台​

4. 最小使用示例（用起来什么样）​

4.1 REST：/product/add 与 /product/search​

4.2 Python：MOS.simple() 一行起步​

5. 阅读地图（建议顺序）​

6. 全局代码地图（导航索引）​