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
9.0 KB
Raw Blame

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 noteLifecycle write, the lifecycle path reuses the freshen machinery (the FRESHEN_CLAIM_FILE single-runner claim, backoff state, a decideFreshen-style pure decision) through the same deferred dynamic import readIndexEvidence already established, spawning one detached low-priority incremental indexVault run; IndexEvidence gains 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 extends retargetsFor and decideBasename with 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), while decideBasename's ambiguous withholding stays untouched. Separator tolerance lands inside the pure kernel as a separator-insensitive occurrence matcher in anchorEntityForms (form spaces match runs of space, hyphen or underscore in the haystack; slug-prefixed occurrences match at a /-segment boundary), keeping normalizeEntityName identity keys unchanged so registry duplicate refusal, doctor lints and search alias expansion see no identity change. Link-derived attachment is threaded through opts: extraction callers resolve the source page's outbound links server-side from note bytes and pass candidate entity ids into decomposeAtomicFacts, 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_LENGTH still 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.
  • 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; IndexEvidence becomes 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 via resolveLinkTargets as the single authority, eliminating the duplicated ladder because rewrite, repair and reporting read one source. Separator folding moves into normalizeEntityName itself, 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), and decideFreshen is extended so a dirty marker makes any read immediately due, bypassing search_freshen_interval_s; IndexEvidence reports "converges on next read" instead of bare stale plus next_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.