Minima

What is Minima?

Minima is an open-source, on-premises conversational RAG (Retrieval Augmented Generation) system. It enables users to query their local documents securely and privately, without relying on external cloud services for data processing. It supports integration with popular LLMs like ChatGPT and Anthropic Claude, as well as providing a fully local RAG solution.

How to use Minima?

Minima can be run in several configurations using Docker Compose, depending on your desired setup:

1. Isolated Installation (Fully Local): Use docker compose -f docker-compose-ollama.yml --env-file .env up --build to run Minima entirely on-premises with local neural networks (LLM, reranker, embedding).
2. Custom GPT Integration: Use docker compose -f docker-compose-chatgpt.yml --env-file .env up --build to query local documents via ChatGPT's custom GPTs. An indexer runs locally, while ChatGPT serves as the primary LLM.
3. Anthropic Claude Integration: Use docker compose -f docker-compose-mcp.yml --env-file .env up --build to use Anthropic Claude for querying local documents. The indexer operates locally, with Claude as the primary LLM.
4. Smithery Installation (for Claude Desktop): Use npx -y @smithery/cli install minima --client claude for automatic installation.

Before running, create a .env file from env.sample and configure variables like LOCAL_FILES_PATH, EMBEDDING_MODEL_ID, EMBEDDING_SIZE, OLLAMA_MODEL (for local), RERANKER_MODEL, USER_ID, and PASSWORD (for ChatGPT).

Key Features of Minima

• On-premises RAG: Keep your data secure and private by processing documents locally.
• Configurable Containers: Easily deploy and manage Minima using Docker and Docker Compose.
• Multiple LLM Support: Integrate with ChatGPT, Anthropic Claude, or use fully local models via Ollama.
• Local Document Indexing: Recursively indexes documents from a specified local folder. Supported file types include .pdf, .xls, .docx, .txt, .md, .csv.
• Customizable Models: Specify embedding and reranker models (e.g., Sentence Transformers, BAAI rerankers).
• MCP Integration: Seamless integration with the Model Context Protocol for enhanced functionality.
• User Authentication: For ChatGPT integration, user ID and password are used for authentication.

Use Cases of Minima

• Secure Document Search: Query sensitive local documents without sending them to external cloud services.
• Personal Knowledge Base: Create a searchable knowledge base from your local files.
• Offline AI Assistant: Utilize a fully local RAG system for environments with limited or no internet connectivity.
• Enhanced LLM Capabilities: Augment ChatGPT or Claude with your private data for more accurate and context-aware responses.
• Developer Tooling: Integrate with tools like GitHub Copilot for context-aware code suggestions based on local documentation.

Minima FAQ

• What file types does Minima support for indexing? Minima supports .pdf, .xls, .docx, .txt, .md, and .csv files.

• Can I use Minima completely offline? Yes, the "Isolated installation" mode allows you to run Minima fully on-premises without external dependencies.

• What are the minimum Python requirements for MCP usage? For MCP usage, your local machine's Python version must be >=3.10, and 'uv' must be installed.

• How do I access the chat UI for a fully local installation? After launching the Docker containers, navigate to http://localhost:3000 in your web browser.

• How do I configure the embedding and reranker models? You can specify the EMBEDDING_MODEL_ID and RERANKER_MODEL in your .env file. Minima supports Sentence Transformer models for embedding and BAAI rerankers.

Minima is an open source RAG on-premises containers, with ability to integrate with ChatGPT and MCP. Minima can also be used as a fully local RAG.

Minima currently supports three modes:

1. Isolated installation – Operate fully on-premises with containers, free from external dependencies such as ChatGPT or Claude. All neural networks (LLM, reranker, embedding) run on your cloud or PC, ensuring your data remains secure.

2. Custom GPT – Query your local documents using ChatGPT app or web with custom GPTs. The indexer running on your cloud or local PC, while the primary LLM remains ChatGPT.

3. Anthropic Claude – Use Anthropic Claude app to query your local documents. The indexer operates on your local PC, while Anthropic Claude serves as the primary LLM.

---

Running as Containers

1. Create a .env file in the project’s root directory (where you’ll find env.sample). Place .env in the same folder and copy all environment variables from env.sample to .env.

2. Ensure your .env file includes the following variables:

3. For fully local installation use: docker compose -f docker-compose-ollama.yml --env-file .env up --build.

4. For ChatGPT enabled installation use: docker compose -f docker-compose-chatgpt.yml --env-file .env up --build.

5. For MCP integration (Anthropic Desktop app usage): docker compose -f docker-compose-mcp.yml --env-file .env up --build.

6. In case of ChatGPT enabled installation copy OTP from terminal where you launched docker and use Minima GPT

7. If you use Anthropic Claude, just add folliwing to /Library/Application\ Support/Claude/claude_desktop_config.json

{
    "mcpServers": {
      "minima": {
        "command": "uv",
        "args": [
          "--directory",
          "/path_to_cloned_minima_project/mcp-server",
          "run",
          "minima"
        ]
      }
    }
  }

8. To use fully local installation go to cd electron, then run npm install and npm start which will launch Minima electron app.

9. Ask anything, and you'll get answers based on local files in {LOCAL_FILES_PATH} folder.

---

Variables Explained

LOCAL_FILES_PATH: Specify the root folder for indexing (on your cloud or local pc). Indexing is a recursive process, meaning all documents within subfolders of this root folder will also be indexed. Supported file types: .pdf, .xls, .docx, .txt, .md, .csv.

EMBEDDING_MODEL_ID: Specify the embedding model to use. Currently, only Sentence Transformer models are supported. Testing has been done with sentence-transformers/all-mpnet-base-v2, but other Sentence Transformer models can be used.

EMBEDDING_SIZE: Define the embedding dimension provided by the model, which is needed to configure Qdrant vector storage. Ensure this value matches the actual embedding size of the specified EMBEDDING_MODEL_ID.

OLLAMA_MODEL: Set up the Ollama model, use an ID available on the Ollama site. Please, use LLM model here, not an embedding.

RERANKER_MODEL: Specify the reranker model. Currently, we have tested with BAAI rerankers. You can explore all available rerankers using this link.

USER_ID: Just use your email here, this is needed to authenticate custom GPT to search in your data.

PASSWORD: Put any password here, this is used to create a firebase account for the email specified above.

---

Examples

Example of .env file for on-premises/local usage:

LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
EMBEDDING_SIZE=768
OLLAMA_MODEL=qwen2:0.5b # must be LLM model id from Ollama models page
RERANKER_MODEL=BAAI/bge-reranker-base # please, choose any BAAI reranker model

To use a chat ui, please navigate to http://localhost:3000

Example of .env file for Claude app:

LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
EMBEDDING_SIZE=768

For the Claude app, please apply the changes to the claude_desktop_config.json file as outlined above.

To use MCP with GitHub Copilot:

1. Create a .env file in the project’s root directory (where you’ll find env.sample). Place .env in the same folder and copy all environment variables from env.sample to .env.

2. Ensure your .env file includes the following variables:

   • LOCAL_FILES_PATH
   • EMBEDDING_MODEL_ID
   • EMBEDDING_SIZE

3. Create or update the .vscode/mcp.json with the following configuration:

{
  "servers": {
    "minima": {
      "type": "stdio",
      "command": "path_to_cloned_minima_project/run_in_copilot.sh",
      "args": [
        "path_to_cloned_minima_project"
      ]
    }
  }
}

Example of .env file for ChatGPT custom GPT usage:

LOCAL_FILES_PATH=/Users/davidmayboroda/Downloads/PDFs/
EMBEDDING_MODEL_ID=sentence-transformers/all-mpnet-base-v2
EMBEDDING_SIZE=768
USER_ID=user@gmail.com # your real email
PASSWORD=password # you can create here password that you want

Also, you can run minima using run.sh.

---

Installing via Smithery (MCP usage)

To install Minima for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install minima --client claude

For MCP usage, please be sure that your local machines python is >=3.10 and 'uv' installed.

Minima (https://github.com/dmayboroda/minima) is licensed under the Mozilla Public License v2.0 (MPLv2).