Setup

1. Clone and install — git clone <repo> && cd knowtation && npm install. (If you are copying this seed to a new repo instead, see COPY-TO-REPO.md.)
2. Config — Copy config/local.example.yaml to config/local.yaml and set vault_path (absolute path to vault/, e.g. $(pwd)/vault). For search without Qdrant: set vector_store: sqlite-vec and data_dir: data/. Optionally set qdrant_url and embedding provider. Do not commit config/local.yaml.
3. Secrets — Copy .env.example to .env and set API keys. .env is gitignored and loaded automatically.
   • Two lanes: Embeddings (Meaning search / knowtation index) and chat (Hub proposal Enrich, review hints, completeChat in lib/llm-complete.mjs) use different providers in config/env. Anthropic powers chat only (Messages API); it does not offer a public embeddings API for vectors.
   • Embeddings: config/local.yaml → embedding: { provider, model }, optionally overridden by EMBEDDING_PROVIDER / EMBEDDING_MODEL. Providers: ollama (default), openai (OPENAI_API_KEY), voyage (VOYAGE_API_KEY, good cloud option if you want non–OpenAI vectors). Changing embed model or dimension requires a full re-index (existing sqlite-vec / Qdrant dimensions must match).
   • Chat: OPENAI_API_KEY is tried first, then ANTHROPIC_API_KEY, then Ollama (OLLAMA_URL + chat model). Set KNOWTATION_CHAT_PREFER_ANTHROPIC=1 (or true) to try Anthropic before OpenAI when both keys are set (with OpenAI as fallback if Claude fails).
   • Transcription still uses OPENAI_API_KEY when using Whisper (see step 8).
4. Vault — Open your vault folder (see vault_path in config) in Obsidian or any Markdown editor.
5. Index (for semantic search) — Run once: knowtation index or npm run index or node scripts/index-vault.mjs. You need:
   • Vector store (pick one in config/local.yaml): sqlite-vec + data_dir: data/ — vectors live in a local SQLite file (no extra server; easiest for self-hosted). Or qdrant + qdrant_url — vectors live in a separate Qdrant service (Docker or cloud).
   • Embeddings (pick one): Ollama — install ollama.ai, run ollama pull nomic-embed-text, set embedding: { provider: ollama, model: nomic-embed-text } in config. Or OpenAI — set OPENAI_API_KEY in .env and embedding: { provider: openai, model: text-embedding-3-small } in config. Or Voyage — Voyage AI embeddings API: set VOYAGE_API_KEY and embedding: { provider: voyage, model: voyage-4-lite } (or another Voyage model); you can also set EMBEDDING_PROVIDER=voyage and EMBEDDING_MODEL=voyage-4-lite in .env. After indexing, CLI and Hub semantic search have data. Listing notes in the Hub works without indexing; Search vault needs this step on self-hosted.
6. CLI — From repo root: node cli/index.mjs --help, node cli/index.mjs list-notes, node cli/index.mjs get-note <path>, node cli/index.mjs index, node cli/index.mjs search "query", write, export, import. Use --json for machine output.
7. Capture (optional) — File-based: echo "Note" | node scripts/capture-file.mjs --source file --source-id id123. Webhook: node scripts/capture-webhook.mjs --port 3131 then POST /capture with JSON. See docs/CAPTURE-CONTRACT.md.
8. Transcription (optional) — node cli/index.mjs import audio ./recording.mp3 (requires OPENAI_API_KEY in .env). See docs/PHASE7-MANUAL-TEST.md.
9. Memory (optional) — Set memory.enabled: true in config to store last search and export provenance. Query with knowtation memory query last_search or last_export.
10. Agents — The skill in .cursor/skills/knowtation/SKILL.md is auto-discovered by Cursor when this repo is open. For global use, copy that skill folder to ~/.cursor/skills/knowtation/. For MCP (Cursor, Claude Desktop), run node cli/index.mjs mcp or npm run mcp and configure per docs/AGENT-ORCHESTRATION.md.
11. Hub (optional) — Self-hosted API + OAuth + JWT for shared vault and proposals. From repo root: cd hub && npm install && cd .., set KNOWTATION_VAULT_PATH and HUB_JWT_SECRET, then npm run hub. Open http://localhost:3333/ in a browser (Rich Hub UI is served by the same server). Log in with Google/GitHub if OAuth env vars are set; otherwise use the API only. See hub/README.md and docs/HUB-API.md. CLI: knowtation hub status --hub http://localhost:3333, knowtation propose <path> --hub <url> --intent "..." (requires KNOWTATION_HUB_TOKEN).

Hosted admin (operators): On the hosted product (knowtation.store), admins are designated by setting HUB_ADMIN_USER_IDS in the gateway's env (comma-separated user IDs, e.g. google:108077705743543803349). Users in that list get role admin (Edit, Team tab); others get member. See hub/gateway/README.md.