MCP Memory Service

A standalone memory service that provides persistent storage for AI assistants via the Model Context Protocol (MCP).

Features

• 3-Tier Memory System: SYSTEM, LEARNED, and MEMORY layers for hierarchical knowledge organization
• Entity Management: Track people, organizations, projects, and other entities with relationships
• Interaction History: Store and retrieve conversation history with context
• Vector Search Ready: Prepared for semantic similarity search (future enhancement)
• MCP Protocol: JSON-RPC 2.0 over stdio for Claude Desktop integration
• REST API: Alternative HTTP interface for web applications

Architecture

mcp-memory/
├── src/
│   ├── core/           # Core memory logic
│   ├── models/         # Data models
│   ├── mcp/           # MCP server implementation
│   └── api/           # REST API (optional)
├── tests/             # Test suite
├── config/            # Configuration files
└── scripts/           # Utility scripts

Installation

# Clone the repository
git clone https://github.com/yourusername/mcp-memory.git
cd mcp-memory

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your Turso database credentials

Configuration

Environment Variables

# Required
TURSO_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-auth-token

# Optional
MCP_DEBUG=0                    # Enable debug logging (0 or 1)
LOG_LEVEL=INFO                 # Logging level

Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["/path/to/mcp-memory/src/mcp_server.py"],
      "env": {
        "TURSO_URL": "your-database-url",
        "TURSO_AUTH_TOKEN": "your-auth-token"
      }
    }
  }
}

Usage

MCP Server (for Claude Desktop)

# Start the MCP server
python src/mcp_server.py

# Or with debug logging
MCP_DEBUG=1 python src/mcp_server.py

Python Client

from mcp_memory import MemoryClient

# Initialize client
client = MemoryClient()

# Add a memory
await client.add_memory(
    title="Meeting with John",
    content="Discussed project timeline and deliverables",
    memory_type="professional",
    tags=["meeting", "project-x"]
)

# Search memories
results = await client.search_memories(
    query="project timeline",
    limit=5
)

# Create an entity
entity = await client.create_entity(
    name="John Doe",
    entity_type="person",
    company="Acme Corp",
    title="Project Manager"
)

MCP Tools Available

• memory_add: Add new memory to database
• memory_search: Search memories by query
• memory_delete: Delete memory by ID
• entity_create: Create new entity
• entity_search: Search entities by query
• entity_update: Update entity fields
• unified_search: Search across all data types
• get_statistics: Get database statistics
• get_recent_interactions: Get recent interactions

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src tests/

# Run specific test file
pytest tests/test_memory_core.py

Code Quality

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type checking
mypy src/

Database Schema

Entities Table

• Stores people, organizations, projects, and other entities
• Supports hierarchical relationships
• Includes contact info and metadata

Memories Table

• Three-tier system (SYSTEM, LEARNED, MEMORY)
• Full-text search capable
• Importance scoring and tagging

Interactions Table

• Conversation history
• User prompts and assistant responses
• Feedback and sentiment tracking

Learned Patterns Table

• Pattern recognition from user feedback
• Response style adaptation
• Usage statistics

Roadmap

• [ ] Vector embeddings for semantic search
• [ ] Remote MCP server support
• [ ] Web dashboard for memory management
• [ ] Export/import functionality
• [ ] Multi-user support with access control
• [ ] Memory compression and archiving
• [ ] Integration with popular AI platforms

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Support

For issues and questions:

• Open an issue on GitHub
• Contact: your-email@example.com