---
id: "0003"
date: 2026-06-03
status: Accepted
supersedes:
superseded-by:
affected-paths: []
affected-components: []
migration_confidence: medium
migration_source: "docs/memory-system/03-architecture-decisions.md### ADR-003 — Flat vault with namespaced tags, not folders"
---

# 0003 — Flat vault with namespaced tags, not folders

## Context

Connelly/Huryn organize by folders (`tools/`, `domain/`). User wants a flat
  Obsidian vault with tags as virtual indexes, and cross-cutting filters (client × tool ×
  convention).

## Decision

One **flat markdown vault**; organize via **namespaced, nested tags**
  (`tool/`, `client/`, `domain/`, `convention/`, `scope/`). Slashes are valid Obsidian nested
  tags, so `#tool` matches all children.
- **Rationale**: A note can carry several namespaces at once (`tool/semrush` +
  `client/sesame3g` + `convention/react-ts`) — folders can't express that. Enables "filter by
  client+tool to narrow the index." Enumerable virtual indexes ("what clients/tools exist").

## Consequences

The vault is organized as a single flat markdown store using namespaced, nested tags (tool/, client/, domain/, convention/, scope/) instead of folders, enabling a note to belong to multiple cross-cutting categories at once and supporting enumerable virtual indexes. The trade-off accepted is that while tags give humans/Obsidian free filtering, the AI gets nothing for free from tags alone — they must be materialized into a queryable index (addressed in ADR-004/010).

## Alternatives rejected

Folder hierarchy (single-axis; can't do cross-cutting filters).
  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).
