feat(remember): opt-in memories.budget-chars — warn at 80%, refuse a write that crosses the corpus budget (--force overrides) (#6508)

* feat(remember): opt-in memories.budget-chars — refuse a write that crosses the corpus budget (wy-2pox7y)

The wheelhouse-side tripwire only REPORTS the memory-corpus size, so the corpus
re-trips red every few days and nothing has ever stopped the write that crossed
the line. This is the stop.

New config key `memories.budget-chars` (integer, default 0 = OFF), wired exactly
like `prime.max-memory-chars`: recognized in cmd/bd/config.go, routed to yaml in
internal/config YamlOnlyKeys (it is read through viper, so a DB-backed write
would be accepted and then never read), validated non-negative at set time, and
documented in docs/reference/configuration.md.

With the budget ON, `bd remember` measures the corpus as the sum over every
memory of len(key)+len(content) — BYTES, the same unit `bd prime`'s
--max-memory-chars counts in — projected to AFTER the write would apply. An
overwrite replaces that key's old content in the sum rather than adding to it,
so a memory near the ceiling can still be edited.

  - over budget            -> refused, nothing written, exit 1, one line on stderr
  - over budget + --force  -> written, and the crossing is still announced
  - >= 80% and within      -> written, then warned
  - below 80%, or budget 0 -> silent; with the budget off the corpus is not even
                              read, so behavior is byte-identical to before

Every line goes to STDERR, so --json output is never corrupted; a --json refusal
additionally gets the normal machine-readable error object on stdout.

The whole decision is one pure function (rememberBudgetVerdict), which is what
lets the branches be pinned without a database.

Tests run (targeted, never ./...):
  go build ./...                                             rc 0
  go vet ./cmd/bd/ ./internal/config/                        rc 0
  go test ./cmd/bd/ -run 'Memor|Remember|Prime|Budget' -count=1   rc 0
  go test ./internal/config/ -count=1                        rc 0
  BEADS_TEST_EMBEDDED_DOLT=1 go test ./cmd/bd/ \
      -run TestEmbeddedMemoryCorpusBudget -count=1 -v        rc 0 (6/6 subtests)
  golangci-lint run --config=.golangci.yml --build-tags=gms_pure_go \
      ./cmd/bd/... ./internal/config/...                     0 issues in touched
                                                             files (one
                                                             pre-existing gosec
                                                             G304 in
                                                             internal/config/permissions_open_nonlinux.go)

New tests: cmd/bd/memory_budget_pure_test.go (byte unit incl. multibyte,
overwrite delta, budget-off silence, config read + negative clamp, the
at-budget/one-over boundary, --force, the 80% warn band and its edges,
unclamped percentage, single-line contract);
cmd/bd/memory_embedded_test.go TestEmbeddedMemoryCorpusBudget (the same five
spec points end to end against a real embedded-Dolt store, through
`bd config set`, asserting the exact stderr lines, the nonzero exit, and that a
refused write leaves the old content intact);
internal/config/yaml_config_test.go validation + yaml-only routing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013XmKxqKuXTaKivDiCoBwBV

* fix(remember): one --json refusal line, ceil on the over-budget percentage (wy-2pox7y)

Review fixes on ca9f14d65d. Three items; one review item turned out to be a
false alarm and is recorded here rather than acted on.

- BLOCKER 1 (CLI docs regeneration) — NO CHANGE NEEDED, and that is the
  finding. docs/cli-reference/ and docs/CLI_REFERENCE.md are not generated
  from this checkout: docs/cli-docs.pin pins them to release tag v1.2.2, and
  scripts/generate-cli-docs.sh, check-cli-docs-drift.sh and check-doc-flags.sh
  all resolve that pin (resolve-docs-bd.sh) and build bd from the TAG, because
  the published docs site describes the latest release, not main's source. No
  CI path sets BD_DOCS_IGNORE_PIN. So changing `bd remember`'s help surface on
  main cannot move the generated docs, and it did not:
  ./scripts/generate-cli-docs.sh ran to completion ("Generated CLI docs from:
  bd version 1.2.2 (dev)") and left the tree clean — zero diff. The gate is
  green at this commit and was green at ca9f14d65d. The --force flag and the
  Corpus budget paragraph reach the docs when the pin is bumped at release.

- NIT 1: the --json refusal said the same sentence twice, prose on stderr AND
  the envelope on stdout. It now says it ONCE, the way
  HandleErrorWithHintRespectJSON does it: --json gets only the stdout
  envelope, every other route gets the bare sentence on stderr. New subtest
  TestEmbeddedMemoryCorpusBudget/json_refusal_is_said_once asserts a nonzero
  exit, EXACTLY one JSON document on stdout (a second Decode must be io.EOF),
  the refusal sentence inside the envelope, a stderr with no "memory corpus"
  in it, and that the refused write left the old content intact.

- NIT 2: floor arithmetic made the refusal at 201 of 200 read "(100%)" — the
  exactly-at-budget value this code deliberately ALLOWS, so the refusal wore
  the number of the case it is not. The percentage now CEILINGS over the
  budget (101%) and still FLOORS within it. The split is on the VALUE, not on
  --force, so one projection cannot report two different percentages
  depending on a flag; that is why the forced over-budget line moved too.
  TestRememberBudgetVerdictBoundary, TestRememberBudgetVerdictForceWrites and
  TestMemoryBudgetLinePercentIsUnclamped updated; the warn band gains a
  999-of-1000 case pinning the floor inside the budget, so "100%" can only
  ever mean at-budget.

- NIT 5: one comment at the List/Remember seam saying the budget is ADVISORY
  and not atomic — the two are separate transactions, so concurrent writers
  can both measure inside the budget and both land. No locking.

Nits 3 (primeConfigInt duplication) and 4 were left alone by instruction.

Gates run from the worktree:
  go build ./...                                                      rc 0
  go vet ./cmd/bd/ ./internal/config/                                 rc 0
  go test ./cmd/bd/ -run 'Memor|Remember|Prime|Budget' -count=1       rc 0
  go test ./internal/config/ -count=1                                 rc 0
  BEADS_TEST_EMBEDDED_DOLT=1 go test ./cmd/bd/ \
      -run TestEmbeddedMemoryCorpusBudget -count=1 -v                 rc 0 (7/7)
  gofmt -l cmd/bd internal/config                                     no output
  golangci-lint run ./cmd/bd/ ./internal/config/                      1 issue, all
      pre-existing: gosec G304 in internal/config/permissions_open_nonlinux.go
      (last touched f4d496fed, not by this branch)
  ./scripts/check-cli-docs-drift.sh                                   rc 0
  ./scripts/check-doc-flags.sh                                        rc 0

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JFSKdUYCTyuhBM97tHyoye

* ci: list the PR's tests in the embedded shard manifest and cmd/bd BUILD.bazel

#7156 made the embedded-Dolt shard manifests exact-once, and Bazel equivalence
requires every test file in the go_test srcs. Adds TestEmbeddedMemoryCorpusBudget
(generator output, incremental) and memory_budget_pure_test.go (the line CI's
bazel-sync patch printed).

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

* fix(remember): budget the key ResolveKey writes; hint on stderr too

Review fixes for #6508 (apply-fixes iteration 1; all minor or nit):

- The budget credits an overwrite under memoryapi.ResolveKey's key, the
  one rule every Remember implementation writes under, instead of a
  parallel flag-else-derived copy of it. A write ResolveKey refuses
  skips the budget, so a whitespace-only --key gets the role's "memory
  key must not be empty" instead of an over-budget refusal that points
  at --force.
- The stderr refusal now carries the same hint as the --json envelope
  (raise the budget, forget a memory, or --force), printed the way
  HandleErrorWithHintRespectJSON prints one.
- The memoryCorpusChars comment and `bd remember --help` no longer
  imply that a budget equal to prime.max-memory-chars keeps prime from
  eliding memories: the unit (bytes) is the same, but prime counts each
  memory as rendered, markup included, so the budget has to sit below
  that cap for that.
- New embedded pins: a write without --key that crosses the budget is
  refused with exit 1 and writes nothing; a blank --key gets the
  validation error; the Hint line is on stderr and not under --json.
  Each pin was checked red against a mutant of the code it guards.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
This commit is contained in:
Bee 2026-10-06 23:04:06 +00:00 • committed by GitHub
commit 1ea5145092
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 732 additions and 1 deletions

View file

@ -293,6 +293,7 @@
50 16 TestEmbeddedGateInheritsDownParentChain
50 16 TestEmbeddedKV
50 16 TestEmbeddedMaxRowsReady
50 16 TestEmbeddedMemoryCorpusBudget
50 16 TestEmbeddedOpen_EmptyDatabaseRejected
50 16 TestEmbeddedRestoreConcurrent
50 16 TestEmbeddedVCCommitVariantsAndMerge

View file

@ -918,6 +918,7 @@ go_test(
"markdown_test.go",
"max_rows_embedded_test.go",
"max_rows_test.go",
"memory_budget_pure_test.go",
"memory_embedded_test.go",
"memory_proxied_integration_test.go",
"memory_pure_test.go",

View file

@ -1356,6 +1356,10 @@ var recognizedConfigKeys = map[string]bool{
"auto_compact_enabled": true, "schema_version": true,
"output.title-length": true,
"prime.max-memories": true, "prime.max-memory-chars": true,
// Opt-in ceiling on the persistent-memory corpus, enforced by `bd
// remember` (0 = off). Yaml-only for the same reason the prime caps are:
// it is read through viper, so a DB-backed write would never be seen.
"memories.budget-chars": true,
// The events-journal family. All four are startup settings that land in
// config.yaml (config.YamlOnlyKeys), and every one of them is documented as
// a `bd config set` invocation — including the auto-prune opt-out, where an

View file

@ -9,6 +9,7 @@ import (
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/memoryapi"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage/kvkeys"
@ -106,6 +107,112 @@ func matchesKnownCommand(cmd *cobra.Command, insight string) (string, bool) {
return "", false
}
// memoryForceFlag is `bd remember --force`: write even when the corpus budget
// would be crossed. It only has meaning when memories.budget-chars is set.
var memoryForceFlag bool
// memoryConfigInt reads an integer config key (stubbable for tests), the way
// primeConfigInt does for the prime-side injection caps.
var memoryConfigInt = func(key string) int {
return config.GetInt(key)
}
// memoryCorpusBudget resolves the memories.budget-chars ceiling. 0 — the
// default — means OFF, and so does a negative value: the budget is opt-in, and
// a nonsense setting must not turn into a refusal the operator never asked for.
func memoryCorpusBudget() int {
budget := memoryConfigInt("memories.budget-chars")
if budget < 0 {
return 0
}
return budget
}
// memoryCorpusChars sums len(key)+len(content) over a corpus.
//
// The unit is BYTES (Go len), deliberately the same unit prime's
// --max-memory-chars cap counts in, so the two numbers are comparable. They are
// not the same MEASURE: prime counts each entry as it renders it — the key and
// value plus a few bytes of heading or bullet markup per memory, and the
// compact form truncates long values — so a corpus sitting exactly at a budget
// equal to prime.max-memory-chars can still have memories elided at injection.
// A budget meant to keep prime from eliding anything has to sit below that cap.
func memoryCorpusChars(memories map[string]string) int {
total := 0
for k, v := range memories {
total += len(k) + len(v)
}
return total
}
// projectedMemoryCorpusChars is that sum AFTER a write of content under key
// would apply. An OVERWRITE replaces the key's old content in the sum instead
// of adding to it — the delta, not the sum — which is what makes editing an
// existing memory possible at all once a corpus is near its ceiling.
func projectedMemoryCorpusChars(existing map[string]string, key, content string) int {
total := memoryCorpusChars(existing)
if old, ok := existing[key]; ok {
total -= len(key) + len(old)
}
return total + len(key) + len(content)
}
// memoryBudgetLine renders the ONE stderr line the budget check emits, and
// says whether the write must be refused.
//
// Three outcomes, in order of severity:
// - over budget, no --force: refuse, naming the override.
// - over budget with --force: write, but SAY SO — a forced crossing that
// printed nothing would make the budget invisible exactly when it matters.
// - at or above 80% of budget and within it: write, warn. That is the whole
// point of a budget over a tripwire: the warning arrives while there is
// still room to act on it.
//
// Below 80%, and whenever the budget is off, it returns "" and the command is
// silent — byte-identical to the pre-budget behavior.
//
// The percentage FLOORS within the budget and CEILINGS over it, and the
// rounding is not cosmetic: floor(201*100/200) is 100, and "100%" is exactly
// the at-budget reading this code deliberately ALLOWS — so a floored refusal
// would report the number of the case it is not. Ceiling above the line makes
// every over-budget line read 101% or more, and the split is on the VALUE, not
// on --force, so the same projection never reports two different percentages
// depending on a flag. Both forms are int64 arithmetic, so a large budget
// cannot overflow the comparison.
func memoryBudgetLine(projected, budget int, force bool) (line string, refuse bool) {
if budget <= 0 {
return "", false
}
pct := int(int64(projected) * 100 / int64(budget))
if projected > budget {
pct = int((int64(projected)*100 + int64(budget) - 1) / int64(budget))
}
switch {
case projected > budget && !force:
return fmt.Sprintf("bd remember: memory corpus would be %d chars, budget is %d (%d%%) — refused; use --force to override", projected, budget, pct), true
case projected > budget:
return fmt.Sprintf("bd remember: memory corpus at %d of %d chars (%d%%) — over budget, written anyway (--force)", projected, budget, pct), false
case int64(projected)*5 >= int64(budget)*4:
return fmt.Sprintf("bd remember: memory corpus at %d of %d chars (%d%%)", projected, budget, pct), false
}
return "", false
}
// rememberBudgetVerdict is the whole budget decision as ONE pure function:
// given the corpus as it stands, the write about to be made, the budget and
// --force, it answers with the line to print (empty = say nothing) and whether
// the write must be refused. The command around it only has to fetch the
// corpus and obey.
//
// Keeping it pure is what lets every branch — off, boundary, overwrite delta,
// force, warn — be pinned by a test that needs neither a database nor cgo.
func rememberBudgetVerdict(existing map[string]string, key, content string, budget int, force bool) (line string, refuse bool) {
if budget <= 0 {
return "", false
}
return memoryBudgetLine(projectedMemoryCorpusChars(existing, key, content), budget, force)
}
// rememberBareKeyPath implements the desire-path / footgun guard for
// `bd remember <bare-slug>` (no --key): a bare slug naming an EXISTING memory
// is recalled instead of stored; a bare slug naming nothing is refused. The
@ -247,6 +354,14 @@ unless --key is given). As a convenience, if the arg is a bare key naming an
existing memory, it is RECALLED instead of stored (same as 'bd recall');
a bare key naming nothing is refused. Use --key to store slug-like content.
Corpus budget (opt-in, off by default): set the memories.budget-chars config
key to a byte ceiling for the whole memory corpus (sum of len(key)+len(content)).
A write that would cross it is refused, and --force overrides; a write that
lands at or above 80% of the budget warns. With the key unset nothing changes.
bd prime's --max-memory-chars also counts bytes, but of each memory as
injected, formatting included, so a budget equal to that cap does not
guarantee prime injects every memory; set the budget below it for that.
Examples:
bd remember "always run tests with -race flag"
bd remember "Dolt phantom DBs hide in three places" --key dolt-phantoms
@ -324,6 +439,68 @@ Examples:
return rememberBareKeyPath(derived, insight, recalled.Value)
}
// Corpus budget (memories.budget-chars, OPT-IN, 0 = off). The
// wheelhouse-side tripwire only REPORTS the corpus size, so the corpus
// re-trips red every few days and nothing ever stops the write that
// crossed the line. This is the stop.
//
// It sits here, between the read-shaped branches above and the write
// below, because it is the last thing that can decide NOT to write —
// and above the role because a budget is a front-door policy, not a
// property of the memory plane (an HTTP POST must not inherit it).
//
// When the budget is off the whole block is skipped: no extra List, no
// output, nothing. Behavior is then byte-identical to the pre-budget
// command, which is what TestRememberBudgetVerdictOffIsSilent and the embedded
// budget_off_is_silent case pin.
//
// The key an overwrite is credited against is ResolveKey's, the one
// rule every Remember implementation lands a write under, so it cannot
// drift from the store's key. A write ResolveKey refuses (empty
// content, a whitespace-only --key, content that derives no key) skips
// the budget: Remember refuses it below with its own validation
// sentence, and a refused write crosses nothing.
budgetKey, budgetKeyErr := memoryapi.ResolveKey(memoryKeyFlag, insight)
var budgetLine string
if budget := memoryCorpusBudget(); budget > 0 && budgetKeyErr == nil {
// ADVISORY, not atomic: this List and the Remember below are
// separate transactions, so two concurrent writers can both measure
// a corpus inside the budget and both land, leaving it over. The
// budget is a guardrail against a corpus drifting past its ceiling
// one deliberate write at a time, not a hard limit — no locking.
corpus, err := memories.List(rootCtx, memoryops.ListRequest{})
if err != nil {
return HandleErrorRespectJSON("reading the memory corpus for the budget check: %v", err)
}
line, refuse := rememberBudgetVerdict(corpus.Memories, budgetKey, insight, budget, memoryForceFlag)
if refuse {
// The budget line IS the refusal sentence, so it prints as
// itself: routing it through HandleError would prefix it with
// "Error: " and reword text agents will match on.
//
// It is said ONCE, on exactly one stream, the way
// HandleErrorWithHintRespectJSON does it: --json gets only the
// machine-readable envelope on stdout (printing the prose to
// stderr as well would make the same refusal arrive twice),
// and every other route gets the bare sentence on stderr,
// where it can never corrupt structured output. Both routes
// carry the same hint, so a terminal user is offered the same
// ways out as a JSON consumer.
const hint = "raise memories.budget-chars, forget a memory, or pass --force"
if jsonOutput {
jsonStdoutError(line, hint)
} else {
fmt.Fprintln(os.Stderr, line)
fmt.Fprintf(os.Stderr, "Hint: %s\n", hint)
}
return SilentExit()
}
// Not a refusal: the write happens first and the line reports the
// corpus that now exists, so no line ever describes a write that
// did not land.
budgetLine = line
}
result, err := memories.Remember(rootCtx, memoryops.RememberRequest{Key: memoryKeyFlag, Content: insight})
if err != nil {
// The role's two refusals ARE this command's shipped sentences —
@ -338,6 +515,10 @@ Examples:
}
noteDirectMemoryWrite()
if budgetLine != "" {
fmt.Fprintln(os.Stderr, budgetLine)
}
// Remembered versus Updated is Replaced, observed in the SAME
// transaction as the write. The shipped code read the row first and
// described a moment that had already passed.
@ -485,6 +666,7 @@ func truncateMemory(s string, maxLen int) string {
func init() {
rememberCmd.Flags().StringVar(&memoryKeyFlag, "key", "", "Explicit key for the memory (auto-generated from content if not set). If a memory with this key already exists, it will be updated in place")
rememberCmd.Flags().BoolVar(&memoryForceFlag, "force", false, "Store even when the write would cross the memories.budget-chars corpus budget (no effect when the budget is unset)")
rootCmd.AddCommand(rememberCmd)
rootCmd.AddCommand(memoriesCmd)

View file

@ -0,0 +1,258 @@
// Pure-Go tests for the `bd remember` corpus budget (memories.budget-chars).
// No cgo / Dolt dependency, so this file carries no build tag and compiles
// under CGO_ENABLED=0 with gms_pure_go, exactly like memory_pure_test.go.
//
// The whole budget decision lives in one pure function (rememberBudgetVerdict),
// so every branch the knob has — off, boundary, overwrite delta, --force, the
// 80% warn — is pinned here without a database. The end-to-end plumbing (the
// stderr routing and the nonzero exit) is pinned against a real store by
// TestEmbeddedMemoryCorpusBudget in memory_embedded_test.go.
package main
import (
"fmt"
"strings"
"testing"
)
// budgetCorpus builds a corpus whose measured size is exactly want bytes,
// under a single key. len(key)+len(content) is the unit the budget counts in,
// so the content is padded to want-len(key).
func budgetCorpus(t *testing.T, key string, want int) map[string]string {
t.Helper()
if want < len(key) {
t.Fatalf("corpus of %d bytes cannot hold key %q (%d bytes)", want, key, len(key))
}
corpus := map[string]string{key: strings.Repeat("x", want-len(key))}
if got := memoryCorpusChars(corpus); got != want {
t.Fatalf("corpus fixture measured %d bytes, want %d", got, want)
}
return corpus
}
// TestMemoryCorpusCharsCountsKeyAndContentBytes pins the UNIT: bytes of
// len(key)+len(content), the same unit prime's --max-memory-chars counts in.
// A rune-counting implementation would disagree on any non-ASCII memory, which
// is why the multibyte case is here.
func TestMemoryCorpusCharsCountsKeyAndContentBytes(t *testing.T) {
if got := memoryCorpusChars(nil); got != 0 {
t.Fatalf("empty corpus = %d, want 0", got)
}
corpus := map[string]string{"ab": "cde", "f": "gh"}
if got, want := memoryCorpusChars(corpus), 2+3+1+2; got != want {
t.Fatalf("corpus = %d, want %d", got, want)
}
// "é" is two bytes; the budget must see two.
if got, want := memoryCorpusChars(map[string]string{"k": "é"}), 3; got != want {
t.Fatalf("multibyte corpus = %d, want %d (bytes, not runes)", got, want)
}
}
// TestProjectedMemoryCorpusCharsOverwriteCountsDelta is spec point (c): an
// overwrite REPLACES the key's old content in the sum instead of adding to it.
// Without this, editing one memory down to nothing would still read as growth
// and a corpus at its ceiling could never be repaired.
func TestProjectedMemoryCorpusCharsOverwriteCountsDelta(t *testing.T) {
existing := map[string]string{"k": "aaaa", "other": "bb"} // 1+4 + 5+2 = 12
// New key: pure addition.
if got, want := projectedMemoryCorpusChars(existing, "new", "xyz"), 12+3+3; got != want {
t.Errorf("new key projection = %d, want %d", got, want)
}
// Overwrite with longer content: only the delta lands.
if got, want := projectedMemoryCorpusChars(existing, "k", "aaaaaa"), 12+2; got != want {
t.Errorf("growing overwrite projection = %d, want %d", got, want)
}
// Overwrite with shorter content: the corpus SHRINKS.
if got, want := projectedMemoryCorpusChars(existing, "k", "a"), 12-3; got != want {
t.Errorf("shrinking overwrite projection = %d, want %d", got, want)
}
// Identical rewrite: no change at all.
if got, want := projectedMemoryCorpusChars(existing, "k", "aaaa"), 12; got != want {
t.Errorf("identical overwrite projection = %d, want %d", got, want)
}
// A key whose stored value is empty still has its key counted once, not twice.
empty := map[string]string{"k": ""}
if got, want := projectedMemoryCorpusChars(empty, "k", "zz"), 3; got != want {
t.Errorf("empty-valued overwrite projection = %d, want %d", got, want)
}
}
// TestRememberBudgetVerdictOffIsSilent is spec point (a): with the budget unset
// (or 0, or a nonsense negative) nothing is ever refused and nothing is ever
// printed, no matter how large the corpus is.
func TestRememberBudgetVerdictOffIsSilent(t *testing.T) {
huge := budgetCorpus(t, "k", 1_000_000)
for _, budget := range []int{0, -1, -1000} {
for _, force := range []bool{false, true} {
line, refuse := rememberBudgetVerdict(huge, "new", strings.Repeat("y", 5000), budget, force)
if refuse || line != "" {
t.Fatalf("budget=%d force=%v: budget-off must be silent, got refuse=%v line=%q", budget, force, refuse, line)
}
}
}
}
// TestMemoryCorpusBudgetReadsConfig pins the config read, including the clamp
// that keeps a negative value meaning OFF rather than "refuse everything".
func TestMemoryCorpusBudgetReadsConfig(t *testing.T) {
orig := memoryConfigInt
t.Cleanup(func() { memoryConfigInt = orig })
values := map[string]int{}
memoryConfigInt = func(key string) int { return values[key] }
if got := memoryCorpusBudget(); got != 0 {
t.Fatalf("unset budget = %d, want 0 (off)", got)
}
values["memories.budget-chars"] = 4096
if got := memoryCorpusBudget(); got != 4096 {
t.Fatalf("configured budget = %d, want 4096", got)
}
values["memories.budget-chars"] = -5
if got := memoryCorpusBudget(); got != 0 {
t.Fatalf("negative budget = %d, want 0 (off)", got)
}
}
// TestRememberBudgetVerdictBoundary is spec point (b): a projection exactly AT
// the budget writes; exactly one byte over refuses. The two cases differ by a
// single byte of content, so nothing but the comparison can explain a failure.
func TestRememberBudgetVerdictBoundary(t *testing.T) {
const budget = 200
// Corpus at 100 bytes; the new memory's key costs 3.
existing := budgetCorpus(t, "old", 100)
// Exactly at the budget: 100 + 3 + 97 = 200. Writes (and warns: 100%).
atBudget, refuse := rememberBudgetVerdict(existing, "new", strings.Repeat("z", 97), budget, false)
if refuse {
t.Fatalf("a projection exactly at the budget must write, got refusal %q", atBudget)
}
if !strings.Contains(atBudget, "at 200 of 200 chars (100%)") {
t.Errorf("at-budget line = %q, want the 100%% warn line", atBudget)
}
// One byte over: 201. Refused.
over, refuse := rememberBudgetVerdict(existing, "new", strings.Repeat("z", 98), budget, false)
if !refuse {
t.Fatalf("a projection one byte over the budget must refuse, got line %q", over)
}
// 201 of 200 is 100.5%, and it must NOT round down into "100%": that is the
// at-budget reading the case just above deliberately ALLOWS, so a floored
// refusal would wear the number of the case it is not. Over the line the
// percentage ceilings.
want := "bd remember: memory corpus would be 201 chars, budget is 200 (101%) — refused; use --force to override"
if over != want {
t.Errorf("refusal line =\n %q\nwant\n %q", over, want)
}
}
// TestRememberBudgetVerdictForceWrites is spec point (d): --force turns the
// refusal into a write, and STILL prints a line — a forced crossing that said
// nothing would make the budget invisible exactly when it matters most.
func TestRememberBudgetVerdictForceWrites(t *testing.T) {
existing := budgetCorpus(t, "old", 100)
line, refuse := rememberBudgetVerdict(existing, "new", strings.Repeat("z", 98), 200, true)
if refuse {
t.Fatalf("--force must not refuse, got refusal %q", line)
}
if line == "" {
t.Fatal("--force over budget must still print a line")
}
// (101%), not (100%): the ceiling over the budget is a property of the
// VALUE, so the same projection cannot report two different percentages
// depending on whether --force was passed.
for _, want := range []string{"201", "200", "(101%)", "--force"} {
if !strings.Contains(line, want) {
t.Errorf("forced line %q is missing %q", line, want)
}
}
if strings.Contains(line, "refused") {
t.Errorf("forced line must not claim a refusal: %q", line)
}
}
// TestRememberBudgetVerdictWarnBand is spec point (e) plus its two edges: below
// 80% of the budget the command is silent (today's behavior), and from 80% up
// to the budget it writes AND warns.
func TestRememberBudgetVerdictWarnBand(t *testing.T) {
const budget = 1000
cases := []struct {
name string
projected int
wantLine bool
wantPct int
}{
{"well below", 100, false, 0},
{"one byte under the warn band", 799, false, 0},
{"exactly 80 percent", 800, true, 80},
{"inside the band", 950, true, 95},
// One byte under: 99.9%, which must FLOOR to 99. Within the budget the
// rounding goes down, so "100%" belongs to the exactly-at-budget case
// alone and never to a projection that merely rounds up to it.
{"one byte under the budget", 999, true, 99},
{"exactly at budget", 1000, true, 100},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
// Project by writing a fresh key of known cost into an empty corpus.
key := "k"
content := strings.Repeat("q", tc.projected-len(key))
line, refuse := rememberBudgetVerdict(map[string]string{}, key, content, budget, false)
if refuse {
t.Fatalf("projection %d of %d must not refuse", tc.projected, budget)
}
if !tc.wantLine {
if line != "" {
t.Fatalf("projection %d of %d must be silent, got %q", tc.projected, budget, line)
}
return
}
want := fmt.Sprintf("bd remember: memory corpus at %d of %d chars (%d%%)", tc.projected, budget, tc.wantPct)
if line != want {
t.Errorf("warn line =\n %q\nwant\n %q", line, want)
}
})
}
}
// TestMemoryBudgetLinePercentIsUnclamped pins the arithmetic: over the budget
// the percentage is ceil(projected*100/budget) and is NOT clamped at 100, so a
// corpus forced well past its ceiling reports how far past it actually is. A
// clamp here would make 101% and 400% read identically — exactly the reading an
// operator needs. The ceiling is what keeps an over-budget line off the "100%"
// that means at-budget-and-allowed.
func TestMemoryBudgetLinePercentIsUnclamped(t *testing.T) {
cases := []struct {
projected, budget int
want string
}{
{101, 100, "(101%)"},
{201, 200, "(101%)"}, // ceil(100.5) — never floors back onto at-budget
{400, 100, "(400%)"}, // exact: ceil and floor agree
{1001, 1000, "(101%)"},
}
for _, tc := range cases {
line, _ := memoryBudgetLine(tc.projected, tc.budget, false)
if !strings.Contains(line, tc.want) {
t.Errorf("memoryBudgetLine(%d, %d) = %q, want it to contain %q", tc.projected, tc.budget, line, tc.want)
}
}
}
// TestMemoryBudgetLineHasNoTrailingNewline guards the "ONE line" contract: the
// callers add the newline, so a line that carried its own would print a blank
// line into stderr between the warning and whatever follows.
func TestMemoryBudgetLineHasNoTrailingNewline(t *testing.T) {
for _, force := range []bool{false, true} {
line, _ := memoryBudgetLine(500, 100, force)
if line == "" {
t.Fatalf("force=%v: expected an over-budget line", force)
}
if strings.ContainsAny(line, "\n\r") {
t.Errorf("force=%v: budget line must be a single line, got %q", force, line)
}
}
}

View file

@ -3,7 +3,10 @@
package main
import (
"encoding/json"
"errors"
"fmt"
"io"
"os"
"os/exec"
"path/filepath"
@ -486,3 +489,224 @@ func TestEmbeddedMemoryConcurrent(t *testing.T) {
t.Fatal("expected at least 1 worker to succeed")
}
}
// bdRememberBuffers runs "bd remember" and hands back stdout, stderr and the
// error separately. The budget's lines are STDERR by contract — that is what
// keeps them out of --json output — so a helper that folds the two streams
// together cannot test them.
func bdRememberBuffers(t *testing.T, bd, dir string, args ...string) (string, string, error) {
t.Helper()
cmd := exec.Command(bd, append([]string{"remember"}, args...)...)
cmd.Dir = dir
cmd.Env = bdEnv(dir)
stdout, stderr, err := runCommandBuffers(t, cmd)
return stdout.String(), stderr.String(), err
}
// TestEmbeddedMemoryCorpusBudget exercises memories.budget-chars against a REAL
// store, end to end: the config key routed through `bd config set`, the corpus
// measured from rows that are actually there, the refusal's nonzero exit, and
// the fact that a refused write leaves NOTHING behind.
//
// The arithmetic below is exact and deliberate — every content length is chosen
// so the projected corpus lands on a named boundary — because a budget test
// that only asserts "some line appeared" would pass with an off-by-one budget.
// The pure branch coverage lives in memory_budget_pure_test.go; this is the
// wiring.
func TestEmbeddedMemoryCorpusBudget(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Parallel()
bd := buildEmbeddedBD(t)
// ===== Budget OFF: byte-identical to the pre-budget command =====
t.Run("budget_off_is_silent", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mb")
stdout, stderr, err := bdRememberBuffers(t, bd, dir, strings.Repeat("x", 5000), "--key", "big")
if err != nil {
t.Fatalf("remember with no budget failed: %v\nstdout:\n%s\nstderr:\n%s", err, stdout, stderr)
}
if !strings.Contains(stdout, "Remembered [big]") {
t.Errorf("expected the shipped success line, got %q", stdout)
}
if strings.Contains(stderr, "memory corpus") {
t.Errorf("budget off must print no budget line, got stderr %q", stderr)
}
})
// ===== Budget ON =====
dir, _, _ := bdInit(t, bd, "--prefix", "mb")
// The arithmetic below assumes a fresh, empty corpus. Say so out loud, so
// a future `bd init` that seeds a memory fails HERE instead of failing as
// an inscrutable off-by-N in the assertions.
if out := bdMemories(t, bd, dir); !strings.Contains(out, "No memories stored") {
t.Fatalf("budget arithmetic needs an empty corpus after init, got:\n%s", out)
}
cfg := exec.Command(bd, "config", "set", "memories.budget-chars", "100")
cfg.Dir = dir
cfg.Env = bdEnv(dir)
if out, err := cfg.CombinedOutput(); err != nil {
t.Fatalf("bd config set memories.budget-chars failed: %v\n%s", err, out)
} else if strings.Contains(string(out), "not a recognized") || strings.Contains(string(out), "Unrecognized") {
t.Fatalf("memories.budget-chars must be a recognized config key, got:\n%s", out)
}
// 3 ("pad") + 90 = 93 of 100 -> writes, warns at 93%.
t.Run("warn_band_writes_and_warns", func(t *testing.T) {
_, stderr, err := bdRememberBuffers(t, bd, dir, strings.Repeat("a", 90), "--key", "pad")
if err != nil {
t.Fatalf("a write inside the budget must succeed: %v\nstderr:\n%s", err, stderr)
}
if want := "bd remember: memory corpus at 93 of 100 chars (93%)"; !strings.Contains(stderr, want) {
t.Errorf("stderr = %q, want the warn line %q", stderr, want)
}
if out := bdRecall(t, bd, dir, "pad"); !strings.Contains(out, strings.Repeat("a", 90)) {
t.Errorf("the warned write must still have landed, got %q", out)
}
})
// An OVERWRITE of the same size is a no-op on the corpus (delta, not sum).
// Were it summed, the projection would be 186 and this would be refused.
t.Run("overwrite_counts_delta_not_sum", func(t *testing.T) {
_, stderr, err := bdRememberBuffers(t, bd, dir, strings.Repeat("b", 90), "--key", "pad")
if err != nil {
t.Fatalf("a same-size overwrite must not be refused: %v\nstderr:\n%s", err, stderr)
}
if want := "bd remember: memory corpus at 93 of 100 chars (93%)"; !strings.Contains(stderr, want) {
t.Errorf("stderr = %q, want %q (an overwrite must not add to the sum)", stderr, want)
}
if out := bdRecall(t, bd, dir, "pad"); !strings.Contains(out, strings.Repeat("b", 90)) {
t.Errorf("overwrite did not land: %q", out)
}
})
// 93 + 2 ("ab") + 5 = exactly 100. Exactly AT the budget writes.
t.Run("exactly_at_budget_writes", func(t *testing.T) {
_, stderr, err := bdRememberBuffers(t, bd, dir, "ccccc", "--key", "ab")
if err != nil {
t.Fatalf("a write landing exactly on the budget must succeed: %v\nstderr:\n%s", err, stderr)
}
if want := "bd remember: memory corpus at 100 of 100 chars (100%)"; !strings.Contains(stderr, want) {
t.Errorf("stderr = %q, want %q", stderr, want)
}
})
// Overwriting "pad" with one more byte projects 101 — exactly ONE over.
t.Run("one_byte_over_refuses_and_writes_nothing", func(t *testing.T) {
stdout, stderr, err := bdRememberBuffers(t, bd, dir, strings.Repeat("d", 91), "--key", "pad")
if err == nil {
t.Fatalf("a write one byte over the budget must exit nonzero; stdout:\n%s\nstderr:\n%s", stdout, stderr)
}
want := "bd remember: memory corpus would be 101 chars, budget is 100 (101%) — refused; use --force to override"
if !strings.Contains(stderr, want) {
t.Errorf("stderr = %q, want %q", stderr, want)
}
// A terminal user is offered the same ways out as the --json envelope.
if hint := "Hint: raise memories.budget-chars, forget a memory, or pass --force"; !strings.Contains(stderr, hint) {
t.Errorf("stderr = %q, want the hint %q", stderr, hint)
}
if strings.Contains(stdout, "Remembered") || strings.Contains(stdout, "Updated") {
t.Errorf("a refused write must print no success line, got stdout %q", stdout)
}
if out := bdRecall(t, bd, dir, "pad"); !strings.Contains(out, strings.Repeat("b", 90)) {
t.Errorf("a refused write must leave the old content intact, got %q", out)
}
})
// The commonest call passes no --key, so the write lands under the key
// derived from the content, and that is the key the budget must measure:
// 100 + 22 ("derived-keys-count-too") + 24 (the content) projects 146.
t.Run("derived_key_write_is_budgeted", func(t *testing.T) {
stdout, stderr, err := bdRememberBuffers(t, bd, dir, "Derived keys count, too!")
var exitErr *exec.ExitError
if !errors.As(err, &exitErr) || exitErr.ExitCode() != 1 {
t.Fatalf("a write with no --key over the budget must exit 1, got %v; stdout:\n%s\nstderr:\n%s", err, stdout, stderr)
}
want := "bd remember: memory corpus would be 146 chars, budget is 100 (146%) — refused; use --force to override"
if !strings.Contains(stderr, want) {
t.Errorf("stderr = %q, want %q", stderr, want)
}
if strings.Contains(stdout, "Remembered") || strings.Contains(stdout, "Updated") {
t.Errorf("a refused write must print no success line, got stdout %q", stdout)
}
bdRecallFail(t, bd, dir, "derived-keys-count-too")
})
// A whitespace-only --key names nothing, so the role refuses the write with
// its own validation sentence. The budget must not answer first: on this
// full corpus it would call the write over budget and point at --force,
// and the --force retry would only then meet the validation error.
t.Run("blank_key_gets_the_validation_error_not_the_budget", func(t *testing.T) {
stdout, stderr, err := bdRememberBuffers(t, bd, dir, "some content", "--key", " ")
if err == nil {
t.Fatalf("a whitespace-only --key must be refused; stdout:\n%s\nstderr:\n%s", stdout, stderr)
}
if !strings.Contains(stderr, "memory key must not be empty") {
t.Errorf("stderr = %q, want the role's validation error", stderr)
}
if strings.Contains(stderr, "memory corpus") {
t.Errorf("a write the role refuses must not be measured against the budget, got stderr %q", stderr)
}
})
// The same refusal under --json is said ONCE, and only on stdout: the
// machine-readable envelope, nothing else. Printing the prose to stderr as
// well would deliver one refusal twice to a caller reading both streams.
t.Run("json_refusal_is_said_once", func(t *testing.T) {
stdout, stderr, err := bdRememberBuffers(t, bd, dir, strings.Repeat("d", 91), "--key", "pad", "--json")
if err == nil {
t.Fatalf("a --json write one byte over the budget must exit nonzero; stdout:\n%s\nstderr:\n%s", stdout, stderr)
}
// Exactly ONE JSON document on stdout — no second envelope, no prose
// before or after it.
dec := json.NewDecoder(strings.NewReader(stdout))
var doc map[string]interface{}
if decErr := dec.Decode(&doc); decErr != nil {
t.Fatalf("stdout is not a JSON document (%v):\n%s", decErr, stdout)
}
if decErr := dec.Decode(new(json.RawMessage)); !errors.Is(decErr, io.EOF) {
t.Errorf("stdout carries more than one JSON document (second Decode = %v):\n%s", decErr, stdout)
}
// The envelope carries the refusal sentence, under either the enveloped
// or the flat error shape.
inner := doc
if data, ok := doc["data"].(map[string]interface{}); ok {
inner = data
}
msg, _ := inner["error"].(string)
want := "bd remember: memory corpus would be 101 chars, budget is 100 (101%) — refused; use --force to override"
if msg != want {
t.Errorf("JSON error = %q, want %q (full stdout:\n%s)", msg, want, stdout)
}
// ...and stderr says nothing, so the refusal arrived exactly once.
if strings.Contains(stderr, "memory corpus") || strings.Contains(stderr, "Hint:") {
t.Errorf("--json refusal must not also print the prose line to stderr, got stderr %q", stderr)
}
// A refused --json write still leaves the old content intact.
if out := bdRecall(t, bd, dir, "pad"); !strings.Contains(out, strings.Repeat("b", 90)) {
t.Errorf("a refused --json write must leave the old content intact, got %q", out)
}
})
// The same write with --force lands, and still says so.
t.Run("force_writes_over_budget", func(t *testing.T) {
_, stderr, err := bdRememberBuffers(t, bd, dir, strings.Repeat("d", 91), "--key", "pad", "--force")
if err != nil {
t.Fatalf("--force must write over the budget: %v\nstderr:\n%s", err, stderr)
}
if want := "bd remember: memory corpus at 101 of 100 chars (101%) — over budget, written anyway (--force)"; !strings.Contains(stderr, want) {
t.Errorf("stderr = %q, want %q", stderr, want)
}
if out := bdRecall(t, bd, dir, "pad"); !strings.Contains(out, strings.Repeat("d", 91)) {
t.Errorf("--force did not land the write, got %q", out)
}
})
}

View file

@ -88,7 +88,7 @@ The full namespaces routed to YAML are:
Plus these individual keys:
`no-db`, `json`, `db`, `actor`, `identity`, `no-push`, `no-git-ops`, `agent.profile`, `create.require-description`, `import.auto`, `import.path`, `prime.max-memories`, `prime.max-memory-chars`, and the secret keys `github.token`, `gitlab.token`, `jira.api_token`, `ado.pat`, `linear.api_key`, `linear.oauth_client_id`, `linear.oauth_client_secret`, `notion.token`.
`no-db`, `json`, `db`, `actor`, `identity`, `no-push`, `no-git-ops`, `agent.profile`, `create.require-description`, `import.auto`, `import.path`, `prime.max-memories`, `prime.max-memory-chars`, `memories.budget-chars`, and the secret keys `github.token`, `gitlab.token`, `jira.api_token`, `ado.pat`, `linear.api_key`, `linear.oauth_client_id`, `linear.oauth_client_secret`, `notion.token`.
Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `password` is treated as a secret: it is refused on git-tracked `config.yaml` files unless you pass `--force-git-tracked`. Prefer exporting the value as an environment variable instead (e.g. `LINEAR_API_KEY`).
@ -108,6 +108,7 @@ Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `passwor
| `agent.profile` | — | `BD_AGENT_PROFILE` | `conservative` | Policy profile `bd prime` uses for git/commit authority: `conservative`, `minimal`, `team-maintainer`; invalid values fall back to `conservative` |
| `prime.max-memories` | `--max-memories` | `BD_PRIME_MAX_MEMORIES` | `0` | Max persistent memories injected by `bd prime` (0 = unlimited) |
| `prime.max-memory-chars` | `--max-memory-chars` | `BD_PRIME_MAX_MEMORY_CHARS` | `0` | Max total bytes of memory entries injected by `bd prime`, at whole-memory boundaries (0 = unlimited) |
| `memories.budget-chars` | — | `BD_MEMORIES_BUDGET_CHARS` | `0` | Ceiling on the whole persistent-memory corpus, in bytes of `len(key)+len(content)` summed over every memory (0 = off). `bd remember` refuses a write that would cross it — pass `--force` to store anyway — and warns on a write that lands at or above 80% of it. Read at `bd remember` time only; `bd prime` injection is capped separately by `prime.max-memory-chars` |
| `dolt.auto-commit` | `--dolt-auto-commit` | `BD_DOLT_AUTO_COMMIT` | `on` | `off\|on\|batch`: `on` creates a Dolt history commit after each successful write; `batch`/`off` defer it to `bd dolt commit` (see [below](#auto-commit-sql-commits-vs-dolt-commits)) |
| `dolt.auto-push` | — | `BD_DOLT_AUTO_PUSH` | `false` | Auto-push to Dolt remote after writes (opt-in; see [below](#auto-push)) |
| `dolt.auto-push-interval` | — | `BD_DOLT_AUTO_PUSH_INTERVAL` | `5m` | Minimum time between auto-pushes |

View file

@ -79,6 +79,11 @@ var YamlOnlyKeys = map[string]bool{
"prime.max-memories": true,
"prime.max-memory-chars": true,
// Memory-corpus budget enforced by `bd remember` (0 = off). Yaml for the
// same reason the prime caps are: it is read through viper (config.GetInt),
// so a DB-backed write would be set successfully and then never read.
"memories.budget-chars": true,
// Validation settings (bd-t7jq)
// Values: "warn" | "error" | "none"
"validation.on-create": true,
@ -1596,6 +1601,14 @@ func validateYamlConfigValue(key, value string) error {
if n < 0 {
return fmt.Errorf("prime.max-memory-chars must be a non-negative integer (0 = unlimited), got %q", value)
}
case "memories.budget-chars":
n, err := strconv.Atoi(value)
if err != nil {
return fmt.Errorf("memories.budget-chars must be a non-negative integer (0 = off), got %q", value)
}
if n < 0 {
return fmt.Errorf("memories.budget-chars must be a non-negative integer (0 = off), got %q", value)
}
}
return nil
}

View file

@ -917,6 +917,53 @@ func TestValidateYamlConfigValue_PrimeMaxMemoryChars(t *testing.T) {
}
}
// TestValidateYamlConfigValue_MemoriesBudgetChars tests validation of
// memories.budget-chars, the opt-in `bd remember` corpus ceiling. A negative
// value is rejected at SET time rather than silently clamped at read time, so
// an operator who types "-1" hears about it instead of getting a budget that
// is quietly off.
func TestValidateYamlConfigValue_MemoriesBudgetChars(t *testing.T) {
tests := []struct {
name string
value string
expectErr bool
errMsg string
}{
{"valid zero (off)", "0", false, ""},
{"valid positive", "250000", false, ""},
{"invalid negative", "-1", true, "memories.budget-chars must be a non-negative integer (0 = off), got \"-1\""},
{"invalid non-integer", "abc", true, "memories.budget-chars must be a non-negative integer (0 = off), got \"abc\""},
{"invalid float", "3.5", true, "memories.budget-chars must be a non-negative integer (0 = off), got \"3.5\""},
{"invalid empty", "", true, "memories.budget-chars must be a non-negative integer (0 = off), got \"\""},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := validateYamlConfigValue("memories.budget-chars", tt.value)
if tt.expectErr {
if err == nil {
t.Errorf("expected error for value %q, got nil", tt.value)
} else if err.Error() != tt.errMsg {
t.Errorf("expected error %q, got %q", tt.errMsg, err.Error())
}
} else {
if err != nil {
t.Errorf("unexpected error for value %q: %v", tt.value, err)
}
}
})
}
}
// TestMemoriesBudgetCharsIsYamlOnly pins the routing: the key is read through
// viper (config.GetInt), so a DB-backed write would be accepted and then never
// read by `bd remember`. YamlOnlyKeys is what keeps `bd config set` honest.
func TestMemoriesBudgetCharsIsYamlOnly(t *testing.T) {
if !IsYamlOnlyKey("memories.budget-chars") {
t.Error("memories.budget-chars must be yaml-only: bd remember reads it through viper")
}
}
func TestIsSecretKey(t *testing.T) {
tests := []struct {
key string