Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mnemossearch the react-docs collection for how to use useEffect"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🧠 Mnemos
Self-hosted, Multi-context Memory Server for Developers
Mnemos is an MCP compatible knowledge server that turns your documentation piles into a multi context memory system. It organizes documents into isolated collections, eliminates redundant processing with content hashing, and runs fully offline using Postgres + pgvector and Ollama.
Features
Multi-context Collections: Isolate your memory by project (e.g.,
react-docs,rust-book,company-internal) with case insensitive search filtering.Deterministic Re-ingestion: SHA-256 content hashing guarantees idempotent operation—skipping unchanged files and automatically re-chunking on diffs.
Enhanced Terminal UI: Explore your context with a full screen search interface, result navigation, and detailed chunk inspection modals.
Recursive Site Crawling: Ingest entire documentation sites with path based filtering (e.g., crawl only
/learnonreact.dev).Stable Local Embeddings: Optimized for Ollama with persistent connections, automatic runner backoff, and load throttling.
Chunk Quality Control: Automatic noise filtering (minimum length thresholds + alphanumeric validation) ensures high quality retrieval.
100% Private: Fully offline. Your context never leaves your local machine.
Quick Start
Prerequisites
Docker & Docker Compose
Python 3.11+
Ollama (for local embeddings)
1. Install Ollama & Pull Embedding Model
2. Start the Database
3. Install Dependencies
4. Start the Server
5. Add Documents
6. Search
CLI Commands
Command | Description | Flags |
| Add a document or directory |
|
| Ingest a URL or crawl a site |
|
| Search for relevant context |
|
| List all documents |
|
| Backup knowledge base to JSON |
|
| Delete a document |
|
| Start the API server |
|
API Endpoints
REST API
Mnemos provides a standard REST API for document management and operations.
Method | Endpoint | Description |
|
| Upload a document |
|
| List all documents |
|
| List all unique collections |
|
| Full JSON backup of chunks |
|
| Delete a document |
|
| Vector similarity search |
|
| Ingest a single URL |
|
| Crawl a documentation site |
|
| Health & Stats check |
MCP Endpoints
Mnemos exposes its retrieval capabilities via the Model Context Protocol (MCP), allowing AI agents to query it as an external context provider. Mnemos is designed to be stateless from the MCP client’s perspective; all persistence lives server-side.
Method | Endpoint | Description |
|
| List available MCP tools |
|
| Execute an MCP tool |
MCP Integration
Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
Available MCP Tools
search_context: Search the knowledge base for relevant context
list_documents: List all documents in the knowledge base
get_document_info: Get detailed information about a document
Configuration
Environment variables (.env):
Variable | Default | Description |
|
| Postgres connection string |
|
|
|
|
| Ollama embedding model |
|
| Ollama API URL |
|
| Target characters per chunk |
|
| Overlap between chunks |
Architecture
Design Principles
Local-first by default: All heavy lifting (vectors/search) happens on your hardware.
Deterministic ingestion: SHA-256 hashing ensures idempotency and safe re-runs.
Explicit context isolation: Multi-collection support prevents cross-project context pollution.
Inspectable retrieval: Similarity scores and chunk metadata are exposed to build trust.
Zero vendor lock-in: Standards-based tech stack (Postgres, MCP, REST).
Supported Embedding Models
Model | Dimensions | Notes |
| 768 | Default, good balance |
| 1024 | Higher quality |
| 384 | Faster, smaller |
Security Posture
Local-Only: By default, Mnemos binds to
0.0.0.0but does not include authentication. It is intended for local use or behind a secure tunnel.No External Calls: All vector generation and retrieval happen locally. No telemetry or document data is sent to external servers.
SQLi Prevention: Uses SQLAlchemy ORM and parameterized queries for all database interactions.
Non-Goals
Cloud Hosting: Mnemos is not designed to be a multi-tenant cloud SaaS.
Advanced LLM Orchestration: It focuses on context provision, not on being a full RAG agent.
Browser Automation: Ingestion is via CLI or URL crawler, not a GUI automation tool.