Mem0 记忆系统架构详解

发表于 分类于 Waline：
深入解析 Mem0 v1.0.11 记忆系统的完整架构，包括核心数据结构、增删查改流程、图存储集成及设计优势。

一、系统架构总览

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
┌─────────────────────────────────────────────────────────────┐
│                    Memory 类                        │
│  ┌──────────────────────────────────────────┐   │
│  │ 1. 配置层         │                       │
│  │ - Memory (用户/会话/智能体配置)         │
│  │ - LLM/Embedder/VectorStore/Graph      │
│  └──────────────────────────────────────────┘   │
│                                                     │
│  ┌──────────────────────────────────────────┐   │
│  │ 2. 接口层         │                       │
│  │ - add() / search() / update() / delete()│
│  │ - get() / get_all() / history() / reset()│
│  └──────────────────────────────────────────┘   │
│                                                     │
│  ┌──────────────────────────────────────────┐   │
│  │ 3. 核心处理层     │                       │
│  │ - _add_to_vector_store (智能推理)          │
│  │ - _search_vector_store (向量检索)          │
│  │ - _create_memory / _update_memory / _delete_memory│
│  └──────────────────────────────────────────┘   │
│                                                     │
│  ┌──────────────────────────────────────────┐   │
│  │ 4. 存储层         │                       │
│  │ ┌─ 向量存储 ───┐ ┌─ 图存储 ───┐│
│  │ │ │Qdrant/Pinecone/... │ │ │Neo4j/Memgraph││
│  │ └───────────────────┘ └───────────────────┘│
│  └──────────────────────────────────────────┘   │
│                                                     │
│  ┌──────────────────────────────────────────┐   │
│  │ 5. 历史追踪层 │                       │
│  │ - SQLiteManager.history 表                  │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

二、核心数据结构

2.1 记忆项

存储位置：向量数据库（Qdrant/Pinecone/Chroma等）

数据结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 代码位置：mem0/configs/base.py
class MemoryItem(BaseModel):
    id: str                    # UUID，主键
    memory: str               # 记忆内容文本
    hash: str                 # MD5(content)，用于去重
    created_at: str           # 创建时间（ISO 8601）
    updated_at: str           # 最后更新时间（ISO 8601）
    user_id: str              # 用户标识（会话隔离）
    agent_id: str             # 智能体标识（多智能体共享）
    run_id: str               # 运行标识（单次任务隔离）
    actor_id: str             # 执行者名称（谁创建/修改）
    role: str                 # user/assistant/system（消息来源）
    metadata: dict             # 扩展字段（自定义数据）

存储方式：

1
2
3
4
5
6
7
8
9
10
11
# 代码位置：mem0/memory/main.py:1223-1253
def _create_memory(...):
    # 1. 生成嵌入向量
    embeddings = self.embedding_model.embed(data, memory_action="add")

    # 2. 存储到向量数据库
    self.vector_store.insert(
        vectors=[embeddings],
        ids=[memory_id],
        payloads=[new_metadata],  # 包含 memory, hash, created_at 等
    )

2.2 历史记录

存储位置：SQLite 数据库（memory/history.db）

数据结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 代码位置：mem0/memory/storage.py:100-125
# SQLite 表结构
CREATE TABLE history (
    id              TEXT PRIMARY KEY,        # 历史记录ID（独立UUID）
    memory_id       TEXT,                 # 关联的记忆项ID
    old_memory      TEXT,                 # 操作前的值
    new_memory      TEXT,                 # 操作后的值（或None）
    event           TEXT,                 # 事件类型：ADD/UPDATE/DELETE/NONE
    created_at      DATETIME,              # 创建时间
    updated_at      DATETIME,              # 更新时间
    is_deleted      INTEGER,               # 标记是否已删除（0/1）
    actor_id       TEXT,                 # 执行者ID
    role           TEXT                  # 消息角色
)

存储方式：

1
2
3
4
5
6
7
8
9
10
11
12
# 代码位置：mem0/memory/main.py:1245-1254
# 每次记忆操作都记录历史
self.db.add_history(
    memory_id,           # 关联到记忆项ID
    old_memory,          # DELETE时=旧值，ADD时=None
    new_memory,          # ADD/UPDATE时=新值，DELETE时=None
    event,               # "ADD" / "UPDATE" / "DELETE"
    created_at,          # 创建时间
    updated_at,          # 更新时间
    actor_id,            # 执行者
    role,                # user/assistant
)

2.3 图三元组

1
2
3
4
5
6
# 代码位置：mem0/graphs/utils.py
{
    "source": "john",           # 实体1
    "relationship": "works_at",   # 关系
    "destination": "openai",        # 实体2
}

三、增加完整流程

3.1 入口函数

代码位置：mem0/memory/main.py:380-483

1
2
3
4
5
6
7
8
9
10
11
12
def add(
    self,
    messages,
    *,
    user_id: Optional[str] = None,
    agent_id: Optional[str] = None,
    run_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    infer: bool = True,                    # 关键参数！
    memory_type: Optional[str] = None,
    prompt: Optional[str] = None,
):

3.2 完整流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
用户调用：memory.add("我是John，是软件工程师", user_id="user123")
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 1. 参数验证与格式化         │
        │ - 检查 messages 类型               │
        │ - 构建元数据                       │
        │ - 处理特殊类型（过程性记忆）        │
        │ - 解析视觉消息                    │
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 2. 分支：推理模式 vs 直接模式   │
        │                                    │
        │ ┌───── infer=True ───┐       │
        │ │ 智能记忆管理       │       │
        │ │ - LLM提取事实      │       │
        │ │ - 向量检索相似     │       │
        │ │ - LLM判断操作类型  │       │
        │ │ - 执行 ADD/UPDATE/DELETE │       │
        │ └───────────────────────┘       │
        │                                    │
        │ ┌───── infer=False ───┐       │
        │ │ 直接存储模式       │       │
        │ │ - 跳过所有LLM调用  │       │
        │ │ - 直接写入向量存储  │       │
        │ └───────────────────────┘       │
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 3. 双轨并行处理              │
        │ ┌─ 线程1：向量存储 ─────────┐       │
        │ │ _add_to_vector_store()  │       │
        │ └───────────────────────┘       │
        │ ┌─ 线程2：图存储 ────┐       │
        │ │ _add_to_graph()            │       │
        │ └───────────────────────┘       │
        └──────────────────────────────────────┘
                            │
                            ▼
                     返回结果

3.3 infer=True 的详细流程

代码位置：mem0/memory/main.py:485-680

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
def _add_to_vector_store(self, messages, metadata, filters, infer=True):
    """
    智能推理模式：自动判断 ADD/UPDATE/DELETE
    """

    # ─────────────────────────────────────────────────────
    # 步骤1：LLM提取新事实
    # ─────────────────────────────────────────────────────
    system_prompt, user_prompt = get_fact_retrieval_messages(...)

    # 检查是否使用智能体记忆提取
    is_agent_memory = self._should_use_agent_memory_extraction(messages, metadata)

    response = self.llm.generate_response(
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_prompt},
        ],
        response_format={"type": "json_object"},
    )

    # 解析LLM返回
    new_retrieved_facts = json.loads(response)["facts"]
    # 示例: ["名字是John", "是软件工程师"]

    # ─────────────────────────────────────────────────────
    # 步骤2：检索现有相似记忆
    # ─────────────────────────────────────────────────────
    for new_mem in new_retrieved_facts:
        # 缓存嵌入避免重复API调用
        messages_embeddings[new_mem] = self.embedding_model.embed(new_mem, "add")

        # 向量相似度度搜索
        existing_memories = self.vector_store.search.search(
            query=new_mem,
            vectors=messages_embeddings,
            top_k=5,                  # 取最相似的5条
            filters=search_filters,
        )

        # 收集现有记忆
        for mem in existing_memories:
            retrieved_old_memory.append({
                "id": mem.id,
                "text": mem.payload.get("data", "")
            })

    # ─────────────────────────────────────────────────────
    # 步骤3：LLM判断操作类型（关键！）
    # ─────────────────────────────────────────────────────
    function_calling_prompt = get_update_memory_messages(
        retrieved_old_memory,   # 旧记忆列表
        new_retrieved_facts,    # 新事实列表
        self.config.custom_update_memory_prompt
    )

    response: str = self.llm.generate_response(
        messages=[{"role": "user", "content": function_calling_prompt}],
        response_format={"type": "json_object"},
    )

    # LLM返回的操作序列
    # 示例：
    # {
    #   "memory": [
    #     {"id": "0", "text": "名字是JohnJohn", "event": "NONE"},  # 已存在
    #     {"id": "1", "text": "是软件工程师", "event": "ADD"},  # 新增
    #     {"id": "2", "text": "爱吃披萨", "event": "DELETE"},  # 冲突删除
    #     {"id": "3", "text": "喜欢芝士", "event": "UPDATE", "old_memory": "爱吃芝士和芝士"}
    #   ]
    # }

    # ─────────────────────────────────────────────────────
    # 步骤4：执行LLM返回的操作
    # ─────────────────────────────────────────────────────
    for resp in new_memories_with_actions.get("memory", []):
        event_type = resp.get("event")

        if event_type == "ADD":
            # 添加新记忆
            memory_id = self._create_memory(
                data=resp["text"],
                existing_embeddings=new_message_embeddings,
                metadata=deepcopy(metadata),
            )

        elif event_type == "UPDATE":
            # 更新现有记忆
            memory_id = _resolve_mapped_id(temp_uuid_mapping, resp, "UPDATE")
            self._update_memory(
                memory_id=memory_id,
                data=resp["text"],
                existing_embeddings=new_message_embeddings,
                metadata=deepcopy(metadata),
            )

        elif event_type == "DELETE":
            # 删除冲突记忆
            memory_id = _resolve_mapped_id(temp_uuid_mapping, resp, "DELETE")
            self._delete_memory(memory_id=memory_id)

3.4 infer=False 的详细流程

代码位置：mem0/memory/main.py:486-521

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
def _add_to_vector_store(self, messages, metadata, filters, infer=False):
    """
    直接存储模式：跳过所有LLM推理
    """

    for message_dict in messages:messages:
        if message_dict.get("role") == "system":
            continue

        msg_content = message_dict.get("content")

        # 直接获取嵌入
        msg_embeddings = self.embedding_model.embed(msg_content, "add")

        # 直接创建记忆，不做任何判断
        mem_id = self._create_memory(
            data=msg_content,
            existing_embeddings={msg_content: msg_embeddings},
            metadata=per_msg_meta,
        )

四、DELETE 触发机制详解

4.1 DELETE 的判断逻辑

代码位置：mem0/configs/prompts.py:263-292

1
2
3
4
5
6
7
8
9
10
11
12
13
14
DEFAULT_UPDATE_MEMORY_PROMPT = """
You are a smart memory manager which controls memory of a system.
You can perform four operations: (1) add into memory, (2) update memory,
(3) delete from memory, and (4) no change.

3. **Delete**: If retrieved facts contain information that **contradicts**
   information present in memory, then you have to delete it.

   示例：
   - 旧记忆: [{"text" : "Loves cheese pizza"}]
   - 新事实: ["Dislikes cheese pizza"]
   - 判断: 冲突！
   - 操作: {"event" : "DELETE"}
"""

4.2 DELETE 的实际场景

场景描述旧记忆新输入LLM判断
事实纠正“住在北京”“其实我住在上海”DELETE旧 + ADD新
偏好反转“喜欢吃披萨”“现在不喜欢吃披萨了”DELETE旧 + ADD新
信息过时“电话是123456”“电话变了，是789012”DELETE旧 + ADD新
矛盾陈述“已婚”“我离婚了”DELETE旧 + ADD新

五、查询完整流程

5.1 入口函数

代码位置：mem0/memory/main.py:883-950

1
2
3
4
5
6
7
8
9
10
11
12
def search(
    self,
    query: str,
    *,
    user_id: Optional[str] = None,
    agent_id: Optional[str] = None,
    run_id: Optional[str] = None,
    top_k: int = 100,
    filters: Optional[Dict[str, Any]] = None,
    threshold: Optional[float] = None,
    rerank: bool = True,
):

5.2 查询流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
用户调用：memory.search("我的职业是什么？", user_id="user123")
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 1. 构建过滤器              │
        │ - 用户ID/智能体ID/运行ID       │
        │ - 处理高级操作符                   │
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 2. 向量嵌入                │
        │ embeddings = embed(query)     │
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 3. 向量相似度检索            │
        │ results = vector_store.search(  │
        │     query=query,              │
        │     vectors=embeddings,      │
        │     top_k=top_k,           │
        │     filters=filters          │
        │ )                             │
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 4. 重排序（可选）              │
        │ - BM25重排序                    │
        │ - 交叉编码器重排序              │
        └──────────────────────────────────────┘
                            │
                            ▼
                     返回带相似度分数的结果

5.3 高级过滤器支持

代码位置：mem0/memory/main.py:934-1050

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 支持的操作符
{
    "eq": "等于",          # {"key": "value"}
    "ne": "不等于",        # {"key": {"ne": "value"}}
    "gt": "大于",          # {"key": {"gt": 10}}
    "gte": "大于等于",     # {"key": {"gte": 10}}
    "lt": "小于",          # {"key": {"lt": 10}}
    "lte": "小于等于",     # {"key": {"lte": 10}}
    "in": "在列表中",      # {"key": {"in": ["a", "b"]}}
    "nin": "不在列表中",     # {"key": {"nin": ["a", "b"]}}
    "contains": "包含",      # {"key": {"contains": "text"}}
    "AND": "逻辑与",        # {"AND": [condition1, condition2]}
    "OR": "逻辑或",         # {"OR": [condition1, condition2]}
    "NOT": "逻辑非",        # {"NOT": [condition]}
    "*": "通配符"         # {"key": "*"}
}

六、修改完整流程

6.1 入口函数

代码位置：mem0/memory/main.py:1188-1260

1
2
3
4
5
6
7
def update(
    self,
    memory_id: str,
    data: str,
    *,
    metadata: Optional[Dict[str, Any]] = None,
):

6.2 修改流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
用户调用：memory.update(memory_id="abc123", data="更新后的内容")
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 1. 验证记忆存在              │
        │ existing = vector_store.get(memory_id)│
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 2. 准备新嵌入              │
        │ new_embeddings = embed(data)     │
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 3. 更新向量存储              │
        │ vector_store.update(           │
        │     id=memory_id,              │
        │     vector=new_embeddings,      │
        │     payload=new_metadata       │
        │ )                             │
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 4. 记录历史                │
        │ db.add_history(               │
        │     memory_id=memory_id,        │
        │     old_memory=old_value,      │
        │     new_memory=data,            │
        │     event="UPDATE"              │
        │ )                             │
        └──────────────────────────────────────┘
                            │
                            ▼
                     返回成功消息

七、删除完整流程

7.1 入口函数

代码位置：mem0/memory/main.py:1262-1290

1
def delete(self, memory_id: str):

7.2 删除流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
用户调用：memory.delete(memory_id="abc123")
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 1. 从向量存储获取获取              │
        │ existing = vector_store.get(memory_id)│
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 2. 从向量存储删除              │
        │ vector_store.delete(id=memory_id)   │
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 3. 清理图存储（如果启用）    │
        │ if self.graph:                     │
        │     graph.delete(data, filters)      │
        └──────────────────────────────────────┘
                            │
                            ▼
        ┌──────────────────────────────────────┐
        │ 4. 记录删除历史              │
        │ db.add_history(                   │
        │     memory_id=memory_id,           │
        │     old_memory=existing.payload,     │
        │     new_memory=None,                │
        │     event="DELETE"                │
        │     is_deleted=1                    │
        │ )                                  │
        └──────────────────────────────────────┘
                            │
                            ▼
                     返回记忆ID

八、图存储集成流程

8.1 图存储并行处理

代码位置：mem0/memory/main.py:468-483

1
2
3
4
5
6
7
8
9
# 在 add() 函数中，向量存储和图存储并行执行
with concurrent.futures.ThreadPoolExecutor() as executor:
    future1 = executor.submit(self._add_to_vector_store, messages, metadata, filters, infer)
    future2 = executor.submit(self._add_to_graph, messages, filters)

    concurrent.futures.wait([future1, future2])

    vector_store_result = future1.result()
    graph_result = future2.result()

8.2 图实体提取

代码位置：mem0/memory/graph_memory.py:219-250

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
def _retrieve_nodes_from_data(self, data, filters):
    """提取实体并分类"""

    _tools = [EXTRACT_ENTITIES_TOOL]
    search_results = self.llm.generate_response(
        messages=[
            {
                "role": "system",
                "content": "Extract all entities from text"
            },
            {"role": "user", "content": data},
        ],
        tools=_tools,
    )

    # 返回实体类型映射
    # 示例：{"john": "person", "openai": "company"}
    entity_type_map = {...}

8.3 图关系提取

代码位置：mem0/memory/graph_memory.py:252-292

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
def _establish_nodes_relations_from_data(self, data, filters, entity_type_map):
    """建立实体间的关系"""

    extracted_entities = self.llm.generate_response(
        messages=[
            {
                "role": "system",
                "content": "Extract relationships between entities"
            },
            {"role": "user", "content": data},
        ],
        tools=[RELATIONS_TOOL],
    )

    # 返回关系列表
    # 示例：[
    #     {"source": "john", "relationship": "works_at", "destination": "openai"}
    # ]

8.4 图搜索增强

代码位置：mem0/memory/graph_memory.py:96-130

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
def search(self, query, filters, top_k=100):
    search_results = []
    # 1. 从查询中提取实体
    entity_type_map = self._retrieve_nodes_from_data(query, filters)
    # 示例：{"john": "person", "sarah": "person"}

    # 2. 在图中搜索相关节点和关系
    search results = self._search_graph_db(
        node_list=list(entity_type_map.keys()),
        filters=filters
    )
    # 示例：返回John相关的所有关系

    # 3. BM25重排序（结合词频和向量）
    bm25 = BM25Okapi(search_outputs_sequence)
    reranked_results = bm25.get_top_n(tokenized_query, sequence, n=5)

    return search_results

九、完整代码索引

功能代码文件行号范围
Memory类定义mem0/memory/main.py257-330
add() 入口mem0/memory/main.py380-483
_add_to_vector_store()mem0/memory/main.py485-680
_add_to_graph()mem0/memory/graph_memory.py76-94
_create_memory()mem0/memory/main.py1223-1253
_update_memory()mem0/memory/main.py1297-1353
_delete_memory()mem0/memory/main.py1356-1380
search() 入口mem0/memory/main.py883-950
_search_vector_store()mem0/memory/main.py1079-1113
update() 入口mem0/memory/main.py1188-1260
delete() 入口mem0/memory/main.py1262-1290
history()mem0/memory/main.py1392-1414
get()mem0/memory/main.py1416-1462
get_all()mem0/memory/main.py792-834
reset()mem0/memory/main.py1382-1390

十、记忆项 vs 历史记录

10.1 ID关系

1
2
3
4
5
6
7
┌─────────────────────────────────────────────────┐
│                                         │
│  记忆项           ←────  1:N  ←────  历史记录
│  (memory_id)      (同一个ID可有多条历史)   │
│                                         │
│  记忆内容（快照）    历史变更链（时间线）       │
└─────────────────────────────────────────────────┘

关键点：

  • 记忆项的ID是历史的外键（memory_id字段）
  • 一个记忆项可以关联多条历史记录
  • 历史记录形成变更链，可追溯完整生命周期

10.2 数据职责对比

维度记忆项历史记录
用途存储当前状态的快照记录所有变更历史
查询方式向量相似度检索按时间线/ID查询
更新方式完整替换追加新记录
删除方式从向量库删除标记is_deleted=1
去重依据hash字段基于event区分
典型数量1条记录/记忆项多条历史/记忆项

10.3 历史记录的实际价值

场景1：审计追踪

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# 代码位置：mem0/memory/main.py:1392-1414
def history(self, memory_id: str):
    return self.db.get_history(memory_id)

# 返回示例
[
    {
        "id": "hist-001",
        "memory_id": "mem-123",           # 关联记忆
        "old_memory": None,                    # ADD操作
        "new_memory": "名字是JohnJohn",
        "event": "ADD",
        "created_at": "2025-04-10T10:00:00Z",
        "actor_id": "user",
        "role": "user"
    },
    {
        "id": "hist-002",
        "memory_id": "mem-123",           # 同一记忆
        "old_memory": "名字是JohnJohn",
        "new_memory": "名字是Mike",          # UPDATE操作
        "event": "UPDATE",
        "created_at": "2025-04-11T14:30:00Z",
        "actor_id": "user",
        "role": "user"
    },
    {
        "id": "hist-003",
        "memory_id": "mem-123",           # 同一记忆
        "old_memory": "名字是Mike",
        "new_memory": None,                  # DELETE操作
        "event": "DELETE",
        "created_at": "2025-04-15T09:00:00Z",
        "actor_id": "ai_agent",
        "role": "assistant",
        "is_deleted": 1                    # 软删除标记
    }
]

场景2：时序分析

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 问题：用户什么时候改变了偏好？
histories = memory.history("mem-123")

# 分析时序
for h in histories:
    print(f"{h['event']}: {h['old_memory']} → {h['new_memory']}")
    print(f"  时间: {h['created_at']}")
    print(f"  执行者: {h['actor_id']}")

# 输出：
# ADD: None → 名字是JohnJohn
#   时间: 2025-04-10T10:00:00Z
#   执行者: user
# UPDATE: 名字是JohnJohn → 名字是Mike
#   时间: 2025-04-11T14:30:00Z
#   执行者: user

10.4 历史记录的额外字段

is_deleted字段的作用：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 代码位置：mem0/memory/storage.py:135-1380
# 删除记忆时特殊标记
self.db.add_history(
    memory_id,
    prev_value,          # 旧值（"喜欢吃披萨"）
    None,                # new_memory为None
    "DELETE",
    created_at,
    updated_at,
    actor_id,
    role,
    is_deleted=1,        # 软删除标记！
)

用途：

  • 区分逻辑删除和物理删除
  • 查询时过滤掉已软删除的记录
  • 支持记忆的软删除模式

十一、设计优势总结

11.1 双存储架构的优势

1
2
3
4
5
6
7
8
9
10
11
12
单一向量存储          双存储架构（向量+图）
├──────────────┐      ├──────────────────────────┐
│ 擅点：              │      │ 优势：              │
│ - 无法理解关系      │      │ - 关系推理              │
│ - 无法扩展上下文    │      │ - 路径遍历              │
│ - 依赖相似度阈值  │      │ - 实体消歧              │
├──────────────┤      ├──────────────────────────┤
│ 适用场景：          │      │ 适用场景：            │
│ - 模糊搜索          │      │ - 社交网络查询          │
│ - 简单事实检索      │      │ - 推荐系统              │
└──────────────┘      │ - 多跳事实关联          │
                       └──────────────────────────┘

11.2 历史记录的价值

价值说明应用场景
可审计性所有变更都有完整记录安全审计、合规要求
可追溯性可还原记忆的完整生命周期调试错误根因分析
时序分析支持时间线查询用户行为分析、趋势检测
软删除支持is_deleted字段标记支持回收站模式

附录：infer 参数详解

参数作用LLM调用次数智能程度
infer=False原始存储0次❌ 无
infer=True智能管理2-3次✅ 有

infer的本质：

  • 不是 “是否需要推理”
  • 而是** “是否让系统自动管理记忆生命周期”**