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.
Variants considered (consultant output verbatim)
The consultant brainstorm ran per the feature-release-playbook phase 0; the consultant prompt is cli-output/prompt.md and its reply is cli-output/claude.md.
Variant 1: Detached refresh claims, contract-preserving write side
- Approach: After an applied
noteLifecyclewrite, the lifecycle path reuses the freshen machinery (theFRESHEN_CLAIM_FILEsingle-runner claim, backoff state, adecideFreshen-style pure decision) through the same deferred dynamic importreadIndexEvidencealready established, spawning one detached low-priority incrementalindexVaultrun;IndexEvidencegains a "refresh claimed" reporting arm so the honesty contract is upgraded rather than inverted - the index stays a reported fact and the report now names the run converging it. The rewrite policy extendsretargetsForanddecideBasenamewith a pure minimal-spelling ladder over the already-scanned population (emit the shortest of full-path/suffix-less/basename spellings that resolves to exactly one note under the store's exact-one rule), plus a third-party repair arm that fires only when the rename provably changes a bare link's resolution (pinning it to the minimal spelling of its single pre-rename target), whiledecideBasename's ambiguous withholding stays untouched. Separator tolerance lands inside the pure kernel as a separator-insensitive occurrence matcher inanchorEntityForms(form spaces match runs of space, hyphen or underscore in the haystack; slug-prefixed occurrences match at a/-segment boundary), keepingnormalizeEntityNameidentity keys unchanged so registry duplicate refusal, doctor lints and search alias expansion see no identity change. Link-derived attachment is threaded throughopts: extraction callers resolve the source page's outbound links server-side from note bytes and pass candidate entity ids intodecomposeAtomicFacts, and a relink verb recomputes anchors for stored facts through the same kernel and lexicon (resolveEntityLexicon) with the new matcher, writing only additional anchors at no model cost. - Trade-offs:
- Pro: honors the acyclic-import ratchet with the exact precedent (
readIndexEvidence) the tree already endorses; no new static edges, no new dependencies. - Pro: honesty contract preserved and strengthened; behavior-preserving defaults hold (ambiguous basenames still withheld, repair only under provable rules,
MIN_ANCHOR_FORM_LENGTHstill gates matching). - Pro: kernel stays pure text; relink is deterministic, model-free, and testable with plain bun test in a temp vault.
- Con: the detached run still takes time, so a read issued immediately after a write can beat the run and answer stale - a narrower window than today, but not zero.
- Con: the minimal-spelling ladder duplicates, in pure form, resolution semantics the index store also implements, so the two must be kept aligned by shared fixtures.
- Con: separator-insensitive matching widens anchor recall, so some facts gain anchors literal matching never gave them; precision needs explicit test coverage.
- Pro: honors the acyclic-import ratchet with the exact precedent (
- Complexity: medium
- Risk: low
Variant 2: Maintained invariant index with identity-level fold
- Approach: Define a write-to-index port (interface plus no-op default) in the Brain tree, implemented by the search barrel and injected at the MCP/CLI seam so no static edge exists, and have every applied lifecycle write synchronously update just the touched document's rows in the links table under the existing writer lock and guarded-write rules;
IndexEvidencebecomes a maintained-invariant report ("current" or "degraded") and the module doc's honesty contract is rewritten. Minimal-spelling rewriting and third-party repair then resolve against the index's stored links table viaresolveLinkTargetsas the single authority, eliminating the duplicated ladder because rewrite, repair and reporting read one source. Separator folding moves intonormalizeEntityNameitself, making "foo-bar", "foo bar" and "foo_bar" one identity everywhere at once (duplicate refusal, alias resolution, search alias expansion, anchoring), with a one-time migration re-keying stored identities and a relink pass riding the same migration. Link-derived attachment becomes a maintained page-to-entity edge written by extraction alongside anchors and backfilled by the migration, so relink is a materialization of an invariant rather than a verb. - Trade-offs:
- Pro: strongest truth guarantee - no staleness window after a write, and no read-side freshen special cases for writes.
- Pro: one resolution authority for rewrite, repair and reporting; no ladder drift.
- Pro: separator tolerance arrives globally, so recall, dedup and search all agree on identity.
- Con: puts an index write on the critical path of every guarded note write; index failure must degrade the lifecycle result without failing it, which is new machinery on the hottest path.
- Con: needs port/injection discipline to stay inside the ratchet, plus writer-lock contention with the freshen daemon and the watch daemon.
- Con: the identity fold changes duplicate refusal and stored keys - the wave's largest blast radius - and the "reported fact, not maintained invariant" contract is deliberately abandoned, with carve-outs still needed because deletes rewrite nothing.
- Complexity: large
- Risk: high
Variant 3: Convergence-on-read with a shared resolution layer
- Approach: The lifecycle path only records a durable dirty marker (a note-change stamp beside
FRESHEN_STATE_FILE, written through the same deferred dynamic import), anddecideFreshenis extended so a dirty marker makes any read immediately due, bypassingsearch_freshen_interval_s;IndexEvidencereports "converges on next read" instead of bare stale plusnext_command. A single pure resolution module is factored out and shared by the rewrite pass, dangling-wikilink listing and unlinked mentions: it computes minimal resolving spellings over a walked population and applies the proven-safe third-party repair rule, so resolution and rewriting cannot disagree. Separator tolerance lives in that shared layer and in the anchoring gate as match-time folding, leaving stored identities untouched. Link-derived attachment is a read-time projection over the links table plus stored fact texts, exposed through the claim-graph projection, with a relink verb that materializes the projection into stored anchors deterministically and without a model. - Trade-offs:
- Pro: write path stays minimal - one tiny marker write, no index coupling, no ratchet pressure beyond the existing deferred import.
- Pro: the shared resolution layer is the wave's best structural payoff: one ladder behind rewrite, dangling listing and unlinked mentions permanently.
- Pro: no migration of stored rows; folding and projected attachment are pure additions.
- Con: the first read after a write still answers from the stale index while the detached run completes - exactly the window card t_c256d428 targets survives in weakened form.
- Con: freshness semantics become conditional (interval OR dirty) and spread across read sites, diluting the single-result honesty story.
- Con: read-time attachment means anchored recall differs between paths that materialize and paths that project unless every consumer adopts the projection.
- Complexity: medium
- Risk: medium
Recommended: Variant 1
Rationale: It is the only variant that starts closing the staleness window at the moment it is created - the write itself claims the refresh - while keeping the module's hard-won honesty contract intact: the index remains a reported fact and the report simply gains the claim. It respects every structural invariant with precedents already in the tree, using the deferred dynamic import the ratchet already tolerates, the freshen claim-file pattern for detached single-runner refresh, and a pure kernel that gains a matcher rather than new identity semantics, so no stored-key migration touches the registry, doctor or search alias expansion. Variant 2 buys a stronger invariant at the cost of an index write on the guarded-write critical path, an injection seam, and the wave's largest migration blast radius, while Variant 3 leaves the very post-write staleness window the spine targets and disperses freshness semantics across read sites. Variant 1's duplicated minimal-spelling ladder is its main liability, and it is containable with the plain bun test fixtures and shared resolution fixtures the project already standardizes on.
Orchestrator decision
Variant 1 adopted. Rationale: it is the only variant that closes the staleness window from the write side while preserving the index-evidence honesty contract, honors the acyclic-import ratchet with the readIndexEvidence precedent, and keeps the anchoring kernel pure without an identity-key migration. Variant 2's synchronous index write on the guarded-write critical path and stored-key migration are the largest blast radius in the tree for this wave's value; Variant 3 leaves the post-write window the spine targets and splits freshness semantics across read sites.