v1.5.0

Choose at setup how often briefings are rewritten, and a project's own rule now wins over a user-wide one. Linux amd64 is tested; Windows amd64 is tested in CI. The Linux arm64 and macOS binaries are built but not tested.

Update from v1.4.0 or any earlier release with backsight update apply: it takes a verified backup first and rolls back if a step fails. Then restart Claude Code (and Codex), so they read the new memory instructions. New install: see below.

• The server is unchanged (Hindsight 1.2.0): no server upgrade. The memory bank's template is unchanged.
• The instruction set is v21 (v20 before): the precedence rule below.
• The plugins and the metrics index are unchanged.
• No new setting: recall.briefing_refresh_interval exists since v0.1.32-m7, and an existing install keeps its value. An older backsight reads this version's config.toml as is.

What changed

• How often briefings are rewritten, asked at setup. The briefing each session starts with is a page the server's LLM rewrites from the project's memories, at most once per recall.briefing_refresh_interval. Setup now asks it (briefing_refresh): 1h (close to your latest work), 6h (the default, balanced) or 24h (the cheapest; a session can start on a briefing up to a day behind), or any duration. Each option shows what it costs a month per active project with the model you picked, from what one install measured: about 105,000 input tokens a rewrite, and about 5, 2 and 1 rewrites a day per project worked on daily. With DeepSeek's peak prices that is about 5.36, 2.14 and 1.07 USD; with Claude Haiku 5.5 about 2.24, 0.89 and 0.45 USD; on a Claude subscription, no money but your plan's usage. Setup writes the answer to config.toml only when it is not 6h; an installed PC changes it there, and the next jobs tick gives every page the new floor. Setup asks it on the PC it sets up, not on a server-only host; a PC joined with backsight connect keeps 6h until you set the same value in its config.toml (#325).
• Refreshing a briefing when a session opens it: measured, not built. A rewrite takes about 22 s, more than a session start can wait, so the session that triggered it would still see the old page: the first session after a break, the one that needs a fresh page most. At today's freshness it would save about 1 USD a month. Since v0.1.32-m7's floor, briefings are about 7 % of the server's LLM cost, not 31 % (#325).
• A project's own rule wins over a user-wide one there. The memory instructions said "User-wide rules override conflicting project facts", which let a general rule beat a project's deliberate exception ("this repository uses merge commits" against "squash-merge"). Now a project's own standing convention, decision or correction wins in that project; a project memory that records a past event never overrides a user-wide rule (#336).

Install

On Linux:

curl -fsSL https://raw.githubusercontent.com/Barben360/backsight/main/scripts/install.sh | sh
backsight setup

On Windows x86_64, in PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Barben360/backsight/main/scripts/install.ps1 | iex"
backsight setup

Requirements as for v0.1.22-m7. On Windows, Claude Code must find Git Bash: if Git for Windows is portable or installed in a place of your own, set CLAUDE_CODE_GIT_BASH_PATH to its bin\bash.exe (doctor's git-bash check gives the command).

For Codex, install Codex 0.167.0 or newer first (npm install -g @openai/codex@latest): setup then asks which tools to wire. Claude Code is not needed for Codex alone (Codex).

Known limits

• Briefing refresh:
  • The monthly costs setup shows come from one install's usage over four days: a project with more new memories a day gets more rewrites, up to 24, 4 and 1 a day at 1h, 6h and 24h. DeepSeek bills half price off-peak, so its figures can be up to twice the real cost.
  • Each PC sets its own floor on every page: PCs sharing one memory with different values undo each other's every day (doctor's bank check names it). backsight connect does not carry the host's value, and server install --ssh does not take it: set the same value in every PC's config.toml.
  • Setup does not ask it again on an installed PC: change recall.briefing_refresh_interval in config.toml.
• Codex:
  • No test with a real model yet: the automated checks run a real Codex 0.167.0 against a fake model. How a real model follows the guide with Codex's tool names (when it searches and credits), the skills' texts and the sandbox line, and its tokens per session are not measured yet.
  • On Windows, the hooks' cmd /C form (paths with spaces in particular) and the skills' backsight commands in PowerShell, Codex's shell there, have not been run on a real PC. Check that backsight's first line appears at your first prompt once you trust the hooks.
  • The memory tools' new declarations are served to Claude Code too; that they change nothing in its permission prompts is not checked with a real session yet.
  • A coding-tool filter (--client, the dashboard's Coding tool) counts this PC's data only: the other PCs send no tool, the PC switch is not offered under it, and the server's figures stay whole (not_filtered).
  • A setup rerun that picks only codex, on a PC where Claude Code is wired, does not offer Claude Code's past sessions: its backfill covers the tools picked (backsight retain backfill --tools claude-code sends them).
  • A headless Codex session is queued only for the facts stored explicitly in it (memory_store), as a Claude Code Agent SDK session is.
  • A Codex with no record of the Claude Code shell it was started from (its hooks not trusted yet, or started before this update): pause, store, why and feedback log inside it fall back to that Claude Code session. Pause by id there: backsight pause --session <id>, with the value of $CODEX_SESSION_ID.
  • Codex reports no failed tool call to its hooks, so recall.failure_pitfalls does nothing there. backsight does not manage how long Codex keeps its history. After /clear, Codex sends no end: the old session is sent by the background job, 30 minutes after its last turn.
  • A forked Codex session may be sent with some turns twice, never fewer (not checked yet). A turn that works in several folders is filed under the project of the first one, sorted.
  • Codex runs each hook through your login shell ($SHELL -lc): a slow profile slows every prompt.
• backsight memory states:
  • GitHub only, and only memories saying a pull request or issue is still open: a memory saying a fix is merged but in no release yet is not checked.
  • It reads the memory's words, not its meaning: a stale memory worded in a way it does not recognise is not listed (skipped or not counted), and a memory listed is worth a glance before --retire. The wordings are English.
  • GitHub answers "not found" both for a missing repository and for one your login cannot see: with several owners, a repository hidden under one owner leaves a same-named one under another to decide.
  • It runs only when you run it; no background job checks these memories.
• The new extraction rules apply to what is extracted from now on: a memory already wrong stays until Claude reports it or you retire it (backsight memory stale, backsight memory states, backsight forget <id>). Whether the server's model follows them is checked on live extractions, not in tests.
• Whether 5 memories and 1,500 characters on a prompt help more than they cost in context is measured on live use (the Per recall line), not in tests.
• A fact Claude stores as a correction, then reports outdated with memory_credit, is stored as two correction notes.
• Dashboard:
  • Version switches and settings changes are marked on a day's page and on Releases only, not on every chart.
  • The custom window goes back 13 months, as far as this PC keeps its history.
  • Time to recall needs a few days of history, and 20 sessions before it shows times; it is judged (ok or watch) only from 100 sessions, and reads "too few" until then.
  • A window, custom or typed in a URL, can span at most 400 days, between 2000 and 2099.
  • Bank growth still counts a UTC day that straddles the window's start as a whole day.
  • Memory yield needs four weeks: a week counts 28 days after it ends.
  • On a window over 200 days, charts show no per-day values on hover, and "Show as a table" lists the latest 120 days.
  • A week that is not complete shows no count of new memories.
  • The project filter takes a typed name, not a pick from a list (the Projects page lists the names). The Projects list cannot be sorted. The context card names the session budget rather than showing its value.
  • The Projects page reads the date of each project's latest memory from the server, one small read per project, four at a time (cached by the dashboard): with many projects, the page's first load takes longer.
• GPU reranker:
  • It needs the Docker runtime, on the server's PC.
  • Tested on one NVIDIA RTX A2000 (Linux) and one AMD Radeon 890M (Linux). Intel GPUs, macOS and Windows are not tested.
• Owner checks:
  • The short-lived native units created during install, start and restore are not checked.
  • On Windows, when neither schtasks nor the task's file can be read, the task is driven as before.
• retain resend-failed: it does not cover notes and sub-agent reports sent while extraction failed (the queue drops them once sent). A transcript rewritten or moved after its worktree was deleted loses the project recorded for those turns, so the session is then filed by today's rules.
• The metrics index: an index already in write-ahead mode whose folder no longer allows it fails its writes until the state directory is back on a local disk. stats days reads a year of prompts with no index for it (about 0.1 s locally).
• Import: a file the server keeps rejecting holds that folder's next files until it passes. The last tick before a cap can overshoot it by what was already in flight. A file deleted from the folder stays in the memory until import purge.
• Windows:
  • WSL is not tested, and Windows on Arm has no binary.
  • The native runtime is the only runtime there (server runtime switch is refused). It serves this PC only, has no web UI, and starts with your logon, not at boot.
  • backsight server status keeps showing the server's last refusal while it is stopped, until a start passes the check.
  • backsight's .exe files are not code-signed: SmartScreen or Smart App Control may warn about them. The install script checks the release signature before it runs anything.
• The terminal's look:
  • On Windows, the splash draws the ASCII logo unless the console's code page is UTF-8 (65001; chcp 65001): many consoles default to another one.
  • The views' tables (stats <view>) and section headings are not colored yet, nor setup --undo's list.
  • The braille logo needs a font with braille characters (most coding fonts have them); with one that lacks them, set terminal.logo = "blocks". The logo's dot can take two columns in an East Asian terminal.
• A new install reads "learning" for its first week, and some numbers read "too few" until enough prompts and turns accumulate.
• Extraction cost needs a price: the built-in table's, or one set under [llm] in the config file for another model (doctor's price check says when none is known). The server reports token counts for all PCs together.
• On native, PostgreSQL is 18.1 with pgvector 0.8.5, where the Docker image runs 18.6 with 0.8.7; backup verify runs in the runtime that will restore.
• On Windows, the commands the dashboard and stats --json offer to copy are quoted for PowerShell; run through Git Bash, a name holding an apostrophe comes out without it.
• Claude cannot run /reload-plugins: after an update from the session, you type it.
• A LAN address carries the API key in clear; a tailnet address encrypts it.
• The shared part of a session continued on two PCs may be stored twice.
• Several PCs: a PC sends its figures once a UTC day, up to the day before, so another PC's today is not in all PCs until the next day; the others' figures are fetched every 6 hours. A PC counts in a window by the noon (UTC) of each of its days. The other PCs send no project, session, memory or coding tool: Projects, Sessions and Memories stay this PC's, and a project filter does not narrow the others (other PCs: not filtered). The verdict stays this PC's. Speed across PCs is a range from time buckets, never an exact time, and the PCs' figures are trusted as sent: nothing signs them.
• The feedback database:
  • After a rollback to an older version and an update again, the counts that version added catch up at the first tick.
  • In a rare race during an update or a rollback, an older version can leave one tick's shows out of its ledger.json; this version's next tick counts them.

Report problems at https://github.com/Barben360/backsight/issues, after reading the diagnostic backsight report prints, or ask Claude /backsight:doctor (in Codex, $backsight:doctor). Report vulnerabilities privately, as https://github.com/Barben360/backsight/blob/main/SECURITY.md describes.