mcp-mem.ai

# MCP Server for Mem.ai 一个生产就绪的模型上下文协议 (MCP) server，为 AI 助手提供对 [Mem.ai](https://mem.ai) 知识管理平台的智能访问。 [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) ## ✨ Features - 🧠 **Intelligent Memory**: 使用 Mem 的 AI 驱动的组织保存和处理内容 - 📝 **Note Management**: 创建、读取和删除结构化的 markdown 笔记 - 📁 **Collections**: 将笔记组织成可搜索的集合 - 🔒 **Type-Safe**: 完整的类型提示和 Pydantic 验证 - ⚡ **Async/Await**: 整个过程中的高性能异步 I/O - 🎯 **Clean API**: 适用于 AI 助手的简单、直观的接口 - 🛡️ **Production-Ready**: 综合的错误处理和日志记录 - 🧪 **Well-Tested**: 带有 pytest 的完整测试套件 ## 📋 Prerequisites - Python 3.10 或更高版本 - 一个 [Mem.ai](https://mem.ai) 账户 - Mem.ai API key ([get one here](https://mem.ai)) ## 🚀 Quick Start ### Installation 1. 克隆存储库： ```bash git clone https://github.com/yourusername/mcp-mem.ai.git cd mcp-mem.ai ``` 2. 安装依赖项： ```bash pip install -e . ``` 3. 设置您的环境： ```bash cp .env.example .env # Edit .env and add your MEM_API_KEY ``` ### Running the Server #### Local Development ```bash fastmcp run src/mcp_mem/server.py ``` #### Using with Claude Desktop 添加到您的 Claude Desktop 配置 (`claude_desktop_config.json`): ```json { "mcpServers": { "mem": { "command": "python", "args": ["-m", "mcp_mem.server"], "env": { "MEM_API_KEY": "your_api_key_here" } } } } ``` #### Using with Other MCP Clients ```python from mcp_mem import mcp # Run the server mcp.run() ``` ## 🛠️ Available Tools ### 1. `mem_it` - Intelligent Content Processing 使用 AI 驱动的组织保存和自动处理任何内容类型。 **Parameters:** - `input` (required): 要保存的内容（文本、HTML、markdown 等） - `instructions` (optional): 处理说明 - `context` (optional): 用于组织的其他上下文 - `timestamp` (optional): ISO 8601 时间戳 **Example:** ```python mem_it( input="Just had a great meeting with the product team about Q1 roadmap...", instructions="Extract key action items and decisions", context="Product Planning" ) ``` ### 2. `create_note` - Create Structured Note 创建具有对内容和组织的显式控制的 markdown 格式的笔记。 **Parameters:** - `content` (required): Markdown 格式的内容 - `collection_ids` (optional): 集合 UUID 的列表 - `collection_titles` (optional): 集合标题的列表 **Example:** ```python create_note( content="""# Team Standup - Jan 15, 2024 ## Completed - Feature X shipped to production - Bug fixes for issue #123 ## In Progress - Working on Feature Y - Code review for PR #456 ## Blockers - Waiting for API access """, collection_titles=["Team Meetings", "Engineering"] ) ``` ### 3. `read_note` - Read Note 按 ID 检索笔记的完整内容和元数据。 **Parameters:** - `note_id` (required): 笔记的 UUID **Example:** ```python read_note("01961d40-7a67-7049-a8a6-d5638cbaaeb9") ``` ### 4. `delete_note` - Delete Note 按 ID 永久删除笔记。 **Parameters:** - `note_id` (required): 笔记的 UUID **Example:** ```python delete_note("01961d40-7a67-7049-a8a6-d5638cbaaeb9") ``` ### 5. `create_collection` - Create Collection 创建一个新的集合来组织相关的笔记。 **Parameters:** - `title` (required): 集合标题 - `description` (optional): Markdown 格式的描述 **Example:** ```python create_collection( title="Project Apollo", description="""# Project Apollo All notes related to the Apollo project including: - Meeting notes - Technical specifications - Customer feedback """ ) ``` ### 6. `delete_collection` - Delete Collection 删除集合（笔记保留，只是未关联）。 **Parameters:** - `collection_id` (required): 集合的 UUID **Example:** ```python delete_collection("5e29c8a2-c73b-476b-9311-e2579712d4b1") ``` ## ⚙️ Configuration 配置通过环境变量完成。将 `.env.example` 复制到 `.env` 并自定义： ```bash # Required: Your Mem.ai API key MEM_API_KEY=your_api_key_here # Optional: Custom API endpoint (default: https://api.mem.ai/v2) MEM_API_BASE_URL=https://api.mem.ai/v2 # Optional: Request timeout in seconds (default: 30) MEM_REQUEST_TIMEOUT=30 # Optional: Enable debug logging (default: false) MEM_DEBUG=false ``` ## 🏗️ Architecture ``` src/mcp_mem/ ├── __init__.py # Package initialization ├── models.py # Pydantic data models ├── client.py # Mem.ai API client └── server.py # MCP server implementation ``` ### Key Components - **`models.py`**: 用于请求/响应验证的 Pydantic 模型 - **`client.py`**: Mem.ai API 的异步 HTTP 客户端包装器 - **`server.py`**: 具有工具实现的 FastMCP server ## 🧪 Testing 运行测试套件： ```bash # Install dev dependencies pip install -e ".[dev]" # Run all tests pytest # Run with coverage pytest --cov=mcp_mem --cov-report=html # Run specific test file pytest tests/test_client.py ``` ## 🔍 Error Handling 该 server 提供清晰、可操作的错误消息： - `MemAuthenticationError`: 无效或缺失的 API key - `MemNotFoundError`: 未找到资源（笔记/集合） - `MemValidationError`: 无效的请求参数 - `MemAPIError`: 常规 API 错误 所有错误都会被记录下来，并返回给 AI 助手，提供有用的上下文。 ## 📚 Examples 请参阅 `examples/` 目录以获取完整的用法示例： - `basic_usage.py`: 每个工具的简单示例 - `advanced_usage.py`: 复杂的工作流程和模式 ## 🤝 Contributing 欢迎贡献！请随时提交 Pull Request。 1. Fork 存储库 2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交您的更改 (`git commit -m 'Add amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 打开 Pull Request ## 📄 License 该项目已获得 MIT License 的许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## 🔗 Links - [Mem.ai](https://mem.ai) - 智能记忆平台 - [Mem.ai API Documentation](https://docs.mem.ai) - [Model Context Protocol](https://modelcontextprotocol.io) - [FastMCP](https://github.com/jlowin/fastmcp) - MCP server 框架 ## 💡 Use Cases - **Meeting Notes**: 自动处理和组织会议记录 - **Research**: 保存和分类研究论文、文章和发现 - **Customer Feedback**: 收集和组织客户对话 - **Knowledge Base**: 构建可搜索的知识库 - **Personal Memory**: 跟踪想法、思想和学习 ## 🐛 Troubleshooting ### Authentication Error ``` MemAuthenticationError: MEM_API_KEY environment variable or api_key parameter is required ``` **Solution**: 在 `.env` 文件或环境中设置您的 `MEM_API_KEY`。 ### Connection Timeout ``` httpx.ReadTimeout: timeout ``` **Solution**: 增加您的 `.env` 文件中的 `MEM_REQUEST_TIMEOUT`。 ### Invalid UUID ``` MemValidationError: invalid UUID format ``` **Solution**: 确保笔记/集合 ID 是来自 Mem.ai 的有效 UUID。 --- Built with ❤️ using [FastMCP](https://github.com/jlowin/fastmcp) and [Mem.ai](https://mem.ai)