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.
Memory write-path integrity and store safety - variant audit trail
Consultant: Claude Code (claude -p), prompt in cli-output/prompt.md, raw
output in cli-output/claude.md. Three variants were requested for the wave
architecture as a whole (shared abstractions vs isolated changes), not for
the worth of individual units. The fallback consultant (Codex) was not
invoked because the primary run succeeded with three parseable variants.
Variant 1: Unified WriteGate framework
- Approach: one cross-cutting gate framework (
src/core/gates/) with a genericGate<T>interface, a composableGatePipeline, and a single typedWriteRejectionerror hierarchy. All eleven units are expressed as gate stages plugged into this pipeline; every persist path (vault writes,vecUpsert,deleteBySource) is refactored to run through it. - Trade-offs:
- Pro: maximally DRY; one place to reason about "what can reject a write"; uniform rejection logging and doctor visibility for free.
- Pro: a single error taxonomy makes CLI/MCP surfacing consistent across all units.
- Con: the units span three genuinely different subsystems (Markdown vault writes, the sqlite-vec store, an HTTP embeddings client) with different payload types and failure semantics; a shared
Gate<T>interface is speculative generality that mostly holdsunknown. - Con: the framework becomes a serialization point - every unit's atomic commit depends on it, so a design flaw discovered late forces rework across the whole wave.
- Con: units t_3beb374c (e5 prefixes), t_66c12a67 (fact retire), and t_29a63073 (permission migration) are not gates at all and get shoehorned in or left inconsistent.
- Complexity: large
- Risk: high
Variant 2: Per-unit isolated changes
- Approach: each unit lands independently at its natural existing choke point with no new shared modules: extend
normalizeEntityNamein place, add checks insidevecUpsert, patchclassifyErrortwice (once per embeddings unit), wrapdeleteBySourcewith a directcreateSnapshotcall, and so on. Error codes are added ad hoc per subsystem as each unit needs them. - Trade-offs:
- Pro: trivially atomic commits with no ordering constraints; any unit can be dropped or reverted without touching the others.
- Pro: smallest possible diff per unit; matches the "improvement, not net-new" scoping of several units.
- Con: the brain write path ends up with five uncoordinated pre-persist checks with inconsistent rejection surfacing - exactly the "scattered per-call-site checks" the project constraints forbid.
- Con: t_8880a68d and t_144b680a both rework
classifyError; done independently they conflict or duplicate Retry-After/quota parsing. - Con: rejection logging conventions diverge per unit, making doctor/hygiene visibility (required by the no-silent-drop constraint) inconsistent.
- Complexity: medium
- Risk: medium
Variant 3: Cluster-scoped kernels, per-unit atomic commits
- Approach: group the eleven units into four subsystem clusters and introduce a small shared kernel only where units provably share a choke point, then land each unit as an atomic commit on top of its kernel. Brain write path gets a light gate chain with one logged-skip convention; the vec store gets a
validateVectorkernel plus preset-aware prefix config; the embeddings client gets oneclassifyErrorrework into{category, retriable, retryAfterMs}consumed by both resilience units in sequence; store safety gets awithSnapshot-style wrapper over the existing engine, reused bydeleteBySourceand the entity prune, with the permission migration landing as a remediation pass. - Trade-offs:
- Pro: DRY exactly where coupling is real (the two embeddings units, the multiple brain gates, the multiple snapshot consumers) without inventing a cross-subsystem abstraction.
- Pro: preserves per-unit atomic commits - each kernel is itself a small commit, units within a cluster stack on it, clusters remain mutually independent, so partial shipping stays possible.
- Pro: error-type design stays subsystem-native (
SearchErrorcodes for search/embeddings, typed brain-side rejections for vault writes), honoring existing conventions instead of unifying them artificially. - Con: requires deciding cluster boundaries and kernel interfaces up front, and sequencing within clusters (classifier before handling, gate chain before the gates that plug into it).
- Con: two error vocabularies coexist; a reviewer must understand which subsystem a rejection belongs to.
- Complexity: medium
- Risk: low
Consultant recommendation
Variant 3. "The wave's units cluster naturally along OSB's existing module
seams (brain vault, search store, embeddings client, snapshot engine), and
Variant 3 puts shared abstractions only at choke points that two or more
units actually share - satisfying the repo's 'shared choke points over
scattered checks' and typed-error constraints without Variant 1's
speculative cross-subsystem framework or Variant 2's duplicated
classifyError rework and uncoordinated gate sprawl. It also keeps every
unit an independently revertable atomic commit on one branch, which is
exactly what an 11-unit single-release wave needs when any one unit could
stall in review." (quoted verbatim from the consultant output)
Orchestrator decision
Variant 3 is adopted without override. Project context reinforces the
recommendation: v1.30.1 explicitly removed all import cycles and decomposed
oversized modules, so a new cross-subsystem framework (Variant 1) would cut
against the freshly-established one-directional layering, while Variant 2's
double rework of classifyError and scattered brain-write checks would
recreate the DRY violations the operator's brief forbids. The dependency
edges accepted with Variant 3 (classifier before handling, snapshot gate
before prune) are recorded in plan.md.