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
Link graph surfaces - implementation plan
DAG
A2 (rich wikilink parse) βββ
A1 (BacklinkRef +fields) βββ€
βββ> Unit 1 (parse + atom)
β
H2 (alias-index) ββ> Unit 2
H1 + alias wiring ββ> Unit 3 (BacklinkRef populated)
H3 (unlinked-mentions) ββ> Unit 4
H4 (concept-cluster) ββ> Unit 5
H5 (moc-audit) ββ> Unit 6
H6 (property-filter) ββ> Unit 7
A4 + H7 (vault-instr) ββ> Unit 8
Units 1-3 land sequentially (later units depend on earlier shape). Units 4-8 are siblings and can land in any internal order.
Tasks
Unit 1: Rich wikilink parse + BacklinkRef atom extension
- Files:
src/core/brain/wikilink.ts(modify) - exportparseWikilinkRichsrc/core/brain/link-graph/parse-wikilink.ts(new) - canonical home of the rich-parse logicsrc/core/brain/backlinks.ts(modify) -BacklinkRefgains optionaltargetAnchor?: string,targetBlock?: string,aliasSource?: stringtests/core/brain/link-graph/parse-wikilink.test.ts(new) - covers heading anchor, block anchor, alias, folder,.mdsuffix, and combination casestests/core/brain/backlinks-anchor-alias.test.ts(new) - covers existing-consumer compatibility (legacy shape destructure still works) plus new-field populated cases
- Acceptance:
parseWikilinkRich("[[Note#Heading]]")returns{target: "Note", anchor: "Heading", block: undefined, alias: undefined};parseWikilinkRich("[[Note#^abc]]")returns{..., block: "abc"};parseWikilink("[[Note#Heading]]")still returns"Note".BacklinkRefinstances retain backward compat: code reading only{source, sourceKind, field, timestamp}continues to work. - Depends on: none
Unit 2: Alias index helper
- Files:
src/core/brain/link-graph/alias-index.ts(new) -buildAliasIndex(vault)returning frozenMap<aliasLower, canonicalId>tests/core/brain/link-graph/alias-index.test.ts(new) - frontmatter scanned acrosspreferences/,retired/,inbox/,processed/; collisions resolved first-wins; case-insensitive; NFC normalised
- Acceptance: Three notes, two declaring overlapping
aliases: [foo], the alphabetically-first wins; lookup is case-insensitive; result isObject.isFrozen. - Depends on: none
Unit 3: buildBacklinkIndex populates anchor + alias-source
- Files:
src/core/brain/backlinks.ts(modify) - rewrite collectors to push the rich parse and consult the alias indextests/core/brain/backlinks-anchor-alias.test.ts(extend) - new cases asserttargetAnchor,targetBlock,aliasSourceare populated when applicable
- Acceptance: A signal referencing
[[FullName#Section]]produces aBacklinkRefwithtargetAnchor: "Section". A signal referencing[[fooAlias]]where notebar.mddeclaresaliases: [fooAlias]produces a ref keyed on"bar"withaliasSource: "fooAlias". - Depends on: Unit 1, Unit 2
Unit 4: Unlinked-mentions helper + MCP + CLI
- Files:
src/core/brain/link-graph/unlinked-mentions.ts(new) -findUnlinkedMentions(vault, targetId, opts)returning frozenReadonlyArray<MentionRef>src/mcp/brain-tools.ts(modify) - registerbrain_unlinked_mentionsin full scopesrc/cli/brain/verbs/unlinked.ts(new) -runUnlinked(args)src/cli/brain/verbs/index.ts+src/cli/brain/help-text.ts+src/cli/brain.ts(modify) - dispatch + helptests/core/brain/link-graph/unlinked-mentions.test.ts(new) - confirms[[...]]exclusion, alias expansion, multi-line context, codepoint-aware word boundariestests/cli/brain-unlinked-cli.test.ts(new)tests/mcp/link-graph-mcp-fields.test.ts(new) - covers tool registration, JSON-RPC round trip,INVALID_PARAMSfor malformed input
- Acceptance: Given a target
Notewith frontmatteraliases: [downstream], and a sibling note containing the prose"the downstream effect of Note here", the scanner yields twoMentionRefrows (one per match). A reference[[Note]]in the same sibling does NOT produce a mention. Tool registered infullscope only. - Depends on: Unit 2
Unit 5: Concept-cluster helper + MCP + CLI
- Files:
src/core/brain/link-graph/concept-cluster.ts(new) -buildConceptCluster(vault, targetId, opts)returning a frozen envelope{target, linkers, unlinkedMentions, generatedAt}src/mcp/brain-tools.ts(modify) - registerbrain_concept_synthesisin full scopesrc/cli/brain/verbs/synthesise.ts(new)src/cli/brain.ts+src/cli/brain/verbs/index.ts+src/cli/brain/help-text.ts(modify)tests/core/brain/link-graph/concept-cluster.test.ts(new) - envelope shape, frozen guarantees,include_unlinkedflag toggles inclusiontests/cli/brain-synthesise-cli.test.ts(new)tests/mcp/link-graph-mcp-fields.test.ts(extend) - covers concept-synthesis registration + JSON-RPC
- Acceptance: For a target
Notewith two linkers (pref-abody contains[[Note]],pref-bevidenced_by[[Note]]), envelope reports both linkers with theirsourceKind+field. Wheninclude_unlinked: true, envelope also contains the unlinked-mention rows. Helper does NOT make an LLM call. - Depends on: Unit 3, Unit 4
Unit 6: Per-MOC audit helper + MCP + CLI
- Files:
src/core/brain/link-graph/moc-audit.ts(new) -auditMoc(vault, hubId, opts)returning{wellCovered, fragile, candidateMissing, suggestedNext}src/core/brain/policy.ts(modify) - addlink_graph.moc_min_outbound_links(default 5) andlink_graph.moc_min_link_ratio(default 0.3) config slotssrc/mcp/brain-tools.ts(modify) - registerbrain_moc_auditin full scopesrc/cli/brain/verbs/moc-audit.ts(new)src/cli/brain.ts+src/cli/brain/verbs/index.ts+src/cli/brain/help-text.ts(modify)tests/core/brain/link-graph/moc-audit.test.ts(new) - heuristic threshold behaviour, bucket assignment, suggestedNext deterministic orderingtests/cli/brain-moc-audit-cli.test.ts(new)tests/mcp/link-graph-mcp-fields.test.ts(extend) - covers moc-audit registration + JSON-RPC
- Acceptance: A hub note with 6 outbound links and link-ratio 0.5 qualifies as MOC; one linker with body-length above the well-covered floor + 3 inbound backlinks β
wellCovered; one linker with 1 backlink and short body βfragile. MOC detection rejects a note with 4 outbound links (below the default threshold) regardless of title. - Depends on: Unit 1 (rich parse for outbound-link enumeration)
Unit 7: Property-filter helper + search wiring + MCP + CLI flag
- Files:
src/core/search/property-filter.ts(new) -filterByProperties(results, filters, frontmatterReader); multi-value within a key = OR, multiple keys = ANDsrc/core/search/types.ts(modify) -SearchOptions.properties?: ReadonlyMap<string, ReadonlyArray<string>>(or equivalent shape)src/core/search/search.ts(modify) - wire post-FTS phase whenopts.propertiessetsrc/mcp/search-tools.ts(modify) - extendbrain_searchschema + handler to accept apropertiesargumentsrc/cli/search.ts(modify) - repeated--property KEY=VALUEflag ono2b search "<query>"tests/core/search/property-filter.test.ts(new) - covers AND/OR logic, missing-key behaviour, malformed-filter rejectiontests/cli/search-property-cli.test.ts(new)
- Acceptance:
search({query: "foo", properties: new Map([["type", ["decision"]]]))returns only chunks whose source frontmatter hastype: decision. Multi-value filter ontagsincludes any chunk whosetagsarray intersects the requested set. Absentpropertiesβ identical to existingsearch()output (verified by snapshot). - Depends on: none (parallel to other units)
Unit 8: Vault-root instruction file reader + brain_context envelope extension
- Files:
src/core/brain/vault-instruction-file.ts(new) -readVaultInstructionFile(vault, name)src/core/brain/policy.ts(modify) - addvault_instruction_fileconfig (defaultVAULT.md)src/mcp/brain-tools.ts(modify) - extendbrain_contextenvelope with optionalvault_instructionfieldtests/core/brain/vault-instruction-file.test.ts(new) - reads default name, configurable name, absent file β null, oversized file warning, vault-relative path emissiontests/mcp/brain-context-vault-instruction.test.ts(new) - covers envelope extension + absent-file = field omitted
- Acceptance:
<vault>/VAULT.mdcontaining# My vaultβreadVaultInstructionFilereturns{content: "# My vault", path: "VAULT.md", lines: 1}. Configurable rename via_brain.yamlβvault_instruction_file: GUIDE.mdreads<vault>/GUIDE.md. Absent file β returnsnull; envelope omits the field. - Depends on: none (parallel to other units)
Cross-cutting items (land alongside the final unit)
src/mcp/instructions.ts- inventory bump.src/mcp/tools.ts- add the three full-scope tool names to the table.README.md- one new capability paragraph + tool-count bump.CHANGELOG.md- one new[0.10.17]entry under a concrete header.- Version manifests bump (one commit in Phase 6, not during implementation).
.ai-notes/images/v0.10.17-link-graph.{excalidraw,png}- release diagram.
Verification artifacts
- Each unit's tests must pass in isolation (
bun test tests/core/brain/link-graph/<file>.test.ts). - Full suite must pass at the end of every unit's commit (
bun test). bun run typecheckclean at every commit boundary.bun run sync-version:checkruns only after Phase 6 version bump.