follow-up: synchronous semantic read-after-write for brain_update — DEFERRED (retro skill uses option b) #47
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: mathias/hyperguild#47
Reference in New Issue
Block a user
RESOLUTION (2026-06-22): NOT needed for the retro skill → option (b). Deferred, not closed-wontfix.
The retro skill is batch: one session in, finite findings out, exit. Worked the decision:
brain_get(id)+ content-hash check — direct file read, immediate, strictly better than fuzzy vector search for confirming a known id.Decision: option (b). No synchronous re-embed built. This issue stays open-deferred as a ready spec — reopen/build only if a future consumer needs sub-5-min semantic read-after-write (e.g. a continuous/iterative skill that re-reads its own evolving output semantically, unlike this batch one).
Design rule banked into the retro-skill spec: front-load all brain reads before any
brain_update; no semantic query after the firstbrain_updatein a run. Batch shape satisfies this naturally — it's a guardrail, not a fight. Falsifiable check: if the skill design ever wants to issue a semantic query post-supersede, that's the signal to revisit (a).Context
Deferred from #45 / PR #46. Surfaced by the Step 0 trace there.
Today no MCP write handler re-embeds in-handler. Embedding refresh is out-of-band and mtime-driven via
vectorstore.StartSync(default 5 min ticker,ingestion/cmd/server/main.go:301) plusPOST /backfill-embeddings.brain_updaterewriting a note advances its mtime, so the next Sync pass re-embeds it — but that leaves a ≤5 min staleness window on the vector/semantic retrieval path.BM25/lexical search and
brain_get(direct file read) are immediate; only pgvector retrieval lags.Problem (the gap this issue specs, if ever needed)
If a consumer needs sub-5-min semantic read-after-write — supersede a note then immediately do a vector query expecting the new content — the current architecture won't satisfy it within seconds. The batch retro skill does not trigger this (see Resolution above).
Proposed (option a — the build, if revived)
Wire a
vectorstore.Store+ embedder into the MCPServer(mirroringHandler.WithEmbedSync) sobrain_update/brain_writecan re-embed just the changed file in-handler (chunk → embed → upsert, delete stale chunks), best-effort, after the file write. Keep the Sync ticker as the backstop.Related
brain_update(the supersede verb this windows)wiki/hyperguild/decisions/retro-skill-semantic-read-after-write-staleness-constraint.md(the constraint + this resolution)wiki/hyperguild/facts/brain-mcp-embeddings-out-of-band-sync.md(the underlying footgun)follow-up: optional synchronous in-handler embedding refresh for brain_update / brain_writeto follow-up: synchronous semantic read-after-write for brain_update — BLOCKS retro skill (need confirmed)follow-up: synchronous semantic read-after-write for brain_update — BLOCKS retro skill (need confirmed)to follow-up: synchronous semantic read-after-write for brain_update — DEFERRED (retro skill uses option b)Closing — resolved to option (b): do not build.
The issue records its own resolution — synchronous semantic read-after-write for
brain_updateis deferred, with no build wanted unless a future consumer actually needs sub-five-minute semantic read-after-write. No such consumer has appeared since it was filed 2026-06-22, and it has sat with zero comments throughout.A deferred-with-a-decision issue left open is indistinguishable from unplanned work in a tracker. Closing so it stops reading as a commitment.
Closed during the 2026-08-27 estate backlog triage. Reopen if a consumer materialises — the analysis in the body stays valid.