Architecture

Understanding the two-tier vault system and how ContextVault works under the hood.

Two-Tier Vault System

ContextVault uses a two-tier architecture to separate reusable cross-project knowledge from project-specific documentation.

┌─────────────────────────────────────────────────────────────────┐
│                   TWO-TIER CONTEXTVAULT SYSTEM                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   TIER 1: GLOBAL (~/.claude/vault/)                            │
│   ├── Cross-project knowledge                                   │
│   ├── Patterns, best practices, tools                          │
│   ├── Reusable learnings                                        │
│   └── Available in ALL projects                                 │
│                                                                 │
│   TIER 2: PROJECT (./.claude/vault/)                           │
│   ├── Project-specific knowledge                                │
│   ├── This codebase's architecture, configs                    │
│   ├── Local decisions and implementations                       │
│   └── Only relevant to THIS project                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Why Two Tiers?

Separation of Concerns — Project docs don't pollute global knowledge
Reusability — Patterns learned once apply everywhere
Context Efficiency — Only load relevant docs per project
Team Collaboration — Project vault can be committed to git

Folder Structure

~/.claude/                          # GLOBAL (all projects)
├── CLAUDE.md                       # Global instructions for Claude
├── commands/                       # 25 slash command definitions
│   ├── ctx-init.md
│   ├── ctx-doc.md
│   ├── ctx-error.md
│   └── ... (22 more)
├── settings.json                   # Hooks and global settings
└── vault/
    ├── index.md                    # Global knowledge index
    ├── settings.json               # Vault mode settings
    ├── _template.md                # Template for new docs
    ├── G001_topic.md               # Global docs (G prefix)
    └── archive/                    # Deprecated global docs

./.claude/                          # PROJECT-SPECIFIC (per project)
└── vault/
    ├── index.md                    # Project knowledge index
    ├── P001_architecture.md        # Project docs (P prefix)
    ├── P002_feature.md
    └── archive/                    # Deprecated project docs

Document Naming Convention

Documents use prefixes to indicate their scope and ensure unique identification.

Prefix	Meaning	Location	Example
`G###`	Global knowledge	`~/.claude/vault/`	`G001_docker_patterns.md`
`P###`	Project knowledge	`./.claude/vault/`	`P001_auth_system.md`

Auto-Incrementing IDs

When you create a document, ContextVault automatically assigns the next available ID. You never need to manage IDs manually.

The Index System

Each vault has an index.md file that catalogs all documents. This is the key to efficient context loading.

How It Works

At session start, Claude reads the index files (not all docs)
The index contains: ID, title, summary, and related terms
Claude uses the index to find relevant docs when needed
Only then does it load the specific document

Index Structure

# ContextVault Index

| ID | Title | Summary | Updated |
|----|-------|---------|---------|
| P001 | Architecture | Tech stack and project structure | 2026-01-15 |
| P002 | Auth System | JWT-based authentication flow | 2026-01-18 |
| P003 | API Endpoints | REST API route documentation | 2026-01-20 |

## Related Terms
- authentication, login, signin → P002
- routes, endpoints, api → P003

Core Rules for Indexes

Always Read First — Read indexes at session start
Always Update — Update index after any doc change
Keep Summaries Short — Max 15 words per summary
Max 50 Entries — Per vault to keep context manageable

Smart Hooks System

ContextVault uses Claude Code hooks to provide automatic reminders and enforce documentation habits.

Hook Types

Hook	Trigger	Purpose
`SessionStart`	New session begins	Shows vault status, reminds to read indexes
`PreToolUse`	Before file edits	Tracks edits, suggests documentation after significant work
`Stop`	Session ends	Blocks exit if significant undocumented work detected

How Enforcement Works

The PreToolUse hook tracks file edits during a session. Based on your enforcement level:

Light — Only the Stop hook reminds at session end
Balanced — Reminder after 8+ edits across 2+ files
Strict — Reminder after 4+ edits across 2+ files

Non-Blocking Reminders

v1.8+ uses "remind, don't block" philosophy. Hooks suggest documentation but don't prevent your work (except at session end with significant changes).

Document Lifecycle

┌─────────────────────────────────────────────────────────────────┐
│                    DOCUMENT LIFECYCLE                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. SEARCH                                                     │
│      └─→ Check both indexes for existing docs                   │
│                                                                 │
│   2. DECIDE                                                     │
│      ├─→ Doc exists? UPDATE it                                  │
│      └─→ No doc? CREATE new one                                 │
│                                                                 │
│   3. ROUTE (if creating)                                        │
│      ├─→ Reusable? → Global vault (G###)                        │
│      └─→ Project-only? → Project vault (P###)                   │
│                                                                 │
│   4. WRITE                                                      │
│      └─→ Follow template, max 100 lines                         │
│                                                                 │
│   5. INDEX                                                      │
│      └─→ Update index.md immediately                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Routing Decision Tree

When creating a new document, ask: "Would this help in OTHER projects?"

If the knowledge is...	Route to...	Example
General pattern, reusable	Global `G###`	Docker best practices
Tool/tech best practice	Global `G###`	Git workflow tips
Code snippet for reuse	Global `G###`	Auth middleware pattern
Project architecture	Project `P###`	This app's folder structure
Project-specific config	Project `P###`	Environment variables
Local bug fix	Project `P###`	Fix for this codebase

Context Loading Strategy

ContextVault minimizes token usage by loading only what's needed:

Session Start:
  1. Read ~/.claude/vault/index.md (global index)
  2. Read ./.claude/vault/index.md (project index)
  3. Done! (No documents loaded yet)

When Working:
  4. Need info on auth? → Load P002_auth.md
  5. Done with auth → Context contains: 2 indexes + 1 doc

Maximum Context:
  - 2 index files
  - 1 document at a time
  - Never load "just in case"