======================================== [Thu Mar 5 17:27:03 AEDT 2026] CC VPS triggered by Rivet ======================================== Task: Analyze and report for Builder/Rocky: (1) How Claude Code works in our current system architecture (local + CCVPS + bridges + repos), (2) how Claude Code memory works right now by default (session context, file context, persistence limits), (3) best-practice memory architecture options for us including Obsidian-based approach, repo-based memory, DB-based memory, and hybrid model, (4) concrete recommended SOP for our team (Rocky product lead, Builder senior dev reviewer, Claude Code executor), and (5) immediate implementation checklist for next 48h. Return concise markdown with sections and actionable steps. ---------------------------------------- # Claude Code Architecture & Memory Strategy Report ## 1. Current System Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Local Development (Builder/Rocky) │ │ └─ Claude Desktop/Web → Interactive sessions │ │ └─ Manual memory management via notes/docs │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ CCVPS (VPS Server) - /home/ccuser/ │ │ ├─ the-50-dollar-app/ (read-only root-owned repo) │ │ ├─ workdir/ (writable clone for changes) │ │ ├─ rateright-growth/ (growth/ops repo) │ │ ├─ .claude/projects/-home-ccuser-the-50-dollar-app/ │ │ │ └─ memory/MEMORY.md (auto memory, <200 lines) │ │ └─ Bridge scripts: │ │ └─ rivet-action (receives actions from Rivet) │ │ └─ ccvps-bridge (executes & reports back) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Remote Resources │ │ ├─ GitHub repos (requires manual push from CCVPS) │ │ ├─ Supabase DB (eciepjpcyfurbkfzekok) │ │ └─ Production Vercel deployments │ └─────────────────────────────────────────────────────────────┘ ``` **Current Limitations:** - CCVPS has no GitHub push credentials → manual git operations fail - Root-owned main repo → requires workdir workaround - Memory isolated per project directory - No shared knowledge base between local and CCVPS sessions ## 2. Claude Code Memory System (Current State) ### Active Memory Layers 1. **Session Context**: Full conversation history until compression kicks in (~200k tokens) 2. **Auto Memory**: `/home/ccuser/.claude/projects/-home-ccuser-the-50-dollar-app/memory/MEMORY.md` - Loaded into every session system prompt - **Hard limit: 200 lines** (truncated after) - Persists across sessions, same project - User must manually write/edit with Write/Edit tools 3. **File Context**: - `CLAUDE.md` in repo root (project instructions) - `.cc-local/MEMORY.md` (checked for project-specific memory) 4. **Session Logs**: `*.jsonl` files for search (slow, last resort) ### Memory Persistence Gaps - ❌ No cross-project memory sharing - ❌ No automatic knowledge extraction from sessions - ❌ 200-line limit forces aggressive pruning - ❌ No structured knowledge graph - ❌ Topic files referenced in MEMORY.md but rarely used in practice - ✅ Good: MEMORY.md loaded automatically - ✅ Good: Write/Edit tools work for updates ## 3. Best-Practice Memory Architecture Options ### Option A: Obsidian-Based Knowledge System ⭐ **RECOMMENDED** ``` /home/ccuser/rateright-knowledge/ (Obsidian vault) ├─ 00-INDEX.md (required reading, <200 lines) ├─ Architecture/ │ ├─ system-overview.md │ ├─ database-schema.md │ └─ api-routes.md ├─ Conventions/ │ ├─ code-style.md │ ├─ git-workflow.md │ └─ deployment-process.md ├─ Decisions/ │ ├─ 2026-03-01-auth-flow.md │ ├─ 2026-03-05-memory-strategy.md │ └─ ADR-template.md ├─ Issues/ │ ├─ known-bugs.md │ └─ tech-debt.md └─ SOPs/ ├─ ccvps-workflow.md ├─ release-checklist.md └─ security-audit-process.md ``` **Pros:** - Human-readable markdown, version-controlled - Bidirectional links between decisions/code - Builder/Rocky can edit locally, sync via git - Claude Code can grep/read specific topics - Scales to 1000+ documents **Cons:** - Requires discipline to maintain - Claude must be instructed which files to read ### Option B: Repo-Based Memory (Current Hybrid) ``` /home/ccuser/the-50-dollar-app/ ├─ CLAUDE.md (project config) ├─ .cc-local/MEMORY.md (ephemeral notes) ├─ docs/ │ ├─ architecture.md │ └─ decisions/ADR-001-*.md ``` **Pros:** - Already in repo, travels with code - Natural for code-adjacent docs **Cons:** - Mixes code and operational knowledge - Gets bloated over time - Harder to share across projects (RateRight has 2+ repos) ### Option C: Supabase Table (Structured Memory) ```sql CREATE TABLE claude_memory ( id uuid PRIMARY KEY, category text, -- 'architecture', 'decision', 'bug', 'sop' topic text, content text, tags text[], created_at timestamptz, updated_at timestamptz ); ``` **Pros:** - Queryable, searchable - Can power in-app docs/wiki later - Programmatic updates **Cons:** - Harder for humans to browse/edit - Requires tooling/UI layer - Overkill for current team size (2 people) ### Option D: Hybrid (Obsidian + Repo) - **Obsidian vault** for cross-cutting knowledge (architecture, SOPs, decisions) - **Repo docs/** for code-specific docs (API references, component guides) - **MEMORY.md** as a cached index pointing to both ## 4. Recommended SOP for Team ### Roles & Responsibilities #### Rocky (Product Lead) - **Memory writes:** Product decisions, feature specs, user research - **Location:** Obsidian `Decisions/` and `Features/` - **Tool:** Obsidian desktop app (synced via git or Obsidian Sync) - **Before starting work:** Update `00-INDEX.md` with new priorities - **After decisions:** Create ADR (Architecture Decision Record) in `Decisions/YYYY-MM-DD-topic.md` #### Builder (Senior Dev Reviewer) - **Memory writes:** Code patterns, architecture choices, security reviews - **Location:** Obsidian `Architecture/`, `Conventions/`, `SOPs/` - **Tool:** Obsidian or text editor + git - **Before code review:** Check `Issues/known-bugs.md` and `Issues/tech-debt.md` - **After review:** Update conventions if new patterns emerge #### Claude Code (Executor via CCVPS) - **Memory reads:** 1. Load `00-INDEX.md` (auto-included in system prompt) 2. Grep relevant topic files based on task 3. Read CLAUDE.md (auto-loaded) 4. Check MEMORY.md (auto-loaded) - **Memory writes:** 1. Update `Issues/known-bugs.md` when discovering bugs 2. Update `Issues/tech-debt.md` when adding TODOs 3. Append to `00-INDEX.md` for significant discoveries (keep <200 lines) 4. Suggest new ADRs for Builder/Rocky approval - **Tool:** Write/Edit tools, instructed to check memory before starting ### Workflow Example: New Feature Request ``` 1. Rocky creates Decisions/2026-03-06-contractor-ratings.md └─ Includes: Why, What, Success criteria 2. Rocky updates 00-INDEX.md: ## Current Priorities - [ ] Contractor ratings system (see Decisions/2026-03-06) 3. Builder reviews decision, adds technical notes: └─ Architecture/ratings-implementation.md └─ Links to DB schema, API design 4. Rocky invokes CCVPS via Rivet: "Implement contractor ratings per 2026-03-06 decision" 5. Claude Code (on CCVPS): - Reads 00-INDEX.md (sees priority) - Reads Decisions/2026-03-06-contractor-ratings.md - Reads Architecture/ratings-implementation.md - Implements feature - Updates Issues/tech-debt.md with "TODO: Add bulk rating import" - Commits, builds, reports back 6. Builder reviews PR: - Checks against Architecture/ratings-implementation.md - Updates Conventions/code-style.md if new pattern used ``` ## 5. Immediate Implementation Checklist (Next 48h) ### Day 1 (Next 24h) - [ ] **Create Obsidian vault** at `/home/ccuser/rateright-knowledge/` ```bash mkdir -p /home/ccuser/rateright-knowledge/{Architecture,Conventions,Decisions,Issues,SOPs,Features} ``` - [ ] **Migrate existing MEMORY.md** to structured format - Extract "Environment Notes" → `Architecture/ccvps-setup.md` - Extract "Key Architecture" → `Architecture/system-overview.md` - Extract "Completed Audit Fixes" → `Issues/audit-2026-03-completed.md` - [ ] **Create 00-INDEX.md** (the <200 line master index) ```markdown # RateRight Knowledge Index Last updated: 2026-03-05 ## Start Here - Architecture/system-overview.md - Tech stack, repos, deployment - SOPs/ccvps-workflow.md - How to work with CCVPS bridge ## Current Priorities - [ ] [Priority from Rocky] ## Quick Links - Repo: /home/ccuser/the-50-dollar-app - Supabase: eciepjpcyfurbkfzekok - Conventions: Conventions/code-style.md ``` - [ ] **Update CLAUDE.md** to reference knowledge vault ```markdown ## Knowledge Base Check `/home/ccuser/rateright-knowledge/00-INDEX.md` before starting work. For specific topics, grep the vault: `Grep pattern="topic" path="/home/ccuser/rateright-knowledge/"` ``` - [ ] **Create SOPs/ccvps-workflow.md** - Document Rivet → rivet-action → ccvps-bridge flow - Document git workflow (no push, workdir clone) - Document environment vars setup ### Day 2 (24-48h) - [ ] **Setup git repo for knowledge vault** ```bash cd /home/ccuser/rateright-knowledge git init git remote add origin [private-repo-url] git add . git commit -m "Initial knowledge base structure" ``` - [ ] **Builder: Create architecture docs** - [ ] `Architecture/database-schema.md` (11 tables, RLS policies) - [ ] `Architecture/api-routes.md` (4 current routes) - [ ] `Architecture/auth-flow.md` (Supabase Auth, verify-email) - [ ] **Rocky: Document product decisions** - [ ] `Decisions/2026-03-XX-mvp-scope.md` (what's in, what's out) - [ ] `Features/contractor-signup.md` (AI research flow) - [ ] `Features/worker-signup.md` (5 questions) - [ ] **Create ADR template** ```markdown # ADR-XXX: [Title] Date: YYYY-MM-DD Status: [Proposed/Accepted/Deprecated] Deciders: [Rocky/Builder/Both] ## Context ## Decision ## Consequences ## Alternatives Considered ``` - [ ] **Test CCVPS memory access** - Invoke CCVPS with task requiring memory - Verify it reads 00-INDEX.md and topic files - Confirm it updates Issues/ when finding bugs - [ ] **Setup sync strategy** (choose one): - Option A: Git-based (manual push/pull from CCVPS) - Option B: Obsidian Sync (if using Obsidian app) - Option C: rsync from local to CCVPS ### Ongoing Maintenance - [ ] **Weekly: Prune 00-INDEX.md** (keep <200 lines) - [ ] **After each sprint: Create ADR** for major decisions - [ ] **When stuck: Search vault first** before re-asking Claude - [ ] **When Claude discovers bugs: Auto-update Issues/** --- ## Summary **Immediate Action:** Implement Option D (Hybrid Obsidian + Repo) with 00-INDEX.md as the <200-line anchor loaded into every CCVPS session. This gives you: - ✅ Human-editable knowledge base (Obsidian) - ✅ Auto-loaded context (00-INDEX.md in system prompt) - ✅ Scalable topic files (Architecture/, Decisions/, etc.) - ✅ Version-controlled and shareable - ✅ Works with current CCVPS bridge architecture **Critical success factor:** 00-INDEX.md must stay <200 lines and act as a map to the full knowledge base, not contain all knowledge itself. ---------------------------------------- [Thu Mar 5 17:28:18 AEDT 2026] Task finished (exit code: 0)