From f73cb46a532cb171884c54373e2910fd53355048 Mon Sep 17 00:00:00 2001 From: jared Date: Thu, 4 Jun 2026 09:35:38 -0400 Subject: [PATCH] ADR-011: Faceted tag taxonomy; ADR-012: reuse SecondBrain vault MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lock two design decisions: (1) six independent namespaced tag facets (type/client/project/domain/tool/convention/) plus scope/, with hierarchy expressed via hub notes and Graphify edges, not nested paths; (2) adopt the existing ~/Documents/SecondBrain vault as the knowledge layer rather than creating a new one — it is already flat, governs to the correct semantics, and contains useful patterns (proactive-query spec, tag-inference table). See ADR-011 and ADR-012 for rationale, rejected alternatives, and migration cost (mechanical schema updates on existing ~20 notes). --- .../03-architecture-decisions.md | 82 ++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/docs/memory-system/03-architecture-decisions.md b/docs/memory-system/03-architecture-decisions.md index f5eb57e..5f9e084 100644 --- a/docs/memory-system/03-architecture-decisions.md +++ b/docs/memory-system/03-architecture-decisions.md @@ -47,7 +47,8 @@ Alternatives rejected · Status. Newest decisions extend the log; supersede rath Pure-prefix path filtering via memsearch `source_prefix` (would force directories back in). - **Trade-off accepted**: Tags give the *human/Obsidian* free filtering, but the *AI* gets nothing for free from tags — we must materialize them into a queryable index (see ADR-004). -- **Status**: Accepted. +- **Status**: **Refined by ADR-011** (type/ and project/ namespaces added; hierarchy-vs-facets + clarified). Core decision — flat vault, namespaced tags — stands. ## ADR-004 — SQLite + Sequel (Ruby) tag index as the knowledge-layer cache @@ -176,6 +177,85 @@ Alternatives rejected · Status. Newest decisions extend the log; supersede rath suffices). - **Status**: Accepted (to be built — see 04-build-plan.md and 06-graphify-evaluation.md). +## ADR-011 — Faceted tag taxonomy: six independent namespaces (refines ADR-003) + +_Date: 2026-06-04_ + +- **Context**: ADR-003 introduced five namespaces (`tool/`, `client/`, `domain/`, + `convention/`, `scope/`). During vault-reuse assessment (ADR-012) it became clear that (1) + the existing SecondBrain vault uses a de-facto first-tag convention for note kind + (research/plan/log/adr/howto) that should be made explicit and machine-queryable, and (2) + for a freelancer working many projects per client, project identity deserves a first-class + namespace rather than being implied by `client/` or `domain/`. +- **Decision**: Knowledge-vault notes are classified by **six independent, flat tag facets** + that sit side-by-side, never nested into one another: + - `type/` — note kind: `research`, `howto`, `adr`, `hub`, `plan`, `log`, `clip`, etc. + - `client/` — which client + - `project/` — which project (first-class; a freelancer's projects are the primary unit of + work) + - `domain/` — knowledge domain / topic area + - `tool/` — tool-specific knowledge + - `convention/` — conventions + - …plus `scope/global` or `scope/project` (retained from ADR-003) + + Hierarchy and relationships are expressed via **hub notes** (`type/hub`), **wikilinks**, and + **Graphify knowledge-graph edges** — NOT via nested tag paths. + + By convention `type/` is listed **first** in frontmatter, preserving the SecondBrain vault's + existing type-first ordering habit and making the note kind immediately visible. +- **Rationale**: The vault is flat — hierarchy is not expressed through folder paths or tag + nesting. The user's reality is many-to-many (many projects per client, knowledge domains + spanning clients), which a single-parent tree models badly and forces false hierarchy. A + project hub note links out to both its `client/` and relevant `domain/` tags rather than + being buried under either. Per-type `_templates` will be provided for **core types only** + (research, howto, adr, hub); the long tail stays freeform until a pattern earns a template. + Consistent per-type structure also improves Graphify's local-SLM extraction reliability. +- **Alternatives rejected**: Hierarchical nesting in the style of John Conneely's + `domain/{product}/{project}.md` folder structure (from the youngleaders.tech article "How I + finally sorted my Claude Code memory" — **secondary/interview-grade source, not verified + against primary implementation**). Rejected because: (1) the vault is flat — hierarchy is + not expressed through folder paths; (2) the user's many-to-many reality maps badly onto a + single-parent folder tree and forces false hierarchy; (3) nesting one facet through another + (e.g. `domain/client/project`) creates Law-of-Demeter-style traversal coupling. Conneely's + structure was the inspiration but diverges here on hierarchy-vs-facets. Faceted parallel tags + are the flat-vault analogue of what the Graphify graph already does with edges, so they + compose naturally with the chosen knowledge layer. +- **Status**: Accepted (supersedes the namespace list in ADR-003; core flat-vault + + namespaced-tags decision stands). + +## ADR-012 — Reuse the existing SecondBrain vault as the knowledge vault + +_Date: 2026-06-04_ + +- **Context**: The design called for a flat markdown vault as the semantic knowledge layer + (ADR-003/008/010). The question was whether to stand up a new `~/brain` vault from scratch + or adopt the existing `~/Documents/SecondBrain` vault. +- **Decision**: **Adopt `~/Documents/SecondBrain`** as the knowledge vault rather than + creating a new vault. +- **Rationale**: Assessment found the SecondBrain vault is already flat (all notes at root, + only a `_templates/` exception — exactly what the design permits), already articulates the + correct "durable knowledge, not working memory" role in its `CLAUDE.md` and + `vault-conventions.md`, and contains ~20 real notes. It also includes two patterns that + **improve on the current design** and should be adopted: + 1. `vault-conventions.md`'s "act without being asked" section specifying *when* the AI + should proactively query the vault — a behavioral spec the cc-os docs lacked. + 2. Project-config hub notes with a tag-inference table (auto-tag by path pattern) that + operationalizes *how* to tag a note from a given project. +- **Adaptations required (migration cost)**: + - Add `summary:` frontmatter to existing notes. + - Migrate flat unnamespaced tags to the six-facet namespaced form (per ADR-011). + - Add `scope/global` or `scope/project` to each note. + - Initialize git in the vault (no `.git` exists yet — required by ADR-008's sync strategy). + - Replace the vault's `~/.claude/scripts/vault_search.rb` reference (script does not exist) + with `graphify query` (ADR-010). + These are mechanical schema migrations, not structural rework. +- **Alternatives rejected**: Starting fresh with a new `~/brain` vault. Rejected because the + hardest design decision — flat structure, durable-knowledge-only role, governance philosophy + — is already made and practiced in SecondBrain. The improved behavioral patterns + (proactive-query spec, tag-inference table) and the existing notes are worth preserving; the + remaining work is mechanical migration. +- **Status**: Accepted. + ## Rejected tools (summary) | Tool | Why rejected for our use |