ADR-0001: Use Git-backed markdown knowledge base
Context and Problem Statement
RoRo Studio needs a knowledge management system that serves both AI agents (via MCP retrieval) and humans (via Obsidian and web). The system must support structured metadata, full-text and semantic search, version history, and multi-device access.
Decision Drivers
- Agents work in one repo at a time — knowledge must be accessible within a single repository
- Markdown is the universal interchange format every tool reads natively
- Git provides full version history without additional infrastructure
- The existing PostgreSQL instance can handle indexing and search
- Solo developer context: minimize operational overhead
Considered Options
- Git monorepo with markdown + YAML frontmatter
- Dedicated knowledge management platform (Notion, Confluence)
- Database-first approach (structured data in PostgreSQL)
- Wiki system (MediaWiki, GitBook)
Decision Outcome
Chosen option: “Git monorepo with markdown + YAML frontmatter”, because it provides universal tool compatibility, zero additional infrastructure cost, native Obsidian support, and straightforward MCP retrieval via the existing FastMCP server.
Consequences
- Good, because every tool in the stack reads markdown natively
- Good, because Git history provides complete audit trail
- Good, because Obsidian vault format enables rich human editing
- Good, because pgvector + FTS can index the same files for agent retrieval
- Bad, because search requires a separate indexing pipeline (n8n workflow)
- Neutral, because scaling beyond ~500 files may require index optimization
More Information
- Full architecture: roro-knowledge-layer-implementation-architecture-v2.md
- Linear issue: ENG-31