cc-os/docs/adr/0014-graph-connectivity-comes-from-authored-structure-migration-scaffolding-is-a-first-class-prerequisite.md

id	date	status	supersedes	superseded-by	affected-paths	affected-components	migration_confidence	migration_source
0014	2026-06-05	Accepted					medium	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.