Melian
Getting Started / Installation

Installation

Preparing the ground: what you need before the forest can grow.

Prerequisites

  • Bun v1.3 or later: Melian's runtime and bundler
  • Docker: for running Qdrant (vector database)
  • macOS: required for iMessage integration; Linux is supported without it
  • An OpenAI-compatible LLM endpoint: LM Studio is recommended for local inference
  • SQLite: bundled with Bun, no separate install needed

1. Install Bun

If you don't have Bun installed, fetch it from bun.sh:

curl -fsSL https://bun.sh/install | bash

Restart your shell or source your profile, then verify:

bun --version
# 1.3.x or later

2. Clone and Install Dependencies

git clone https://github.com/your-username/melian.git
cd melian
bun install

Bun reads package.json, resolves the lockfile, and writes binaries to node_modules/.bin. No separate build step is needed. Bun compiles TypeScript on first run.

3. Start Qdrant

Qdrant is the vector database used for archival memory. Run it via Docker with a named volume so data persists across restarts:

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant

Verify it's responding:

curl http://localhost:6333/healthz
# {"title":"qdrant - vector search engine","version":"..."}

The Qdrant dashboard is available at http://localhost:6333/dashboard if you want to inspect collections manually.

4. macOS Permissions

Two macOS permissions are required for the iMessage and automation integrations.

Full Disk Access (iMessage)

Melian reads the iMessage SQLite database at ~/Library/Messages/chat.db. macOS restricts this to applications with Full Disk Access:

  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Click the + button and add your terminal application (e.g. Terminal, iTerm2, Ghostty)
  3. Restart the terminal and confirm access:
sqlite3 ~/Library/Messages/chat.db "SELECT count(*) FROM message;"

If this returns a number rather than an error, access is granted.

Accessibility (AppleScript / System Events)

Some automation capabilities (composing messages, interacting with apps via AppleScript) require Accessibility access:

  1. Open System Settings → Privacy & Security → Accessibility
  2. Add your terminal application
  3. Toggle it on

Without this permission, AppleScript calls that target System Events will silently fail.

5. LLM Setup

Melian requires an OpenAI-compatible HTTP endpoint for inference. LM Studio is recommended for local setup:

  1. Download LM Studio
  2. Pull a model. Qwen2.5-14B-Instruct or similar works well at 14B
  3. Start the local server: Developer → Local Server → Start Server
  4. Default endpoint: http://localhost:1234/v1

Any server that speaks the OpenAI Chat Completions API (POST /v1/chat/completions) will work: Ollama with --api openai, llama.cpp's server, vLLM, etc.

For embeddings (used by the archival memory system), Melian needs a model that returns dense vectors. nomic-embed-text-v1.5 (768 dimensions) is the tested default. Load it in LM Studio alongside your chat model, or point embeddings.baseUrl to a separate server.

6. Google Cloud Vision (Optional)

Vision is used for OCR: extracting text from screenshots, scanned documents, and images attached to emails.

Vision uses the same Gmail OAuth credentials configured in email.yaml. When a Gmail account is set up with OAuth (client ID, client secret, and refresh token), Melian calls refreshAccessToken() to obtain a valid access token for the Vision API. No separate service account or key file is needed.

The default OCR provider is Tesseract (configured as "tesseract" in the config). Google Cloud Vision is available as an alternative when Gmail OAuth is configured. If no OAuth credentials are present, Vision-dependent features fall back to Tesseract or are disabled.

7. Remarkable Cloud (Optional)

If you use a Remarkable tablet with a Connect subscription, Melian can sync annotations and handwritten notes.

  1. Log into my.remarkable.com and generate a one-time code under Settings → Integration → Developer tokens
  2. Set in your config or .env:
REMARKABLE_TOKEN=<your-token>

On first connection Melian exchanges the one-time code for a device token and stores it in ~/.melian/remarkable-token. Subsequent syncs use the stored token.

8. Verify the Installation

Copy the example environment file and configure your LLM endpoint:

cp .env.example .env
# Edit .env: set LLM_BASE_URL, QDRANT_URL, etc.

Then start the server:

bun run start

You should see output like:

[melian] Qdrant connected: archival_memory collection ready
[melian] Core memory loaded (0 facts)
[melian] Scheduler started: 5 seeded jobs registered
Melian running on http://127.0.0.1:3000

Open http://localhost:3000 in your browser. The Nan Elmoth chat interface should appear. If you're on a LAN and want to reach Melian from another device, use your machine's local IP address on port 3000.