Skip to main content
Glama
bobmatnyc

mcp-memory

by bobmatnyc
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python

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: