feat(remember): pave the read desire path — bare existing key recalls instead of writing

'bd remember <x>' takes CONTENT, but 'remember X' reads as a getter in
English, so agents repeatedly type 'bd remember some-key' meaning a read
(AGENT-ERGONOMICS.md desire path; bit again 2026-07-01 creating junk
memories whose content was their own key). Builds on the unmerged
overwrite guard (33fbdb9c4) and goes further: when no --key is given and
the arg round-trips slugify unchanged (a bare slug — real prose never
does):

  - key EXISTS  -> recall it (stdout = content like 'bd recall', stderr
                   hint, JSON {action: recalled}); no write occurs
  - no such key -> refuse with pointers to 'bd memories' and --key,
                   instead of silently storing the token as its own
                   content

--key states explicit write intent and bypasses both branches. Prose
content behavior is unchanged. Updates remember's help text and the
TestEmbeddedMemory guard subtests to the new semantics.
This commit is contained in:
Steve Yegge 2026-07-01 22:03:31 -07:00
commit 9ee97c264c
2 changed files with 58 additions and 25 deletions

View file

@ -53,10 +53,16 @@ var rememberCmd = &cobra.Command{
Memories are injected at prime time (bd prime) so you have them
in every session without manual loading.
The positional arg is the memory CONTENT (the key is auto-generated from it
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.
Examples:
bd remember "always run tests with -race flag"
bd remember "Dolt phantom DBs hide in three places" --key dolt-phantoms
bd remember "auth module uses JWT not sessions" --key auth-jwt`,
bd remember "auth module uses JWT not sessions" --key auth-jwt
bd remember dolt-phantoms # bare existing key: reads it (= bd recall)`,
GroupID: "setup",
Args: cobra.ExactArgs(1),
SilenceUsage: true,
@ -98,20 +104,36 @@ Examples:
verb = "Updated"
}
// Footgun guard: `bd remember <x>` is a WRITE whose positional arg is the CONTENT, not a
// key. A common slip is treating it like a getter -- `bd remember some-existing-key` --
// which slugifies the bare key back to itself and SILENTLY OVERWRITES that memory. Refuse
// when (a) no explicit --key was given, (b) the content round-trips through slugify
// unchanged (so it is already a bare slug, the tell-tale of a mistyped read), and (c) a
// memory with that key already exists. Existing keys are themselves slugify outputs, so
// this precisely catches "content names an existing memory" with ~zero false positives on
// real prose insights. Passing --key explicitly bypasses the guard (deliberate intent).
if memoryKeyFlag == "" && existing != "" && slugify(insight) == insight {
// Desire path + footgun guard: `bd remember <x>` is a WRITE whose positional arg is
// the CONTENT, not a key -- but "remember X" reads as a getter in English, so agents
// routinely type `bd remember some-key` meaning "do you remember X?". The tell-tale of
// a mistyped read is content that round-trips through slugify unchanged (a bare slug);
// real prose insights never do. When that happens and no explicit --key was given:
// - the key EXISTS -> pave the desire path: recall it instead of writing
// - no such key -> refuse; storing a key-like token as its own content would
// create a junk memory that hides the mistake
// Passing --key states write intent and bypasses both branches.
if memoryKeyFlag == "" && slugify(insight) == insight {
if existing != "" {
if jsonOutput {
return outputJSON(map[string]interface{}{
"key": key,
"value": existing,
"found": true,
"action": "recalled",
})
}
fmt.Fprintf(os.Stderr,
"(recalled %q -- a bare existing key READS. To overwrite: `bd remember \"<new content>\" --key %s`)\n",
key, key)
fmt.Printf("%s\n", existing)
return nil
}
return HandleErrorRespectJSON(
"refusing to overwrite existing memory %q with its own key as content -- "+
"no memory named %q to recall -- and refusing to store a bare key-like token as its own content. "+
"`bd remember` WRITES (its positional arg is CONTENT, not a key). "+
"To read it: `bd recall %s`. To overwrite anyway: `bd remember \"<new content>\" --key %s`",
key, key, key)
"To store it anyway: `bd remember %q --key %s`. To browse keys: `bd memories`",
key, insight, key)
}
if err := store.SetConfig(ctx, storageKey, insight); err != nil {

View file

@ -146,19 +146,19 @@ func TestEmbeddedMemory(t *testing.T) {
}
})
// Footgun guard: `bd remember <existing-key>` (treating remember as a getter) must NOT
// silently overwrite that memory with its own key as content.
t.Run("remember_guard_blocks_key_as_content", func(t *testing.T) {
// Desire path: `bd remember <existing-key>` (treating remember as a getter) is a READ --
// it recalls the memory instead of overwriting it with its own key as content.
t.Run("remember_bare_existing_key_recalls", func(t *testing.T) {
bdRemember(t, bd, dir, "the real insight worth keeping", "--key", "guard-key")
// Now fat-finger a "read": positional arg is the existing bare key.
out := bdRememberFail(t, bd, dir, "guard-key")
if !strings.Contains(out, "recall") {
t.Errorf("expected guard error to suggest `bd recall`, got: %s", out)
// Fat-finger a "read": positional arg is the existing bare key. Succeeds as a recall.
out := bdRemember(t, bd, dir, "guard-key")
if !strings.Contains(out, "the real insight worth keeping") {
t.Errorf("expected bare existing key to recall the memory content, got: %s", out)
}
// The original content must be intact, not clobbered to "guard-key".
recalled := bdRecall(t, bd, dir, "guard-key")
if !strings.Contains(recalled, "the real insight worth keeping") {
t.Errorf("guard must preserve original content, got: %s", recalled)
t.Errorf("recall-instead-of-write must preserve original content, got: %s", recalled)
}
})
@ -172,12 +172,23 @@ func TestEmbeddedMemory(t *testing.T) {
}
})
t.Run("remember_guard_allows_new_slug_content", func(t *testing.T) {
// Slug-shaped content is fine when no memory by that key exists yet (no overwrite).
bdRemember(t, bd, dir, "brand-new-slug-memory")
t.Run("remember_bare_slug_without_memory_refuses", func(t *testing.T) {
// A bare slug naming NO existing memory is a mistyped read (or junk content) --
// refuse rather than silently creating a memory whose content is its own key.
out := bdRememberFail(t, bd, dir, "brand-new-slug-memory")
if !strings.Contains(out, "memories") {
t.Errorf("expected refusal to point at `bd memories`, got: %s", out)
}
// Nothing may have been stored.
bdRecallFail(t, bd, dir, "brand-new-slug-memory")
})
t.Run("remember_new_slug_with_explicit_key_stores", func(t *testing.T) {
// --key states write intent: slug-like content stores fine.
bdRemember(t, bd, dir, "brand-new-slug-memory", "--key", "brand-new-slug-memory")
out := bdRecall(t, bd, dir, "brand-new-slug-memory")
if !strings.Contains(out, "brand-new-slug-memory") {
t.Errorf("expected new slug-keyed memory to be stored, got: %s", out)
t.Errorf("expected --key to store slug content, got: %s", out)
}
})