🧠 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 (for local embeddings)

1. Install Ollama & Pull Embedding Model

brew install ollama

ollama serve

ollama pull nomic-embed-text

2. Start the Database

cd docker
docker-compose up -d

3. Install Dependencies

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

4. Start the Server

# 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

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

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

CLI Commands

Command	Description	Flags
`mnemos add <path>`	Add a document or directory	`-c <collection>`, `-r` (recursive)
`mnemos ingest <url>`	Ingest a URL or crawl a site	`-c <collection>`, `--path-filter`
`mnemos search <query>`	Search for relevant context	`-c <collection>`, `-k <limit>`
`mnemos list`	List all documents	`-c <collection>`, `-n <limit>`
`mnemos export <file>`	Backup knowledge base to JSON	`-c <collection>`
`mnemos delete <id>`	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):

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

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

black src/ cli/

pytest tests/