Implement Memory System for Better Claude Code Context

[jeremyeder]

Overview

Implement a structured "memory system" to provide Claude Code with better context loading capabilities. Instead of relying solely on the comprehensive CLAUDE.md file (always loaded), this system creates scenario-specific, loadable-on-demand context.

Value Proposition

• Targeted context loading: Load only relevant context for specific tasks
• Reduced context bloat: Keep main CLAUDE.md focused on universal rules
• Better decision traceability: Document WHY decisions were made, not just WHAT
• Faster onboarding: New Claude sessions (and team members) understand context quickly
• Pattern reuse: Codified best practices reduce reinventing the wheel

Implementation Plan

Complete coldstartable implementation plan: `docs/implementation-plans/memory-system-implementation.md`

This plan contains ready-to-execute instructions with all file content included.

Components (Priority Order)

1. Context Files (`.claude/context/`) ⭐ HIGHEST VALUE

Scenario-specific context files loadable on-demand:

• `backend-development.md` - Go backend, K8s integration, handler patterns
• `frontend-development.md` - NextJS, Shadcn UI, React Query patterns
• `security-standards.md` - Auth, RBAC, token handling, security patterns

Usage: "Claude, load the backend-development context and help me add a new endpoint"

2. ADR Infrastructure (`docs/adr/`)

Architectural Decision Records documenting WHY decisions were made:

• `template.md` - ADR template for future decisions
• `README.md` - ADR index and workflow
• `0001-kubernetes-native-architecture.md`
• `0002-user-token-authentication.md`
• `0003-multi-repo-support.md`
• `0004-go-backend-python-runner.md`
• `0005-nextjs-shadcn-react-query.md`

Usage: "Claude, check ADR-0002 and explain why we use user tokens"

3. Repomix Usage Guide (`.claude/repomix-guide.md`)

Guide for using existing 7 repomix views effectively:

• When to use each view (architecture, backend, frontend, etc.)
• Example prompts for each scenario
• Best practices for combining views with context files

Usage: "Claude, load the backend-focused repomix view (04) and help me debug the operator"

4. Decision Log (`docs/decisions.md`)

Lightweight chronological record of major decisions:

• Quick reference format (Date, Decision, Why, Impact, Related)
• Lower overhead than full ADRs
• Links to ADRs where they exist

Usage: Quickly see what changed when and why

5. Pattern Catalog (`.claude/patterns/`)

Reusable code patterns with examples:

• `error-handling.md` - Consistent error patterns (backend, operator, runner)
• `k8s-client-usage.md` - When to use user token vs. service account
• `react-query-usage.md` - Data fetching patterns (queries, mutations, caching)

Usage: "Claude, use the error-handling pattern and add proper error handling here"

CLAUDE.md Updates

The main CLAUDE.md will be updated to:

1. Add Memory System Section at the top (after Table of Contents):

   • Quick reference to all memory files
   • When to use each type of memory file
   • Example prompts

2. Remove redundant content that now lives in memory files:

   • Deep backend/frontend patterns → Context files
   • Historical decisions → ADRs
   • Code examples → Pattern files

3. Keep universal rules that always apply:

   • Branch verification requirements
   • Linting workflows
   • Security requirements
   • Git workflow standards

Success Criteria

• All 5 components implemented with content from implementation plan
• CLAUDE.md updated with memory system reference section
• Documentation tested with Claude Code in new session
• README.md updated with memory system overview

Acceptance Criteria

This issue is complete when:

1. ✅ All files created per implementation plan
2. ✅ CLAUDE.md updated with memory system section
3. ✅ Claude can successfully reference memory files in new session
4. ✅ Example prompts tested and verified working

Implementation Time Estimate

30-45 minutes (all file content is ready in the implementation plan)

Related Documentation

• Implementation Plan: `docs/implementation-plans/memory-system-implementation.md`
• Current CLAUDE.md: Contains comprehensive but monolithic context
• Existing Repomix Views: `repomix-analysis/*.xml` (7 views)

Next Steps After Implementation

1. Update monthly: Add new decisions to decision log
2. Quarterly review: Update ADRs, patterns, context files
3. Monitor effectiveness: Track whether Claude responses improve

---

Note: This is a coldstartable plan - all file content is included in `docs/implementation-plans/memory-system-implementation.md`. No additional research or decisions needed during implementation.

[jeremyeder]

CLAUDE.md Optimization Plan

After the memory system is implemented, CLAUDE.md should be optimized to work as a "routing layer" that points to memory files rather than containing all context inline.

Coldstartable implementation plan: docs/implementation-plans/claude-md-optimization.md

Overview

This plan transforms CLAUDE.md from a monolithic ~2000+ line file into a focused ~1200-1500 line routing layer that:

✅ Contains universal rules (always apply, never violate)
✅ Provides memory system guide (when to load which files)
✅ Links to deep context (patterns, ADRs, context files)
❌ Removes detailed examples (now in memory files)
❌ Removes historical context (now in ADRs)

Key Changes

1. Add Memory System Guide section

• Table of available context files, patterns, ADRs
• When to use each type of memory file
• Example prompts for common scenarios
• Quick reference mapping tasks to memory files

2. Slim down Backend/Frontend sections

• Keep critical rules (5-10 per component)
• Add links to context files for deep patterns
• Remove detailed code examples (>20 lines)
• Remove anti-patterns (move to pattern files)

3. Update security/testing sections

• Link to security-standards.md
• Link to E2E testing guide
• Keep only critical requirements inline

Before/After Comparison

Before: Detailed K8s client patterns with full examples (~100 lines)
After: Critical rule + link to .claude/patterns/k8s-client-usage.md (~20 lines)

Before: React Query examples with mutations/optimistic updates (~150 lines)
After: Critical rules + link to .claude/patterns/react-query-usage.md (~30 lines)

Success Criteria

• Memory System Guide section added
• File size reduced by 30-40%
• All critical rules still present
• Links to all memory files correct
• Claude can reference memory files in new session

Execution Order

1. ✅ Implement memory system first (this issue)
2. ⏳ Then optimize CLAUDE.md using the plan

Full plan with all content: docs/implementation-plans/claude-md-optimization.md

[jeremyeder]

this is a critical one. im going to start establishing patterns for claude.md like linters and optimizers. i dont see a use for /init anymore since we will use this more advanced system of files on disk.