Opus Vault

architecture

4 min read

System Architecture

Overview

Opus is a personal AI assistant system that uses Claude Code CLI as its runtime. The system is organized around an Obsidian vault for knowledge management and a feature request workflow for self-improvement.

Components

1. Obsidian Vault (vault/)

The central knowledge base. Stores system docs, feature requests, daily operations, and long-term knowledge. Designed to be opened directly in Obsidian for visual navigation.

2. Claude Code CLI (Runtime)

Claude Code sessions serve as the agent runtime. Each session reads CLAUDE.md for instructions and can autonomously work on features, answer questions, and manage the vault.

3. Feature Request System (vault/10_features/)

A kanban-style workflow for tracking what the system should build next. Feature requests move through: ideas → new → planned → in-progress → review → done. Ideas are vague future braindumps (no FR number). Once concrete enough, they become a feature request in new.

4. Codebase (src/) — Future

Applications and automation. Covers system orchestration, personal tools, and integrations. Structured as a monorepo with shared utilities. Not yet implemented.

5. Skills (.claude/skills/)

Custom slash commands that automate common operations like creating feature requests, generating briefings, checking status, and writing changelogs.

6. Hooks (.claude/hooks/)

Automated scripts triggered by Claude Code events. Configured in .claude/settings.json. No hooks built yet — see FR-011.

7. Agents (.claude/agents/)

Specialized sub-agent definitions for focused, parallel work. Launched via the Task tool. No dedicated agents defined yet — sub-agents are used ad-hoc. See FR-043.

8. Rules (.claude/rules/)

Context-specific instructions loaded based on which files are being worked on. Separate rules for vault operations vs. code operations.

9. MCP Servers (.mcp.json)

External tool integrations that extend Claude’s capabilities. Configured per-project in .mcp.json. None configured yet.

10. Dashboards (vault/00_system/dashboards/)

Tracking files that summarize system state — features, decisions, ideas, reviews, tasks, and capabilities. Updated by Claude after structural changes.

11. Master Instructions (CLAUDE.md)

The central configuration file that governs all Claude behavior. Defines communication style, core behaviors, project structure, and self-improvement policies. Loaded automatically at the start of every session.

12. Templates (vault/_templates/)

Standardized formats for recurring content types — feature requests, proposals, knowledge, ideas, dashboards, designs, docs, logs, extern references, and scratchpads. Enforce consistency across the vault.

13. Git & GitHub

Version control and remote backup. All vault and code changes are tracked via git. GitHub serves as the remote repository for collaboration, backup, and future CI/CD.

14. Auto-Memory (.claude/projects/.../memory/)

Claude’s persistent cross-session memory. Stored outside the vault in the Claude Code config directory. Survives conversation resets and provides continuity between sessions.

15. Knowledge Base (vault/20_knowledge/)

Long-term reference material — technical knowledge, personal insights, domain-specific learnings. Distinct from features (what to build) and inbox (what to process).

16. Inbox (vault/90_inbox/)

Quick capture for unprocessed content. Three entry points:

  • proposals/ — Claude-initiated suggestions, organized in typed subfolders (skills/, agents/, hooks/, features/, code/)
  • drafts/ — Claude-processed user messages (WhatsApp/Telegram) awaiting review before routing
  • quick-notes.md — Direct user captures from Obsidian mobile; processed during inbox review

17. Logs (vault/00_system/logs/)

Historical records of decisions and self-improvement actions. Provides an audit trail for how the system evolved and why certain choices were made.

18. External References (vault/00_system/external/)

Reference documents from outside sources — implementation guides, templates, documentation. Read-only material that informs system design without being part of it.

Design Principles

  • Self-documenting: The system tracks its own evolution via feature requests.
  • Vault-first: All knowledge lives in the Obsidian vault, not in code comments.
  • Incremental: Build only what’s needed now; capture future ideas as feature requests.
  • Autonomous-ready: CLAUDE.md gives enough context for any session to be productive.
  • User-driven: Claude proposes, user reviews and approves. No autonomous action without permission.
  • Self-improving: The system detects recurring patterns and proposes new skills, agents, and rules.
  • Boundary-aware: Opus and the personal vault (Atlas) are separate. No duplication of personal content.

Graph View