---
id: "0014"
date: 2026-06-05
status: Accepted
supersedes:
superseded-by:
affected-paths: []
affected-components: []
migration_confidence: medium
migration_source: "docs/memory-system/03-architecture-decisions.md### ADR-014 — Graph connectivity comes from authored structure; migration scaffolding is a first-class prerequisite"
---

# 0014 — Graph connectivity comes from authored structure; migration scaffolding is a first-class prerequisite

## Context

ADR-011 specified hub notes + wikilinks + Graphify graph edges as the mechanism
  for expressing hierarchy and cross-note relationships, with ADR-013 deferring bulk vault
  migration to the final stage. Before build began, a discriminating empirical test compared a
  cached-replay graph (per-fixture isolated extractions) against a clean single-pass deep
  extraction (`graphify extract ~/Documents/SecondBrain --backend ollama --model
  qwen25-coder-7b-16k --max-concurrency 1 --token-budget 8000 --mode deep --exclude
  .obsidian`) against the real `~/Documents/SecondBrain` vault under Graphify 0.8.31 +
  qwen2.5-coder:7b. See `07-graph-connectivity-findings.md` for the full data and methodology.
  [primary/measured — 2026-06-05 session]

## Decision

**The connective spine of the knowledge graph must be author-provided.** Hub
  notes and wikilinks are not optional scaffolding to add "someday" — they are the mechanism
  by which Graphify connects thematically related notes, and they must be authored **as part of
  the migration step**, not deferred to bulk import. Migration scaffolding (hub notes +
  wikilinks for key concepts) is treated as a **first-class build deliverable** in the
  migrate-incrementally phase of ADR-013.
- **Rationale**: The empirical test found that Graphify is a **structure extractor, not a topic
  clusterer**. Even at `--mode deep --token-budget 8000`, no emergent shared-topic hub nodes
  appeared (no "Pest Control" node, no "Niche Prospecting" node). All cross-note edges observed
  came from explicit references, wikilinks, or document-level semantic similarity — not from
  shared thematic identity. A practical test query ("how do we do niche prospecting outreach for
  pest control?") returned 3 starting notes and traversal could not reach the email templates /
  ACV data / business-model notes (separate communities, no connecting edges). This confirms
  that useful retrieval is gated on migration scaffolding, not on Graphify's extraction power.
  The clean single-pass run also showed the cached graph was partially a build artifact (cross-
  note edges rose from 41% to 78% in a single-pass run), but the structural finding — no
  emergent hub nodes — held in both runs.
- **Relationship to ADR-011**: Validates the hub-notes + wikilinks half of ADR-011 empirically.
  The facet-tag half is **not yet validated**: no edge was observed to arise from shared
  frontmatter facet tags alone. Whether `client/X` or `tool/Y` tags create graph connectivity
  is an **open question** — see "Deferred" below. Do not assume facet tags contribute to graph
  traversal retrieval until tested.
- **Relationship to ADR-013**: Refines the migrate-incrementally stage. "Migration" must be
  defined to include hub note authoring and wikilink addition for key concepts, not just
  frontmatter schema migration (adding `summary:` and namespaced facet tags). The build plan
  (`04-build-plan.md`) should be updated to name this deliverable explicitly.

## Consequences

Empirical testing showed Graphify is a structure extractor, not a topic clusterer — no emergent shared-topic hub nodes appeared even in deep-mode extraction — so hub notes and wikilinks must be author-provided and are now treated as a first-class migration deliverable rather than optional scaffolding added later. This refines ADR-013's migrate-incrementally stage to explicitly include hub-note authoring and wikilinking, while leaving open whether shared frontmatter facet tags alone contribute to graph connectivity.

## Alternatives rejected

Relying on the SLM to auto-cluster topics and synthesize hub
  entities — **empirically does not happen** at 7B model size with `--mode deep`. The design
  already intended human-authored hub notes for this; the test confirms that intent was correct
  and the fallback assumption ("maybe the LLM will do it") is false.
- **Deferred**:
  1. **Facet-tag-to-graph-edge question**: Do shared frontmatter facet tags (`client/`,
     `tool/`, `domain/`, etc.) cause Graphify to create edges between notes, or does graph
     connectivity come only from explicit wikilinks/references and semantic similarity? This was
     NOT tested. Resolve before designing graph-traversal retrieval skills.
  2. **Larger extraction model**: Whether a substantially larger SLM (14B, 30B) would
     synthesize emergent topic-hub nodes is untested. Secondary — the design does not depend on
     it — but worth one test run before the build ships.
  3. **`reasoning_effort:"none"` patch**: The clean run required a local patch to `graphify/
     llm.py`. Track the upstream Graphify issue tracker for an official fix; treat the
     installed version as pinned until resolved.