---

About

Mnemosyne provides intelligent search and analysis for your local files:

• Hybrid Search: Vector semantic search + FTS5 keyword search, fused with Reciprocal Rank Fusion (RRF).
• Multi-Format: Text (txt/md/csv/json...), PDF, images, audio, video.
• Multilingual Models: BGE-M3 (100+ languages) and Chinese CLIP for Chinese text-to-image search.
• Multiple UIs: Desktop GUI (Tauri 2), CLI, REST API.
• Real-time Updates: File watcher detects changes and updates the index incrementally. File deletions are automatically removed from the index.
• Smart Directory Filtering: Automatically skips node_modules, .git, target, and 60+ other irrelevant directories.
• Zero External Services: All data stored in a single SQLite file.

---

Features

---

Architecture

┌─────────────────────────────────────────────┐
│                 UI Layer                    │
│  [Tauri2 GUI]  [CLI]  [REST API / axum]     │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│         mnemosyne-retrieval                  │
│   SearchEngine · BackgroundIndexer           │
│   FileWatcher · IgnoreConfig                 │
└──┬────────────────┬────────────────┬────────┘
   │                │                │
┌──▼──────────┐  ┌──▼───────┐  ┌────▼──────────┐
│   model     │  │  parser  │  │    index       │
│BERT/BGE-M3  │  │Text/PDF/ │  │ HybridIndex    │
│CLIP/Whisper │  │Image/... │  │ Vector + FTS5  │
└─────────────┘  └──────────┘  └──────┬────────┘
                                        │
                               ┌────────▼────────┐
                               │    storage       │
                               │ SQLite + WAL     │
                               │ sqlite-vec (KNN) │
                               └─────────────────┘

Crate Dependency Graph

mnemosyne-core          ← Base types / traits / errors
  ← mnemosyne-storage   ← SQLite CRUD + sqlite-vec integration
  ← mnemosyne-model     ← Text / image / audio embeddings (Candle / Metal)
  ← mnemosyne-parser    ← File parsing plugins
  ← mnemosyne-index     ← Hybrid search engine
    ← mnemosyne-retrieval  ← SearchEngine facade + IgnoreConfig
      ← cli / api / src-tauri

---

Installation

Prerequisites

On macOS, you also need Xcode Command Line Tools:

xcode-select --install

Building with build.sh (recommended)

git clone <repo-url> mnemosyne && cd mnemosyne

# Full ML backend + auto-download sqlite-vec
# Apple Silicon automatically enables Metal GPU acceleration
./scripts/build.sh --full --sqlite-vector

# Common options
./scripts/build.sh --candle              # BERT text only
./scripts/build.sh --full --no-metal     # Disable Metal, force CPU
./scripts/build.sh --full --gui          # Also build desktop GUI
./scripts/build.sh --dev                 # Debug profile (faster compile)

build.sh options:

Manual Cargo Build

# Full backend (add --features metal-backend for Apple Silicon)
cargo build --release -p mnemosyne-cli \
  --features "candle-backend,clip-backend,whisper-backend"

Build artifacts in target/release/: mnemosyne (CLI), mnemosyne-server (API)

---

Usage

CLI

# Index a directory (auto-skips node_modules/.git/etc.)
mnemosyne index ~/Documents

# Hybrid search
mnemosyne search "Rust memory safety"

# Keyword / vector search
mnemosyne search "async trait" --mode keyword --limit 20
mnemosyne search "machine learning papers" --mode vector

# Download embedding models
mnemosyne model-download BAAI/bge-m3                               # Multilingual (recommended)
mnemosyne model-download OFA-Sys/chinese-clip-vit-base-patch16    # Chinese image search
mnemosyne model-download openai/clip-vit-base-patch32             # English image search
mnemosyne model-download openai/whisper-tiny                      # Audio transcription

# Real-time watching (file deletions are auto-removed from index)
mnemosyne watch ~/Documents

# Stats / list / remove
mnemosyne stats
mnemosyne list --limit 50
mnemosyne remove <file-id>

# Start REST API
mnemosyne serve --port 8080

REST API

curl -X POST http://localhost:8080/api/search \
  -H "Content-Type: application/json" \
  -d '{"text": "machine learning", "mode": "hybrid", "limit": 10}'

Desktop GUI Features

• Hybrid / vector / keyword search mode; adjustable weights and score threshold
• Directory management (add, re-index, real-time watching)
• File browser and preview (text, PDF, images, audio)
• Model management (download, switch BERT/CLIP/Whisper models)
• HuggingFace mirror configuration (direct / hf-mirror.com / custom)
• Proxy configuration
• Built-in REST API server toggle (with Swagger UI link)
• Real-time log viewer
• Clear index database (requires typing a random obscure confirmation word to prevent accidents)

---

Embedding Models

Text Models (candle-backend)

Vision Models (clip-backend)

Audio Models (whisper-backend)

sqlite-vec KNN Acceleration

Install asg017/sqlite-vec to enable HNSW KNN search:

# Automatic via build.sh
./scripts/build.sh --sqlite-vector

# Manual (macOS arm64)
mkdir -p ~/.mnemosyne/lib
curl -fsSL https://github.com/asg017/sqlite-vec/releases/latest/download/sqlite-vec-0.1.9-loadable-macos-aarch64.tar.gz \
  | tar -xzO vec0.dylib > ~/.mnemosyne/lib/vec0.dylib

Automatically detected at startup; silently falls back to pure Rust HNSW if absent.

---

Directory Filtering (IgnoreConfig)

The following directories are automatically skipped during indexing:

Customizable via IgnoreConfig in mnemosyne-retrieval.

---

Data Storage

~/.mnemosyne/
  db.sqlite
    ├── files              # File metadata + SHA-256 hash
    ├── document_chunks    # Content chunks
    ├── fts_chunks         # FTS5 full-text index (BM25)
    ├── embeddings         # Vector BLOBs (f32 little-endian)
    ├── embedding_vec_384  # sqlite-vec HNSW (BERT 384-dim)
    ├── embedding_vec_512  # sqlite-vec HNSW (CLIP 512-dim)
    ├── embedding_vec_1024 # sqlite-vec HNSW (BGE-M3 1024-dim)
    └── model_registry     # Downloaded model records
  models/                  # Local model cache
  lib/vec0.dylib           # sqlite-vec extension (optional)

---

Development

cargo test -p mnemosyne-storage -p mnemosyne-retrieval
cargo check --workspace
cargo fmt --all
cargo clippy --workspace -- -D warnings

---

Tech Stack