readwise-vector-db

Readwise Vector DB provides a fast, semantic search layer over your Readwise highlights. It exposes a HTTP API (via a FastAPI app served with Uvicorn) for vector-based search and a streaming MCP endpoint for real-time results. You can perform standard vector searches, filter by metadata, and subscribe to streaming search results over SSE or via the MCP TCP interface. Start the server locally, then use the /search endpoint for vector queries or connect to /mcp/stream to receive live results as you type. The MCP TCP option lets you integrate with LLM clients that expect a traditional JSON-RPC style workflow over a persistent connection, while the HTTP SSE endpoint is ideal for browser clients or serverless frontends that need streaming updates.

Prerequisites:

• Python 3.12
• Poetry >= 1.8
• Docker + Compose (for local Postgres with pgvector) (optional if using Supabase)

1. Install dependencies and set up environment

git clone https://github.com/leonardsellem/readwise-vector-db.git
cd readwise-vector-db
poetry install --sync

2. Run local PostgreSQL (Docker) and migrate database (optional; used in Quick Start)

docker compose up -d db
poetry run alembic upgrade head

3. Start the API server (Python + Uvicorn)

# Ensure required environment variables are set (READWISE_TOKEN, OPENAI_API_KEY, DATABASE_URL)
poetry run uvicorn readwise_vector_db.api:app --reload

4. Verify the API health (in another terminal)

curl http://127.0.0.1:8000/health

Optional: If you prefer a serverless/Supabase setup, follow the Supabase cloud steps in the README and adapt environment variables accordingly.

Tips and considerations:

• SSE vs MCP TCP: use the HTTP SSE endpoint (/mcp/stream) for browser or serverless clients; use the MCP TCP endpoint for traditional RPC-based integrations or local development with persistent connections.
• Environment variables are critical: missing DB_BACKEND or SUPABASE_DB_URL will cause startup errors in cloud deployments. Ensure READWISE_TOKEN and OPENAI_API_KEY are present before starting.
• If using Supabase: enable the vector extension (pgvector) and provide DATABASE_URL pointing to your Supabase Postgres instance.
• For production: consider using the Vercel deployment path described in the README to get automatic SSE streaming and serverless scalability. Ensure your DNS and TLS are correctly set up for http/https endpoints.
• The server supports both local Docker-based Postgres with pgvector and cloud Postgres (Supabase). Adjust the DATABASE_URL and DB_BACKEND accordingly.
• The API exposes /docs for interactive Swagger UI to experiment with the search API before integrating it into your app.