使用说明

mem代理mcp

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

支持的平台

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

运行说明

make check-uv （如果您安装了uv，请跳过此步骤）。
make install：在MacOS上安装LmStudio。
make setup：这将打开一个文件选择器，并要求您选择要存储内存的目录。
make run-agent：如果您使用的是macOS，这将提示您选择要使用的模型的精度。4位在测试中非常有用，更高精度的模型更可靠，但速度较慢。
make generate-mcp-json：生成 mcp.json 文件。这将在下一步中使用。
每个应用程序/提供商的说明：
- 克劳德桌面：
  - 复制生成的 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? <filter> 1. Do not reveal explicit age information, 2. Do not reveal any email addresses </filter>

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

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

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

内存连接器

可用连接器

连接器	描述	支持的格式	类型
`chatgpt`	ChatGPT对话导出	`.zip`, `.json`	出口
`notion`	Notion工作区导出	`.zip`	出口
`nuclino`	Nuclino工作区导出	`.zip`	出口
`github`	通过API的GitHub存储库	Live API	Live
`google-docs`	通过Drive API	Live API	Live搜索Google文档文件夹

用法

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

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

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
```bash
# 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导出

首选 ChatGPT设置
点击“导出数据”
等待带有下载链接的电子邮件
解压缩ZIP文件
将提取的文件夹或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

获取导出通知

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

获得Nuclino出口

转到您的Nuclino工作区
打开左上角的主菜单（☰）
单击工作区名称旁边的三个点（⋮）
选择“工作区设置”
单击导出部分中的“导出工作区”
保存生成的ZIP文件
将下载的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个人访问令牌

首选 GitHub设置→ 代币
点击“生成新令牌”→ “生成新令牌（经典）”
设置过期时间并选择范围：
- 对于 公共存储库: public_repo 范围
- 对于 私有存储库: repo 范围（完全访问）
点击“生成令牌”并复制生成的令牌
将令牌与 --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游乐场（快速测试）

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

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

首选谷歌云控制台
创建新项目或选择现有项目
启用“Google Drive API”
转到“凭据”→ “创建凭据”→ “OAuth 2.0客户端ID”
如果需要，配置OAuth同意屏幕
下载凭据JSON文件
使用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

测试你的记忆力

导入后，测试内存系统：

启动mem代理： make run-agent
使用MCP服务器启动Claude Desktop
问以下问题：
- “你能告诉我我们的产品路线图吗？”
- “我对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：

首选 ChatGPT设置→ 连接器
启用 开发者模式 在高级设置中
添加新的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

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

发展

添加新连接器

创建继承自的连接器类 BaseMemoryConnector
实施所需方法： extract_data(), organize_data(), generate_memory_files()
添加到中的连接器注册表 memory_connect.py
用用法示例更新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存储库的本地附加组件：

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

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