cc-os/docs/adr/0010-graphify-knowledge-graph-as-the-knowledge-layer-supersedes-adr-004-005-006.md

id	date	status	supersedes	superseded-by	affected-paths	affected-components	migration_confidence	migration_source
0010	2026-06-03	Accepted	0004, 0005, 0006				medium	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).