77 lines
5.1 KiB
Markdown
77 lines
5.1 KiB
Markdown
---
|
|
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.
|