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

Related MCP server: MCP Memory Tracker

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