Configuration

Advanced Configuration

How to be a Waystone rock star. The default install is intentionally minimal — this is for power users who want to tune past the defaults. Everything here lives in ~/.waystone/config.yaml; missing keys fall back to defaults.

Embeddings: local model vs. API

Semantic search and paraphrase de-duplication need an embedding model. There are two backends.

Local (default)

Uses BAAI/bge-small-en-v1.5 via sentence-transformers — fully offline, no API cost, but it pulls in PyTorch (a large download), so it's an opt-in extra:

pip install "waystone[semantic]"

sqlite-vec (the vector store) is always installed; only the embedding model is optional.

API backend (no PyTorch)

Embed through your LLM provider's embedding endpoint via litellm (already a core dependency) — no PyTorch, no local model download. Ideal for lightweight environments (Windows especially) where you'd rather use an API key than install a multi-GB ML stack.

embeddings:
  backend: api
  model: gemini/text-embedding-004   # any litellm-supported embedding model
  dim: 768                           # MUST match the model's output dimension
  api_key_env: GEMINI_API_KEY        # optional; falls back to your llm api key

Provider	model	dim
Gemini	`gemini/text-embedding-004`	768
OpenAI	`text-embedding-3-small`	1536
OpenAI	`text-embedding-3-large`	3072

dim must exactly match the model. The vector table's column width is fixed at creation; a mismatch makes inserts fail.

Switching backends → re-embed

Vectors from different models aren't comparable, and the vector table's dimension is fixed when created. After changing backend, model, or dim, rebuild the embeddings:

waystone reembed <project>

This drops the vector table, recreates it at the new dimension, and re-embeds every node. New/empty projects don't need it — the table is created at the configured dimension on first use.

Retrieval strategy tuning

The retrieval pipeline is a sequence of toggleable strategies — set them in config, or override per-query with --enable/--disable:

strategies:
  superseded_pruning: true     # drop facts that have been superseded
  confidence_threshold: 0.0    # e.g. 0.6 to hide tentative facts
  recency_decay: false         # weight recent facts higher
  recency_half_life_days: 30   # how fast old facts fade (when decay is on)
  token_budget: 0              # 0 = unlimited; e.g. 500 to cap injected context
  relevance_scoring: true      # rank entry nodes by tag overlap
defaults:
  hops: 3                      # BFS traversal depth
  top_k: 10                    # max facts returned per query

Noisy / oversized context? Lower top_k, set a token_budget, or raise confidence_threshold.
Missing relevant facts? Raise hops and top_k.
Fast-moving project? Enable recency_decay so stale decisions fade.

Test changes live: waystone query <project> "<question>" --stats.

Chat attachment auto-extraction

Long Discord/Telegram messages arrive as message.txt attachments, so their text never reaches the prompt directly. Waystone's submit hook scans the plugin inbox (.claude/discord/inbox/, .claude/telegram/inbox/) and auto-extracts any new .txt attachment into the graph like a normal turn. A per-project ledger prevents re-extraction. No action needed — it's automatic.

Pausing extraction

Extraction calls your LLM. To pause it while keeping retrieval from the existing graph:

waystone pause     # turns are still buffered while paused, not lost
waystone resume