How do I use MCP Agent Memory?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Agent Memory search for recent updates about the API integration from other agents" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Agent Memory - v2.0

Python 3.10+ License: 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

Clone or download this repository
Install dependencies:
pip install mcp pydantic
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:

Fork the repository
Create a feature branch
Add tests for new features
Ensure all tests pass
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.