MCP Agent Memory MCP Server

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