5.4 · 历史记录与审计轨迹（History and Audit Trails）

历史记录与审计轨迹

历史记录与审计追踪

相关源文件

本章引用的主要源码文件：

• 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。

系统数据流

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

来源： 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。

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

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

模式定义

历史记录表

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

消息表

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。

来源： 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 实现映射

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

关键类总结

来源： 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