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

# 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:

{
  "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

# 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 - Comprehensive deployment instructions
• Troubleshooting Guide - Common issues and solutions
• Configuration Examples - 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:

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

Getting Help

See 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 - Common issues and solutions
• 🚀 Deployment Guide - 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