DiffMem：为AI智能体提供基于Git的版本化记忆存储库

DiffMem是一个为AI智能体和对话式系统设计的轻量级记忆后端。 它创新地使用Git作为记忆存储的核心，将AI的记忆以人类可读的Markdown文件形式保存。 Git的提交历史被用来追踪记忆随时间的演变，同时系统采用内存中的BM25索引来实现快速和可解释的信息检索。 这个项目目前是一个概念验证（PoC），旨在探索如何利用版本控制系统为AI应用构建一个高效、可扩展的记忆基础。 DiffMem将记忆视为一个版本化的知识库：知识的“当前状态”存储在可编辑的文件中，而历史变迁则保存在Git的提交图里。这种设计使得智能体可以在一个紧凑、最新的知识层面上进行查询，同时又能在需要时深入研究记忆的演变过程。

功能列表

• Git驱动的记忆存储：利用Git的版本控制能力来管理和追踪AI记忆的演变，每一次记忆更新都对应一次Git提交。
• 人类可读的格式：记忆以简单的Markdown文件形式存储，方便开发者直接阅读、编辑和管理。
• 当前状态聚焦：默认仅对知识的“当前状态”文件进行索引和搜索，减少了查询的范围，提升了检索效率和在大型语言模型（LLM）上下文中的令牌经济性。
• 差分演化追踪：通过git diff等指令，智能体可以高效查询特定信息随时间的变化，而无需加载完整的历史记录。
• 快速文本检索：内置一个内存中的BM25索引，为关键词搜索提供毫秒级的快速响应。
• 模块化组件：系统由几个核心模块组成，包括负责分析对话并提交更新的写入智能体、负责整合查询上下文的上下文管理器，以及负责执行搜索的搜索智能体。
• 轻量级与易于集成：项目依赖项少，无需部署独立的服务器，可以作为Python模块直接集成到现有项目中。

使用帮助

DiffMem的设计使其可以作为一个简单的Python模块导入，无需复杂的服务器部署。以下是详细的安装和使用流程。

环境准备与安装

1. 克隆代码库
   首先，需要从GitHub上克隆DiffMem的源代码库到你的本地计算机。打开终端或命令行工具，然后输入以下命令：

   git clone https://github.com/Growth-Kinetics/DiffMem.git
   

   执行后，代码库将被下载到当前目录下的一个名为DiffMem的文件夹中。

2. 进入项目目录
   使用cd命令进入项目文件夹：

   cd DiffMem
   

3. 安装依赖项
   DiffMem依赖于一些Python库来运行，这些依赖项都记录在requirements.txt文件中。你可以使用pip来安装它们：

   pip install -r requirements.txt
   ```    这个命令会自动下载并安装`gitpython`、`rank-bm25`和`sentence-transformers`等必要的库。
   

4. 设置API密钥
   DiffMem需要使用大型语言模型（LLM）来协同工作，例如分析对话内容。项目中使用了OpenRouter来管理LLM的调用。你需要在环境变量中设置你的API密钥。
   对于Linux或macOS系统，使用export命令：

   export OPENROUTER_API_KEY='你的密钥'
   

   对于Windows系统，使用set命令：

   set OPENROUTER_API_KEY='你的密钥'
   

   请将你的密钥替换为你自己的有效API密钥。

核心功能操作

DiffMem的主要功能通过DiffMemory类暴露给用户。你可以初始化这个类，然后调用它的方法来读取、写入和查询记忆。

1. 初始化记忆库
   首先，你需要导入DiffMemory类，并用一个本地路径来初始化它。这个路径将作为存储记忆的Git仓库。

   from src.diffmem import DiffMemory
   # 初始化记忆库，指定仓库路径、用户名和API密钥
   # 如果路径不存在，系统会自动创建一个新的Git仓库
   memory = DiffMemory(
   repo_path="/path/to/your/memory_repo",
   user_name="alex",
   api_key="你的OpenRouter密钥"
   )
   

   在上面的代码中，将/path/to/your/memory_repo替换为你希望存储记忆的文件夹路径。

2. 处理和提交记忆
   你可以将一段对话或会话内容传递给process_and_commit_session方法。DiffMem的写入智能体将自动分析文本，提取或更新实体信息，然后将这些变更作为一次Git提交保存下来。

   # 假设你有一段新的对话内容
   conversation_text = "今天和妈妈一起喝了咖啡，她提到下周要去旅行。"
   session_id = "session-12345" # 为这次会话指定一个唯一的ID
   # 处理并提交这次会话的记忆
   memory.process_and_commit_session(conversation_text, session_id)
   print("记忆已成功处理并提交。")
   

   执行后，相关的知识会被更新到Markdown文件中，并生成一条新的Git提交记录，提交信息会包含会话ID。

3. 获取上下文
   当需要与AI进行交互时，你可以使用get_context方法来为当前的对话获取相关的背景信息。这个方法支持不同的“深度”参数，以控制返回信息的详细程度。
   • depth="basic": 获取核心信息块。
   • depth="wide": 进行语义搜索，返回更广泛相关的信息。
   • depth="deep": 返回与查询相关的完整文件内容。
   • depth="temporal": 返回包含Git历史记录的时间性信息。

   # 假设当前的对话是关于“妈妈的旅行计划”
   current_conversation = "妈妈的旅行计划定了吗？"
   # 获取深度上下文
   context = memory.get_context(current_conversation, depth="deep")
   # 将获取到的上下文信息打印出来
   print("获取到的相关上下文：")
   print(context)
   

   这个上下文可以被输入到LLM中，以生成更准确、更具背景知识的回复。

4. 直接执行搜索
   你也可以直接使用search方法来检索记忆库中的信息。

   query = "关于妈妈的信息"
   search_results = memory.search(query)
   print(f"关于 '{query}' 的搜索结果:")
   for result in search_results:
   print(f"- {result}")
   

示例代码运行

在项目的examples/目录下，提供了一个完整的用法演示文件usage.py。你可以直接运行它来观察DiffMem的完整工作流程。
在终端中执行以下命令：

python examples/usage.py

这个脚本会演示如何初始化记忆库、提交新的记忆，并根据新的对话内容检索上下文，展示了DiffMem从信息输入到输出的整个链路。

应用场景

1. 个人AI助理
   可以为个人AI助理提供长期记忆能力。助理能够记住用户的偏好、过去的对话、重要的日期和事件。由于记忆会随时间演变，助理可以准确地回忆起“上周我们讨论过什么”或者“我女儿的年龄现在是多少”，因为它只关注信息的最新状态，同时保留了历史轨迹。
2. 需要持续学习的AI系统
   在客户服务、技术支持等领域，AI智能体需要不断学习新的产品知识和业务流程。DiffMem可以记录这些知识的演变过程。当一个操作指南更新时，系统会保存新版本，同时通过Git历史记录下变更，确保AI总能提供最准确的信息，并且可以追溯任何知识点的历史版本。
3. 多智能体协作
   在多智能体系统中，不同的智能体可以共享同一个DiffMem记忆库。通过Git的分支和合并请求（Merge Request）机制，智能体之间可以协同更新共享知识，并解决可能出现的“记忆冲突”，最终形成一致的、版本化的团队记忆。
4. 可解释性与调试
   对于开发者而言，AI的行为有时像一个“黑箱”。DiffMem将记忆以人类可读的文本和Git提交历史的形式存储，极大地增强了AI记忆的可解释性。开发者可以像审查代码一样，通过git log和git diff来查看AI“学到了什么”以及“知识是如何变化的”，这对于调试AI的行为和决策过程非常有帮助。

QA

1. DiffMem与传统的向量数据库有何不同？
   向量数据库主要用于高维数据的相似性搜索，它将信息（如文本）转换为向量并存储，然后通过计算向量间的距离来查找相似内容。 DiffMem则采用了完全不同的思路，它不依赖向量嵌入，而是将记忆作为版本化的文本文档来管理。 它的核心优势是处理随时间演变的信息，能够清晰地追踪一个事实的变化（例如，一个人的年龄从9岁变为10岁），而向量数据库在处理这类“事实更新”时可能会保留过时和有噪声的信息。
2. 为什么选择Git作为后端技术？
   选择Git是因为它为版本化文档管理提供了成熟且强大的解决方案。 Git的优点与AI记忆的需求非常契合：它天然支持追踪变化（diff）、记录历史（log）、回溯到任意时间点（checkout）以及分支管理（branch）。 此外，Git是分布式的，数据存储在简单的文件中，这使得记忆库具有很高的可移植性和持久性，并且不依赖任何专有格式。
3. DiffMem是否适合生产环境？
   目前，DiffMem是一个概念验证（PoC）项目，其作者明确表示它尚未经过生产环境的强化。 它存在一些局限性，例如需要手动进行Git的远程同步（push/pull）、错误处理机制比较基础、没有为多用户并发访问设计锁定机制等。 因此，直接用于大规模商业应用前还需要进一步的开发和测试。
4. 运行DiffMem需要哪些主要软件依赖？
   DiffMem是一个轻量级项目，主要依赖项包括GitPython库（用于在Python中操作Git仓库）、rank-bm25库（用于实现高效的文本检索算法）和sentence-transformers（用于支持语义相关的搜索功能）。