MCP内存服务器-Python实现
一个完整的Python官方移植 TypeScript MCP内存服务器该服务器通过模型上下文协议（MCP）提供知识图存储和检索功能。
⚠️ 平台兼容性
此实现仅在macOS上开发和测试。 虽然它应该在其他类Unix系统上工作，但还没有在Windows、Linux或其他平台上进行测试。在其他平台上使用由您自行承担风险。
特性
- 完整的知识图谱管理：存储和管理实体、关系和观察结果
- JSONL文件格式：与TypeScript版本的文件格式兼容
- 9 MCP工具：与原始TypeScript实现完全相同的功能
- 搜索功能：按名称、类型或观察内容查询实体
- 图的遍历：探索实体连接和关系
- 环境配置：可定制的存储位置
开发环境设置
先决条件
- Python 3.8或更高版本
- macOS（测试平台）
虚拟环境设置
- 创建虚拟环境：
python3 -m venv .venv- 激活虚拟环境：
source .venv/bin/activate- 安装依赖项：
pip install -r requirements.txt- 完成后停用：
deactivate安装
- 克隆或下载此存储库
- 设置虚拟环境 （见上文）
- 测试安装：
source .venv/bin/activate
python mcp_memory_server.py服务器应启动并通过stdin/stdout等待MCP协议消息。
配置
环境变量
MEMORY_FILE_PATH：内存存储文件的路径（默认值：./memory.json)
例子：
export MEMORY_FILE_PATH="/path/to/my/memory.json"
source .venv/bin/activate
python mcp_memory_server.pyMCP客户端配置
克劳德桌面
将此配置添加到您的Claude Desktop设置中：
{
"mcpServers": {
"memory": {
"command": "python",
"args": ["/path/to/mcp_memory_server.py"],
"env": {
"MEMORY_FILE_PATH": "/path/to/memory.json"
}
}
}
}备注：请确保在运行之前激活您的虚拟环境，或者在虚拟环境中使用Python解释器的完整路径。
光标IDE
- 打开光标IDE设置
- 导航到MCP服务器配置
- 使用以下命令添加新服务器：
- 名字: memory - 命令: python - 参数: ["/path/to/mcp_memory_server.py"] - 环境: {"MEMORY_FILE_PATH": "/path/to/memory.json"}
AWS Q CLI
在AWS Q CLI MCP设置中配置内存服务器：
{
"mcp_servers": {
"memory": {
"command": ["python", "/path/to/mcp_memory_server.py"],
"env": {
"MEMORY_FILE_PATH": "/path/to/memory.json"
}
}
}
}通用MCP客户端配置
对于支持基于stdio的服务器的任何MCP客户端：
{
"servers": {
"memory": {
"command": "python",
"args": ["/path/to/mcp_memory_server.py"],
"cwd": "/path/to/server/directory",
"env": {
"MEMORY_FILE_PATH": "/path/to/memory.json"
}
}
}
}与Claude一起使用
要充分利用内存服务器，请将此系统提示添加到Claude中：
Follow these steps for each interaction:
1. User Identification:
- You should assume that you are interacting with default_user
- If you have not identified default_user, proactively try to do so.
2. Memory Retrieval:
- Always begin your chat by saying only "Remembering..." and retrieve all relevant information from your knowledge graph
- Always refer to your knowledge graph as your "memory"
3. Memory
- While conversing with the user, be attentive to any new information that falls into these categories:
a) Basic Identity (age, gender, location, job title, education level, etc.)
b) Behaviors (interests, habits, etc.)
c) Preferences (communication style, preferred language, etc.)
d) Goals (goals, targets, aspirations, etc.)
e) Relationships (personal and professional relationships up to 3 degrees of separation)
4. Memory Update:
- If any new information was gathered during the interaction, update your memory as follows:
a) Create entities for recurring organizations, people, and significant events
b) Connect them to the current entities using relations
c) Store facts about them as observations可用工具
服务器提供了9个MCP工具，与TypeScript版本完全兼容：
1. create_entities
在知识图中创建新实体。
输入：
{
"entities": [
{
"name": "John Doe",
"entityType": "person",
"observations": ["Software engineer", "Lives in San Francisco"]
}
]
}2. create_relations
创建实体之间的关系。
输入：
{
"relations": [
{
"from": "John Doe",
"to": "Acme Corp",
"relationType": "works_at"
}
]
}3. add_observations
向现有实体添加新的观察结果。
输入：
{
"additions": [
{
"entityName": "John Doe",
"observations": ["Enjoys hiking", "Plays guitar"]
}
]
}4. delete_entities
删除实体及其关联关系。
输入：
{
"names": ["John Doe", "Jane Smith"]
}5. delete_relations
删除特定关系。
输入：
{
"relations": [
{
"from": "John Doe",
"to": "Acme Corp",
"relationType": "works_at"
}
]
}6. delete_observations
从实体中删除具体观察结果。
输入：
{
"deletions": [
{
"entityName": "John Doe",
"observations": ["Old observation to remove"]
}
]
}7. read_graph
检索整个知识图谱。
输入： 无
输出： 包含所有实体和关系的完整图。
8. search_nodes
按查询字符串搜索实体。
输入：
{
"query": "software engineer"
}输出： 与查询匹配的实体及其相互连接。
9. open_nodes
获取特定实体及其连接。
输入：
{
"names": ["John Doe", "Acme Corp"]
}输出： 被请求的实体加上任何关联实体和所有相关关系。
文件格式
服务器使用JSONL（JSON行）格式进行存储，每行包含一个实体或关系：
{"type": "entity", "name": "John Doe", "entityType": "person", "observations": ["Software engineer"]}
{"type": "relation", "from": "John Doe", "to": "Acme Corp", "relationType": "works_at"}这种格式与TypeScript版本完全兼容，允许您迁移现有的内存文件。
直接服务器测试
您可以在没有MCP客户端的情况下直接测试服务器：
- 启动服务器：
source .venv/bin/activate
python mcp_memory_server.py- 通过stdin发送MCP协议消息。 服务器需要遵循MCP规范的JSON-RPC 2.0消息。
错误处理
该服务器包括全面的错误处理功能，用于：
- 内存文件中的JSON格式错误
- 缺少必填字段
- 文件I/O错误
- 无效的工具参数
- 并发访问保护
演出
服务器针对以下方面进行了优化：
- 包含数百个实体的图形
- 跨实体名称、类型和观察值进行高效搜索
- 快速文件I/O，内存使用量最小
- 并发访问安全
日志记录
服务器记录重要事件以帮助调试：
- 服务器启动和配置
- 图形加载和保存操作
- 错误条件和警告
- 工具执行结果
兼容性
这个Python实现提供了：
- 功能兼容性：适用于TypeScript版本中的现有memory.json文件
- 工具兼容性：所有9个工具的工作方式与TypeScript版本相同
- 文件格式兼容性：可以读/写相同的JSONL格式
- 客户端兼容性：适用于Claude Desktop、Cursor IDE、AWS Q CLI和其他MCP客户端
发展
项目结构
mcp-memory-server-py/
├── mcp_memory_server.py # Main server implementation
├── requirements.txt # Python dependencies
├── README.md # This documentation贡献
在为该项目做出贡献时：
- 保持与TypeScript版本的兼容性
- 遵循Python最佳实践和PEP 8
- 添加全面的错误处理
- 更新文档以了解任何更改
- 在macOS（主要支持的平台）上进行测试
许可证
此实现遵循与原始TypeScript MCP内存服务器相同的许可。
支持
对于问题、错误或功能请求，请参阅原始的MCP内存服务器文档，并针对此Python实现调整解决方案。
请记住：此实现仅在macOS上开发和测试。在其他平台上使用可能需要额外的测试和修改。