# 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

```bash
# 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

```bash
# 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`):

```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)

```bash
# Start the MCP server
python src/mcp_server.py

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

### Python Client

```python
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

```bash
# Run all tests
pytest

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

# Run specific test file
pytest tests/test_memory_core.py
```

### Code Quality

```bash
# 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