使用说明

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 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个项目

#### Notion Workspace Import
```bash
# 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

#### Getting ChatGPT Export
1. Go to [ChatGPT Settings](https://chatgpt.com/settings/data-controls)
2. Click "Export data"
3. Wait for email with download link
4. Extract the ZIP file
5. Use the extracted folder or ZIP file with the connector

#### Nuclino Workspace Import
```bash
# 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

#### Getting Notion Export
1. Go to your Notion workspace settings
2. Click "Settings & members" → "Settings"
3. Scroll to "Export content" and click "Export all workspace content"
4. Choose "Markdown & CSV" format
5. Click "Export" and wait for the download
6. Use the downloaded ZIP file with the connector

#### Getting Nuclino Export
1. Go to your Nuclino workspace
2. Open the main menu (☰) in the top left
3. Click the three dots (⋮) next to your workspace name
4. Select "Workspace settings"
5. Click "Export Workspace" in the Export section
6. Save the generated ZIP file
7. Use the downloaded ZIP file with the connector

#### GitHub Live Integration
```bash
# 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

#### Getting GitHub Personal Access Token
1. Go to [GitHub Settings → Tokens](https://github.com/settings/tokens)
2. Click "Generate new token" → "Generate new token (classic)"
3. Set expiration and select scopes:
   - For **public repositories**: `public_repo` scope
   - For **private repositories**: `repo` scope (full access)
4. Click "Generate token" and copy the generated token
5. Use the token with the `--token` parameter or enter it when prompted

**Note**: Keep your token secure and never commit it to version control!

#### Google Docs Live Integration
```bash
# 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

#### Getting Google Drive Access Token

**Option 1: Google OAuth 2.0 Playground (Quick Testing)**
1. Go to [Google OAuth 2.0 Playground](https://developers.google.com/oauthplayground/)
2. In "Select & Authorize APIs" section:
   - Find "Drive API v3"
   - Select `https://www.googleapis.com/auth/drive.readonly`
3. Click "Authorize APIs" and sign in to your Google account
4. Click "Exchange authorization code for tokens"
5. Copy the "Access token" (valid for ~1 hour)

**Option 2: Google Cloud Console (Production Use)**
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing one
3. Enable the "Google Drive API"
4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID"
5. Configure OAuth consent screen if needed
6. Download the credentials JSON file
7. Use Google's OAuth 2.0 libraries to get access tokens

**Required Scopes**: `https://www.googleapis.com/auth/drive.readonly`

**Finding Folder ID from Google Drive URL**:
- From URL: `https://drive.google.com/drive/folders/1ABC123DEF456ghi789`  
- Folder ID: `1ABC123DEF456ghi789`

**Note**: Access tokens expire (usually 1 hour). For production use, implement token refresh or use service accounts.

### Memory Organization

The connectors automatically organize your conversations into:

- **Topics**: Conversations grouped by subject (AI Agents, Programming, Product Strategy, etc.)
- **User Profile**: Your communication style and preferences
- **Entity Links**: Cross-referenced relationships and projects
- **Search Strategy**: Optimized for mem-agent discovery

Example organized structure:

内存/mcp服务器/ ├── user.md#您的个人资料和导航 └── 实体/ └── chatgpt历史/ ├── index.md#概述和使用示例 ├── topics/#主题组织对话列表 │ ├── dria.md │ ├── ai-agents.md │ └── 编程.md └── 对话/#单个对话文件 ├── conv_0项目调试.md └── conv_1技术规划.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存储库的本地附加组件：

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

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