memex

A personal knowledge engine. Semantic search, MCP server, and sync stack for your second brain — exposed to Claude, ChatGPT, and any HTTP client.

No cloud. No subscriptions. Everything runs on your machine.

• Hybrid search combining vector similarity + full-text (RRF fusion) over your vault
• HyDE query expansion for short/conversational queries
• Time-decay scoring to surface recent notes
• 7 MCP tools: search_vault, get_note, get_backlinks, related_notes, search_by_tag, recent_notes, vault_stats
• REST endpoint for non-MCP clients (n8n, scripts, ChatGPT connectors)
• Incremental sync every 15 minutes — only re-embeds changed notes
• API key auth (Bearer, X-API-Key header, or query param)

Obsidian Vault (local)
    ↓ (mount)
sync daemon  →  embeddings service (mxbai-embed-large-v1, local)
    ↓
pgvector (PostgreSQL 17 + pgvector extension)
    ↓
MCP server (Node.js, port 3456)
    ├── Claude Desktop / Claude Code (MCP transport)
    ├── ChatGPT connector (REST via Cloudflare Tunnel)
    └── Any HTTP client

• Docker + Docker Compose
• ~4GB disk for the embedding model (downloaded on first build)
• ~500MB RAM for the embeddings service at idle
• Your notes accessible as a local directory (Obsidian, Markdown files, etc.)

git clone https://github.com/ped-ro/memex
cd memex

# 1. Configure
cp .env.example .env
# Edit .env — set VAULT_PATH, PGPASSWORD, MCP_API_KEY

# 2. Build and start
docker compose up -d

# 3. Run initial import (first time only)
docker exec vault-sync python /app/host/sync.py --vault /vault

# 4. Verify
curl http://localhost:3456/health

First startup takes a few minutes — the embeddings service downloads the model (~1.3GB).

All config lives in .env. Copy .env.example to get started:

| Variable | Required | Default | Description | |---|---|---|---| | VAULT_PATH | ✅ | — | Absolute path to your notes directory |