Mem Agent MCP

mem代理mcp

这是我们型号的MCP服务器 driaforal/mem代理，可以连接到Claude Desktop或Lm Studio等应用程序，与类似黑曜石的存储系统进行交互。

支持的平台

• macOS（金属后端）
• Linux（带GPU、vLLM后端）

运行说明

1. make check-uv （如果您安装了uv，请跳过此步骤）。
2. make install：在MacOS上安装LmStudio。
3. make setup：这将打开一个文件选择器，并要求您选择要存储内存的目录。
4. make run-agent：如果您使用的是macOS，这将提示您选择要使用的模型的精度。4位在测试中非常有用，更高精度的模型更可靠，但速度较慢。
5. make generate-mcp-json：生成 mcp.json 文件。这将在下一步中使用。
6. 每个应用程序/提供商的说明：

- 克劳德桌面： - 复制生成的 mcp.json 到哪里你 claude_desktop.json 然后退出并重新启动Claude Desktop。检查 本指南 详细说明。 - Lm工作室： - 复制生成的 mcp.json 到 mcp.json Lm工作室。检查 本指南 详细说明。如果有问题，请更改.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 是包含用户及其关系信息的主文件，并附有以下格式的enity文件链接 [[entities/[entity_name].md]] 每段关系。应严格遵循链接格式。
• entities/ 是包含实体文件的目录。
• 每个实体文件都遵循与以下相同的结构 user.md.
• 手动修改内存不需要重新启动MCP服务器。

user.md示例

# User Information
- user_name: John Doe
- birth_date: 1990-01-01
- birth_location: New York, USA
- living_location: Enschede, Netherlands
- zodiac_sign: Aquarius

## User Relationships
- company: [[entities/acme_corp.md]]
- mother: [[entities/jane_doe.md]]

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

# Jane Doe
- relationship: Mother
- birth_date: 1965-01-01
- birth_location: New York, USA

# Acme Corporation
- industry: Software Development
- location: Enschede, Netherlands

过滤

该模型经过训练，可以接受介于两者之间的各种域上的过滤器 用户查询后的标签。这些过滤器用于过滤检索到的信息和/或完全混淆它。一个带有过滤器的用户查询示例是：

What's my mother's age?  1. Do not reveal explicit age information, 2. Do not reveal any email addresses 

要使用MCP的此功能，您有两个make目标：

• make add-filters：打开一个输入循环，并将用户给出的过滤器添加到.filters文件中。
• make reset-filters：重置.filters文件（清除它）。

添加或删除筛选器不需要重新启动MCP服务器。

内存连接器

可用连接器

用法

🧙‍♂️ 交互式内存向导（推荐）

连接内存源的最简单方法：

make memory-wizard
# or
python memory_wizard.py

向导将指导您完成以下操作：

• ✅ 带说明的连接器选择
• ✅ 身份验证设置（令牌、范围）
• ✅ 源配置（文件、URL、ID）
• ✅ 输出目录设置
• ✅ 连接器特定选项
• ✅ 配置确认
• ✅ 自动执行
• ✅ 下一步成功确认

手动CLI使用

使用示例内存快速演示：

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

内存包示例(healthcare 和 client_success)包括用于演示不同数据类型的mem代理功能。使用交互式CLI浏览这些记忆和测试提示。

列出可用连接器：

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

#### ChatGPT History Import

Basic usage

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

AI-powered categorization with TF-IDF (fast)

python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method ai --embedding-model tfidf

AI-powered categorization with LM Studio (high-quality semantic)

python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method ai --embedding-model lmstudio

Keyword-based with custom categories

python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method keyword --edit-keywords

Process limited conversations

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

**分类方法：**

- **基于关键字**：使用预定义关键字快速定制类别
- **人工智能驱动（TF-IDF）**：统计聚类，发现对话模式
- **人工智能驱动（LM工作室）**：通过神经网络进行语义嵌入（需要LM Studio）

# 自定义输出位置

使连接内存CONNECTOR=chatgpt SOURCE=/path/to/export.zip输出=。/内存/自定义

# 仅处理前100个对话

使连接内存CONNECTOR=chatgpt SOURCE=/path/to/export.zip MAX_ITEMS=100

# 直接CLI使用

python memory_connect.py chatgpt/path/to/export.zip--输出。/内存--最多100个项目

#### 概念工作区导入

Basic usage

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

Custom output location

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设置](https://chatgpt.com/settings/data-controls)
1. 点击“导出数据”
1. 等待带有下载链接的电子邮件
1. 解压缩ZIP文件
1. 将提取的文件夹或ZIP文件与连接器一起使用

#### Nuclino工作区导入

Basic usage

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

Custom output location

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

Direct CLI usage

python memory_connectors/memory_connect.py nuclino /path/to/export.zip --output ./memory

#### 获取导出通知

1. 转到您的Notion工作区设置
1. 点击“设置和成员”→ “设置”
1. 滚动到“导出内容”，然后单击“导出所有工作区内容”
1. 选择“Markdown和CSV”格式
1. 点击“导出”，等待下载
1. 将下载的ZIP文件与连接器一起使用

#### 获得Nuclino出口

1. 转到您的Nuclino工作区
1. 打开左上角的主菜单（☰）
1. 单击工作区名称旁边的三个点（⋮）
1. 选择“工作区设置”
1. 单击导出部分中的“导出工作区”
1. 保存生成的ZIP文件
1. 将下载的ZIP文件与连接器一起使用

#### GitHub Live集成

Basic usage - single repository

make connect-memory CONNECTOR=github SOURCE="microsoft/vscode" TOKEN=your_github_token

Multiple repositories

make connect-memory CONNECTOR=github SOURCE="owner/repo1,owner/repo2" TOKEN=your_token

Custom output and limits

make connect-memory CONNECTOR=github SOURCE="facebook/react" OUTPUT=./memory/custom MAX_ITEMS=50 TOKEN=your_token

Direct CLI usage with interactive token input

python memory_connectors/memory_connect.py github "microsoft/vscode" --max-items 100

Include specific content types

python memory_connectors/memory_connect.py github "owner/repo" --include-issues --include-prs --include-wiki --token your_token

#### 获取GitHub个人访问令牌

1. 首选 
1. 点击“生成新令牌”→ “生成新令牌（经典）”
1. 设置过期时间并选择范围：
   - 对于 **公共存储库**: `public_repo` 范围
   - 对于 **私有存储库**: `repo` 范围（完全访问）
1. 点击“生成令牌”并复制生成的令牌
1. 将令牌与 `--token` 参数或在提示时输入

**备注**：确保您的令牌安全，永远不要将其提交给版本控制！

#### 谷歌文档实时集成

Basic usage - specific folder

make connect-memory CONNECTOR=google-docs SOURCE="1ABC123DEF456_folder_id" TOKEN=your_access_token

Using Google Drive folder URL

make connect-memory CONNECTOR=google-docs SOURCE="https://drive.google.com/drive/folders/1ABC123DEF456" TOKEN=your_token

Custom output and limits

make connect-memory CONNECTOR=google-docs SOURCE="folder_id" OUTPUT=./memory/custom MAX_ITEMS=20 TOKEN=your_token

Direct CLI usage with interactive token input

python memory_connectors/memory_connect.py google-docs "1ABC123DEF456_folder_id" --max-items 15

#### 获取Google Drive访问令牌

**选项1:谷歌OAuth 2.0游乐场（快速测试）**

1. 首选 [谷歌OAuth 2.0游乐场](https://developers.google.com/oauthplayground/)
1. 在“选择和授权API”部分：
   - 查找“驱动器API v3”
   - 选择 `https://www.googleapis.com/auth/drive.readonly`
1. 点击“授权API”并登录您的Google帐户
1. 点击“代币兑换授权码”
1. 复制“访问令牌”（有效期约为1小时）

**选项2：谷歌云控制台（生产使用）**

1. 首选 [谷歌云控制台](https://console.cloud.google.com/)
1. 创建新项目或选择现有项目
1. 启用“Google Drive API”
1. 转到“凭据”→ “创建凭据”→ “OAuth 2.0客户端ID”
1. 如果需要，配置OAuth同意屏幕
1. 下载凭据JSON文件
1. 使用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小时）。对于生产使用，实现令牌刷新或使用服务帐户。

### 存储器结构

连接器会自动将您的对话组织成：

- **话题**：按主题分组的对话（人工智能代理、编程、产品战略等）
- **用户档案**：您的沟通风格和偏好
- **实体链接**：相互参照的关系和项目
- **搜索策略**：针对内存代理发现进行了优化

组织结构示例：

memory/mcp-server/ ├── user.md # Your profile and navigation └── entities/ └── chatgpt-history/ ├── index.md # Overview and usage examples ├── topics/ # Topic-organized conversation lists │ ├── dria.md │ ├── ai-agents.md │ └── programming.md └── conversations/ # Individual conversation files ├── conv_0-project-discussion.md └── conv_1-technical-planning.md

### 测试你的记忆力

导入后，测试内存系统：

1. 启动mem代理： `make run-agent`
1. 使用MCP服务器启动Claude Desktop
1. 问以下问题：
   - “你能告诉我我们的产品路线图吗？”
   - “我对AI代理框架有什么看法？”
   - “总结我最近的技术讨论”

代理应该访问您的真实对话历史记录，而不是提供通用的响应。

## 建筑

### Mem代理

- **Dria记忆剂**：专门针对内存管理和检索进行了微调的LLM
- **本地部署**：通过LM Studio（MLX）或vLLM运行，以保护隐私和提高速度
- **多种变体**：4位、8位和bf16量化可用
- **工具集成**：专为文件操作和内存搜索而构建

### 存储结构

- **黑曜石风格**：带有维基链接导航的Markdown文件
- **主题组织**：按主题自动分类
- **实体关系**：对话之间的交叉引用连接
- **搜索优化**：结构化以实现高效的代理发现

### MCP集成

- **FastMCP框架**：高性能模型上下文协议服务器
- **克劳德桌面版**：克劳德的桌面应用程序
- **克劳德代码**：Anthropic的代理编码工具，位于您的终端中

#### Claude代码设置

**先决条件**：首先启动内存服务器：

make run-agent # Required: vLLM or MLX model server must be running

**添加MCP服务器：**

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

**验证和使用：**

claude mcp list # Should show mem-agent as connected

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

- **工具执行**：内存操作的沙盒代码执行
- **调试日志记录**：用于故障排除的全面日志记录

#### ChatGPT集成

**先决条件**：完成内存设置并启动本地代理：

make setup # Configure memory directory make run-agent # Start local vLLM/MLX model server

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

make serve-mcp-http # Starts server on localhost:8081/mcp

**用ngrok（独立端子）露出：**

ngrok http 8081 # Copy the forwarding URL

**配置ChatGPT：**

1. 首选 [ChatGPT设置→ 连接器](https://chatgpt.com/#settings/Connectors)
1. 启用 **开发者模式** 在高级设置中
1. 添加新的MCP服务器：
   - **名字**: `mem-agent`
   - **统一资源定位符**: `https://your-ngrok-url.ngrok.io/mcp`
   - **协议**：HTTP
   - **认证**：无

**ChatGPT中的用法：**
选择 **开发者模式** → 选择 `mem-agent` 连接器→ 问以下问题：

- “使用mem-agent在我的记忆中搜索有关人工智能研究的讨论”
- “查询我的内存以获取有关最近项目工作的信息”

## 故障排除

### 常见问题

**代理返回通用响应，而不是使用内存：**

- 检查配置的路径中是否存在内存文件
- 验证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项来限制处理范围
- 验证导出是否包含预期的数据结构

### 调试模式

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

FASTMCP_LOG_LEVEL=DEBUG make serve-mcp

或者在操作过程中在日志文件中检查代理的内部推理。

## 发展

### 添加新连接器

1. 创建继承自的连接器类 `BaseMemoryConnector`
1. 实施所需方法： `extract_data()`, `organize_data()`, `generate_memory_files()`
1. 添加到中的连接器注册表 `memory_connect.py`
1. 用用法示例更新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]: # Parse source data pass

def organize_data(self, extracted_data: Dict[str, Any]) -> Dict[str, Any]: # Organize into topics pass

def generate_memory_files(self, organized_data: Dict[str, Any]) -> None: # Generate markdown files pass

### 贡献

该系统被设计为不影响主mem-agent mcp存储库的本地附加组件：

- 内存连接器是本地扩展
- 保持传统兼容性
- 所有更改都保留现有功能
- 调试改进增强了故障排除

欢迎对新连接器和改进的请求！