MCP Agent Memory

# MCP Agent Memory - v2.0 [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](./tests) **Production-ready MCP server providing shared memory for multi-agent collaboration.** --- ## Overview MCP Agent Memory is an enhanced Model Context Protocol (MCP) server that enables multiple AI agents (like Claude Code instances) to communicate asynchronously through a shared memory space. Think of it as a sophisticated shared notepad where AI agents can leave messages, search for information, and coordinate their work. ### Key Features - 🔒 **Concurrency Safe** - File locking for shared environments - 📝 **Full CRUD** - Create, Read, Update, Delete operations - 🔍 **Advanced Search** - Full-text search across all fields - 🏷️ **Organization** - Tags, priority levels, metadata - 📊 **Analytics** - Comprehensive memory statistics - 💾 **Reliable** - Automatic backups and corruption recovery - 📋 **Structured Logging** - Complete operation visibility - 🛡️ **Health Monitoring** - Built-in health check system --- ## Quick Start ### Installation 1. **Clone or download** this repository 2. **Install dependencies:** ```bash pip install mcp pydantic ``` 3. **Run the server:** ```bash python3 shared_memory_mcp.py ``` ### Basic Usage ```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() ``` ### Configuration Add to your Claude Code config (`~/.claudeCode/config.json`): ```json { "mcpServers": { "shared-memory": { "command": "python3", "args": ["/path/to/shared_memory_mcp.py"] } } } ``` --- ## What's New in v2.0 ### New Tools (6 total) - ✅ `update_memory` - Modify existing entries - ✅ `delete_memory` - Remove specific entries - ✅ `get_memory` - Retrieve single entry by ID - ✅ `search_memory` - Full-text search - ✅ `get_memory_stats` - Memory analytics - ✅ `health_check` - System health monitoring ### Enhanced Tools - ⚡ `add_memory` - Now supports tags, priority, metadata - ⚡ `read_memory` - Advanced filtering and sorting - ⚡ `clear_memory` - Auto-backup before clearing ### Core Improvements - 🔒 Thread-safe file locking - 💾 Automatic backups (keeps 10) - 📝 Structured logging - 🔄 Auto-rotation at 1000 entries - 🛡️ Corruption recovery - 🆔 Unique entry IDs (UUID) **Zero breaking changes!** All v1 code works without modification. --- ## Architecture ``` 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 ``` ### Storage ``` ~/.shared_memory_mcp/ ├── memory.json # Main storage ├── mcp_memory.log # Rotating logs └── backups/ # Auto-backups (10 kept) └── memory_backup_*.json ``` --- ## Documentation ### Getting Started - 📖 [SHARED_MEMORY_README.md](./SHARED_MEMORY_README.md) - Full user guide - 🚀 [Quick Start Guide](./archive/QUICKSTART.md) - 5-minute setup ### Reference - 📚 [API Reference](./docs/API_REFERENCE_V2.md) - Complete API documentation - 📋 [Changelog](./docs/CHANGELOG_V2.md) - Version 2.0 changes - ⬆️ [Upgrade Guide](./docs/UPGRADE_GUIDE.md) - Migrate from v1 to v2 ### Developer - 🔧 [Implementation Summary](./docs/IMPLEMENTATION_SUMMARY.md) - Technical details - 🧪 [Testing Guide](#testing) - How to run tests - 🏗️ [Architecture Details](#architecture) - System design --- ## API Overview ### Memory Operations | Tool | Description | Type | |------|-------------|------| | `add_memory` | Create new entry with tags/priority | Write | | `read_memory` | Read with advanced filtering | Read | | `update_memory` | Modify existing entry | Write | | `delete_memory` | Remove specific entry | Write | | `get_memory` | Retrieve single entry by ID | Read | | `search_memory` | Full-text search | Read | | `get_memory_stats` | Memory analytics | Read | | `clear_memory` | Clear all entries | Write | | `health_check` | System health status | Read | See [API Reference](./docs/API_REFERENCE_V2.md) for detailed documentation. --- ## Testing ### Run Basic Tests ```bash python3 run_basic_tests.py ``` ### Run Full Test Suite (requires pytest) ```bash pip install pytest pytest-cov pytest tests/ -v --cov ``` ### Test Coverage - ✅ 70+ test cases - ✅ Unit tests (operations, filtering, search) - ✅ Concurrency tests (locking, atomic writes) - ✅ Integration tests --- ## Development ### Setup Development Environment ```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 . ``` ### Code Quality Tools - ✅ pytest - Testing framework - ✅ mypy - Type checking - ✅ ruff - Linting and formatting - ✅ pre-commit - Git hooks --- ## Performance ### Typical Operations - Add entry: 5-15ms (includes backup) - Read entries: 2-10ms - Search (100 entries): 1-5ms - Update/Delete: 5-15ms (includes backup) ### Limits - Max words per entry: 200 - Max tags per entry: 10 - Max entries before rotation: 1000 - File lock timeout: 10 seconds - Backup retention: 10 backups --- ## Use Cases ### Multi-Agent Collaboration ```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"]) ``` ### Task Tracking ```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" ) ``` ### Knowledge Base ```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") ``` --- ## FAQ **Q: Is v2 compatible with v1 code?** A: Yes! 100% backward compatible. All v1 code works without changes. **Q: How does migration work?** A: Automatic. v2 detects v1 format and migrates on first write. **Q: Can multiple agents write simultaneously?** A: Yes! File locking ensures safe concurrent access. **Q: What happens if storage gets corrupted?** A: Automatic recovery from the most recent valid backup. **Q: How much disk space does it use?** A: ~500-1000 bytes per entry. 1000 entries ≈ 500KB-1MB. **Q: Can I use it for production?** A: Yes! v2 is production-ready with reliability features. See [UPGRADE_GUIDE.md](./docs/UPGRADE_GUIDE.md) for more details. --- ## Troubleshooting ### Common Issues **File lock timeout** ```bash # Check for other running instances ps aux | grep shared_memory_mcp # Increase timeout in code if needed ``` **JSON parse error** ```bash # Restore from backup cp ~/.shared_memory_mcp/backups/memory_backup_*.json \ ~/.shared_memory_mcp/memory.json ``` **Check system health** ```python health = await health_check({}) print(health.message) # "All systems operational" ``` ### Logs ```bash # View logs tail -f ~/.shared_memory_mcp/mcp_memory.log # Check for errors grep ERROR ~/.shared_memory_mcp/mcp_memory.log ``` --- ## Contributing Contributions welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Add tests for new features 4. Ensure all tests pass 5. Submit a pull request ### Code Style - Use type hints - Follow existing patterns - Add docstrings - Run pre-commit hooks --- ## License MIT License - See LICENSE file for details --- ## Changelog ### v2.0.0 (2025-10-30) - ✅ Added concurrency safety (file locking) - ✅ Added structured logging - ✅ Added 6 new MCP tools - ✅ Enhanced data model (tags, priority, metadata) - ✅ Added automatic backups and recovery - ✅ Added comprehensive test suite (70+ tests) - ✅ Added complete documentation - ✅ Zero breaking changes See [CHANGELOG_V2.md](./docs/CHANGELOG_V2.md) for detailed history. --- ## Acknowledgments Built on the Model Context Protocol (MCP) by Anthropic. Enhanced with production-ready features while maintaining the simplicity and elegance of the original design. --- ## Links - **Documentation:** [./docs/](./docs/) - **Tests:** [./tests/](./tests/) - **API Reference:** [API_REFERENCE_V2.md](./docs/API_REFERENCE_V2.md) - **MCP Protocol:** https://modelcontextprotocol.io/ --- **Made with ❤️ for multi-agent collaboration** *Version 2.0.0 - Production Ready* 🚀