Mnemos

Mnemos is an MCP compatible knowledge server that turns your documentation into a private, multi-context memory system. It lets you ingest, organize, and retrieve context across separate collections entirely offline, making it ideal for private teams and individual developers who want fast, trusted access to their documents.

How to use

You interact with Mnemos through MCP tools exposed by the server. Start by choosing a client that can talk to MCP and then use the available tools to explore, search, and retrieve your documents. The server supports multiple collections so you can keep project contexts isolated and filter results by collection.

Discover what you can do by listing available MCP tools and then call the tools to perform actions such as searching for relevant context, listing documents, or getting detailed information about a document.

When you make a call to Mnemos, you’ll receive results that include the most relevant chunks along with their similarity scores and metadata. This lets you understand why a result was chosen and evaluate the context before you reuse it in your workflows.

How to install

Prerequisites: you need Docker and Docker Compose, Python 3.11 or newer, and Ollama for local embeddings.

Step 1: Install Ollama and pull the embedding model.

brew install ollama

ollama serve

ollama pull nomic-embed-text

Step 2: Start the database.

cd docker
docker-compose up -d

Step 3: Set up a Python environment and install dependencies.

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Step 4: Start Mnemos server using the CLI (recommended) or run the API directly for development.

# Option A: Start via CLI (recommended)
python cli/mnemos.py server

# Option B: Run API directly (development)
uvicorn src.main:app --reload

Additional content

Configuration and usage notes help you tailor Mnemos to your needs. The server runs locally and keeps all data on your machine, with a focus on privacy and deterministic ingestion.

MCP integration lets you call Mnemos programmatically. You can expose tools to an MCP client and query for context, documents, or details about specific chunks.

Security and privacy are built in: the system is designed for offline use, with private vectors and controlled access through MCP endpoints.

Configuration

Environment variables you may configure include database connection, embedding provider, and chunking options. The common variables are described below for reference.

• DATABASE_URL: Postgres connection string, for example postgresql+asyncpg://user:pass@host/db
• EMBEDDING_PROVIDER: either ollama (local embeddings) or openai
• EMBEDDING_MODEL: the embedding model name (e.g., nomic-embed-text)
• OLLAMA_BASE_URL: API URL for Ollama, typically http://127.0.0.1:11434
• CHUNK_SIZE: target characters per chunk
• CHUNK_OVERLAP: overlap between adjacent chunks

Tools and endpoints

Mnemos provides a Model Context Protocol (MCP) interface so AI agents can query it as a context provider. The server exposes HTTP endpoints for MCP in addition to a local CLI-based runtime.

Available tools

search_context

Search the knowledge base for relevant context and return matching chunks with scores.

list_documents

List all documents stored in Mnemos with their metadata.

get_document_info

Retrieve detailed information about a specific document, including chunk metadata and provenance.