# Mnemos Mcp

> Self hosted MCP knowledge server. Turn docs into searchable context with multi collection isolation, deterministic ingestion, and local vector search via Ollama + pgvector. 100% private, zero vendor lock in.

- **Type:** MCP server
- **Install:** `agentstack add mcp-tanush1912-mnemos-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Tanush1912](https://agentstack.voostack.com/s/tanush1912)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Tanush1912](https://github.com/Tanush1912)
- **Source:** https://github.com/Tanush1912/mnemos-mcp

## Install

```sh
agentstack add mcp-tanush1912-mnemos-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🧠 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 `/learn` on `react.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](https://ollama.ai) (for local embeddings)

### 1. Install Ollama & Pull Embedding Model

```bash
brew install ollama

ollama serve

ollama pull nomic-embed-text
```

### 2. Start the Database

```bash
cd docker
docker-compose up -d
```

### 3. Install Dependencies

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

### 4. Start the Server

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

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

### 5. Add Documents

```bash
python cli/mnemos.py add ./docs/my-document.pdf --collection my-project

# Or crawl a site
python cli/mnemos.py ingest https://react.dev/learn --path-filter /learn --collection react
```

### 6. Search

```bash
python cli/mnemos.py search "how to use useEffect"
```

## CLI Commands

| Command | Description | Flags |
|---------|-------------|-------|
| `mnemos add ` | Add a document or directory | `-c `, `-r` (recursive) |
| `mnemos ingest ` | Ingest a URL or crawl a site | `-c `, `--path-filter` |
| `mnemos search ` | Search for relevant context | `-c `, `-k ` |
| `mnemos list` | List all documents | `-c `, `-n ` |
| `mnemos export ` | Backup knowledge base to JSON | `-c ` |
| `mnemos delete ` | Delete a document | `-f` (force) |
| `mnemos server` | Start the API server | `--host`, `--port` |

## API Endpoints

### REST API

Mnemos provides a standard REST API for document management and operations.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/documents` | Upload a document |
| `GET` | `/api/documents` | List all documents |
| `GET` | `/api/collections` | List all unique collections |
| `GET` | `/api/documents/export` | Full JSON backup of chunks |
| `DELETE` | `/api/documents/{id}` | Delete a document |
| `POST` | `/api/search` | Vector similarity search |
| `POST` | `/api/ingest/url` | Ingest a single URL |
| `POST` | `/api/ingest/site` | Crawl a documentation site |
| `GET` | `/api/health` | 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 |
|--------|----------|-------------|
| `GET` | `/mcp/tools` | List available MCP tools |
| `POST` | `/mcp/call` | Execute an MCP tool |

## MCP Integration

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mnemos": {
      "command": "curl",
      "args": ["-X", "POST", "http://localhost:8000/mcp/call", "-H", "Content-Type: application/json", "-d"]
    }
  }
}
```

### 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 |
|----------|---------|-------------|
| `DATABASE_URL` | `postgresql+asyncpg://...` | Postgres connection string |
| `EMBEDDING_PROVIDER` | `ollama` | `ollama` (local-first default) or `openai` |
| `EMBEDDING_MODEL` | `nomic-embed-text` | Ollama embedding model |
| `OLLAMA_BASE_URL` | `http://127.0.0.1:11434` | Ollama API URL |
| `CHUNK_SIZE` | `300` | Target characters per chunk |
| `CHUNK_OVERLAP` | `40` | Overlap between chunks |

## Architecture

```mermaid
graph TD
    User([User CLI / App]) --> API[FastAPI Server]
    API --> DB[(PostgreSQL + pgvector)]
    API --> Ollama[Ollama Local Embeddings]
    
    subgraph Ingestion Pipeline
        API --> Parser[Document Parser]
        Parser --> Chunker[Text Chunker]
        Chunker --> HashCheck[SHA-256 Content Hash]
        HashCheck --> Embedding[Vector Generation]
    end
    
    subgraph Retrieval
        API --> Search[Vector Search]
        Search --> Context[Context Assembler]
    end
```

## 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 |
|-------|------------|-------|
| `nomic-embed-text` | 768 | Default, good balance |
| `mxbai-embed-large` | 1024 | Higher quality |
| `all-minilm` | 384 | Faster, smaller |

## Security Posture

- **Local-Only**: By default, Mnemos binds to `0.0.0.0` but 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.

## Development

```bash
black src/ cli/

pytest tests/
```

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Tanush1912](https://github.com/Tanush1912)
- **Source:** [Tanush1912/mnemos-mcp](https://github.com/Tanush1912/mnemos-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tanush1912-mnemos-mcp
- Seller: https://agentstack.voostack.com/s/tanush1912
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.