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

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 🚀