Tesserae v0.18.0 — ask answers, the engine remembers, doctor heals

<!-- translations:start -->

한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end -->

Released 2026-07-10 · PyPI · GitHub release · pip install --upgrade tesserae==0.18.0

A full revision of the command surface, driven by one observation: tesserae ask "what happened recently?" used to return static concept pages and an honest shrug. The theme: the commands now do what their names promise.

ask plans its retrieval — and answers by default

tesserae ask no longer needs --llm: the model reads your question first, plans which knowledge-graph primitives can answer it (timeline, recent sessions, activity digest, temporal facts, wiki pages), executes that plan, and synthesizes a cited answer. Temporal questions get dated evidence instead of concept-page soup. --no-llm forces search-only; TESSERAE_QUERY_DRY_RUN and the classic BM25 path remain the deterministic fallback on any failure. Raw retrieval — BM25 hits, semantic search, and the explicit raganything/cognee backends — now lives in tesserae query.

Daily session chunks: 20× faster time-range recall

The engine's session tailer now writes every observed turn into a daily chunk store (.tesserae/session_chunks.db), and refresh backfills it incrementally under a skip-if-held lock. Windowed reads (summary, decisions, ask's activity retrieval, MCP) serve covered days from chunks — measured 2.3s vs 48.8s on a 45k-node project — with a parity-guaranteed raw-scan fallback, so a missing or corrupt chunk db can never change results, only speed. tesserae sessions chunk-backfill [--since] builds history on demand.

tesserae doctor

Twenty health checks in about two seconds: init/graph/config parsing, registry consistency, staleness, live locks, login state, hygiene. --fix applies only the provably safe repairs (stale pidfiles, oversized hook logs, registry pruning, site rebuilds) and never touches a live compile lock. Reports persist to .tesserae/doctor-report.{md,json} and are served over MCP as doctor_report.

init is the whole installation

tesserae init detects the LLM CLIs on your machine, checks they are actually logged in, and lets you pick — including a custom claude-compatible endpoint (--llm-provider custom --llm-base-url … --llm-api-key … --llm-model …). Keys resolve env → project → global (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, TESSERAE_LLM_MODEL); a plaintext-persisted key warns once. Re-init merges your config instead of clobbering it.

Leaner backends, honest flags

cognee is now off by default, silenced when used, installable as tesserae[cognee], and the codex_cognify mode is gone (−556 LOC). understand-anything no longer auto-adopts on artifact presence. And an adversarial pass over all 26 commands renamed or removed every lying flag — summary --project→--name (with strict name validation), context --synthesize→--llm, refresh --skip-sessions→--no-sessions, vault --poll-interval→--interval, ingest --exact→--full, dead flags deleted — each old spelling prints a one-line pointer to the new one and exits 2. Behavior fixes ride along: an empty sessions import can no longer wipe the store, ingest --dry-run is truly dry, serve --dry-run runs before builds, and the MCP server finally reports its real version.

Breaking changes

Every removed or renamed flag/command prints its replacement and exits 2 — nothing fails silently. The full table: ask --llm|--wiki|--backend|--cognee-*, query --llm|--no-llm|--model, summary|decisions --project, context --synthesize, refresh --skip-sessions, vault sync --poll-interval, vault export --vault, ingest --exact, research --no-web, compile --claude-timeout, config setup, wiki|projects activate.