MCP Agent Memory - v2.0

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:

   pip install mcp pydantic

3. Run the server:

   python3 shared_memory_mcp.py

Basic Usage

# 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):

{
  "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 - Full user guide
• 🚀 Quick Start Guide - 5-minute setup

Reference

• 📚 API Reference - Complete API documentation
• 📋 Changelog - Version 2.0 changes
• ⬆️ Upgrade Guide - Migrate from v1 to v2

Developer

• 🔧 Implementation Summary - Technical details
• 🧪 Testing Guide - How to run tests
• 🏗️ Architecture Details - 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 for detailed documentation.

---

Testing

Run Basic Tests

python3 run_basic_tests.py

Run Full Test Suite (requires pytest)

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

# 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

# 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

# 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

# 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 for more details.

---

Troubleshooting

Common Issues

File lock timeout

# Check for other running instances
ps aux | grep shared_memory_mcp

# Increase timeout in code if needed

JSON parse error

# Restore from backup
cp ~/.shared_memory_mcp/backups/memory_backup_*.json \
   ~/.shared_memory_mcp/memory.json

Check system health

health = await health_check({})
print(health.message)  # "All systems operational"

Logs

# 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 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/
• Tests: ./tests/
• API Reference: API_REFERENCE_V2.md
• MCP Protocol: https://modelcontextprotocol.io/

---

Made with ❤️ for multi-agent collaboration

Version 2.0.0 - Production Ready 🚀