mathias/hyperguild
1
0
Fork 0
Code Issues 30 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

design(brain): remember + recall consolidations under ADR-0009/0012 (blocked on 0009 design) #80

New Issue
Open
opened 2026-07-07 07:45:59 +00:00 by mathias · 2 comments
mathias commented 2026-07-07 07:45:59 +00:00
Owner
Copy Link
Copy Source

Charter: ADR-0012 (consolidation heuristic) · Blocked on: ADR-0009 design being decided first

Intent

The two big consolidations ADR-0012 names for the brain surface:

  • remember — collapse brain_write / brain_ingest / brain_ingest_raw (three doors for one intent: "put this knowledge in"). Per the consolidation heuristic, the caller has no legitimate stake in which extraction mechanism runs — that's the server's call — so this is a clean collapse to one intent-named verb, with extraction strategy as an optional server-defaulted hint.
  • recall — collapse brain_query / brain_answer / brain_graph (three retrieval mechanisms for one intent: "find what's relevant"). Here the caller sometimes has a legitimate stake (occasionally you really do want graph traversal), so per the heuristic this is one verb + an optional strategy hint defaulting to server choice — NOT a hard wall hiding the mechanisms. brain_get stays separate (fetch-exact-handle is a distinct intent, not a mechanism of recall).

Why this is blocked, not ready

This is not immediately actionable. ADR-0012 explicitly hands the brain-specific verb-set design to ADR-0009 (consumer-split), which is still a STUB with its Decision section as TODO. The agent-facing vs human-facing split has to be decided first — e.g. does remember mean the same thing for an autonomous agent as for a human curating raw→wiki? Is recall's default strategy consumer-dependent? Those are 0009's questions. Building remember/recall before 0009 is decided would hard-code answers to questions that are supposed to be deliberated.

So: this issue tracks the consolidation intent and keeps ADR-0012's "tracked separately" claim honest, but its first real step is doing ADR-0009's design, under the charter.

Acceptance (gated)

  • ADR-0009 Decision section filled (consumer-split + verb set decided, under ADR-0012)
  • remember verb designed (write/ingest/ingest_raw → one verb + optional extraction hint)
  • recall verb designed (query/answer/graph → one verb + optional strategy hint, server-default)
  • brain_get confirmed to remain separate (distinct intent)
  • Versioned deprecation plan for the old verbs (add-new / deprecate / migrate / remove) — do not hard-break callers
  • SKILLs / agents / capture BrainStore caller-migration accounted for

Related

  • ADR-0009 (the blocker — brain consumer-split design must be decided first)
  • ADR-0012 (the charter + consolidation heuristic) · #43/#44 (evidence) · sibling cleanups #78 (brain_index), #79 (legacy params)
**Charter:** ADR-0012 (consolidation heuristic) · **Blocked on:** ADR-0009 design being decided first ## Intent The two big consolidations ADR-0012 names for the brain surface: - **`remember`** — collapse `brain_write` / `brain_ingest` / `brain_ingest_raw` (three doors for one intent: "put this knowledge in"). Per the consolidation heuristic, the caller has no legitimate stake in *which extraction mechanism* runs — that's the server's call — so this is a clean collapse to one intent-named verb, with extraction strategy as an optional server-defaulted hint. - **`recall`** — collapse `brain_query` / `brain_answer` / `brain_graph` (three retrieval mechanisms for one intent: "find what's relevant"). Here the caller *sometimes* has a legitimate stake (occasionally you really do want graph traversal), so per the heuristic this is one verb + an optional `strategy` hint defaulting to server choice — NOT a hard wall hiding the mechanisms. `brain_get` stays separate (fetch-exact-handle is a distinct intent, not a mechanism of recall). ## Why this is blocked, not ready This is **not** immediately actionable. ADR-0012 explicitly hands the brain-specific verb-set design to **ADR-0009** (consumer-split), which is still a STUB with its Decision section as TODO. The agent-facing vs human-facing split has to be decided first — e.g. does `remember` mean the same thing for an autonomous agent as for a human curating raw→wiki? Is `recall`'s default strategy consumer-dependent? Those are 0009's questions. Building `remember`/`recall` before 0009 is decided would hard-code answers to questions that are supposed to be deliberated. So: this issue tracks the consolidation intent and keeps ADR-0012's "tracked separately" claim honest, but its first real step is **doing ADR-0009's design**, under the charter. ## Acceptance (gated) - [ ] ADR-0009 Decision section filled (consumer-split + verb set decided, under ADR-0012) - [ ] `remember` verb designed (write/ingest/ingest_raw → one verb + optional extraction hint) - [ ] `recall` verb designed (query/answer/graph → one verb + optional strategy hint, server-default) - [ ] `brain_get` confirmed to remain separate (distinct intent) - [ ] Versioned deprecation plan for the old verbs (add-new / deprecate / migrate / remove) — do not hard-break callers - [ ] SKILLs / agents / capture BrainStore caller-migration accounted for ## Related - **ADR-0009** (the blocker — brain consumer-split design must be decided first) - ADR-0012 (the charter + consolidation heuristic) · #43/#44 (evidence) · sibling cleanups #78 (brain_index), #79 (legacy params)
mathias commented 2026-08-22 06:41:05 +00:00
Author
Owner
Copy Link
Copy Source

Unblocked — ADR-0009 is decided, and this design follows from it

ADR-0009's Decision section is filled (infra PR #296): no consumer split; split by authority instead. The blocker this issue names is gone. Design below, no implementation — that stays gated on your review of both.

The decision that matters for this issue: the authority gate decides the layer, so callers stop choosing paths. That single move dissolves #43's "layer routing is a noun with no verb" and the brain_ingest_raw-ignores-the-path-prefix bug class, because no caller states a layer any more.

The verb set

Verb Collapses Heuristic test Authority
remember brain_write + brain_ingest_raw No caller stake in which layer — the server routes by authority open
digest brain_ingest Kept separate — see deviation below open
recall brain_query + brain_answer + brain_graph Sometimes-legitimate stake → one verb + optional strategy, server default open
get brain_get + brain_read No caller stake in parsed-vs-raw → optional raw hint open
supersede brain_update Already intent-named; rename only open
revise brain_edit Distinct intent: byte-level patch, not whole-note replace open
promote / reject brain_promote + brain#81 Curation-state transition gated
(governance edit) brain_edit_root Instruction-carrying file gated, de-surfaced

brain_pending becomes the read half of promote rather than a verb of its own. brain_index is already gone (#78, verified live — 17 tools, absent).

Two deviations from ADR-0012's literal suggestion, both justified per its own rule

1. remember does NOT swallow brain_ingest. The charter names "remember collapsing write/ingest/ingest_raw." Applying the charter's own consolidation heuristic rather than its example, that collapse fails the test:

  • brain_write / brain_ingest_raw — "record this thing I concluded." Differ only in destination layer. The caller has no legitimate stake once authority decides the layer. Collapse.
  • brain_ingest — "digest this external source into pages." An LLM pipeline rewrites the input; my words do not survive verbatim. A caller absolutely does have a stake in whether the corpus stores what it said or a model's extraction of what it said.

Those are two intents, not two mechanisms for one intent — the heuristic's third bullet. #44's "write-schema confusion (3 param shapes + ingest)" is real evidence, but it is confusion about parameter shape, not about intent; collapsing intents to fix a params problem would trade a small annoyance for a permanent ambiguity about whether the corpus holds your claim or a paraphrase of it.

2. get absorbing brain_read is a new consolidation the charter did not name. Both mean "fetch this exact handle"; they differ only in parsed-frontmatter vs raw bytes. That is textbook rule-1 mechanism leak, and it postdates ADR-0012 (brain_read shipped 2026-08-18). Worth catching now rather than after callers accumulate.

recall's strategy hint must stay escapable

Per ADR-0009 §3: agents distrusted brain_answer and re-queried within a minute because synthesis quality was insufficient, not because the name was wrong. recall defaults to server choice, but a caller that does not trust synthesis must be able to ask for raw retrieval — otherwise the rename hides a trust problem behind a nicer surface. Suggested shape:

recall(query, strategy?: "auto" | "lexical" | "semantic" | "graph" | "synthesis")   // default "auto"

Deprecation — versioned, no hard breaks

Per ADR-0012's obligation. Three phases, each independently shippable and revertible:

  1. Add the intent-named verbs alongside the existing ones. Both live. Old verbs unchanged, not yet marked. Zero caller impact.
  2. Deprecate — old verbs stay functional, gain a deprecation note in their description, and get de-surfaced from tools/list one at a time (the #78 precedent: de-surfaced ≠ removed, a caller that knows the name still works). Migrate the known callers: SKILLs, agentsquad, capture's BrainStore, brain-gardener, dma-cli.
  3. Remove only after a full cycle with no old-verb calls observed in the logs. If anything still calls them, that is a migration bug, not a reason to keep the alias forever.

The surface gets temporarily larger, not smaller — worth stating plainly since it looks like regression mid-migration.

Needs your call before implementation

  • digest as a name. It is the one coined verb here, and ADR-0012 requires new verbs to fit the existing vocabulary (capture, recall, remember, supersede, ship). digest fits grammatically; ingest is the incumbent but is mechanism-named. Alternative: keep brain_ingest un-renamed and out of scope, on the grounds that its callers are pipelines rather than models.
  • Does brain_context fold into recall? It is arguably recall with a project scope and a server-chosen limit. Folding it is tidy; it is also the one verb with a session-start intent that a strategy hint does not express. My lean: leave it, revisit after the migration.
  • brain_classify and brain_tunnel are both mechanism-named and both auto-called in places. Rule 4 says an auto-called op must not be a caller verb. Neither was audited here — worth their own pass rather than a guess in this comment.

Refs: ADR-0009 (infra PR #296), ADR-0012, #43, #44, #45, #78, #96, #97, brain#81.

## Unblocked — ADR-0009 is decided, and this design follows from it ADR-0009's Decision section is filled (infra PR #296): **no consumer split; split by authority instead.** The blocker this issue names is gone. Design below, no implementation — that stays gated on your review of both. The decision that matters for this issue: **the authority gate decides the layer, so callers stop choosing paths.** That single move dissolves #43's "layer routing is a noun with no verb" *and* the `brain_ingest_raw`-ignores-the-path-prefix bug class, because no caller states a layer any more. ## The verb set | Verb | Collapses | Heuristic test | Authority | |---|---|---|---| | `remember` | `brain_write` + `brain_ingest_raw` | No caller stake in *which layer* — the server routes by authority | open | | `digest` | `brain_ingest` | **Kept separate — see deviation below** | open | | `recall` | `brain_query` + `brain_answer` + `brain_graph` | Sometimes-legitimate stake → one verb + optional `strategy`, server default | open | | `get` | `brain_get` + `brain_read` | No caller stake in parsed-vs-raw → optional `raw` hint | open | | `supersede` | `brain_update` | Already intent-named; rename only | open | | `revise` | `brain_edit` | Distinct intent: byte-level patch, not whole-note replace | open | | `promote` / `reject` | `brain_promote` + brain#81 | Curation-state transition | **gated** | | (governance edit) | `brain_edit_root` | Instruction-carrying file | **gated**, de-surfaced | `brain_pending` becomes the read half of `promote` rather than a verb of its own. `brain_index` is already gone (#78, verified live — 17 tools, absent). ## Two deviations from ADR-0012's literal suggestion, both justified per its own rule **1. `remember` does NOT swallow `brain_ingest`.** The charter names "`remember` collapsing write/ingest/ingest_raw." Applying the charter's own consolidation heuristic rather than its example, that collapse fails the test: - `brain_write` / `brain_ingest_raw` — "record this thing I concluded." Differ only in destination layer. The caller has no legitimate stake once authority decides the layer. **Collapse.** - `brain_ingest` — "digest this external source into pages." An LLM pipeline rewrites the input; my words do not survive verbatim. A caller absolutely does have a stake in whether the corpus stores *what it said* or *a model's extraction of what it said*. Those are two intents, not two mechanisms for one intent — the heuristic's third bullet. #44's "write-schema confusion (3 param shapes + ingest)" is real evidence, but it is confusion about **parameter shape**, not about intent; collapsing intents to fix a params problem would trade a small annoyance for a permanent ambiguity about whether the corpus holds your claim or a paraphrase of it. **2. `get` absorbing `brain_read` is a new consolidation the charter did not name.** Both mean "fetch this exact handle"; they differ only in parsed-frontmatter vs raw bytes. That is textbook rule-1 mechanism leak, and it postdates ADR-0012 (`brain_read` shipped 2026-08-18). Worth catching now rather than after callers accumulate. ## `recall`'s strategy hint must stay escapable Per ADR-0009 §3: agents distrusted `brain_answer` and re-queried within a minute because synthesis quality was insufficient, not because the name was wrong. `recall` defaults to server choice, but a caller that does not trust synthesis must be able to ask for raw retrieval — otherwise the rename hides a trust problem behind a nicer surface. Suggested shape: ``` recall(query, strategy?: "auto" | "lexical" | "semantic" | "graph" | "synthesis") // default "auto" ``` ## Deprecation — versioned, no hard breaks Per ADR-0012's obligation. Three phases, each independently shippable and revertible: 1. **Add** the intent-named verbs alongside the existing ones. Both live. Old verbs unchanged, not yet marked. Zero caller impact. 2. **Deprecate** — old verbs stay functional, gain a deprecation note in their description, and get de-surfaced from `tools/list` one at a time (the #78 precedent: de-surfaced ≠ removed, a caller that knows the name still works). Migrate the known callers: SKILLs, agentsquad, capture's BrainStore, brain-gardener, dma-cli. 3. **Remove** only after a full cycle with no old-verb calls observed in the logs. If anything still calls them, that is a migration bug, not a reason to keep the alias forever. **The surface gets temporarily larger, not smaller** — worth stating plainly since it looks like regression mid-migration. ## Needs your call before implementation - **`digest` as a name.** It is the one coined verb here, and ADR-0012 requires new verbs to fit the existing vocabulary (`capture`, `recall`, `remember`, `supersede`, `ship`). `digest` fits grammatically; `ingest` is the incumbent but is mechanism-named. Alternative: keep `brain_ingest` un-renamed and out of scope, on the grounds that its callers are pipelines rather than models. - **Does `brain_context` fold into `recall`?** It is arguably `recall` with a project scope and a server-chosen limit. Folding it is tidy; it is also the one verb with a *session-start* intent that a strategy hint does not express. My lean: leave it, revisit after the migration. - **`brain_classify` and `brain_tunnel`** are both mechanism-named and both auto-called in places. Rule 4 says an auto-called op must not be a caller verb. Neither was audited here — worth their own pass rather than a guess in this comment. Refs: ADR-0009 (infra PR #296), ADR-0012, #43, #44, #45, #78, #96, #97, brain#81.
mathias commented 2026-08-22 08:50:45 +00:00
Author
Owner
Copy Link
Copy Source

Decision on digest: don't coin it. brain_ingest stays out of scope.

Reversing my own recommendation from the design comment above, on the "keep it simple" principle.

I proposed digest as a new intent-named verb for the extraction path. Rejecting it, for now:

  • It adds a name without removing a door. The other consolidations each delete callers' choices: three write doors become one remember, three read doors become one recall, two fetch doors become one get. digest deletes nothing — it renames a single verb that already has exactly one job. That is churn plus a deprecation cycle for a vocabulary improvement.
  • Its callers are pipelines, not models. ADR-0012's cost is measured in model confusion — a caller having to know the storage mechanism to pick a tool. The extraction path is invoked by the ingest pipeline and the ntfy URL-push trigger, which do not shop for a verb.
  • The design point it protected survives without the rename. The substantive finding was that remember must not swallow extraction: "store what I concluded" and "digest this external source into pages" are different intents, and collapsing them would make it ambiguous whether the corpus holds your words or a model's paraphrase. That holds whatever the second verb is called. brain_ingest keeps the boundary today at zero cost.

Revised scope for this issue: remember, recall, get, supersede, revise, plus the gated promote/reject. brain_ingest is explicitly out, not forgotten.

Reverses if: a model-facing caller ever needs to choose extraction deliberately — at which point it needs an intent name and digest is the one to use — or if brain_ingest grows a second mechanism-named sibling, which would make it a consolidation candidate on rule 1's own terms rather than on tidiness.

Recording it here so the next reader doesn't re-derive digest from ADR-0012's example list and assume it was overlooked.

## Decision on `digest`: don't coin it. `brain_ingest` stays out of scope. Reversing my own recommendation from the design comment above, on the "keep it simple" principle. I proposed `digest` as a new intent-named verb for the extraction path. Rejecting it, for now: - **It adds a name without removing a door.** The other consolidations each delete callers' choices: three write doors become one `remember`, three read doors become one `recall`, two fetch doors become one `get`. `digest` deletes nothing — it renames a single verb that already has exactly one job. That is churn plus a deprecation cycle for a vocabulary improvement. - **Its callers are pipelines, not models.** ADR-0012's cost is measured in *model* confusion — a caller having to know the storage mechanism to pick a tool. The extraction path is invoked by the ingest pipeline and the ntfy URL-push trigger, which do not shop for a verb. - **The design point it protected survives without the rename.** The substantive finding was that `remember` must *not* swallow extraction: "store what I concluded" and "digest this external source into pages" are different intents, and collapsing them would make it ambiguous whether the corpus holds your words or a model's paraphrase. That holds whatever the second verb is called. `brain_ingest` keeps the boundary today at zero cost. **Revised scope for this issue:** `remember`, `recall`, `get`, `supersede`, `revise`, plus the gated `promote`/`reject`. `brain_ingest` is explicitly out, not forgotten. **Reverses if:** a model-facing caller ever needs to choose extraction deliberately — at which point it needs an intent name and `digest` is the one to use — or if `brain_ingest` grows a second mechanism-named sibling, which would make it a consolidation candidate on rule 1's own terms rather than on tidiness. Recording it here so the next reader doesn't re-derive `digest` from ADR-0012's example list and assume it was overlooked.
mathias added the risk/mediumsize/ltype/decision labels 2026-08-27 05:25:42 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agent/ready
Meets the agent-ready contract; authorizes unattended execution
 blocked/client
Waiting on the client
 blocked/supplier
Waiting on a supplier
 blocked/upstream
Waiting on an upstream project or vendor
 risk/high
Irreversible, security-relevant, or control plane
 risk/low
Reversible, local, test-covered
 risk/medium
Touches shared state, deploys or data
 size/l
Too big - split it
 size/m
Under two days
 size/s
Under half a day
 size/xs
Under an hour
 status:dispatch
status:dispatched
status:review
status:reviewing
type/chore
Maintenance, no behaviour change
 type/decision
Human decision required; never agent/ready
 type/docs
Documentation only
 type/feat
New capability
 type/fix
Corrects broken behaviour
 type/ops
Infrastructure, deploy, runtime
 type/research
Investigate; output is a finding, not code
 type/test
Test coverage only
No labels risk/medium size/l type/decision
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
renovate-bot mathias
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mathias/hyperguild#80