53 lines
3.2 KiB
Markdown
53 lines
3.2 KiB
Markdown
|
---
|
||
|
|
id: "0010"
|
||
|
|
date: 2026-06-03
|
||
|
|
status: Accepted
|
||
|
|
supersedes: "0004, 0005, 0006"
|
||
|
|
superseded-by:
|
||
|
|
affected-paths: []
|
||
|
|
affected-components: []
|
||
|
|
migration_confidence: medium
|
||
|
|
migration_source: "docs/memory-system/03-architecture-decisions.md### ADR-010 — Graphify knowledge graph as the knowledge layer (supersedes ADR-004/005/006)"
|
||
|
|
---
|
||
|
|
|
||
|
|
# 0010 — Graphify knowledge graph as the knowledge layer (supersedes ADR-004/005/006)
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
ADR-004 specced a hand-built Ruby/Sequel/SQLite tag index (+ CLI) as the
|
||
|
|
machine-queryable layer over the vault, with ADR-005/006 deferring meaning-based recall to a
|
||
|
|
future QMD vector layer. Before building any of it, we evaluated **Graphify** (`graphify`,
|
||
|
|
PyPI `graphifyy`) — a tool that turns a folder into a queryable knowledge graph (local
|
||
|
|
tree-sitter AST for code, local-SLM entity/relationship extraction for docs). See
|
||
|
|
`06-graphify-evaluation.md`.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
Use **Graphify as the knowledge-layer engine** over the vault, with a **local
|
||
|
|
Ollama** backend for doc extraction and free AST for per-project code graphs. **Drop** the
|
||
|
|
Ruby/SQLite tag-index CLI (ADR-004) and the earmarked QMD layer (ADR-006); **retain** the
|
||
|
|
`summary` + namespaced-tag frontmatter from ADR-003/004 as note metadata.
|
||
|
|
- **Rationale**: One off-the-shelf tool delivers both what the tag index was for (structured
|
||
|
|
retrieval) and what QMD was deferred for (connection/meaning-based recall via graph
|
||
|
|
traversal + `explain`) — without writing or maintaining a bespoke index, and without a vector
|
||
|
|
store. Code graphs come free. Keeps the markdown-as-truth, no-Docker, no-API-key, local-first
|
||
|
|
properties (extraction runs against local Ollama). Net scope reduction: the entire Ruby build
|
||
|
|
(old critical-path Step 2) and the QMD layer are removed.
|
||
|
|
- **What's retained / changed**: `summary` stays the human-written router hint Graphify does not
|
||
|
|
generate; namespaced tags stay useful for Obsidian filtering and as node attributes. How
|
||
|
|
tightly metadata should feed graph queries is a **build-time refinement**, not settled here.
|
||
|
|
- **Trade-off accepted**: Graphify's `--update` doesn't prune deleted nodes (stale-node drift) —
|
||
|
|
mitigated by a periodic `--force` rebuild on the session-start staleness check (ADR-007's lazy
|
||
|
|
model still applies). Graphify also moves fast (flags are version-dependent; anchored to
|
||
|
|
v0.8.30) and its headline token-savings numbers are corpus-dependent — benchmark our own.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
Graphify becomes the knowledge-layer engine over the vault (local Ollama backend for docs, free tree-sitter AST for code), replacing the planned Ruby/SQLite tag index (ADR-004) and the earmarked QMD semantic layer (ADR-006), while retaining the summary + namespaced-tag frontmatter as note metadata. This reduces the scope of what must be built and maintained, but introduces reliance on Graphify's behavior, including a known trade-off that `--update` doesn't prune deleted nodes (mitigated by periodic `--force` rebuilds) and that its flags/behavior are version-dependent.
|
||
|
|
|
||
|
|
## Alternatives rejected
|
||
|
|
|
||
|
|
Building the Ruby/SQLite index as originally planned (more code to
|
||
|
|
own; no semantic recall); adding QMD as a second system on top (two stores where one graph
|
||
|
|
suffices).
|