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.
Brain Model Semantics foundation - variants
Consultant output
Variant 1: Frontmatter-native vocabulary extension
- Approach: Lay the foundation entirely in the source-of-truth Markdown by extending the existing
relation-vocab.tsvocabulary with the preference-specific relation types the upstream tasks imply (depends_on,refines, plus the already-presentcontradicts/superseded_by), and adding optionalrelation-shaped frontmatter fields and a single optionallayertag to the preference parser. The explorer projects these throughExplorerEdge.kindso typed edges and layer become visible without any new storage. Branching is represented only as an optionalbranchstring label on a preference (a soft namespace), with no copy-on-write machinery - selective pick remains a future merge-side concern. - Trade-offs:
- Pro: Maximally aligned with constraints - reuses the single validation boundary, no parallel subsystem, byte-identical default (fields absent unless supplied).
- Pro: Deterministic and LLM-free; edges/layers live in the plain files the README promises to own.
- Pro: Smallest test surface - extends
explorer.test.tsandbacklinks-relation.test.tsrather than adding suites. - Con: Branching is only a label, not isolation - defers the hardest upstream feature almost entirely.
- Con: Layer is a flat tag with no per-layer lifecycle, so L0-L3 retention policies are not yet expressible.
- Complexity: small
- Risk: low
Variant 2: Unified semantics descriptor with deterministic backfill
- Approach: Introduce one cohesive optional "semantics" block on the preference model in
types.tsthat carries all three concepts together - typed edges (validated againstrelation-vocab), alayerenum (L0-L3), and abranchlabel - parsed and written throughpreference.ts. Pair it with a dry-run-default backfill tool (mirroring ContextLattice'smemory-edge-backfill) that deterministically derives high-confidencesame-session/exact-topicedges from existingevidenced_byand topic slugs. The descriptor is the shared foundation all three future layers build on. - Trade-offs:
- Pro: Treats the three tasks as one coherent model layer, avoiding three disjoint half-features.
- Pro: The backfill-with-dry-run pattern is directly reusable by existing merge/scan operations and is fully deterministic.
- Pro: Single descriptor gives every future layer (branch isolation, per-layer lifecycle) a stable home.
- Con: Larger schema footprint up front; risk of speculative fields that stay empty if branching/layering never land.
- Con: A
layerenum baked into the core preference type nudges toward the L0-L3 restructure the constraints explicitly say not to do in one PR. - Con: Backfill tooling adds a CLI surface and its own test suite.
- Complexity: medium
- Risk: medium
Variant 3: Derived projection and index layer
- Approach: Keep preference files essentially untouched and compute typed semantics on the read side -
explorer.tsand a deterministic derivation step infer edges (depends_on/refines/contradicts) and a layer classification from existing signals (evidenced_by, topic slugs, confidence, session adapters) into a derived, regenerable index rather than stored frontmatter. Branching and selective pick are modeled as alternate derivation views over the same vault, not stored state. - Trade-offs:
- Pro: Zero schema change to the source of truth; default install is trivially byte-identical and nothing is written unless regenerated.
- Pro: Edges and layers stay always-consistent with their sources because they are recomputed, never hand-maintained.
- Pro: Naturally fits the existing derived-artifact pattern (active.md is already auto-generated).
- Con: Operator cannot author an explicit relationship (e.g. "pref-a depends-on pref-b") - only inferred edges exist, contradicting the upstream "first-class typed edge" intent.
- Con: A derivation/index step risks becoming the parallel graph subsystem the constraints forbid.
- Con: Heuristic layer classification is fragile and hardest to test deterministically.
- Complexity: medium
- Risk: high
Recommended: Variant 1
Rationale: It is the only variant that satisfies every hard constraint at once - additive, deterministic, schema-compatible, byte-identical by default, and built strictly on the existing relation-vocab/backlink/explorer surfaces rather than a new subsystem. The task is explicitly a foundation, and the validator comments require an ADR before branching and L0-L3 lifecycle are built, so Variant 1 establishes the typed-edge and layer-tag vocabulary now while deferring copy-on-write branching and per-layer lifecycle exactly as the constraints demand. Variant 2's unified descriptor and Variant 3's derived index both over-commit to mechanisms (a baked-in layer enum, an inference subsystem) that pre-empt decisions the ADRs are meant to make.
Orchestrator decision
Chosen: Variant 1.
The existing typed graph semantics work already established src/core/graph/relation-vocab.ts as the single validation boundary, and the Brain backlink index already consumes known frontmatter relation fields. Reusing that path gives the selected scope a real implementation foundation without introducing speculative branch storage, a second graph, or layer-specific lifecycle policy before the ADR has settled those decisions.
The implementation should therefore ship a narrow additive slice: preference-authored typed edge vocabulary and explorer projection, optional memory_layer / memory_branch metadata with validation, and a deterministic dry-run planner for supersession-edge backfill. Full copy-on-write branches, selective pick commands, REST service mode, and per-layer retention remain out of scope for this PR.