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:
The skill's only semantic read is the dedup / "what already exists" pass, which runs before any write, on prior-session notes that are long-since embedded — no staleness exposure.
Its read-after-write (step 4, "did my supersede land?") is naturally brain_get(id) + content-hash check — direct file read, immediate, strictly better than fuzzy vector search for confirming a known id.
The only thing option (a) would buy is the exotic within-run "supersede note A, then semantically re-discover A's fresh form in the same run" loop. A batch retro that dedups up front never does this.
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 first brain_update in 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) plus POST /backfill-embeddings. brain_update rewriting 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 MCP Server (mirroring Handler.WithEmbedSync) so brain_update / brain_write can 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
#45 — brain_update (the supersede verb this windows)
brain: wiki/hyperguild/decisions/retro-skill-semantic-read-after-write-staleness-constraint.md (the constraint + this resolution)
brain: wiki/hyperguild/facts/brain-mcp-embeddings-out-of-band-sync.md (the underlying footgun)
Consumer: session-retro skill (batch; uses option b)
## 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:
- The skill's only semantic read is the **dedup / "what already exists" pass**, which runs **before** any write, on **prior-session** notes that are long-since embedded — no staleness exposure.
- Its read-after-write (step 4, "did my supersede land?") is naturally `brain_get(id)` + content-hash check — direct file read, immediate, strictly better than fuzzy vector search for confirming a known id.
- The only thing option (a) would buy is the exotic within-run "supersede note A, then semantically re-discover A's fresh form in the same run" loop. A batch retro that dedups up front never does this.
**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 first `brain_update` in 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`) plus `POST /backfill-embeddings`. `brain_update` rewriting 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 MCP `Server` (mirroring `Handler.WithEmbedSync`) so `brain_update` / `brain_write` can 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
- #45 — `brain_update` (the supersede verb this windows)
- PR #46 — implementation + Step 0 finding
- brain: `wiki/hyperguild/decisions/retro-skill-semantic-read-after-write-staleness-constraint.md` (the constraint + this resolution)
- brain: `wiki/hyperguild/facts/brain-mcp-embeddings-out-of-band-sync.md` (the underlying footgun)
- Consumer: session-retro skill (batch; uses option b)
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking 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)