beads/website/docs/cli-reference
Wldc4rd c8de26d4a6
feat(prime): cap injected memories with count/char budgets and a visible elision banner (#4569)
* feat(prime): cap injected memories with count/char budgets and a visible elision banner

bd prime injects every persistent memory, whole, in alphabetical key
order, with no cap. Hook hosts cap what they ingest from SessionStart
(Claude Code persists ~25K tokens and previews far less), so a large
memory set silently loses everything past the cut -- and because the
order is alphabetical, whether a memory survives is an accident of its
key's first letter, unrelated to importance. On a real workspace with
102 memories (~160KB, ~40K tokens) roughly 80% of memories were never
ingested on any session start, which surfaced as agents "forgetting"
in-flight work after every compaction.

Add two opt-in caps, resolved flag-over-config so hook commands or
repos can adopt them without touching every hook line:

  --max-memories N      / prime.max-memories
  --max-memory-chars N  / prime.max-memory-chars

Caps apply at whole-memory boundaries and at least one memory is
always emitted, so a single oversized memory can exceed the char
budget rather than vanish. When entries are elided, a banner ahead of
the entries -- where host truncation cannot hide it -- reports how
many were cut and points at bd memories for the rest: a capped prime
never silently drops context. An explicit flag value of 0 forces
unlimited over a configured cap. Defaults leave output byte-identical
to today.

Keys stay in sorted order because the memory store keeps no
timestamps; recency- or pin-aware selection needs sidecar metadata and
is left as follow-up.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(prime): validate cap config keys, banner names only the binding cap

Maintainer follow-ups from review of #4569, kept on the contributor
branch so the PR can merge as-is:

- validateYamlConfigValue gains non-negative-integer cases for
  prime.max-memories / prime.max-memory-chars. Without them a typo like
  `bd config set prime.max-memory-chars 25k` reported success while
  viper's GetInt coerced the value to 0 = uncapped, silently disabling
  the cap the user believed was active - the exact failure this feature
  exists to prevent.
- The elision banner now names only the cap that actually fired. With
  both caps configured and only one binding, it previously listed both,
  producing self-contradictory output ("showing 3 of 10 ... capped by
  max-memories=50") and steering users to the wrong knob.
- Flag help and doc comments now say the char cap counts bytes of the
  memory entries only (header and banner excluded), matching the
  implementation; document the keys in docs/CONFIG.md alongside their
  peers.
- gofmt alignment in recognizedConfigKeys; reuse existing sortedKeys()
  and truncate() helpers instead of inline re-implementations.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie

* docs(cli): regenerate CLI reference for prime memory-cap flags

Regenerated with scripts/generate-cli-docs.sh (pinned pure-Go build) so
the check-doc-flags CI job passes; #4569 added two bd prime flags
without refreshing the generated docs.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie

---------

Co-authored-by: Charlie Coutts <240021994+Wldc4rd@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: CI Bot <ci@beads.test>
2026-07-06 15:29:49 -07:00
..
admin.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
ado.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
assign.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
audit.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
backup.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
batch.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
blocked.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
bootstrap.md fix(init): use git origin as default Dolt remote (#3909) 2026-05-13 07:02:39 -07:00
branch.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
children.md fix(cli): implement children pretty and defer reason 2026-06-13 21:22:38 -07:00
close.md fix(close): support per-id reasons (#4194) 2026-05-27 20:41:07 -07:00
comment.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
comments.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
compact.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
completion.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
config.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
context.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
cook.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
count.md feat(count): add --include-infra for exact bd list cardinality parity (#4389) 2026-06-13 04:14:28 -07:00
create-form.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
create.md feat(create): add status flag for initial issue status (#4536) 2026-07-05 11:15:48 -07:00
defer.md fix(cli): implement children pretty and defer reason 2026-06-13 21:22:38 -07:00
delete.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
dep.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
diff.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
doctor.md fix(init): use git origin as default Dolt remote (#3909) 2026-05-13 07:02:39 -07:00
dolt.md feat(dolt): git-origin collision guard in bd dolt remote add + bd doctor (be-7eu1d) (#4153) 2026-07-04 14:37:51 -07:00
duplicate.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
duplicates.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
edit.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
epic.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
export.md feat(prune): reference-aware bd prune skips closed beads cited by open beads (be-jewoem, be-u2mw2x) (#4023) 2026-07-05 15:57:27 -07:00
federation.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
find-duplicates.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
flatten.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
forget.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
formula.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
gate.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
gc.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
github.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
gitlab.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
graph.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
heartbeat.md feat(lease): land the leasing stack + schema v54 (claim-TTL, heartbeat, reclaim) (#4537) 2026-07-03 23:28:55 -07:00
history.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
hooks.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
human.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
import.md feat(count): add --include-infra for exact bd list cardinality parity (#4389) 2026-06-13 04:14:28 -07:00
index.md feat(prune): reference-aware bd prune skips closed beads cited by open beads (be-jewoem, be-u2mw2x) (#4023) 2026-07-05 15:57:27 -07:00
info.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
init-safety.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
init.md fix(init): guard JSONL init against remote history 2026-06-22 15:28:38 -07:00
jira.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
kv.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
label.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
linear.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
link.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
lint.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
list.md Fix rig bead durability (#4373) 2026-06-22 17:06:35 -07:00
mail.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
memories.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
merge-slot.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
metrics.md fix(cli): handle unchecked output-helper errors + regen metrics CLI docs (#4482) 2026-06-23 02:18:01 -07:00
migrate-personal.md feat(prune): reference-aware bd prune skips closed beads cited by open beads (be-jewoem, be-u2mw2x) (#4023) 2026-07-05 15:57:27 -07:00
migrate.md /{cmd,docs,website}: gen docs again 2026-05-26 10:13:11 -07:00
mol.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
note.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
notion.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
onboard.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
orphans.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
ping.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
preflight.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
prime.md feat(prime): cap injected memories with count/char budgets and a visible elision banner (#4569) 2026-07-06 15:29:49 -07:00
priority.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
promote.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
prune.md feat(prune): reference-aware bd prune skips closed beads cited by open beads (be-jewoem, be-u2mw2x) (#4023) 2026-07-05 15:57:27 -07:00
purge.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
q.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
query.md /docs: regen CLI reference for bd query --offset flag 2026-06-24 14:47:29 -07:00
quickstart.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
ready.md docs: regenerate CLI reference for bd ready --offset 2026-06-18 13:55:12 -07:00
recall.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
reclaim.md feat(lease): land the leasing stack + schema v54 (claim-TTL, heartbeat, reclaim) (#4537) 2026-07-03 23:28:55 -07:00
recompute-blocked.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
remember.md docs(cli): regenerate CLI reference for bd remember bare-key reads (#4545) 2026-07-02 09:14:33 -07:00
rename-prefix.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
rename.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
reopen.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
repo.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
restore.md fix(compact): archive content before destructive compaction; make restore work (#4464) 2026-06-20 14:12:07 -07:00
rules.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
search.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
set-state.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
setup.md init: run Codex project setup by default 2026-05-26 13:03:37 -07:00
ship.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
show.md feat(show): count-only JSON details with opt-in streamed payloads 2026-05-22 16:54:15 -07:00
sql.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
stale.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
state.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
status.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
statuses.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
supersede.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
swarm.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
tag.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
todo.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
types.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
undefer.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
update.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
upgrade.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
vc.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
version.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
where.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00
worktree.md fix(docgen): generate CLI docs in one process (#4474) 2026-06-22 18:25:58 -07:00