Content
# MCP Synaptic
A memory-enhanced MCP (Model Context Protocol) server with local RAG (Retrieval-Augmented Generation) database and expiring memory capabilities.
## Features
### 🧠 Memory Management
- **Expiring Memories**: Store temporary memories with configurable TTL (Time To Live)
- **Memory Types**: Support for different memory categories (short-term, long-term, ephemeral)
- **Automatic Cleanup**: Background processes to remove expired memories
- **Redis Integration**: Optional Redis backend for distributed memory storage
### 📚 RAG Database
- **Local Vector Storage**: ChromaDB-based vector database for document storage
- **Embedding Models**: Built-in support for sentence-transformers models
- **Semantic Search**: Similarity-based document retrieval
- **Document Management**: Add, update, and delete documents with versioning
### 🔄 Real-time Communication
- **Server-Sent Events (SSE)**: Real-time updates for memory and RAG operations
- **MCP Protocol**: Full Model Context Protocol implementation
- **WebSocket Support**: Alternative real-time communication channel
- **Event Streaming**: Live updates for memory expiration and document changes
### 🐳 Docker Ready
- **Organized Docker Structure**: Clean separation of base, overrides, and variants
- **Multi-Environment Support**: Laptop (Traefik HTTP) and Desktop (Traefik WEB) configurations
- **Development & Production**: Dedicated variants with appropriate optimizations
- **Flexible Deployment**: Composable configuration files for different scenarios
## Quick Start
### Prerequisites
- Python 3.11 or higher
- [UV](https://github.com/astral-sh/uv) package manager
- Docker (optional, for containerized deployment)
### Installation
1. **Clone the repository:**
```bash
git clone https://github.com/your-org/mcp-synaptic.git
cd mcp-synaptic
```
2. **Install dependencies:**
```bash
# For API-based embeddings (recommended - lightweight)
uv sync
# For local embeddings (includes PyTorch - heavy)
uv sync --extra local-embeddings
```
3. **Initialize the project:**
```bash
uv run mcp-synaptic init
```
4. **Start the server:**
```bash
uv run mcp-synaptic server
```
The server will start on `http://localhost:8000` by default.
### Docker Deployment
1. **Build and run with Docker Compose:**
```bash
docker-compose up --build
```
2. **Or run individual container:**
```bash
docker build -t mcp-synaptic .
docker run -p 8000:8000 mcp-synaptic
```
## Configuration
### Environment Variables
Create a `.env` file in the project root (use `.env.example` as template):
```env
# Server Configuration
SERVER_HOST=localhost
SERVER_PORT=8000
DEBUG=false
LOG_LEVEL=INFO
# Database Configuration
SQLITE_DATABASE_PATH=./data/synaptic.db
CHROMADB_PERSIST_DIRECTORY=./data/chroma
# Memory Configuration
DEFAULT_MEMORY_TTL_SECONDS=3600
MAX_MEMORY_ENTRIES=10000
MEMORY_CLEANUP_INTERVAL_SECONDS=300
# RAG Configuration
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_PROVIDER=api
EMBEDDING_API_BASE=http://localhost:4000
EMBEDDING_API_KEY=your-api-key-here
MAX_RAG_RESULTS=10
RAG_SIMILARITY_THRESHOLD=0.7
# Redis (Optional)
REDIS_URL=redis://localhost:6379/0
REDIS_ENABLED=false
```
### Memory Types
- **Ephemeral**: Very short-lived memories (seconds to minutes)
- **Short-term**: Session-based memories (minutes to hours)
- **Long-term**: Persistent memories (days to weeks)
- **Permanent**: Never-expiring memories
### Embedding Configuration
**API-based Embeddings (Recommended)**
- Lightweight deployment without PyTorch dependencies
- Works with LiteLLM, OpenAI API, or any OpenAI-compatible endpoint
- Set `EMBEDDING_PROVIDER=api` and configure `EMBEDDING_API_BASE`
**Local Embeddings**
- Includes full PyTorch and sentence-transformers
- No external API dependency but much larger container
- Set `EMBEDDING_PROVIDER=local` and install with `--extra local-embeddings`
## Usage Examples
### Python API
```python
import asyncio
from mcp_synaptic import SynapticServer, Settings
async def main():
settings = Settings()
server = SynapticServer(settings)
# Add a memory with 1-hour expiration
await server.memory_manager.add(
key="user_preference",
data={"theme": "dark", "language": "en"},
ttl_seconds=3600
)
# Store a document in RAG database
await server.rag_database.add_document(
content="MCP Synaptic is a memory-enhanced server",
metadata={"source": "documentation", "version": "1.0"}
)
# Search for similar documents
results = await server.rag_database.search(
query="memory enhanced server",
limit=5
)
await server.start()
if __name__ == "__main__":
asyncio.run(main())
```
### CLI Usage
```bash
# Start server with custom configuration
uv run mcp-synaptic server --host 0.0.0.0 --port 9000 --debug
# Initialize new project
uv run mcp-synaptic init ./my-project
# Show version
uv run mcp-synaptic version
```
### SSE Client Example
```javascript
const eventSource = new EventSource('http://localhost:8000/events');
eventSource.onmessage = function(event) {
const data = JSON.parse(event.data);
console.log('Event:', data);
};
// Listen for memory expiration events
eventSource.addEventListener('memory_expired', function(event) {
const data = JSON.parse(event.data);
console.log('Memory expired:', data.key);
});
// Listen for RAG document updates
eventSource.addEventListener('document_added', function(event) {
const data = JSON.parse(event.data);
console.log('Document added:', data.id);
});
```
## API Endpoints
### Memory Management
- `POST /memory` - Add new memory
- `GET /memory/{key}` - Retrieve memory by key
- `DELETE /memory/{key}` - Delete memory
- `GET /memory` - List all memories
### RAG Database
- `POST /rag/documents` - Add document
- `GET /rag/documents/{id}` - Get document by ID
- `POST /rag/search` - Search documents
- `DELETE /rag/documents/{id}` - Delete document
### Real-time Events
- `GET /events` - SSE endpoint for real-time updates
- `GET /ws` - WebSocket endpoint (alternative)
## Development
### Setup Development Environment
```bash
# Install development dependencies
uv sync --group dev
# Install pre-commit hooks
pre-commit install
# Run tests
uv run pytest
# Run type checking
uv run mypy mcp_synaptic
# Run linting
uv run ruff check mcp_synaptic
uv run black mcp_synaptic
# Run all checks
uv run pytest && uv run mypy mcp_synaptic && uv run ruff check mcp_synaptic
```
### Project Structure
```
mcp-synaptic/
├── mcp_synaptic/ # Main package
│ ├── core/ # Core server functionality
│ ├── mcp/ # MCP protocol implementation
│ ├── sse/ # Server-Sent Events
│ ├── rag/ # RAG database
│ ├── memory/ # Memory management
│ ├── config/ # Configuration
│ └── utils/ # Utilities
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── data/ # Data storage
├── docker/ # Docker configuration
└── docs/ # Documentation
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Development Guidelines
- Follow PEP 8 style guidelines
- Add type hints to all functions
- Write comprehensive tests
- Update documentation for new features
- Use conventional commit messages
## Testing
```bash
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=mcp_synaptic --cov-report=html
# Run specific test file
uv run pytest tests/unit/test_memory.py
# Run integration tests only
uv run pytest tests/integration/
```
## Performance
### Benchmarks
- **Memory Operations**: 10,000+ ops/sec
- **RAG Search**: Sub-100ms response time
- **Concurrent Connections**: 1,000+ SSE connections
- **Memory Footprint**: <100MB baseline
### Optimization Tips
- Use Redis for distributed setups
- Tune embedding model for your use case
- Configure appropriate TTL values
- Monitor memory cleanup intervals
## Deployment
### Production Deployment
```bash
# Using Docker Compose
docker-compose -f docker-compose.prod.yml up -d
# Using systemd service
sudo systemctl enable mcp-synaptic
sudo systemctl start mcp-synaptic
```
### Monitoring
- Health check endpoint: `GET /health`
- Metrics endpoint: `GET /metrics`
- Admin interface: `GET /admin`
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk) for the MCP specification
- [ChromaDB](https://github.com/chroma-core/chroma) for vector database capabilities
- [FastAPI](https://fastapi.tiangolo.com/) for the web framework
- [Sentence Transformers](https://github.com/UKPLab/sentence-transformers) for embeddings
## Support
- 📖 [Documentation](https://mcp-synaptic.readthedocs.io/)
- 🐛 [Issue Tracker](https://github.com/your-org/mcp-synaptic/issues)
- 💬 [Discussions](https://github.com/your-org/mcp-synaptic/discussions)
- 📧 [Email Support](mailto:support@mcp-synaptic.com)
---
**MCP Synaptic** - Bridging memories and knowledge for intelligent AI systems.
