Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
11.7 KB
Raw Blame

Recall quality wave - variants and final rationale

Consultant output (Claude Code, primary) reproduced verbatim from cli-output/claude.md. The orchestrator's decision and rationale follow at the end.

Variant 1: Pinned-kernel parallel lanes over a shared derived-artifact substrate

  • Approach: A short serial substrate stage lands the wave's only genuine cross-lane contract as behavior-identical code before peak parallelism: the ValidateEntityLabelOptions extension in leaf canonical.ts (lexicon handle injected parameter-style exactly like the denylist; new shouted-heading / function-word-run reasons; structural code-shape bypass; caseful-only case rules with caseless-script admit) plus one small derived-artifact IO helper (schema-version + dataset-hash + fail-soft read) that both Brain/entities/lexicon.json and Brain/link-graph/hallways.json consume. Then four feature lanes run fully in parallel over disjoint sets β€” (A) admission + lexicon: registry.ts, label-hygiene.ts, new lexicon.ts, doctor entity-checks, entity verb, anchoring boundaries; (B) session mining + hallways: sessions/import.ts, new session-mining.ts, continuity record kind, hallways CLI command, manifest entry; (C) the single v14 migration closing both store cards: schema.ts, store/keyword|vectors|documents|chunks, two-tier hydration cut in search.ts, indexer attribute writes, pool/result filters, MCP+CLI query kind surface, query-cache key; (D) eval + telemetry: lang field + byLang split in benchmark.ts, sibling ZH fixture with CI pins on the offline local-provider stack, dead_weight op + CLI parity β€” plus a fifth micro-lane owning exactly the six repair files (permissions/resolve.ts, extract-intake.ts, delete_by_source/schema-mutation deny evidence in source-cleanup.ts/ingest-tools.ts/store-integrity doctor, install/ownership-measure.ts, three doc/warning items), which intersect no feature set. Ordering is substrate, then lanes, then integration; global registration files (command-manifest.ts, census registries) take an append-only per-lane rule with the ratchet tests as arbiter.
  • Trade-offs:
    • The one semantic coupling β€” mined promotion flowing through the tightened admission gate β€” is pinned and tested before any lane starts; the miner lane codes against landed predicate code, not a promise, and the code-shape bypass the extractor needs is part of the pinned surface.
    • Hallways keeps its precision bias as a structural property (side continuity ledger, incidence+PMI artifact, thresholded promotion through upsertEntity only) and the session/vault graph separation holds because hallways.json is a separate artifact beside β€” never merged into β€” the vault-derived co-occurrence graph.
    • The riskiest single artifact, the atomic first-open v14 migration (virtual chunk_kind, document_attributes backfill, sargable range predicates), is single-lane owned with its full test and census surface and is never blocked by another lane.
    • The repair lane needs no coordination track of its own: extract-intake.ts needs no lexicon change because the creation gate resolves the handle inside upsertEntity, so all six files are genuinely disjoint from A–D.
    • The substrate stage is serial front-loading β€” two to three days before all lanes run β€” and the extracted IO helper is a new shared module two lanes must agree on.
    • A mispredicted predicate shape mid-wave touches lanes A and B simultaneously (mitigated: the default-null handle keeps pre-wiring behavior byte-identical, so amendment is cheap).
    • Five concurrent lanes is the top of the house limit; review attention concentrates in the substrate commit and the migration.
  • Complexity: large
  • Risk: medium

Variant 2: Two-stage layered wave β€” independent front first, coupled entity pair behind the landed gate

  • Approach: Stage 1 runs three lanes in parallel β€” the v14 store migration closing both store cards, the independent observability pair (bilingual eval + dead-weight view), and the six-finding repair lane β€” alongside only the predicate slice of the admission work: canonical.ts gains the new verdict reasons, structural shouted-heading/code-shape/caseful-guard branches and the optional lexicon field with default-null behavior, landing as the gate commit. Stage 2 starts only once the gate commit is on the integration branch: one lane completes lexicon.ts and its wiring at the choke points (creation gate, store-wide heal, anchoring), and another builds the import-loop miner, hallways pass and thresholded promotion against the already-landed gate β€” coupling by merge order instead of by an advance-pinned contract. No shared helper module is extracted; each artifact copies the established co-occurrence/tuning IO pattern directly.
  • Trade-offs:
    • Lowest coordination cost of the three: no contract to negotiate up front, no shared substrate design; stage-2 lanes build on merged, tested code rather than on a parallel lane's in-flight shape.
    • Front-loads the two hardest-to-reverse artifacts β€” the atomic first-open migration and the identity-kernel-adjacent predicate β€” into the window where the most calendar time remains to react to large-vault or false-positive surprises.
    • The repair lane and the observability pair are fully insulated from stage-2 churn.
    • Serializes roughly forty percent of the wave: the entity pair cannot begin until the gate lands, so wall-clock grows and the PR's critical path runs through both stages.
    • Stage-2 iteration on the landed gate churns the integration branch mid-wave with no soak time, since everything still merges as one squash commit.
    • Two integration passes and a mid-PR landing order make the eventual review history muddier than four clean parallel lanes.
  • Complexity: medium
  • Risk: medium

Variant 3: Autonomous vertical slices with a types-only contract stub and duplicated substrate

  • Approach: Five fully autonomous vertical lanes, one per concern β€” admission+lexicon, miner+hallways, v14 store migration, eval+dead-weight, and the six repair findings β€” start simultaneously and run end-to-end with absolute file ownership, each lane even appending its own manifest and census registrations. Coordination is reduced to a day-one types-only stub (the ValidateEntityLabelOptions shape and the two artifact schemas as declarations, no behavior) plus an append-only rule for global registration files. No behavioral substrate exists: lexicon.json and hallways.json each embed their own copy of the derived-artifact IO convention, and the miner implements its own family-scoped, case-preserving ledger pre-check, routing only final promotion through upsertEntity as the contract doc specifies.
  • Trade-offs:
    • Maximum parallelism from hour zero; every lane is reviewable and testable in isolation, and file-disjointness is total by construction.
    • The types-only stub is nearly free and lets the compiler enforce the admission contract between the entity and miner lanes without any serial stage.
    • The derived-artifact convention is now implemented twice more (lexicon, hallways) beside the two existing copies (co-occurrence, tuning) β€” precisely the drift this codebase's schema-versioned, dataset-hashed, fail-soft discipline exists to prevent; expiry and torn-file semantics will diverge subtly.
    • The admission contract is enforced by declaration and review only; the promotion path meets the tightened gate for real only at late integration, where surprises are most expensive to fix.
    • Census surfaces (manifest ratchet, visibility-surface registry, write-site counts) get five simultaneous appenders, so merge-order disputes surface late in the wave.
  • Complexity: large
  • Risk: high

Recommended: Variant 1

Rationale: It is the house delivery model applied straight β€” four to five disjoint lanes with a pinned cross-lane contract β€” except the contract is front-loaded as small, behavior-identical substrate code, so the wave's only real coupling (mined promotion through the tightened admission gate) is resolved before peak parallelism instead of at late integration, for the cost of a two-to-three-day serial head. The single riskiest artifact, the atomic first-open v14 migration, stays isolated inside one lane with its full test and census surface, and the repair lane's six files genuinely intersect nothing, so five lanes need no extra coordination track. Variant 2 buys similar coupling safety by putting the gate and roughly forty percent of the wave on a serialized late critical path inside a single-PR window, and Variant 3 duplicates the derived-artifact substrate that this codebase's own conventions say must not drift.

Final rationale (orchestrator decision)

Variant 1 is chosen. The orchestrator agrees with the consultant's recommendation. Variant 1 is the house delivery model with the wave's one genuine coupling pinned as behavior-identical substrate code; the cost is a short serial head, which is the cheapest form of coordination available here.

Per-card decisions recorded from verified recon, all load-bearing constraints included:

  • t_13a82a31 (R1): Variant B - side continuity ledger + hallways PMI pass + thresholded promotion through upsertEntity only. Constraints: link-graph reach asymmetry (co-occurrence excludes Brain/ from its corpus walk while Store-admit passes include Brain/entities - named, not resolved); session/vault graph separation (hallways.json beside, never merged into, the vault-derived co-occurrence graph); Brain/entities/ stays curated; ambient-consent and private-turn withholding respected.
  • t_11d51443 (R2): Variant A - lexicon through ValidateEntityLabelOptions injection into versioned Brain/entities/lexicon.json. Constraints: canonical.ts is a leaf module that imports nothing - the handle is a parameter, never an import; store-learned vocabulary only; normalizeEntityName byte-stability (validity verdicts change, keys never); structural caseful-only shouted-heading rejection with the prior-stored-occurrence escape; code-shape bypass so the miner's symbols are not junk-rejected; caseless-script admit; fail-open dataset-hash expiry.
  • t_71cbf5bf + t_82851eda (R3): Variant B - one v14 migration. Constraints: single atomic first-open transaction (crash-safe ROLLBACK), never rewriting embeddings/chunk_vec; chunk_kind VIRTUAL generated (STORED explicitly avoided); sargable range predicates with canonicalNotePath caller normalization; promoted keys excluded from document_attributes because existing structures already index them; promoted-key filtering is "as indexed", documented divergence.
  • t_693fa22a + t_1ee67e5b (R4): recon recommendations - lang field + byLang split + bundled self-authored ZH fixture as a sibling fixture dir with its own pins on the offline stack (no real-model embedding calls in committed tests); dead_weight operation on brain_recall_telemetry with CLI parity, walkVaultScope denominator, telemetry-window-bounded "never" semantics, reach-gated output, tool-count pin 115 unmoved.

Why the others lost:

  • Variant 2 serializes roughly forty percent of the wave onto a late critical path: the entity pair cannot begin until the gate commit lands, wall-clock grows, and both stages must still merge as one squash commit - so stage-2 churn on the landed gate hits the integration branch with no soak time, and the review history gets muddier for no coupling gain over Variant 1's pinned substrate.
  • Variant 3 duplicates the substrate - the schema-versioned, dataset-hashed, fail-soft derived-artifact convention would be implemented twice more beside the two existing copies, exactly the drift the convention exists to prevent - and defers the semantic coupling (mined promotion meeting the tightened gate) to late integration, enforced only by declaration and review, where surprises are most expensive.