# Mnemosyne

*Memory and knowledge for your Kubernetes clusters*

Mnemosyne is a Model Context Protocol (MCP) server that gives AI assistants deep visibility into Kubernetes clusters. Named after the Greek goddess of memory, Mnemosyne remembers and recalls everything about your cluster state, making Kubernetes operations accessible through natural language.

## What Mnemosyne Remembers

- **Pod Lifecycles**: Track pod status, restarts, and resource usage across namespaces
- **Service Topology**: Understand service relationships and network connectivity  
- **Application Context**: Extract service descriptions and documentation from running pods
- **Cluster Health**: Monitor node status and resource allocation
- **Operational History**: Access logs and events with intelligent filtering

## Key Features

- **Natural Language Interface**: Ask questions like "What pods are failing?" or "Show me the logs for the auth service"
- **Intelligent Service Discovery**: Automatically finds and describes services using embedded documentation
- **Multi-Protocol Support**: WebSocket and HTTP endpoints for flexible integration
- **Production Hardened**: RBAC, health checks, structured logging, and security best practices
- **Zero-Config Deployment**: Works out of the box with sensible defaults

## Quick Start

### 1. Deploy to Kubernetes

```bash
# Quick deployment for development
./scripts/quick-deploy.sh

# Production deployment
IMAGE_TAG=v1.0.0 NAMESPACE=production ./scripts/build-and-deploy.sh
```

### 2. Connect Your AI Assistant

Add Mnemosyne to your AI assistant's MCP configuration:

```json
{
  "mcpServers": {
    "mnemosyne": {
      "command": "websocket", 
      "args": ["ws://localhost:8080/ws"],
      "disabled": false,
      "autoApprove": ["list_pods", "get_pod_logs", "describe_service"]
    }
  }
}
```

### 3. Start Asking Questions

Now you can ask your AI assistant natural language questions about your cluster:

- *"What pods are running in the production namespace?"*
- *"Show me the logs for the failing authentication service"*
- *"What's the resource usage of the database pods?"*
- *"Describe the user-service and its dependencies"*
- *"Which nodes are under pressure?"*

Mnemosyne translates these questions into the appropriate Kubernetes operations and returns human-readable results.

## Mnemosyne's Capabilities

| Capability | What It Remembers | MCP Tool |
|------------|-------------------|----------|
| **Pod Intelligence** | Status, health, containers, restarts | `list_pods`, `describe_pod` |
| **Log Memory** | Application logs with context and filtering | `get_pod_logs` |
| **Resource Awareness** | CPU, memory usage and limits | `get_pod_resources` |
| **Service Knowledge** | Service topology and embedded documentation | `describe_service` |
| **File Access** | Configuration files and application data | `get_file_from_pod` |
| **Cluster Overview** | Node status and cluster health | `get_nodes` |

### Special Feature: Service Documentation Discovery

Mnemosyne automatically looks for `/mnemosyne/serviceDescription.txt` files in your pods to provide rich context about your services. This makes troubleshooting and understanding service relationships much more intuitive.

## How Mnemosyne Works

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │───▶│    Mnemosyne     │───▶│  Kubernetes     │
│   (Natural      │    │   (Memory &      │    │   Cluster       │
│   Language)     │    │   Translation)   │    │   (Reality)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

Mnemosyne acts as the memory layer between AI assistants and Kubernetes:

- **Memory Layer**: Remembers cluster state, relationships, and context
- **Translation Layer**: Converts natural language to kubectl operations  
- **Intelligence Layer**: Enriches raw Kubernetes data with meaningful insights
- **Protocol Layer**: Speaks MCP to AI assistants and kubectl to clusters

## Development

### Local Development

```bash
# Setup development environment
./scripts/local-dev.sh setup

# Run locally
./scripts/local-dev.sh run

# Run tests
./scripts/local-dev.sh test

# Build and run in Docker
./scripts/local-dev.sh build
./scripts/local-dev.sh docker
```

### Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `DEBUG` | `false` | Enable debug logging |
| `HOST` | `0.0.0.0` | Server bind address |
| `PORT` | `8080` | Server port |
| `KUBECTL_CONTEXT` | (default) | Kubectl context |
| `CORS_ORIGINS` | `*` | Allowed CORS origins |
| `MAX_CONNECTIONS` | `100` | Max concurrent connections |
| `REQUEST_TIMEOUT` | `30` | Request timeout (seconds) |

## Deployment

### Prerequisites

- Kubernetes 1.19+
- kubectl configured
- Docker (for building images)
- Appropriate RBAC permissions

### Deployment Scripts

- `scripts/build-and-deploy.sh` - Full build and deploy
- `scripts/quick-deploy.sh` - Quick development deployment
- `scripts/local-dev.sh` - Local development tools

### Kubernetes Resources

The deployment includes:
- **Deployment**: Server pods with resource limits
- **Service**: Internal cluster access
- **Ingress**: External access configuration
- **ServiceAccount**: RBAC permissions
- **ConfigMap**: Configuration management

## Security

### RBAC Permissions

Minimal required permissions:
- `pods`: get, list, watch
- `pods/log`: get
- `pods/exec`: create
- `services`: get, list
- `nodes`: get, list

### Container Security

- Runs as non-root user
- Minimal base image
- Health checks enabled
- Resource limits configured

### Network Security

- CORS configuration
- TLS support ready
- Network policy compatible

## Monitoring

### Health Endpoints

- `/health` - Liveness probe
- `/ready` - Readiness probe

### Logging

Structured logging with configurable levels:
- Request/response logging
- kubectl command logging (debug)
- Error tracking with correlation IDs

### Metrics

Monitor:
- Response times
- Error rates
- Connection counts
- Resource usage

## Documentation

- [Deployment Guide](docs/DEPLOYMENT.md) - Comprehensive deployment instructions
- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions
- [Configuration Examples](config/) - Environment-specific configurations

## Troubleshooting

### Common Issues

1. **Pod not starting**: Check image availability and resource limits
2. **kubectl errors**: Verify RBAC permissions and kubeconfig
3. **Connection issues**: Check service/ingress configuration and CORS
4. **Performance**: Monitor resource usage and optimize queries

### Debug Mode

Enable debug logging:

```bash
kubectl set env deployment/mnemosyne DEBUG=true -n mcp-server
```

### Getting Help

See [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for detailed guidance.

## Why Mnemosyne?

In Greek mythology, Mnemosyne was the goddess of memory and the mother of the nine Muses. She gave mortals the ability to remember and learn from experience. 

Similarly, this Mnemosyne gives AI assistants the ability to remember and understand your Kubernetes clusters, transforming raw operational data into actionable insights.

## Contributing

Mnemosyne welcomes contributions! Whether you're adding new capabilities, improving documentation, or fixing bugs:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-memory`)
3. Make your changes with tests
4. Submit a pull request

## License

MIT License - See LICENSE file for details

## Support

Mnemosyne remembers everything, but sometimes you need help too:

- 📖 [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions
- 🚀 [Deployment Guide](docs/DEPLOYMENT.md) - Production deployment best practices  
- 💬 Open an issue with your cluster context and we'll help debug

*"Memory is the treasury and guardian of all things."* - Cicero