DiffMem：基于 Git 的差分内存，专为 AI 代理设计

DiffMem 是一种轻量级、基于 Git 的内存后端，专为 AI 代理和对话系统设计。它使用 Markdown 文件进行人类可读的存储，利用 Git 通过差异追踪时间演化，并配备一个原生 Git 检索代理，该代理通过 Shell 命令（grep、git log、git diff、git blame）探索仓库，构建有针对性的上下文。无需向量数据库、无需嵌入、无需 BM25——只需 Git 和一个大语言模型。

在核心理念上，DiffMem 将内存视为一个版本化的仓库：知识的“当前状态”存储在可编辑的文件中，而历史变更则保存在 Git 的提交图中。这种分离使代理能够在不引入历史数据开销的情况下，针对精简、最新的表层数据进行查询和搜索，同时在需要时深入探究其演化过程。

已投入生产

DiffMem 为 Annabelle 提供支持，这是一款模拟智能体，在 WhatsApp 和 Messenger 上持续维护着数千次对话的记忆。

在生产环境中，DiffMem 使 Annabelle 能够：

• 引用数周前对话中的细节
• 长期跟踪关系的演变
• 构建对她所交谈的每个人的结构化理解
• 随着对话的增多自动整合记忆

→ 与 Annabelle 对话体验 → 查看 DiffMem 如何逐章处理新内容

路线图

• PoC 中的索引策略需要更加 robust，目前过于消耗内存且并无必要。
• 实现检索上下文容量的参数化方法。
• 有时某个实体会变成“万能容器”，导致过度负载。
• 添加检索历史功能，以便构建“关联实体”模型来支持维基化。
• PDF 导出功能。
• 研究 PoC：用于上下文压缩的可视化检索。

为什么选择 Git 作为 AI 内存？

传统的 AI 代理内存系统通常依赖于数据库、向量存储或图结构。这些方案在特定规模下表现良好，但在处理长期、不断演化的个人知识时，可能会变得臃肿或效率低下。DiffMem 则另辟蹊径，充分利用 Git 的优势：

• 聚焦当前状态：内存文件仅存储信息的“当下”视图（例如当前的关系、事实或时间线）。这减少了查询和搜索的表面面积，使得操作更快、在 LLM 场景中更节省 token。历史状态默认不会被加载——它们存在于 Git 的历史记录中，按需访问。

• 差分智能：Git 的差异和日志提供了一种自然的方式来追踪记忆如何演变。代理可以询问“这个事实在过去是如何变化的？”，而无需扫描整个历史，只需提取相关提交即可。这类似于人类记忆通过线索重构事件，而非完整重现。

• 持久性与可移植性：纯文本 Markdown 确保记忆对人类可读且不依赖特定工具。Git 的分布式特性意味着数据易于备份，且不会被锁定在专有格式中。

• 代理的高效性：通过将“表层”（当前文件）与“深度”（Git 历史）分离，代理可以灵活选择——快速响应时加载当前状态，分析任务时深入差异。这样既能保持上下文窗口简洁，又能实现丰富的时序推理。

这种方法对于长期运行的 AI 系统尤为适用，因为这些系统的记忆会随时间积累多年；它可以在不造成数据膨胀的情况下扩展规模，同时保持可审计性，并通过修剪实现“智能遗忘”，又保留了可重构性。

工作原理

DiffMem 以可导入模块的形式组织，无需服务器。关键组件包括：

• 写入代理（writer_agent）：分析对话记录，识别并创建实体，在 Git 的工作树中暂存更新。提交是显式的，确保原子性更改。

• 检索代理（retrieval_agent）：一个多轮 LLM 代理，仅有一个 run(command="...") 工具，可通过沙箱化的 Shell 命令探索内存仓库。它读取 index.md，探测 Git 历史中的时间模式，并输出一个结构化的检索计划（文件片段、Git 差异、提交日志），最终转化为上下文。

• API 层（api.py）：用于读写操作的干净接口。示例如下：

  from diffmem import DiffMemory
  
  memory = DiffMemory("/path/to/repo", "alex", "your-api-key")
  
  # 获取对话上下文（代理通过 Git 探索相关部分）
  context = memory.get_context(conversation, max_tokens=15000)
  
  # 处理并提交新记忆
  memory.process_and_commit_session("今天和妈妈一起喝了咖啡...", "session-123")
  

仓库遵循结构化的布局（详情请参阅 repo_guide.md），当前状态存储在 Markdown 文件中，而演化记录则保存在 Git 提交中。检索代理使用与开发者相同的 Git 命令来导航这一结构。

为何有效

DiffMem 的 Git 中心设计解决了 AI 内存系统中的关键挑战：

• 减少查询面：默认情况下，仅探索当前状态的文件。检索代理会读取 index.md 以了解实体格局，然后精准加载相关内容。当需要历史信息时，它会提取有针对性的差异（例如 git diff HEAD~3 file.md），而不是加载完整的档案。

• 可扩展的演化追踪：Git 能够高效地处理超过 50 年的变化。代理可以重建过去的状态（git show <commit>:file.md），而不会使活跃内存膨胀。

• 开发者友好：无需数据库模式或迁移——直接编辑 Markdown 文件即可。Git 提供免费的版本控制、分支管理（例如每月的时间线）和协作功能。

• 轻量级：进程内运行，依赖项极少（gitpython、openai）。无需机器学习模型、无需嵌入、无需向量数据库。

原型状态与局限性

已实现的功能：

• 根据对话记录创建或更新实体。
• 基于 Git 的原生代理检索，具备时序推理能力。
• 针对性上下文组装（文件片段、差异、提交日志）。
• 当代理失败时，可回退到基础用户实体。

已知局限性：

• 检索代理的质量取决于所使用的 LLM 模型。
• 缺乏多用户并发锁机制。
• 写入代理的提示词调优仍在进行中。

我们以开源研发的形式分享此项目，旨在引发讨论。欢迎提出反馈！

未来愿景：这项技术的发展方向

DiffMem 展示了一个 AI 记忆系统如同代码一样具备版本管理和协作能力的未来。试想：

• 代理驱动的修剪：大型语言模型通过将低权重的记忆归档到 Git 分支中来“遗忘”，从而模拟神经可塑性。

• 协作式记忆：多智能体系统共享仓库，并通过合并请求实现“记忆对齐”。

• 时序代理：专门的模型可以查询 Git 日志，回答“我是如何变化的？”——从而实现 AI 的自我反思能力。

• 多提供商检索：在 OpenRouter、Cerebras 或任何兼容 OpenAI 的服务提供商之间切换检索代理。

• 开源生态系统：支持语音输入、移动端同步，或与 Obsidian 等工具集成的插件。

随着 AI 代理逐渐成为长期陪伴的伙伴，类似 Git 的系统将使它们能够在不形成数据孤岛的情况下持续进化。我们非常期待社区能将这一方向推向更广阔的领域——也许会朝着分布式、以隐私为先的个人 AI 发展。

本项目由 Growth Kinetics 公司研发，这是一家专注于 AI 赋能的小型数据解决方案机构。我们正在探索差分记忆如何为下一代智能体提供动力。我们欢迎各方合作、提交 Pull Request，以及坦诚的反馈，以不断完善它。

快速上手

1. 克隆仓库：git clone https://github.com/alexmrval/DiffMem.git
2. 安装依赖：pip install -r requirements.txt
3. 设置环境变量：export OPENROUTER_API_KEY=your_key
4. 运行示例：python examples/usage.py

更多完整演示请参阅 examples/ 目录。

参与贡献

欢迎 Fork、实验并提交 PR！我们期待：

• Git 同步优化；
• 高级搜索插件；
• 实际场景中的集成方案。

欢迎提出问题或提交 PR。让我们携手共建 AI 记忆的未来。

许可证：MIT
Growth Kinetics © 2025

DiffMem 快速上手指南

DiffMem 是一个基于 Git 的轻量级 AI 代理记忆后端。它使用 Markdown 文件存储人类可读的记忆，利用 Git 追踪时间演变，并通过原生 Git 命令（如 grep, git log, git diff）构建精准的上下文，无需向量数据库或嵌入模型。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (需安装 Git)
• Python 版本：3.11 或更高版本
• 前置依赖：
  • 已安装 git 命令行工具
  • 有效的 LLM API Key (默认支持 OpenRouter 或 OpenAI 兼容接口)

安装步骤

1. 克隆仓库 将项目代码下载到本地：

   git clone https://github.com/alexmrval/DiffMem.git
   cd DiffMem
   

2. 安装依赖 使用 pip 安装所需 Python 包。 注：国内用户若遇到下载慢的问题，可使用清华源加速：

   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

3. 配置环境变量 设置您的 API 密钥（以 OpenRouter 为例）：

   export OPENROUTER_API_KEY=your_key
   

   (Windows PowerShell 用户请使用：$env:OPENROUTER_API_KEY="your_key")

基本使用

DiffMem 设计为可导入模块，无需启动额外服务器。以下是最简单的使用示例：

1. 初始化记忆实例 指定本地仓库路径、用户标识和 API Key。

2. 获取上下文与提交新记忆 调用 API 让代理自动探索 Git 历史以获取相关上下文，并处理新的对话会话。

from diffmem import DiffMemory

# 初始化：指定本地 repo 路径，用户 ID 和 API Key
memory = DiffMemory("/path/to/repo", "alex", "your-api-key")

# 1. 获取上下文
# 代理会自动探索 git 历史，找出与当前对话最相关的信息
# max_tokens 限制返回的 token 数量
context = memory.get_context(conversation, max_tokens=15000)

# 2. 处理并提交新记忆
# 分析对话内容，更新实体文件，并执行 Git commit
memory.process_and_commit_session("Had coffee with mom today...", "session-123")

更多详细演示请参考项目中的 examples/usage.py 文件。