5.4 · History 与 Audit Trails（History and Audit Trails）

History 与 Audit Trails（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mem0ai/mem0/5.4-history-and-audit-trails

翻译时间：2026-05-27T08:44:59.365Z

翻译模型：deepseek-chat

原文字符数：9953

项目：Mem0 (mem0)

---

历史记录与审计追踪

相关源文件

以下文件用于生成此维基页面：

• mem0-ts/src/oss/src/memory/index.ts
• mem0-ts/src/oss/src/tests/better-sqlite3-migration.test.ts
• mem0-ts/src/oss/src/tests/sqlite-backward-compat.test.ts
• mem0-ts/src/oss/src/utils/entity_extraction.ts
• mem0-ts/src/oss/src/vector_stores/memory.ts
• mem0-ts/src/oss/src/vector_stores/redis.ts
• mem0-ts/src/oss/tests/vector-store.unit.test.ts
• mem0-ts/src/oss/tests/vector-stores-compat.test.ts
• mem0/__init__.py
• mem0/configs/prompts.py
• mem0/memory/main.py
• mem0/memory/storage.py
• mem0/memory/utils.py
• tests/configs/test_prompts.py
• tests/memory/test_main.py
• tests/test_chatty_llm_parsing.py
• tests/test_main.py
• tests/test_memory.py
• tests/test_proxy.py

本文档描述了 Mem0 的历史记录与审计追踪系统，该系统提供了所有内存修改的完整、不可变日志。历史记录系统追踪对内存执行的每一次添加、更新和删除操作，支持审计、调试以及对内存变更的时间维度分析。

关于向量存储后端的详细信息，请参阅向量存储概述。关于生成历史记录的内存操作详情，请参阅内存操作。

目的与架构

历史记录系统通过 mem0/memory/storage.py:11-219 中的 SQLiteManager 类实现，该类维护一个 SQLite 数据库，其中包含所有内存修改的不可变审计追踪。对内存系统的每次写操作（添加、更新、删除）都会自动生成一条对应的历史记录，其中包含变更的完整元数据。

在 TypeScript 实现中，该角色由 HistoryManager 接口及其具体实现（如 SQLiteHistoryManager，通过 HistoryManagerFactory 别名或直接使用）承担 mem0-ts/src/oss/src/memory/index.ts:16-28。

系统数据流

下图将自然语言操作（添加/更新内存）与负责持久化的代码实体关联起来。

graph TB
    subgraph "自然语言空间"
        UserAction["用户提供输入/消息"]
        FactExtraction["大语言模型（LLM）提取事实/偏好"]
    end

    subgraph "代码实体空间"
        MemoryClass["Memory.add() / Memory.update()<br/>(mem0/memory/main.py)"]
        VectorStore["VectorStoreBase 实现<br/>(例如 Qdrant、RedisDB)"]
        SQLiteManager["SQLiteManager<br/>(mem0/memory/storage.py)"]
    end

    subgraph "持久化存储"
        HistoryTable["history 表<br/>(审计追踪)"]
        MessagesTable["messages 表<br/>(对话上下文)"]
    end

    UserAction --> MemoryClass
    MemoryClass --> FactExtraction
    FactExtraction --> VectorStore
    MemoryClass -- "记录变更" --> SQLiteManager
    SQLiteManager -- "插入" --> HistoryTable
    MemoryClass -- "保存上下文" --> SQLiteManager
    SQLiteManager -- "插入" --> MessagesTable

来源： mem0/memory/storage.py:11-219、mem0/memory/main.py:26、mem0-ts/src/oss/src/memory/index.ts:168-175

SQLiteManager 类

SQLiteManager 类提供对历史数据库的线程安全访问。它使用数据库路径进行初始化，并在启动时创建必要的模式 mem0/memory/storage.py:11-19。

初始化与线程安全

SQLiteManager 构造函数接受一个 db_path 参数，默认值为 ":memory:" mem0/memory/storage.py:12-13。它初始化一个 threading.Lock 来处理多线程环境下的并发访问 mem0/memory/storage.py:15。

sequenceDiagram
    participant Memory as Memory 类
    participant SQLM as SQLiteManager
    participant DB as SQLite 引擎

    Memory->>SQLM: __init__(db_path)
    SQLM->>DB: sqlite3.connect(check_same_thread=False)
    Note over SQLM, DB: 获取 threading.Lock()
    SQLM->>SQLM: _migrate_history_table()
    SQLM->>SQLM: _create_history_table()
    SQLM->>SQLM: _create_messages_table()
    Note over SQLM, DB: 释放 threading.Lock()
    SQLM-->>Memory: 实例就绪

所有数据库操作在执行前都会获取 self._lock，以防止多线程环境下的竞态条件 mem0/memory/storage.py:163-187。

来源： mem0/memory/storage.py:12-18, 163-187

模式定义

历史记录表

history 表使用以下模式 mem0/memory/storage.py:108-119：

列名	类型	描述
id	TEXT PRIMARY KEY	历史记录的唯一标识符（UUID）
memory_id	TEXT	被修改的内存 ID
old_memory	TEXT	内存的先前内容（添加操作为 NULL）
new_memory	TEXT	内存的新内容（删除操作为 NULL）
event	TEXT	操作类型："ADD"、"UPDATE"、"DELETE"
created_at	DATETIME	记录创建时间戳
updated_at	DATETIME	记录更新时间戳
is_deleted	INTEGER	标记删除状态的标志（0 或 1）
actor_id	TEXT	执行操作的实体 ID
role	TEXT	执行者的角色（用户/代理/系统）

消息表

messages 表追踪用于事实提取的对话上下文 mem0/memory/storage.py:128-148。

CREATE TABLE IF NOT EXISTS messages (
    id TEXT PRIMARY KEY,
    session_scope TEXT,
    role TEXT,
    content TEXT,
    name TEXT,
    created_at DATETIME
)

来源： mem0/memory/storage.py:108-119, 132-142

时间查询与操作

添加记录

add_history() 方法创建新的审计追踪条目。当内存被添加、更新或删除时，内存操作会调用此方法 mem0/memory/storage.py:150-191。

# 由 main.py 中的 Memory.update() 调用
self.db.add_history(
    memory_id=memory_id,
    old_memory=old_text,
    new_memory=new_text,
    event="UPDATE",
    actor_id=user_id,
    # ...
)

检索历史记录

get_history() 方法检索特定内存的完整历史记录，按时间顺序排列 mem0/memory/storage.py:224-244。

SELECT id, memory_id, old_memory, new_memory, event,
       created_at, updated_at, is_deleted, actor_id, role
FROM history
WHERE memory_id = ?
ORDER BY created_at ASC, DATETIME(updated_at) ASC

来源： mem0/memory/storage.py:150-162, 227-232

迁移系统

SQLiteManager 包含自动模式迁移功能，用于处理升级。_migrate_history_table() 方法检测预先存在的表是否包含旧的"group-chat"列，并将数据迁移到新模式 mem0/memory/storage.py:20-100。

flowchart TD
    Check["PRAGMA table_info(history)"]
    Compare["比较 old_cols 与 expected_cols"]
    Decision{需要迁移？}
    Rename["ALTER TABLE history RENAME TO history_old"]
    Create["CREATE TABLE history (新模式)"]
    Copy["INSERT INTO history SELECT ... FROM history_old"]
    Drop["DROP TABLE history_old"]

    Check --> Compare --> Decision
    Decision -- 是 --> Rename --> Create --> Copy --> Drop
    Decision -- 否 --> End[完成]

来源： mem0/memory/storage.py:20-100

TypeScript（开源版）中的集成

TypeScript SDK 遵循类似的模式，但使用工厂来创建历史记录管理器 mem0-ts/src/oss/src/memory/index.ts:16-28。如果配置中设置了 disableHistory，则使用 DummyHistoryManager 替代标准的 SQLite 后端存储 mem0-ts/src/oss/src/memory/index.ts:168-175。

在 MemoryVectorStore（基于 SQLite 的向量存储）中，维护了一个单独的 memory_migrations 表，用于追踪向量载荷本身的模式版本 mem0-ts/src/oss/src/vector_stores/memory.ts:69-73。

TypeScript 实现映射

graph LR
    subgraph "TS 接口"
        HManager["HistoryManager（接口）"]
    end

    subgraph "具体实现"
        SQLHManager["SQLiteHistoryManager"]
        DummyHManager["DummyHistoryManager"]
    end

    subgraph "工厂逻辑"
        HMFactory["HistoryManagerFactory.create()"]
    end

    HMFactory -->|config.disableHistory=true| DummyHManager
    HMFactory -->|默认| SQLHManager
    SQLHManager -.->|实现| HManager
    DummyHManager -.->|实现| HManager

来源： mem0-ts/src/oss/src/memory/index.ts:168-175、mem0-ts/src/oss/src/vector_stores/memory.ts:69-73

关键类总结

类名	语言	职责
SQLiteManager	Python	在 SQLite 中管理历史记录和消息表 mem0/memory/storage.py:11
HistoryManagerFactory	TypeScript	实例化适当的历史记录提供者 mem0-ts/src/oss/src/memory/index.ts:171
DummyHistoryManager	TypeScript	用于禁用追踪的空操作历史记录管理器 mem0-ts/src/oss/src/memory/index.ts:169
MemoryVectorStore	TypeScript	基于 SQLite 的向量存储，带有自己的迁移表 mem0-ts/src/oss/src/vector_stores/memory.ts:17

来源： mem0/memory/storage.py:11、mem0-ts/src/oss/src/memory/index.ts:168-175、mem0-ts/src/oss/src/vector_stores/memory.ts:17