Getting Started

Getting Started

There are two ways to run Scholion:

• Lite mode (recommended to start): no Docker; the daemon runs its own Postgres. Semantic search is off.
• Full stack (Docker): Postgres, Qdrant and an embedding server, so context packs also rank by semantic similarity.

Lite mode (Linux and macOS)

curl -fsSL https://raw.githubusercontent.com/vinhqbui/scholion/main/scripts/install.sh | sh
cd your-repo
av init                      # starts the daemon, imports this repo, wires Claude Code

The installer puts scholion, av (the same program) and scholion-daemon into ~/.local/bin from the releases page.

• av up starts scholion-daemon in the background on 127.0.0.1:7420 and waits until it answers; av down stops it. av init calls av up when no daemon answers.
• With no AV_DATABASE_URL, the daemon runs its own user-space Postgres 16. Release builds bundle it; source builds download it on first start. Postgres refuses to run as root.
• Daemon data lives in ~/.scholion (pg/, store/, daemon.log, daemon.pid). Task workspaces appear under ~/ws.

Wire other agents to the same daemon:

av init --for codex --for gemini --for grok --for cursor
av --agent muse init --for mcp-json --path PATH/TO/settings.json   # any mcpServers JSON client

See Agent Integrations.

Full stack (Docker)

Prerequisites: Docker with Compose, and a Rust toolchain for the host-side CLI.

export UID GID=$(id -g) AV_IMPORT_ROOT=~/projects     # bash does not export UID; compose needs both
docker compose -f deploy/docker-compose.yml up -d --build
cargo build --release -p scholion-cli                 # -> target/release/scholion and av
claude mcp add --transport http av http://localhost:7420/mcp
av repo add myrepo /import/myrepo                     # path as seen inside the container

The stack runs Postgres 16, Qdrant, text-embeddings-inference (TEI, BAAI/bge-small-en-v1.5 on CPU) and the daemon, all bound to 127.0.0.1. The first build compiles the daemon and TEI downloads its model on first start, so give it a few minutes.

Semantic layer. It is on when AV_QDRANT_URL is set and an embedder is found: a host ollama with a qwen3-embedding model, otherwise AV_EMBED_URL (TEI in compose). If Qdrant or the embedder is unreachable, packs still return, built from structure and Postgres full-text, and are marked degraded: semantic. After changing the embedding model, run av reindex with no --repo (it recreates the collections at the new dimension).

All variables are listed in Configuration.

Docker Desktop without WSL integration

Without WSL integration for the distro, Docker cannot bind-mount WSL paths (the mount silently lands inside Docker's VM). Keep the workspace and import folders on a Windows drive and give both names:

export AV_WS_ROOT=/mnt/c/Users/me/avws       AV_WS_MOUNT='C:\Users\me\avws'
export AV_IMPORT_ROOT=/mnt/c/Users/me/avsrc  AV_IMPORT_MOUNT='C:\Users\me\avsrc'

docker.exe also does not see WSL variables unless they are listed in WSLENV. Enabling WSL integration for the distro avoids all of this.

Your first task

av task start --repo myrepo --title "Add retry" --goal "retry embedder calls with backoff"
cd ~/ws/myrepo/add-retry           # printed as `workspace:`
# ... edit files ...
av checkpoint                      # snapshot + refresh the index
av record --kind decision --summary "exponential backoff, max 5 tries" --anchor shared/text.py
av context                         # the context pack for this task
av submit                          # to review

Most of the time an agent does this for you through the MCP tools (see Agent Integrations). Open http://localhost:7420/ui to watch tasks, records, the backlog and the activity feed.

Data and shutdown

• Lite mode: av down. Data stays in AV_HOME (~/.scholion).
• Docker: named volumes av-store (jj repositories), av-pg, av-qdrant, av-tei. docker compose -f deploy/docker-compose.yml down stops the stack; scripts/smoke.sh --down also deletes the volumes.