Agent Memory Techniques 部署教程：在本地运行 LLM 记忆技术笔记本

本教程将指导你部署 Agent_Memory_Techniques 项目——一个包含 30 个可运行 Jupyter Notebook 的实战代码库，覆盖了从对话缓冲、向量存储到知识图谱、MemGPT、Mem0 等主流 LLM 智能体记忆技术。

📋 准备工作

1. 硬件与系统要求

  • 操作系统：Windows、macOS 或 Linux。
  • Python 版本：3.9 或更高版本。
  • 网络：稳定的互联网连接，用于下载依赖包和调用 LLM API（如 OpenAI、Anthropic）。
  • API 密钥：你需要至少一个 LLM 提供商的 API 密钥：

💡 提示：如果你不想在本地安装任何环境，每个 Notebook 在 GitHub 上可直接阅读，或通过提供的 Colab 徽章 在云端运行。

🛠️ 安装步骤

1. 克隆仓库

打开终端 (Terminal) 或命令提示符 (CMD)，执行以下命令将项目下载到本地：

1
2
git clone https://github.com/NirDiamant/Agent_Memory_Techniques.git
cd Agent_Memory_Techniques

2. 创建并激活 Python 虚拟环境（推荐）

使用虚拟环境可以隔离项目依赖，避免与其他 Python 项目冲突。

1
2
3
4
5
6
7
8
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境 (macOS/Linux)
source venv/bin/activate

# 激活虚拟环境 (Windows)
venv\Scripts\activate

3. 安装项目依赖

项目所需的所有 Python 包都列在 requirements.txt 文件中，使用 pip 一键安装：

1
pip install -r requirements.txt

4. 配置 API 密钥

  1. 复制项目提供的环境变量示例文件：

    1
    cp .env.example .env

  2. 使用文本编辑器打开 .env 文件，填入你的 API 密钥：

    1
    2
    3
    4
    5
    # 填入你的 OpenAI API 密钥
    OPENAI_API_KEY=sk-你的OpenAI密钥

    # 如果你使用 Anthropic，也填上
    ANTHROPIC_API_KEY=你的Anthropic密钥

🚀 运行与学习

1. 启动 Jupyter Notebook

在项目根目录下，执行以下命令启动 Jupyter：

1
jupyter notebook

该命令会自动在浏览器中打开 Jupyter 文件管理界面。

2. 访问技术笔记本

在 Jupyter 界面中，导航到 all_techniques 文件夹。你会看到按编号排序的 30 个技术子文件夹（如 01_conversation_buffer_memory）。

3. 按顺序运行笔记本

  1. 从 01_conversation_buffer_memory/ 文件夹开始，点击其中的 .ipynb 文件打开。
  2. 在 Notebook 中，按顺序（Shift + Enter）运行每个代码单元格。
  3. 观察代码如何实现该记忆技术，以及运行后的输出结果。

4. 选择学习路径

项目提供了几条清晰的学习路径，你可以根据目标选择：

  • 初学者 (Foundations)：从 01 → 02 → 03 → 05 → 06 → 21，掌握对话缓冲、滑动窗口、摘要等基础。
  • 中级 (Structured Memory)：学习 07 → 08 → 09 → 10 → 20 → 22，深入了解实体、知识图谱和检索模式。
  • 高级 (Cognitive Architectures)：探索 12 → 13 → 14 → 16 → 17 → 19，构建类人的认知记忆模式。
  • 实践者 (Frameworks & Production)：直接学习 25 (Mem0)、26 (Letta/MemGPT)、24 (Graphiti)、27 (Zep)，并参考 28-30 进行评估和部署。

⚙️ 故障排除与技巧

常见问题

  • ModuleNotFoundError：表明缺少某个 Python 包。请确保已执行 pip install -r requirements.txt，或根据需要单独安装（例如 pip install openai）。

  • API 密钥错误：检查 .env 文件中的密钥是否正确，且已填入 OPENAI_API_KEY= 等变量名之后，没有多余空格。如果仍然报错，尝试在运行 Notebook 的单元格中直接设置：

    1
    2
    import os
    os.environ["OPENAI_API_KEY"] = "你的密钥"

  • 内存不足：某些技术（如向量存储、知识图谱）在较大数据集上运行时可能消耗较多内存。如果遇到问题，可以尝试使用 Notebook 提供的示例小数据集。

  • 部分框架（如 Letta）无法导入：项目笔记中可能使用了一些需要额外安装的库。请查看具体 Notebook 开头的说明，并运行 pip install [库名] 进行安装。

进阶技巧

  • 修改 LLM 模型：大多数 Notebook 都使用 OpenAI 或 Anthropic 客户端。你可以修改代码以使用本地模型（如通过 Ollama 或 LM Studio 提供的兼容 OpenAI API 的端点）。
  • 保存学习成果：在运行和修改 Notebook 后，可以另存为新文件，方便日后复习。
  • 查阅文档：项目 docs/ 目录下包含 comparison.md（30 种技术对比）、glossary.md（术语表）等补充资料。

通过以上步骤，你就成功搭建了一个专用于学习和实验 LLM 智能体记忆技术的本地环境。你可以从最基础的对话缓冲开始，逐步深入到前沿的记忆框架，并将这些技术应用到自己的 AI 项目中。