mem-agent-mcp

这是我们模型 driaforall/mem-agent 的 MCP 服务器，可以连接到 Claude Desktop 或 Lm Studio 等应用，与类似 Obsidian 的记忆系统进行交互。

支持的平台

• macOS（Metal 后端）
• Linux（配备 GPU，vLLM 后端）

平台说明：aarch64（ARM64）Linux

• 在 ARM64 Linux 上，默认不会安装 vLLM，以避免构建失败（没有稳定的 wheel 包，源码构建也可能失败）。
• 即使不安装 vLLM，安装也能成功；你可以：
  • 使用默认的 OpenRouter/OpenAI 路径（无需本地 vLLM），或
  • 在兼容的 x86_64 主机上运行 vLLM，并让客户端指向它（参见 agent/model.py 中的 create_vllm_client 方法）。

运行说明

使用 LiteLLM 代理（OpenAI 兼容）

• 如果你本地运行着 LiteLLM 代理（例如在端口 4000 上），可以通过 .env 文件配置客户端：

VLLM_HOST=localhost
VLLM_PORT=4000

• 验证连接性：

curl http://localhost:4000/v1/models

• 然后可以选择以下方式之一：
  • CLI：make chat-cli
  • 通过 STDIO 的 MCP：make serve-mcp
  • 通过 HTTP 的 MCP：make serve-mcp-http

注意：在 ARM64 Linux 上，这是推荐的设置，而不是使用 vLLM。

1. make check-uv（如果你已经安装了 uv，则跳过此步骤）。
2. make install：在 macOS 上安装 LmStudio。
3. make setup：这将打开文件选择器，要求你选择用于存储记忆的目录。
4. make run-agent：如果你在 macOS 上，系统会提示你选择要使用的模型精度。经测试，4-bit 已经非常实用，而更高精度的模型虽然更可靠，但速度较慢。
5. make generate-mcp-json：生成 mcp.json 文件。该文件将在下一步中使用。
6. 各应用/提供商的具体说明：
   • Claude Desktop：
     • 将生成的 mcp.json 复制到你的 claude_desktop.json 所在目录，然后退出并重新启动 Claude Desktop。详细说明请参阅 这篇指南。
   • Lm Studio：
     • 将生成的 mcp.json 复制到 Lm Studio 的 mcp.json 文件中。详细说明请参阅 这篇指南。如果出现问题，可以将 .mlx_model_name 文件中的模型名称（位于本仓库根目录下）从 mem-agent-mlx-4bit 或 mem-agent-mlx-8bit 分别改为 mem-agent-mlx@4bit 或 mem-agent-mlx@8bit。

记忆使用说明

• 每个记忆目录应遵循以下结构：

memory/
    ├── user.md
    └── entities/
        └── [entity_name_1].md
        └── [entity_name_2].md
        └── ...

• user.md 是主文件，包含用户及其关系的信息，并通过链接指向实体文件，格式为 [[entities/[entity_name].md]]，每种关系对应一个链接。链接格式必须严格遵守。
• entities/ 是包含实体文件的目录。
• 每个实体文件的结构与 user.md 相同。
• 手动修改记忆内容无需重启 MCP 服务器。

示例 user.md

# 用户信息
- 用户名：John Doe
- 出生日期：1990-01-01
- 出生地：纽约，美国
- 居住地：恩斯赫德，荷兰
- 星座：水瓶座

## 用户关系
- 公司：[[entities/acme_corp.md]]
- 母亲：[[entities/jane_doe.md]]

示例实体文件（jane_doe.md 和 acme_corp.md）

# Jane Doe
- 关系：母亲
- 出生日期：1965-01-01
- 出生地：纽约，美国

# Acme Corporation
- 行业：软件开发
- 地点：恩斯赫德，荷兰

过滤功能

该模型经过训练，能够在用户查询后的 <filter> 标签中接受各种领域的过滤条件。这些过滤条件用于筛选检索到的信息，甚至完全隐藏相关信息。带有过滤条件的用户查询示例如下：

我妈妈多大了？<filter> 1. 不透露具体的年龄信息，2. 不透露任何电子邮件地址 </filter>

要在 MCP 中使用此功能，你需要两个 make 目标：

• make add-filters：打开输入循环，将用户提供的过滤条件添加到 .filters 文件中。
• make reset-filters：重置 .filters 文件（清空内容）。

添加或移除过滤条件无需重启 MCP 服务器。

记忆连接器

可用连接器

连接器	描述	支持的格式	类型
chatgpt	ChatGPT 对话导出	.zip, .json	导出
notion	Notion 工作区导出	.zip	导出
nuclino	Nuclino 工作区导出	.zip	导出
github	GitHub 仓库通过 API	实时 API	实时
google-docs	Google Docs 文件夹通过 Drive API	实时 API	实时

使用方法

🧙‍♂️ 交互式记忆向导（推荐）

连接记忆来源的最简单方法：

make memory-wizard
# 或
python memory_wizard.py

向导将引导你完成以下步骤：

• ✅ 选择连接器并查看描述
• ✅ 设置身份验证（令牌、权限范围）
• ✅ 配置数据源（文件、URL、ID）
• ✅ 设置输出目录
• ✅ 连接器特定选项
• ✅ 确认配置
• ✅ 自动执行
• ✅ 成功确认及后续步骤

手动 CLI 使用

快速演示：使用示例记忆

make run-agent
make serve-mcp-http
python examples/mem_agent_cli.py

示例记忆包（healthcare 和 client_success）包含在内，用于展示 mem-agent 在不同数据类型上的功能。使用交互式 CLI 探索这些记忆并测试提示。

列出可用连接器：

make connect-memory
# 或
python memory_connectors/memory_connect.py --list

ChatGPT 历史导入

# 基本用法
make connect-memory CONNECTOR=chatgpt SOURCE=/path/to/chatgpt-export.zip

# 基于 TF-IDF 的 AI 助力分类（快速）
python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method ai --embedding-model tfidf

# 基于 LM Studio 的 AI 助力分类（高质量语义）
python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method ai --embedding-model lmstudio

# 基于关键词的自定义分类
python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method keyword --edit-keywords

# 处理有限数量的对话
python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --max-items 100

分类方法：

• 基于关键词：快速，可使用预定义关键词自定义分类
• AI 助力（TF-IDF）：统计聚类，发现对话模式
• AI 助力（LM Studio）：通过神经网络进行语义嵌入（需要 LM Studio）

自定义输出位置

make connect-memory CONNECTOR=chatgpt SOURCE=/path/to/export.zip OUTPUT=./memory/custom

仅处理前 100 条对话

make connect-memory CONNECTOR=chatgpt SOURCE=/path/to/export.zip MAX_ITEMS=100

直接使用命令行

python memory_connect.py chatgpt /path/to/export.zip --output ./memory --max-items 100

Notion 工作区导入

# 基本用法
make connect-memory CONNECTOR=notion SOURCE=/path/to/notion-export.zip

# 自定义输出位置
make connect-memory CONNECTOR=notion SOURCE=/path/to/export.zip OUTPUT=./memory/custom
  
python memory_connectors/memory_connect.py notion /path/to/export.zip --output ./memory

获取 ChatGPT 导出文件

1. 前往 ChatGPT 设置
2. 点击“导出数据”
3. 等待包含下载链接的邮件
4. 解压 ZIP 文件
5. 使用解压后的文件夹或 ZIP 文件与连接器配合使用

Nuclino 工作区导入

# 基本用法
make connect-memory CONNECTOR=nuclino SOURCE=/path/to/nuclino-export.zip

# 自定义输出位置  
make connect-memory CONNECTOR=nuclino SOURCE=/path/to/export.zip OUTPUT=./memory/custom

# 直接使用命令行
python memory_connectors/memory_connect.py nuclino /path/to/export.zip --output ./memory

获取 Notion 导出文件

1. 进入你的 Notion 工作区设置
2. 点击“设置与成员”→“设置”
3. 滚动到“导出内容”并点击“导出全部工作区内容”
4. 选择“Markdown & CSV”格式
5. 点击“导出”并等待下载完成
6. 使用下载的 ZIP 文件与连接器配合使用

获取 Nuclino 导出文件

1. 打开你的 Nuclino 工作区
2. 在左上角打开主菜单 (☰)
3. 点击工作区名称旁边的三个点 (⋮)
4. 选择“工作区设置”
5. 在“导出工作区”部分点击“导出工作区”
6. 保存生成的 ZIP 文件
7. 使用下载的 ZIP 文件与连接器配合使用

GitHub 实时集成

# 基本用法 - 单个仓库
make connect-memory CONNECTOR=github SOURCE="microsoft/vscode" TOKEN=your_github_token

# 多个仓库
make connect-memory CONNECTOR=github SOURCE="owner/repo1,owner/repo2" TOKEN=your_token

# 自定义输出和限制
make connect-memory CONNECTOR=github SOURCE="facebook/react" OUTPUT=./memory/custom MAX_ITEMS=50 TOKEN=your_token

# 直接使用命令行，并交互式输入令牌
python memory_connectors/memory_connect.py github "microsoft/vscode" --max-items 100

# 包含特定内容类型
python memory_connectors/memory_connect.py github "owner/repo" --include-issues --include-prs --include-wiki --token your_token

获取 GitHub 个人访问令牌

1. 前往 GitHub 设置 → 令牌
2. 点击“生成新令牌”→“生成新令牌（经典版）”
3. 设置过期时间并选择作用范围：
   • 对于 公共仓库：选择 public_repo 范围
   • 对于 私有仓库：选择 repo 范围（完全访问权限）
4. 点击“生成令牌”，复制生成的令牌
5. 将令牌与 --token 参数一起使用，或在提示时输入

注意：请妥善保管您的令牌，切勿将其提交到版本控制系统中！

Google Docs 实时集成

# 基本用法 - 特定文件夹
make connect-memory CONNECTOR=google-docs SOURCE="1ABC123DEF456_folder_id" TOKEN=your_access_token

# 使用 Google Drive 文件夹 URL
make connect-memory CONNECTOR=google-docs SOURCE="https://drive.google.com/drive/folders/1ABC123DEF456" TOKEN=your_token

# 自定义输出和限制
make connect-memory CONNECTOR=google-docs SOURCE="folder_id" OUTPUT=./memory/custom MAX_ITEMS=20 TOKEN=your_token

# 直接使用命令行，并交互式输入令牌
python memory_connectors/memory_connect.py google-docs "1ABC123DEF456_folder_id" --max-items 15

获取 Google Drive 访问令牌

选项 1：Google OAuth 2.0 Playground（快速测试）

1. 前往 Google OAuth 2.0 Playground
2. 在“选择并授权 API”部分：
   • 找到“Drive API v3”
   • 选择 https://www.googleapis.com/auth/drive.readonly
3. 点击“授权 API”，并登录您的 Google 账号
4. 点击“交换授权码以获取令牌”
5. 复制“访问令牌”（有效期约 1 小时）

选项 2：Google Cloud 控制台（生产环境使用）

1. 前往 Google Cloud 控制台
2. 创建一个新项目或选择现有项目
3. 启用“Google Drive API”
4. 进入“凭据”→“创建凭据”→“OAuth 2.0 客户端 ID”
5. 如有必要，配置 OAuth 同意屏幕
6. 下载凭据 JSON 文件
7. 使用 Google 的 OAuth 2.0 库获取访问令牌

所需作用范围：https://www.googleapis.com/auth/drive.readonly

从 Google Drive URL 中提取文件夹 ID：

• 例如，URL：https://drive.google.com/drive/folders/1ABC123DEF456ghi789
• 文件夹 ID：1ABC123DEF456ghi789

注意：访问令牌会过期（通常为 1 小时）。对于生产环境，建议实现令牌刷新机制或使用服务账号。

内存组织

连接器会自动将您的对话整理成：

• 主题：按主题分组的对话（如 AI 代理、编程、产品战略等）
• 用户档案：您的沟通风格和偏好
• 实体链接：交叉引用的关系和项目
• 搜索策略：优化用于 mem-agent 发现

示例组织结构：

memory/mcp-server/
├── user.md                     # 您的个人资料和导航
└── entities/
    └── chatgpt-history/
        ├── index.md            # 概述和使用示例
        ├── topics/             # 按主题组织的对话列表
        │   ├── dria.md
        │   ├── ai-agents.md
        │   └── programming.md
        └── conversations/      # 个别对话文件
            ├── conv_0-project-discussion.md
            └── conv_1-technical-planning.md

测试您的内存

导入完成后，请测试内存系统：

1. 启动 mem-agent：make run-agent
2. 使用 MCP 服务器启动 Claude Desktop
3. 提出问题，例如：
   • “你能告诉我关于我们产品路线图的信息吗？”
   • “我对 AI 代理框架有什么看法？”
   • “总结一下我最近的技术讨论”

该代理应能访问您真实的对话历史，而不是给出通用的回答。

架构

Mem-Agent

• Dria 的 Memory Agent：专为内存管理和检索而微调的专用 LLM
• 本地部署：通过 LM Studio (MLX) 或 vLLM 运行，以确保隐私和速度
• 多种版本：提供 4 位、8 位和 bf16 量化版本
• 工具集成：专为文件操作和内存搜索设计

内存结构

• Obsidian 风格：带有维基链接导航的 Markdown 文件
• 主题组织：按主题自动分类
• 实体关系：对话之间的交叉引用连接
• 搜索优化：为高效的 agent 发现而构建

MCP 集成

• FastMCP 框架: 高性能模型上下文协议服务器
• Claude Desktop: Claude 的桌面应用
• Claude Code: Anthropic 提供的代理式编码工具，运行在终端中

Claude Code 设置

先决条件: 首先启动你的记忆服务器：

make run-agent  # 必需：vLLM 或 MLX 模型服务器必须正在运行

添加 MCP 服务器：

claude mcp add mem-agent \
  --env MEMORY_DIR="/path/to/your/memory/directory" \
  -- python "/path/to/mcp_server/server.py"

验证与使用：

claude mcp list  # 应显示 mem-agent 已连接

现在，Claude Code 可以访问你的记忆系统，在开发过程中获得上下文帮助。

• 工具执行: 用于记忆操作的沙箱代码执行
• 调试日志: 全面的日志记录以便排查问题

ChatGPT 集成

先决条件: 完成记忆设置并启动本地代理：

make setup      # 配置记忆目录
make run-agent  # 启动本地 vLLM/MLX 模型服务器

启动符合 MCP 标准的 HTTP 服务器：

make serve-mcp-http  # 在 localhost:8081/mcp 上启动服务器

使用 ngrok 暴露（在另一个终端中）：

ngrok http 8081  # 复制转发 URL

配置 ChatGPT：

1. 前往 ChatGPT 设置 → 连接器
2. 在高级设置中启用 开发者模式
3. 添加新的 MCP 服务器：
   • 名称: mem-agent
   • URL: https://your-ngrok-url.ngrok.io/mcp
   • 协议: HTTP
   • 认证: 无

在 ChatGPT 中使用： 选择 开发者模式 → 选择 mem-agent 连接器 → 提出类似以下的问题：

• “使用 mem-agent 搜索我的记忆中关于 AI 研究的讨论”
• “查询我的记忆中关于最近项目工作的信息”

故障排除

常见问题

代理返回通用回复而非使用记忆：

• 检查配置路径中是否存在记忆文件
• 确认 user.md 是否包含正确的主题导航
• 启用调试日志以查看代理的推理过程
• 尝试直接询问已知对话主题进行测试

MCP 连接问题：

• 检查 Claude Desktop 的配置文件 ~/.config/claude/claude_desktop.json
• 确认 PATH 配置中包含 LM Studio 二进制文件
• 增加超时设置以处理大型记忆导入
• 查看日志文件 ~/Library/Logs/Claude/mcp-server-memory-agent-stdio.log

记忆导入失败：

• 确保导出格式受支持（ChatGPT 支持 .zip 或 .json）
• 检查文件权限和磁盘空间
• 尝试使用 --max-items 限制处理范围
• 验证导出文件是否包含预期的数据结构

调试模式

通过设置环境变量启用详细日志记录：

FASTMCP_LOG_LEVEL=DEBUG make serve-mcp

或者在运行期间检查代理的日志文件以了解其内部推理过程。

开发

添加新连接器

1. 创建继承自 BaseMemoryConnector 的连接器类
2. 实现所需方法：extract_data()、organize_data()、generate_memory_files()
3. 将其添加到 memory_connect.py 中的连接器注册表
4. 更新 README 文件以提供使用示例

连接器示例框架：

from memory_connectors.base import BaseMemoryConnector

class MyConnector(BaseMemoryConnector):
    @property
    def connector_name(self) -> str:
        return "My Service"
    
    @property 
    def supported_formats(self) -> list:
        return ['.zip', '.json']
    
    def extract_data(self, source_path: str) -> Dict[str, Any]:
        # 解析源数据
        pass
    
    def organize_data(self, extracted_data: Dict[str, Any]) -> Dict[str, Any]:
        # 按主题整理
        pass
    
    def generate_memory_files(self, organized_data: Dict[str, Any]) -> None:
        # 生成 Markdown 文件
        pass

贡献

本系统设计为不影响主 mem-agent-mcp 仓库的本地插件：

• 记忆连接器是本地扩展
• 保持对旧版的兼容性
• 所有更改均不破坏现有功能
• 调试改进有助于问题排查

欢迎提交拉取请求以添加新连接器或进行改进！

mem-agent-mcp 快速上手指南

mem-agent-mcp 是一个模型上下文协议（MCP）服务器，用于连接 driaforall/mem-agent 模型。它允许 Claude Desktop、Lm Studio 等应用与类 Obsidian 的记忆系统进行交互，实现基于个人知识库的智能对话。

环境准备

系统要求

• macOS: 需配备 Apple Silicon (ARM64) 芯片，使用 Metal 后端。
• Linux: 需配备 GPU，推荐使用 x86_64 架构以支持 vLLM 后端。
  • 注意: ARM64 (aarch64) Linux 默认不安装 vLLM（因构建不稳定），建议通过 LiteLLM 代理或远程 x86_64 主机运行模型。

前置依赖

• Python 环境（推荐配合 uv 包管理器使用）
• Git
• 目标客户端软件（Claude Desktop 或 Lm Studio）

安装步骤

1. 检查并安装 uv (可选) 如果已安装 uv 可跳过此步。

   make check-uv
   

2. 安装项目依赖 在 macOS 上这将自动配置 LmStudio 相关组件。

   make install
   

3. 配置记忆存储目录 运行设置命令，通过文件选择器指定记忆文件的存储路径。

   make setup
   

4. 启动 Agent 并选择模型精度 运行 Agent，根据提示选择模型精度（推荐 4-bit，兼顾速度与可用性；高精度模型更可靠但较慢）。

   make run-agent
   

5. 生成 MCP 配置文件 生成 mcp.json 文件，用于后续客户端连接。

   make generate-mcp-json
   

6. 连接客户端 将生成的 mcp.json 复制到对应应用的配置目录：

   • Claude Desktop: 复制到 claude_desktop.json 所在目录，重启应用。
   • Lm Studio: 复制到 Lm Studio 的 mcp.json 位置。 注: 若遇问题，请将根目录下 .mlx_model_name 文件中的模型名从 mem-agent-mlx-4bit 改为 mem-agent-mlx@4bit（8bit 同理）。

基本使用

1. 初始化记忆结构

确保你的记忆目录包含以下结构（手动创建或通过导入工具生成）：

memory/
    ├── user.md              # 用户主档案
    └── entities/            # 实体文件夹
        ├── [entity_1].md
        └── [entity_2].md

• user.md: 包含用户信息及关系链接（格式严格为 [[entities/name.md]]）。
• entities/: 存放具体实体（如人物、公司）的详细 Markdown 文件。
• 提示: 修改这些文件无需重启 MCP 服务。

2. 导入外部数据（可选）

使用内置向导快速导入 ChatGPT、Notion、GitHub 等数据源：

make memory-wizard

或者手动导入 ChatGPT 导出包示例：

make connect-memory CONNECTOR=chatgpt SOURCE=/path/to/chatgpt-export.zip

3. 开始对话

配置完成后，在支持的客户端（Claude Desktop / Lm Studio）中即可直接提问。系统会自动检索记忆库并回答。

高级用法：添加过滤规则 若需在查询时隐藏特定信息（如年龄、邮箱），可使用过滤功能：

# 添加过滤规则
make add-filters

# 清除过滤规则
make reset-filters

示例查询: What's my mother's age? <filter> 1. Do not reveal explicit age information </filter>

4. 本地代理模式（ARM64 Linux 推荐）

如果在 ARM64 Linux 上运行，建议使用 LiteLLM 代理而非本地 vLLM：

1. 配置 .env:

   VLLM_HOST=localhost
   VLLM_PORT=4000
   

2. 验证连接:

   curl http://localhost:4000/v1/models
   

3. 启动服务:

   make serve-mcp