Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.backant.io/llms.txt

Use this file to discover all available pages before exploring further.

The first move is always backant status. It surfaces most failures with a clear next step. The rest of this page is for when status isn’t enough.

​
Kairos won’t start

Symptom: backant start says “Backant requires an active subscription”.Fix: re-run backant login. If the subscription is genuinely lapsed, renew at backant.io.
Symptom: backant memory init or backant start fails with “cannot connect to Docker daemon”.Fix: start Docker Desktop (macOS) or sudo systemctl start docker (Linux). Verify with docker ps.
Symptom: ENOENT: no such file or directory referencing ~/.claude/kairos/memory/.Fix: run backant memory init. One-time, ~3-5 min depending on tier + network.
Symptom: Kairos refuses to start, citing “session already in progress” or returns to a corrupt state on every turn.Fix: backant start --fresh discards in-process state and re-reads memory from disk. Memory itself, config, and lessons are preserved.
backant stop
backant start --fresh
Symptom: memory init fails because 127.0.0.1:11434 is taken.Fix: another Ollama instance (native or container) is already bound to the default port. Stop it, or set KAIROS_OLLAMA_URL to a different port before re-running init.
# Identify the offender
lsof -i :11434

​
Memory issues

Three causes in order of likelihood:
  1. Empty memory. A brand-new install has nothing to recall. Memory accumulates as Kairos works.
  2. Wrong tier. Try backant memory recall "<cue>" --tier any.
  3. Stale embeddings. If you switched models via memory init without running memory reindex, the stored vectors don’t match the new model’s dimensionality.
backant memory reindex
Symptom: SqliteError: no such column: ... or similar.Cause: the DB was created by an older Kairos version with a different schema. Migrations are not yet fully automated for all schema changes.Fix: archive and recreate.
backant stop
mv ~/.claude/kairos/memory/.index.db ~/.claude/kairos/memory/.index.db.bak
backant memory init
Your dream logs, eval reports, and .backant.toml are unaffected.
Memory does not grow unbounded — STM entries decay over time and are archived below a threshold. But you can inspect:
backant memory stats
If LTM is bloated with consolidated facts that are no longer relevant, the wake-time triage tools (memory_promote, memory_demote, prune_with_confirmation) handle pruning. Kairos invokes these as part of normal operation.Manual pruning is rarely needed.

​
Cost issues

Three things to try, in order of impact:
  1. Throttle: backant start --pace. Auto-stretches the pause between turns when rate-limit utilization is high.
  2. Lower the per-turn cap: drop max_cost_per_cycle in .backant.toml from 15.0 to 5.0.
  3. Inspect: backant eval run --window-days 3 shows you which turns are expensive and why.
max_cycles_per_day = 100 is the default safety cap. Kairos stops for the day when it’s hit and resumes at local midnight.Most workspaces don’t approach 100/day. If you’re hitting it, something is off — either:
  • The repo is unusually busy
  • Turns are completing trivially without doing work (memory not loading, network flapping)
  • You set the cap unusually low
backant eval report will show whether work is productive.

​
PR / GitHub issues

Symptom: turn reports “gh: not authenticated” or PR-create fails.Fix: gh auth status to verify, gh auth login if needed. Kairos uses your existing gh token.
Tighten .backant.toml:
[permissions]
merge = false
modify_dependencies = false
modify_ci = false

[scope]
exclude = ["the/path/to/protect/**"]
Restart with --fresh so policy changes take immediate effect.
By default, Kairos prefers small focused PRs. If you’re seeing large ones, two knobs:
  • Disable [permissions].create_epics — without epics, Kairos sticks to single-PR work
  • Set [permissions].strategic_work = false — limits Kairos to reactive work (bug fixes, PR feedback)
Restart with --fresh.

​
Kairos got into a bad state

The nuclear option: 
backant stop
rm -rf ~/.claude/kairos/.session ~/.claude/kairos/.state
backant start --fresh
This preserves memory, dreams, eval reports, credentials, and .backant.toml. Only in-process scratch is dropped. If even that doesn’t help, full reset is documented on the Privacy page.

​
Still stuck?

When reporting, include:
  • Output of backant status and backant memory stats
  • The contents of .backant.toml (no secrets — it’s policy)
  • The relevant section of ~/.claude/kairos/logs/ for the time of the incident