Skip to content

Updating

Jump to bottom
Daniel Nevoigt edited this page Jun 1, 2026 · 1 revision

Updating & Settings

How bastra-recall detects new releases, how to update, and the opt-in auto-update. Wie bastra-recall neue Releases erkennt, wie man aktualisiert, und das Opt-in-Auto-Update.

🇬🇧 English

TL;DR

bastra                              # status panel: version, update, daemon, vault
bastra update                       # update now (npm/brew) + re-register + restart daemon
bastra config set update.mode auto  # opt into hands-off updates at session start

The status panel — bastra

Running bastra with no arguments prints a one-shot status panel:

┌ bastra-recall ──────────────────────┐
  version  0.6.0  ✓ up to date
  update   mode: notify
  daemon   ✓ running (port 6723)
  vault    191 memories
└─────────────────────────────────────┘
  bastra help                       all commands
  bastra config set update.mode …   notify | auto | off

It probes the local daemon's /health for the live version, vault size and update status. If the daemon isn't running, it falls back to the compiled-in version and says so. This is the OSS "control surface" — status and flags only; browsing and editing memories lives in the Bastra Mac app.

Update detection

On startup the daemon checks the latest GitHub release once per 24 h (cached in ~/.bastra/update-check.json) and compares it against the running version. The result is surfaced three ways:

  • in /health as update_available,
  • as a dim one-line hint after any bastra command (max once/day),
  • as a <bastra-update> block in the Claude Code SessionStart context, so the assistant can mention it.

The GitHub call is unauthenticated and fail-tolerant — offline or rate-limited, it falls back to the cached result and never blocks anything.

update.mode — three modes

Stored in ~/.bastra/cli-settings.json (separate from the Mac app's config.json). Default: notify.

Mode Behaviour
notify Detect + show hints. You run bastra update yourself. (default)
auto Detect + stage the update automatically at session start (see below).
off No detection, no hints, no auto.

Set it with:

bastra config get update.mode
bastra config set update.mode auto

The env var BASTRA_UPDATE_CHECK=off is a hard kill-switch that overrides the stored mode.

Auto-update (mode = auto)

When auto is on, a new Claude Code session (startup/resume only — never mid-session) triggers a staged update, throttled to once per day:

  1. A detached bastra update --staged swaps the files only (npm i -g / brew upgrade + re-register) — it does not restart the running daemon, so your current session is never disrupted.
  2. The new code goes live on the next daemon restart — automatically after 30 min idle, or immediately when you restart your AI clients.
  3. The session context tells you an update is being applied and to restart your clients when convenient.

This is deliberately conservative: updates are never forced onto a running daemon, and auto is opt-in — package-manager installs + a restart are too invasive to enable silently.

bastra update — manual

bastra update detects how bastra was installed (Homebrew / npm-global / source checkout) and runs the matching update, re-registers every surface (idempotent), and restarts the daemon:

bastra update            # update + re-register + restart
bastra update --dry-run  # show what would happen, change nothing
bastra update --staged   # swap files only, no restart (what auto-mode uses)

🇩🇪 Deutsch

TL;DR

bastra                              # Status-Panel: Version, Update, Daemon, Vault
bastra update                       # jetzt aktualisieren (npm/brew) + neu registrieren + Daemon-Neustart
bastra config set update.mode auto  # freihändige Updates am Session-Start aktivieren

Das Status-Panel — bastra

bastra ohne Argument gibt ein einmaliges Status-Panel aus:

┌ bastra-recall ──────────────────────┐
  version  0.6.0  ✓ up to date
  update   mode: notify
  daemon   ✓ running (port 6723)
  vault    191 memories
└─────────────────────────────────────┘
  bastra help                       all commands
  bastra config set update.mode …   notify | auto | off

Es fragt /health des lokalen Daemons nach Live-Version, Vault-Größe und Update-Status ab. Läuft der Daemon nicht, fällt es auf die einkompilierte Version zurück und sagt das. Das ist die OSS-„Steuerfläche" — nur Status und Flags; das Durchsuchen und Bearbeiten von Memories bleibt der Bastra Mac App vorbehalten.

Update-Erkennung

Beim Start prüft der Daemon einmal pro 24 h den neuesten GitHub-Release (gecacht in ~/.bastra/update-check.json) und vergleicht ihn mit der laufenden Version. Das Ergebnis erscheint an drei Stellen:

  • in /health als update_available,
  • als dezenter Einzeiler nach jedem bastra-Befehl (max. 1×/Tag),
  • als <bastra-update>-Block im Claude-Code-SessionStart-Kontext, damit der Assistent es erwähnen kann.

Der GitHub-Aufruf ist unauthentifiziert und fehlertolerant — offline oder rate-limited fällt er auf den Cache zurück und blockiert nie etwas.

update.mode — drei Modi

Gespeichert in ~/.bastra/cli-settings.json (getrennt von der config.json der Mac App). Default: notify.

Modus Verhalten
notify Erkennen + Hinweise zeigen. Du führst bastra update selbst aus. (Default)
auto Erkennen + Update am Session-Start automatisch stagen (siehe unten).
off Keine Erkennung, keine Hinweise, kein Auto.

Setzen mit:

bastra config get update.mode
bastra config set update.mode auto

Die Umgebungsvariable BASTRA_UPDATE_CHECK=off ist ein harter Kill-Switch, der den gespeicherten Modus übersteuert.

Auto-Update (mode = auto)

Ist Auto aktiv, löst eine neue Claude-Code-Session (nur startup/resume — nie mitten in einer Session) ein gestagetes Update aus, gedrosselt auf 1×/Tag:

  1. Ein detached bastra update --staged tauscht nur die Dateien (npm i -g / brew upgrade + neu registrieren) — es startet den laufenden Daemon nicht neu, deine aktuelle Session wird also nie gestört.
  2. Der neue Code wird beim nächsten Daemon-Neustart aktiv — automatisch nach 30 min Leerlauf, oder sofort, wenn du deine AI-Clients neu startest.
  3. Der Session-Kontext teilt dir mit, dass ein Update angewendet wird und du deine Clients bei Gelegenheit neu starten sollst.

Bewusst konservativ: Updates werden einem laufenden Daemon nie aufgezwungen, und auto ist Opt-in — Paketmanager-Installs + Neustart sind zu invasiv, um sie still zu aktivieren.

bastra update — manuell

bastra update erkennt, wie bastra installiert wurde (Homebrew / npm-global / Source-Checkout), führt das passende Update aus, registriert alle Surfaces neu (idempotent) und startet den Daemon neu:

bastra update            # Update + neu registrieren + Neustart
bastra update --dry-run  # zeigt, was passieren würde, ändert nichts
bastra update --staged   # nur Dateien tauschen, kein Neustart (was Auto-Mode nutzt)

Bastra.Recall Wiki

Clone this wiki locally