MCP代理内存-v2.0
生产就绪的MCP服务器，为多代理协作提供共享内存。
______________________________________________________________________
概述
MCP Agent Memory是一个增强的模型上下文协议（MCP）服务器，它使多个AI代理（如克劳德代码实例）能够通过共享内存空间异步通信。把它想象成一个复杂的共享记事本，人工智能代理可以在其中留言、搜索信息并协调他们的工作。
主要特点
- 🔒 并发安全 -共享环境的文件锁定
- 📝 完整CRUD -创建、读取、更新、删除操作
- 🔍 高级搜索 -在所有字段中进行全文搜索
- 🏷️ 组织 -标签、优先级、元数据
- 📊 分析 -全面的内存统计
- 💾 可靠的 -自动备份和损坏恢复
- 📋 结构化日志记录 -完整的操作可见性
- 🛡️ 健康监测 -内置健康检查系统
______________________________________________________________________
快速开始
安装
- 克隆或下载 此存储库
- 安装依赖项：
pip install mcp pydantic- 运行服务器：
python3 shared_memory_mcp.py基本用法
# 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):
{
"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概述
存储器操作
| 工具 | 描述 | 类型 |
|---|---|---|
add_memory | 创建带有标签/优先级的新条目 | 写入 |
read_memory | 使用高级过滤功能阅读 | 阅读 |
update_memory | 修改现有条目 | 写入 |
delete_memory | 删除特定条目 | 写入 |
get_memory | 按ID检索单个条目 | 读取 |
search_memory | 全文搜索 | 阅读 |
get_memory_stats | 内存分析 | 阅读 |
clear_memory | 清除所有条目 | 写入 |
health_check | 系统健康状态 | 读取 |
看 API 参考 详细文档。
______________________________________________________________________
测试
运行基本测试
python3 run_basic_tests.py运行完整测试套件（需要pytest）
pip install pytest pytest-cov
pytest tests/ -v --cov测试覆盖率
- ✅ 70+测试用例
- ✅ 单元测试（操作、过滤、搜索）
- ✅ 并发测试（锁定、原子写入）
- ✅ 集成测试
______________________________________________________________________
发展
设置开发环境
# 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协作
# 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"])任务跟踪
# 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"
)知识库
# 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 了解更多详情。
______________________________________________________________________
故障排除
常见问题
文件锁定超时
# Check for other running instances
ps aux | grep shared_memory_mcp
# Increase timeout in code if neededJSON解析错误
# Restore from backup
cp ~/.shared_memory_mcp/backups/memory_backup_*.json \
~/.shared_memory_mcp/memory.json检查系统运行状况
health = await health_check({})
print(health.message) # "All systems operational"日志
# 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-生产就绪* 🚀