MCP代理内存-v2.0
生产就绪的MCP服务器,为多代理协作提供共享内存。
概述
MCP Agent Memory是一个增强的模型上下文协议(MCP)服务器,它使多个AI代理(如克劳德代码实例)能够通过共享内存空间异步通信。把它想象成一个复杂的共享记事本,人工智能代理可以在其中留言、搜索信息并协调他们的工作。
主要特点
- 🔒 并发安全 -共享环境的文件锁定
- 📝 完整CRUD -创建、读取、更新、删除操作
- 🔍 高级搜索 -在所有字段中进行全文搜索
- 🏷️ 组织 -标签、优先级、元数据
- 📊 分析 -全面的内存统计
- 💾 可靠的 -自动备份和损坏恢复
- 📋 结构化日志记录 -完整的操作可见性
- 🛡️ 健康监测 -内置健康检查系统
快速开始
安装
- 克隆或下载 此存储库
- 安装依赖项:```bash
pip install mcp pydantic
1. **运行服务器:**```bash
python3 shared_memory_mcp.py
基本用法```python
Add a memory entry
await add_memory(
agent_name="claude-alpha",
content="Analysis complete. Found 3 key insights.",
tags=["analysis", "complete"],
priority="high"
)
Search for entries
results = await search_memory(query="analysis")
Get statistics
stats = await get_memory_stats()
### 配置
添加到您的Claude代码配置中(`~/.claudeCode/config.json`):```json
{
"mcpServers": {
"shared-memory": {
"command": "python3",
"args": ["/path/to/shared_memory_mcp.py"]
}
}
}
v2.0中的新增功能
新工具(共6个)
- ✅
update_memory-修改现有条目 - ✅
delete_memory-删除特定条目 - ✅
get_memory-按ID检索单个条目 - ✅
search_memory-全文搜索 - ✅
get_memory_stats-内存分析 - ✅
health_check-系统健康监测
增强工具
- ⚡
add_memory-现在支持标签、优先级、元数据 - ⚡
read_memory-高级过滤和排序 - ⚡
clear_memory-清除前自动备份
核心改进
- 🔒 线程安全文件锁定
- 💾 自动备份(保留10个)
- 📝 结构化日志记录
- 🔄 1000个条目时自动旋转
- 🛡️ 追回腐败
- 🆔 唯一条目ID(UUID)
零破坏性变化! 所有v1代码无需修改即可工作。
建筑```
MCP Agent Memory v2.0
├── shared_memory_mcp.py # Main server (9 MCP tools)
├── utils/
│ ├── file_lock.py # Concurrency safety
│ └── logger.py # Structured logging
├── tests/
│ ├── test_memory_operations.py
│ └── test_concurrency.py
└── docs/
├── API_REFERENCE_V2.md # Complete API docs
├── CHANGELOG_V2.md # Version history
├── UPGRADE_GUIDE.md # v1→v2 migration
└── IMPLEMENTATION_SUMMARY.md
### 存储```
~/.shared_memory_mcp/
├── memory.json # Main storage
├── mcp_memory.log # Rotating logs
└── backups/ # Auto-backups (10 kept)
└── memory_backup_*.json
文档
入门指南
- 📖 共享_内存_自述.md -完整用户指南
- 🚀 快速入门指南 -5分钟设置
参考
- 📚 API 参考 -完整的API文件
- 📋 更新日志 -2.0版本更改
- ⬆️ 升级指南 -从v1迁移到v2
开发者
- 🔧 实施总结 -技术细节
- 🧪 测试指导 -如何运行测试
- 🏗️ 建筑细部 -系统设计
API概述
存储器操作
| 工具 | 描述 | 类型 |
|---|---|---|
add_memory |
创建带有标签/优先级的新条目 | 写入 |
read_memory |
使用高级过滤功能阅读 | 阅读 |
update_memory |
修改现有条目 | 写入 |
delete_memory |
删除特定条目 | 写入 |
get_memory |
按ID检索单个条目 | 读取 |
search_memory |
全文搜索 | 阅读 |
get_memory_stats |
内存分析 | 阅读 |
clear_memory |
清除所有条目 | 写入 |
health_check |
系统健康状态 | 读取 |
看 API 参考 详细文档。
测试
运行基本测试```bash
python3 run_basic_tests.py
### 运行完整测试套件(需要pytest)```bash
pip install pytest pytest-cov
pytest tests/ -v --cov
测试覆盖率
- ✅ 70+测试用例
- ✅ 单元测试(操作、过滤、搜索)
- ✅ 并发测试(锁定、原子写入)
- ✅ 集成测试
发展
设置开发环境```bash
Install dev dependencies
pip install -r requirements-dev.txt
Install pre-commit hooks
pre-commit install
Run tests
python3 run_basic_tests.py
Type checking
mypy shared_memory_mcp.py
Linting
ruff check .
### 代码质量工具
- ✅ pytest-测试框架
- ✅ mypy-类型检查
- ✅ ruff-镶边和格式化
- ✅ 预提交-Git钩子
______________________________________________________________________
## 演出
### 典型操作
- 添加条目:5-15ms(包括备份)
- 读取条目:2-10ms
- 搜索(100条):1-5ms
- 更新/删除:5-15ms(包括备份)
### 限制
- 每篇最多200字
- 每个条目的最大标签数:10
- 旋转前的最大输入数:1000
- 文件锁定超时:10秒
- 备份保留:10次备份
______________________________________________________________________
## 用例
### 多Agent协作```python
# Agent A: Data collector
await add_memory(
agent_name="data-collector",
content="Collected 10,000 data points",
tags=["data", "ready-for-analysis"],
priority="high"
)
# Agent B: Analyzer picks up work
pending = await read_memory(tags=["ready-for-analysis"])
任务跟踪```python
Start task
result = await add_memory(
agent_name="worker",
content="Starting analysis...",
tags=["analysis", "in-progress"],
priority="high"
)
Update on completion
await update_memory(
entry_id=result.entry_id,
tags=["analysis", "complete"],
priority="low"
)
### 知识库```python
# Search for information
results = await search_memory(
query="user behavior insights",
limit=10
)
# Get statistics
stats = await get_memory_stats()
print(f"Total knowledge: {stats.total_entries} entries")
常见问题解答
Q: v2与v1代码兼容吗?
A: 是的!100%向后兼容。所有v1代码无需更改即可工作。
Q: 移民是如何运作的?
A: 自动。v2检测v1格式并在第一次写入时迁移。
Q: 多个代理可以同时写入吗?
A: 是的!文件锁定可确保安全的并发访问。
Q: 如果存储损坏,会发生什么?
A: 从最近的有效备份中自动恢复。
Q: 它使用了多少磁盘空间?
A: 每个条目约500-1000字节。1000个条目≈500KB-1MB。
Q: 我可以将其用于生产吗?
A: 是的!v2具有生产就绪的可靠性功能。
看 升级_指南.md 了解更多详情。
故障排除
常见问题
文件锁定超时```bash
Check for other running instances
ps aux | grep shared_memory_mcp
Increase timeout in code if needed
**JSON解析错误**```bash
# Restore from backup
cp ~/.shared_memory_mcp/backups/memory_backup_*.json \
~/.shared_memory_mcp/memory.json
检查系统运行状况```python
health = await health_check({})
print(health.message) # "All systems operational"
### 日志```bash
# View logs
tail -f ~/.shared_memory_mcp/mcp_memory.log
# Check for errors
grep ERROR ~/.shared_memory_mcp/mcp_memory.log
贡献
欢迎投稿!拜托:
- 分叉存储库
- 创建要素分支
- 为新功能添加测试
- 确保所有测试通过
- 提交拉取请求
代码的风格
- 使用类型提示
- 遵循现有模式
- 添加文档字符串
- 运行预提交钩子
许可证
MIT许可证-有关详细信息,请参阅许可证文件
更新日志
v2.0.0(2025-10-30)
- ✅ 增加了并发安全(文件锁定)
- ✅ 添加结构化日志记录
- ✅ 新增6个MCP工具
- ✅ 增强的数据模型(标签、优先级、元数据)
- ✅ 添加了自动备份和恢复
- ✅ 添加了全面的测试套件(70+测试)
- ✅ 添加了完整的文档
- ✅ 零突破性变化
看 CHANGELOG_V2.md 详细的历史。
致谢
基于Anthropic的模型上下文协议(MCP)构建。
增强了生产就绪功能,同时保持了原始设计的简洁和优雅。
链接
- 文档: ./docs/
- 测验: ./测试/
- API参考: API_REFERENCE_V2.md
- MCP协议: https://modelcontextprotocol.io/
由以下材料制成❤️ 用于多智能体协作
版本2.0.0-生产就绪 🚀
