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

Link graph surfaces - brainstorm audit trail

Produced by the v0.10.17 brainstorm pass on 2026-05-25. Primary consultant: Claude Code CLI (docs/brainstorm/link-graph-surfaces/cli-output/claude.md). Fallback consultant: not invoked (primary returned three parseable variants + a clear recommendation on the first run).

Variant 1 - Single link-graph subsystem (strict precedent match)

Approach. Mint one new subsystem src/core/brain/link-graph/ that hosts every pure helper for features 1-5 (alias resolver, anchor extractor, unlinked-mention scanner, concept-cluster assembler, MOC classifier). Atoms extend BacklinkRef (anchor + alias-source fields) in place under backlinks.ts and add aliases to the in-memory note record from vault.ts; consumers are new CLI verbs / MCP tools that import from link-graph/. Feature 6 lands as src/core/search/property-filter.ts inside the existing search layer, and feature 7 lands as a small extension to whichever loader already injects active.md into session context.

Trade-offs.

  • Pro: Mirrors v0.10.15 / v0.10.16 exactly - one themed subdir, atoms/helpers/consumers DAG, predictable for reviewers.
  • Pro: Helpers are co-located, so synthesise and moc-audit can re-use the alias / anchor / unlinked-mention helpers without cross-subsystem imports.
  • Pro: Search and session-context changes stay in their natural layers instead of being dragged into a brain/ subdir where they don't belong.
  • Con: link-graph/ becomes a relatively large bag (5 helpers) compared to the tighter v0.10.16 trust/ tree.
  • Con: Two of seven features (property search, VAULT.md) sit outside the named release subsystem, so the release headline isn't quite "everything under one roof."

Complexity. medium Risk. low

Variant 2 - Three small co-equal subsystems (one per concern)

Approach. Carve the release into three named subsystems - src/core/brain/graph/ for link / backlink helpers (1-5), src/core/brain/property-filter/ for the FTS-post property-filter phase (6), and src/core/brain/vault-context/ for the VAULT.md loader (7). Each follows its own atoms/helpers/consumers DAG; the CHANGELOG groups them under one v0.10.17 header but the code tree is unambiguous about which file belongs to which feature cluster.

Trade-offs.

  • Pro: Clean one-feature-cluster-per-subdir mapping; each subdir is small and individually testable.
  • Pro: Property filter and VAULT.md are first-class members of the release, not "miscellaneous additions."
  • Pro: Future bundles can grow any of the three without touching the others.
  • Con: Breaks the "one new subsystem per release" precedent set by v0.10.15 and v0.10.16; three new subdirs in one PR is a noticeable convention drift.
  • Con: property-filter/ under brain/ is awkward because the actual code is search-layer (FTS + chunks), not brain-layer; pulling it under brain/ muddies the layering.
  • Con: VAULT.md is a tiny addition that doesn't deserve its own subsystem; padding it out to atoms/helpers/consumers is ceremony for ~1 file of logic.

Complexity. medium Risk. medium

Variant 3 - In-place enrichment, single small subsystem only for read-views

Approach. Extend existing files directly for the structural plumbing: wikilink.ts keeps anchors instead of stripping them, backlinks.ts learns to resolve aliases when collecting refs, search.ts grows a property-filter post-phase, and the existing session-context loader learns about VAULT.md. Mint one small subsystem src/core/brain/graph-views/ that only contains the higher-level read-only assemblers (unlinked-mentions scanner, concept-synthesis envelope builder, MOC audit classifier) - the things that genuinely need shared helpers and dedicated tests.

Trade-offs.

  • Pro: Smallest blast radius - file count is well under 70, structural changes live next to the code they enrich, no orphan one-file subsystems.
  • Pro: The new subdir holds only the genuinely novel logic (the three "views"), so its scope is crisp and its test directory is well-bounded.
  • Pro: Property filter living inside src/core/search/ matches the actual layer ownership, no awkward cross-tree imports.
  • Con: Diverges from the recent two-release precedent where ALL new helpers landed inside the new subdir; reviewers used to that pattern may need orientation.
  • Con: Atom-level extensions are scattered across wikilink.ts, backlinks.ts, and search.ts rather than visible in one diff stack, so the "what's the v0.10.17 shape change?" question takes more reading.
  • Con: graph-views/ doesn't capture the alias/anchor work in its name, so the release theme is split between "view helpers" and "graph plumbing upgrades."

Complexity. small Risk. low

Recommended: Variant 1

Consultant rationale. It is the only variant that holds the line on the project's established two-release precedent (one named subsystem with the atoms / helpers / consumers DAG), which keeps reviewer mental model, test-directory layout, and CHANGELOG framing identical to v0.10.15 / v0.10.16. The two features that genuinely don't belong under brain/link-graph/ (property search is search-layer, VAULT.md is session-context-layer) land in their natural layers without inventing ceremonial subsystems for them, avoiding Variant 2's drift while still keeping the headline "link-graph subsystem" intact - and unlike Variant 3, the foundational alias/anchor atoms remain visible as part of the new subsystem's shape rather than scattered across pre-existing files.

Orchestrator decision

Accept the consultant's recommendation without override.

The variant aligns with three live constraints not yet captured in the prompt:

  1. The pref-no-hardcoded-languages preference applies to every helper in this bundle; co-locating the helpers under one named subsystem makes the language-agnostic review pass cheaper (one directory to audit, not three).
  2. The CodeRabbit reviewer historically lands more findings when atoms drift across pre-existing files (Variant 3); concentrating them in the new subsystem reduces that surface.
  3. The release-notes excalidraw / PNG (precedent: trust/) renders as three layers (atoms / helpers / consumers). Variants 2 and 3 would require redrawing that layout to two or four bands. Variant 1 reuses the same three-layer template directly.

Property filter remains in src/core/search/property-filter.ts (search-layer, natural ownership). The vault-root instruction file lands in src/core/brain/vault-instruction-file.ts at brain-layer root (it is consumed by brain_context, not by the link-graph subsystem) - not under link-graph/ even though it ships in the same release.