cc-os/docs/adr/0012-reuse-the-existing-secondbrain-vault-as-the-knowledge-vault.md

id	date	status	supersedes	superseded-by	affected-paths	affected-components	migration_confidence	migration_source
0012	2026-06-04	Accepted					medium	docs/memory-system/03-architecture-decisions.md### ADR-012 — Reuse the existing SecondBrain vault as the knowledge vault

0012 — Reuse the existing SecondBrain vault as the knowledge vault

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.

Consequences

The existing ~/Documents/SecondBrain vault is adopted as the knowledge vault instead of creating a new one, since it was already flat and already articulated the correct durable-knowledge role, and it contributes two design improvements (proactive-query behavior spec and a project-config tag-inference table) to be adopted. This requires mechanical migration work: adding summary frontmatter, migrating tags to the six-facet form, adding scope tags, initializing git, and replacing a nonexistent script reference with graphify query.

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.