diff --git a/LANDING-PAGE-DETAILED-PLAN.md b/LANDING-PAGE-DETAILED-PLAN.md deleted file mode 100644 index c644e772..00000000 --- a/LANDING-PAGE-DETAILED-PLAN.md +++ /dev/null @@ -1,2123 +0,0 @@ -# Claude-Mem Landing Page - Detailed Implementation Plan - -**Magic UI Component Integration Strategy** - -This document outlines the complete implementation plan for the claude-mem landing page, integrating Magic UI components to create an intuitive, delightful, and effective storytelling experience. - ---- - -## Executive Summary - -**Goal**: Create a landing page that *shows* rather than *tells* - demonstrating claude-mem's value through interactive, visual storytelling. - -**Approach**: Use Magic UI components strategically to: -- Make abstract concepts (memory, persistence) tangible -- Create moments of delight that mirror the product's value -- Guide users through an intuitive understanding journey -- Reduce friction at conversion points - -**Key Metrics**: -- Average section score: 43.5/50 (87%) -- Total delight factor: 85% -- Primary conversion point: Installation section (44/50) - ---- - -## Section-by-Section Implementation - -### Section 1: HERO - "Claude Never Forgets" - -**Winning Concept**: "Fading Memory" Effect (Score: 42/50) - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Grid Beams Background - Blue/Purple] │ -│ │ -│ ┌────────────────────────────────────────────┐ │ -│ │ [Morphing Text - Main Headline] │ │ -│ │ "Claude Never Forgets" → "Claude Always │ │ -│ │ Remembers" → "Claude Learns Forever" │ │ -│ └────────────────────────────────────────────┘ │ -│ │ -│ [Orbiting Circles Visualization] │ -│ ┌──────────┐ │ -│ ○───│ Brain/ │───○ │ -│ ○ │ Database │ ○ │ -│ ○───│ Icon │───○ │ -│ └──────────┘ │ -│ Inner orbit: File icons (code files) │ -│ Middle orbit: Lightbulb icons (decisions) │ -│ Outer orbit: Bug icons (fixes) │ -│ │ -│ ┌────────────────────────────────────────────┐ │ -│ │ [Scratch To Reveal - Pain Point] │ │ -│ │ Scratch surface with grain texture │ │ -│ │ Reveals: "Every /clear wipes Claude's │ │ -│ │ memory. Until now." │ │ -│ └────────────────────────────────────────────┘ │ -│ │ -│ [Pulsating Button - Main CTA] │ -│ "Give Claude a Memory" │ -│ │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Grid Beams** (Background) -- `gridSize`: 40 -- `gridColor`: "rgba(100, 150, 255, 0.15)" -- `rayCount`: 12 -- `rayOpacity`: 0.3 -- `raySpeed`: 0.8 -- `backgroundColor`: "#0a0f1e" -- Purpose: Creates "memory grid" tech aesthetic - -**Morphing Text** (Headline) -- `texts`: ["Claude Never Forgets", "Claude Always Remembers", "Claude Learns Forever"] -- `duration`: 3000ms per text -- `className`: "text-6xl font-bold text-center" -- Purpose: Reinforces core value proposition from multiple angles - -**Orbiting Circles** (Central Visualization) -```jsx -// Inner orbit - Files - - - - -// Middle orbit - Decisions - - - - -// Outer orbit - Bugs - - - -``` -- Purpose: Visually demonstrates what gets remembered - -**Scratch To Reveal** (Pain Point) -- `width`: 600 -- `height`: 150 -- `minScratchPercentage`: 40 -- `gradientColors`: ["#1a1a2e", "#16213e", "#0f3460"] -- Reveals text: "Every /clear wipes Claude's memory. Until now." -- Purpose: Makes pain point visceral and interactive - -**Pulsating Button** (CTA) -- `pulseColor`: "59, 130, 246" (blue) -- `duration`: "1.5s" -- Text: "Give Claude a Memory" -- Purpose: Primary conversion action - -#### Implementation Notes -- Hero should be full viewport height -- Orbiting circles animate automatically on load -- Scratch-to-reveal activates on first scroll or after 3 seconds -- Grid beams subtle enough to not distract from content -- Ensure accessibility: keyboard navigation for scratch-to-reveal - ---- - -### Section 2: BEFORE/AFTER Comparison - -**Winning Concept**: "Split Screen Wipe" (Score: 44/50) - -#### Layout -``` -┌────────────────────┬────────────────────┐ -│ BEFORE │ AFTER │ -│ │ │ -│ [Safari Mockup] │ [Safari Mockup] │ -│ ┌──────────────┐ │ ┌──────────────┐ │ -│ │ Session 1: │ │ │ Session 1: │ │ -│ │ "We use Redux"│ │ │ "We use Redux"│ │ -│ │ │ │ │ │ │ -│ │ [Fading...] │ │ │ [Persists] │ │ -│ │ opacity: 0.3 │ │ │ ┌──Border──┐ │ │ -│ │ │ │ │ │Beam glow │ │ │ -│ └──────────────┘ │ │ └──────────┘ │ │ -│ │ │ │ │ -│ [Safari Mockup] │ [Safari Mockup] │ -│ ┌──────────────┐ │ ┌──────────────┐ │ -│ │ Session 2: │ │ │ Session 2: │ │ -│ │ "What state │ │ │ Claude knows │ │ -│ │ mgmt do you │ │ │ Redux setup │ │ -│ │ use?" ❌ │ │ │ already ✓ │ │ -│ └──────────────┘ │ └──────────────┘ │ -└────────────────────┴────────────────────┘ -``` - -#### Component Specifications - -**Safari** (Browser Mockups - 4 total) -- `width`: 500 -- `height`: 350 -- `mode`: "simple" -- `url`: "claude.ai/chat" -- Content: Rendered as children (conversation bubbles) - -**Before Side Animations**: -```jsx - - Session 1 conversation - - -// Then fade out -
- Previous session content -
-``` - -**After Side Animations**: -```jsx -
- - Session 2 with context - - - -
-``` - -**Scratch To Reveal** (Optional - Before side) -- Applied over entire Before column -- Scratch to reveal the "forgetting" behavior -- Creates visceral understanding of the problem - -#### Implementation Notes -- Use CSS Grid for split layout -- Before/After labels with subtle divider -- Conversations animate in sequence (Session 1, then Session 2) -- Border Beam pulses on After side every 3 seconds -- Consider responsive: stack vertically on mobile - ---- - -### Section 3: REAL EXAMPLES - 3 Scenarios - -**Winning Concept**: "Timeline Story" (Score: 44/50) - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Arc Timeline - Horizontal] │ -│ │ -│ Mon │ Wed │ Fri │ -│ ●──────────┼─────────●─────────┼────────● │ -│ Context Architecture Bug Pattern │ -│ Across Memory Recognition │ -│ Sessions │ -│ │ -│ [Expanded Node View] │ -│ ┌──────────────────────────────────────────────┐ │ -│ │ [Orbiting Circles around active node] │ │ -│ │ ○ │ │ -│ │ ○ ○ [Active Node] │ │ -│ │ ○ │ │ -│ │ │ │ -│ │ Files: store.ts, actions.ts │ │ -│ │ Decisions: Redux for state │ │ -│ │ Concepts: state-management, architecture │ │ -│ │ │ │ -│ │ [Animated List - Claude Remembers] │ │ -│ │ ✓ Your store structure │ │ -│ │ ✓ Redux patterns you prefer │ │ -│ │ ✓ Async/await convention │ │ -│ └──────────────────────────────────────────────┘ │ -│ │ -│ [Highlighter on key phrases in examples] │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Arc Timeline** -```jsx -const timelineData = [ - { - time: 'Monday', - title: 'Context Across Sessions', - description: 'Redux state management discussion' - }, - { - time: 'Wednesday', - title: 'Architectural Memory', - description: 'API endpoint creation with remembered patterns' - }, - { - time: 'Friday', - title: 'Bug Pattern Recognition', - description: 'Similar issues recognized across weeks' - } -]; - - -``` - -**Orbiting Circles** (Around Active Node) -```jsx -// File orbit - - - - -// Decision orbit - - - - -// Concept orbit - - - -``` - -**Animated List** (Claude Remembers) -```jsx - -
  • ✓ Your store structure
    • -
  • ✓ Redux patterns you prefer
    • -
  • ✓ Async/await convention
    • -
  • ✓ Auth middleware setup
    • -     -``` - -**Highlighter** (Key Phrases) -```jsx - - Your store structure - -``` - -#### Implementation Notes -- Timeline is the central organizing element -- Click timeline node to expand that scenario -- Orbiting circles show related context types -- Animated list reveals sequentially (stagger 500ms) -- Highlight key remembered elements in blue -- Smooth transitions between scenarios - ---- - -### Section 4: HOW IT WORKS - Pipeline - -**Winning Concept**: "Layered Depth Model" (Score: 43/50) - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Grid Beams Background - Subtle] │ -│ │ -│ [Morphing Text - State] │ -│ "Capturing" → "Compressing" → │ -│ "Storing" → "Retrieving" │ -│ │ -│ ┌─────────────────────────────────────────┐ │ -│ │ [Layer 1 - Front] Magic Card │ │ -│ │ You code with Claude today │ │ -│ │ ┌─────────────────────────────────┐ │ │ -│ │ │ [Particles flowing down] │ │ │ -│ └──│───────────────────────────────────│───┘ │ -│ │ │ │ -│ ┌─│─────────────────────────────────│─┐ │ -│ │ │ [Layer 2 - Mid] Magic Card │ │ │ -│ │ └─────────────────────────────────┘ │ │ -│ │ claude-mem captures & compresses │ │ -│ │ [Shine Border - Active] │ │ -│ └──────────────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────────────┐ │ -│ │ [Layer 3 - Back] Magic Card │ │ -│ │ Tomorrow, Claude starts with context│ │ -│ └─────────────────────────────────────┘ │ -│ │ -│ [Border Beam Arrows Between] │ -│ │ -│ [Highlighter on "Automatic. Zero effort."] │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Grid Beams** (Background) -- `gridSize`: 50 -- `gridColor`: "rgba(100, 100, 150, 0.08)" -- `rayCount`: 8 -- `rayOpacity`: 0.2 -- `backgroundColor`: "#0f0f1e" -- Purpose: Represents storage layer - -**Morphing Text** (State Display) -```jsx - -``` - -**Magic Cards** (3 Layers with Z-depth) -```jsx -// Layer 1 - Front - -

    You code with Claude today

    -

    Every tool use, every decision, every file change

    -     - -// Layer 2 - Middle (with Shine Border) -
    - - -

    claude-mem captures & compresses

    -

    AI-powered compression into structured memories

    -     -     -
    - -// Layer 3 - Back - -

    Tomorrow, Claude starts with context

    -

    Full project history injected automatically

    -     -``` - -**Particles** (Flowing Between Layers) -```jsx - -``` - -**Border Beam** (Arrows/Connections) -- Between Layer 1 → Layer 2 -- Between Layer 2 → Layer 3 -- Animated flow showing data movement - -**Highlighter** -```jsx - - Automatic. Zero effort. Always on. - -``` - -#### Implementation Notes -- Use CSS `perspective` for 3D depth -- Cards slide into position on scroll -- Morphing text cycles continuously -- Particles subtle, not distracting -- Responsive: reduce z-depth on mobile -- Ensure cards remain readable with gradients - ---- - -### Section 5: WHAT GETS REMEMBERED - Features - -**Winning Concept**: "Memory Bank Slots" (Score: 41/50) - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Aurora Text - Section Heading] │ -│ "What Gets Remembered" │ -│ │ -│ ┌──────────┬──────────┬──────────┐ │ -│ │ [Scratch │ [Scratch │ [Scratch │ │ -│ │ Card] │ Card] │ Card] │ │ -│ │ │ │ │ │ -│ │ Decisions│ Bugs │ Patterns │ │ -│ │ 💡 │ 🐛 │ 📋 │ │ -│ └──────────┴──────────┴──────────┘ │ -│ │ -│ ┌──────────┬──────────┬──────────┐ │ -│ │ [Scratch │ [Scratch │ [Scratch │ │ -│ │ Card] │ Card] │ Card] │ │ -│ │ │ │ │ │ -│ │ Files │ Refactor │ Deps │ │ -│ │ 📄 │ 🔄 │ 📦 │ │ -│ └──────────┴──────────┴──────────┘ │ -│ │ -│ [Revealed cards show Shine Border] │ -│ [Orbiting circles appear around revealed cards] │ -│ [Pulsating indicators on high-value items] │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Aurora Text** (Heading) -```jsx - - What Gets Remembered - -``` - -**Bento Grid** (6 Cards Layout) -```jsx -
    - {memoryTypes.map((type, index) => ( - - ))} -
    -``` - -**Scratch To Reveal Cards** (6 Individual) -```jsx -const MemoryCard = ({ icon, title, description }) => { - const [revealed, setRevealed] = useState(false); - - return ( -
    - setRevealed(true)} - > - -
    {icon}
    -

    {title}

    -

    {description}

    -     -     - - {revealed && ( - <> - - - - - - )} -
    - ); -}; -``` - -**Memory Types Data** -```javascript -const memoryTypes = [ - { - icon: '💡', - title: 'Decisions', - description: 'Why did we choose this architecture? What trade-offs did we make?' - }, - { - icon: '🐛', - title: 'Bugs Fixed', - description: 'How did we solve this before? What was the root cause?' - }, - { - icon: '📋', - title: 'Code Patterns', - description: "What's our convention for this? How do we structure similar code?" - }, - { - icon: '📄', - title: 'File Changes', - description: 'What did we modify last session? Which files are related?' - }, - { - icon: '🔄', - title: 'Refactorings', - description: 'What was the old implementation? Why did we change it?' - }, - { - icon: '📦', - title: 'Dependencies', - description: 'Which libraries are we using? What versions? Why those?' - } -]; -``` - -**Pulsating Button** (High-value indicators) -- Applied to "Decisions" and "Bugs Fixed" cards -- Subtle pulse before scratching -- `pulseColor`: "59, 130, 246" -- `duration`: "2s" - -#### Implementation Notes -- Cards arranged in 3x2 grid (responsive: 2x3 on tablet, 1x6 on mobile) -- Scratch surface has subtle grain texture -- Revealed cards get Shine Border animation -- Orbiting circles appear with checkmark icon after reveal -- Track which cards are revealed, celebrate when all revealed -- Consider adding a "Reveal All" button for impatient users -- Ensure scratch works on touch devices - ---- - -### Section 6: POWERFUL SEARCH - -**Winning Concept**: "Live Search Demo" (Score: 44/50) - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Section Heading] │ -│ Powerful Search │ -│ │ -│ [Safari Browser Mockup - Search Interface] │ -│ ┌──────────────────────────────────────────────┐ │ -│ │ 🔍 [Text Animate - Typing Query] │ │ -│ │ "Find all the database migrations we did" │ │ -│ │ │ │ -│ │ [Animated List - Results Appearing] │ │ -│ │ ┌────────────────────────────────────────┐ │ │ -│ │ │ [Magic Card with Border Beam] │ │ │ -│ │ │ March 15: Added user_preferences table │ │ │ -│ │ │ [Highlighter on "user_preferences"] │ │ │ -│ │ └────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ ┌────────────────────────────────────────┐ │ │ -│ │ │ [Magic Card with Border Beam] │ │ │ -│ │ │ March 12: Migration for OAuth tokens │ │ │ -│ │ │ [Highlighter on "OAuth tokens"] │ │ │ -│ │ └────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ ┌────────────────────────────────────────┐ │ │ -│ │ │ [Magic Card] │ │ │ -│ │ │ March 8: Index optimization on sessions │ │ │ -│ │ └────────────────────────────────────────┘ │ │ -│ └──────────────────────────────────────────────┘ │ -│ │ -│ [Morphing Text - Search Types] │ -│ "Migrations" → "Decisions" → "Patterns" → "Bugs" │ -│ │ -│ [7 Search Tools - Animated List] │ -│ ✓ search_observations ✓ find_by_concept │ -│ ✓ search_sessions ✓ find_by_file │ -│ ✓ find_by_type ✓ get_recent_context │ -│ ✓ advanced_search (Combined filters) │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Safari** (Search Interface Mockup) -```jsx - - - -``` - -**Text Animate** (Typing Search Query) -```jsx -const queries = [ - "Find all the database migrations we did", - "What decisions did we make about authentication?", - "Show me bug fixes from last week" -]; - - - {currentQuery} - -``` - -**Animated List** (Search Results) -```jsx - - {results.map((result, index) => ( - - - -
    - -
    -

    - {result.date}: - - {result.highlight} - -

    -

    - {result.description} -

    -
    -
    -     - ))} -     -``` - -**Morphing Text** (Search Types Cycling) -```jsx - -``` - -**Highlighter** (Matched Keywords in Results) -```jsx - - {matchedKeyword} - -``` - -**Animated List** (7 Search Tools) -```jsx - -
    - - search_observations -
    -
    - - find_by_concept -
    - {/* ... remaining 5 tools ... */} -     -``` - -#### Implementation Notes -- Safari mockup shows actual search interface -- Query types out character by character (realistic typing) -- Results appear sequentially with stagger (800ms delay) -- Each result card has Border Beam animation -- Highlight matched keywords in blue -- Morphing text cycles to show different search types -- Consider interactive: let user click different query types -- Show "Instant recall. Full project history." tagline - ---- - -### Section 7: THE NUMBERS - Metrics - -**Winning Concept**: "Progress Bar Transformation" (Score: 45/50) ⭐ HIGHEST - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Section Heading] │ -│ The Numbers │ -│ │ -│ ┌──────────────────────────────────────────────┐ │ -│ │ [Magic Card with Shine Border] │ │ -│ │ │ │ -│ │ Context repetition │ │ -│ │ ────────────────────────────────────── │ │ -│ │ BEFORE: ████████████████████ Every session │ │ -│ │ [Red bar - 100%] │ │ -│ │ │ │ -│ │ AFTER: [Green bar - 0%] Never │ │ -│ │ [Morphing animation] │ │ -│ └──────────────────────────────────────────────┘ │ -│ │ -│ [4 more Magic Cards with progress transformations] │ -│ │ -│ [Morphing Text - Cycling Metrics] │ -│ "Context" → "Onboarding" → "Bugs" → "Questions" │ -│ │ -│ [Pulsating Button - "See the Difference"] │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Magic Cards** (5 Metrics) -```jsx -const metrics = [ - { - name: 'Context repetition', - before: { value: 100, label: 'Every session', color: '#ef4444' }, - after: { value: 0, label: 'Never', color: '#10b981' } - }, - { - name: 'Onboarding time', - before: { value: 75, label: '5-10 min per session', color: '#f59e0b' }, - after: { value: 0, label: '0 seconds', color: '#10b981' } - }, - { - name: 'Bug re-investigation', - before: { value: 80, label: 'Common', color: '#ef4444' }, - after: { value: 10, label: 'Rare', color: '#10b981' } - }, - { - name: 'Architectural questions', - before: { value: 90, label: '"What did we decide?"', color: '#f59e0b' }, - after: { value: 5, label: 'Claude already knows', color: '#10b981' } - }, - { - name: 'Code pattern consistency', - before: { value: 60, label: 'Manual enforcement', color: '#f59e0b' }, - after: { value: 95, label: 'Automatic', color: '#10b981' } - } -]; - -{metrics.map((metric, index) => ( - - -

    {metric.name}

    - - {/* Before Progress Bar */} -
    -
    - BEFORE: - {metric.before.label} -
    -
    -
    -
    -
    - - {/* After Progress Bar */} -
    -
    - AFTER: - - {metric.after.label} - -
    -
    -
    -
    -
    - - -))} -``` - -**Morphing Text** (Cycling Metric Names) -```jsx - -``` - -**Pulsating Button** (CTA) -```jsx - - See the Difference - -``` - -#### Animation Sequence -1. Cards appear with stagger (200ms between each) -2. "Before" bars animate in first (duration: 1000ms) -3. "After" bars animate in with delay (delay: 500ms, duration: 1000ms) -4. Shine Border pulses continuously -5. Morphing text cycles through metric names -6. On hover: card spotlights activate - -#### Implementation Notes -- Progress bars use CSS transitions for smooth animation -- Color coding: Red/Orange for "before", Green for "after" -- Bars animate on scroll into view (IntersectionObserver) -- Consider adding count-up animation for percentages -- Ensure high contrast for accessibility -- Mobile: Stack bars vertically if needed - ---- - -### Section 8: INSTALLATION - Quick Start - -**Winning Concept**: "Copy-Paste Delight" (Score: 44/50) - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Section Heading] │ -│ Installation - 2 Minutes │ -│ │ -│ [Safari Terminal Mockup] │ -│ ┌──────────────────────────────────────────────┐ │ -│ │ $ [Text Animate - Typing Command] │ │ -│ │ git clone https://github.com/... │ │ -│ │ │ │ -│ │ [Shiny Button - Copy] 📋 │ │ -│ └──────────────────────────────────────────────┘ │ -│ │ -│ [Animated List - 3 Steps with Checkmarks] │ -│ ┌─────────────────────────────────────────────┐ │ -│ │ ✓ [Step 1] Clone and install │ │ -│ │ git clone + cd claude-mem │ │ -│ │ │ │ -│ │ ○ [Step 2] Add to Claude Code │ │ -│ │ /plugin marketplace add .claude-plugin/... │ │ -│ │ │ │ -│ │ ○ [Step 3] Install │ │ -│ │ /plugin install claude-mem │ │ -│ └─────────────────────────────────────────────┘ │ -│ │ -│ [Highlighter on "2 minutes"] │ -│ [Confetti when all steps complete] │ -│ │ -│ [Pulsating Button - "Get Started"] │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Safari** (Terminal Mockup) -```jsx - - - -``` - -**Text Animate** (Typing Commands) -```jsx -const commands = [ - "git clone https://github.com/thedotmack/claude-mem.git", - "cd claude-mem", - "/plugin marketplace add .claude-plugin/marketplace.json", - "/plugin install claude-mem" -]; - - - $ {currentCommand} - -``` - -**Shiny Button** (Copy Button) -```jsx - - Copy - -``` - -**Animated List** (3 Steps) -```jsx - - {steps.map((step, index) => ( -
    -
    - {step.completed ? '✓' : '○'} -
    -
    -

    - {step.title} -

    - - {step.command} - -
    - {step.completed && } -
    - ))} -     -``` - -**Highlighter** ("2 minutes") -```jsx - - 2 minutes - -``` - -**Confetti** (Completion Celebration) -```jsx -{allStepsComplete && ( - -)} -``` - -**Pulsating Button** (Get Started CTA) -```jsx - - Get Started Now - -``` - -#### Interactive Sequence -1. Terminal appears with first command typing -2. User clicks copy button → copied feedback -3. Shiny Button shows success state briefly -4. Animated list reveals steps sequentially -5. As user progresses (simulated or tracked), checkmarks appear -6. When final step completes → Confetti celebration -7. Pulsating button draws attention to next action - -#### Implementation Notes -- Terminal has realistic command-line styling -- Copy buttons work with clipboard API -- Consider simulating installation progress (for demo) -- Track actual installation if possible (analytics) -- Confetti fires once, not repeatedly -- Ensure keyboard navigation for copy buttons -- Mobile: Reduce terminal size, keep copy buttons visible - ---- - -### Section 9: UNDER THE HOOD - Architecture - -**Winning Concept**: "Layered Stack" (Score: 44/50) - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Warp Background - Depth Effect] │ -│ │ -│ [Morphing Text - Active Layer] │ -│ "Hooks" → "Worker" → "SQLite" → "MCP" → "Context"│ -│ │ -│ [5 Layered Magic Cards] │ -│ │ -│ ┌────────────────────────────────┐ [Layer 1] │ -│ │ Hooks (SessionStart, PostTool) │ ← Shine │ -│ │ 📌 5 lifecycle hooks │ Border │ -│ └─│──────────────────────────────┘ │ -│ │ [Particles flowing down] │ -│ ┌─│────────────────────────────────┐ [Layer 2] │ -│ │ Worker Service │ │ -│ │ ⚙️ Express.js + PM2 │ │ -│ └─│────────────────────────────────┘ │ -│ │ │ -│ ┌─│──────────────────────────────────┐ [Layer 3] │ -│ │ SQLite Database │ │ -│ │ 💾 FTS5 Search + Sessions │ │ -│ └─│──────────────────────────────────┘ │ -│ │ │ -│ ┌─│────────────────────────────────┐ [Layer 4] │ -│ │ MCP Server │ │ -│ │ 🔍 7 Search Tools │ │ -│ └─│────────────────────────────────┘ │ -│ │ │ -│ ┌─│──────────────────────────────────┐ [Layer 5] │ -│ │ Context Injection │ │ -│ │ 🎯 Future Session Loading │ │ -│ └────────────────────────────────────┘ │ -│ │ -│ [Highlighter on "Zero maintenance. Just works."] │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Warp Background** -```jsx - -``` - -**Morphing Text** (Active Layer Indicator) -```jsx - -``` - -**Layered Magic Cards** (5 Layers) -```jsx -const layers = [ - { - title: 'Hooks', - icon: '📌', - description: '5 lifecycle hooks capture tool usage', - details: 'SessionStart, UserPromptSubmit, PostToolUse, Summary, SessionEnd', - zIndex: 50, - transform: 'rotateX(5deg) translateY(0px)', - shine: true - }, - { - title: 'Worker Service', - icon: '⚙️', - description: 'Express.js HTTP API managed by PM2', - details: 'Processes observations, handles AI compression', - zIndex: 40, - transform: 'rotateX(10deg) translateY(60px)' - }, - { - title: 'SQLite Database', - icon: '💾', - description: 'FTS5 full-text search + structured storage', - details: 'Sessions, observations, summaries with citations', - zIndex: 30, - transform: 'rotateX(15deg) translateY(120px)', - highlight: true // Central piece - }, - { - title: 'MCP Server', - icon: '🔍', - description: '7 specialized search tools', - details: 'search_observations, find_by_concept, find_by_type, etc.', - zIndex: 20, - transform: 'rotateX(20deg) translateY(180px)' - }, - { - title: 'Context Injection', - icon: '🎯', - description: 'Loads relevant context into future sessions', - details: 'Automatic retrieval of last 3 session summaries', - zIndex: 10, - transform: 'rotateX(25deg) translateY(240px)' - } -]; - -
    - {layers.map((layer, index) => ( -
    - {layer.shine ? ( - - - - ) : ( - - - - )} -
    - ))} - - -
    -``` - -**Layer Card Component** -```jsx -const LayerCard = ({ layer }) => ( -
    -
    - {layer.icon} -

    {layer.title}

    -
    -

    {layer.description}

    -

    {layer.details}

    -
    -); -``` - -**Highlighter** (Tagline) -```jsx - - Zero maintenance. Runs in the background. Just works. - -``` - -#### Animation Sequence -1. Warp background creates depth immediately -2. Cards slide in from top with stagger (150ms between) -3. Each card settles into z-position -4. Morphing text cycles through layer names -5. Shine Border on top layer (Hooks) pulses -6. Particles flow downward between layers -7. On scroll/hover: cards can expand slightly to show more detail - -#### Implementation Notes -- Use CSS `perspective` and `transform` for 3D effect -- Cards stack with decreasing z-index -- Active layer (from morphing text) gets subtle highlight -- Particles subtle, flow from top to bottom -- Consider scroll interaction: layers separate as you scroll -- Responsive: reduce perspective on mobile, stack more vertically -- Ensure text remains readable at all angles - ---- - -### Section 10: USE CASES - User Types - -**Winning Concept**: "Role Selector" (Score: 46/50) ⭐ HIGHEST DELIGHT - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Section Heading] │ -│ Use Cases │ -│ │ -│ [Dock Component - Role Icons] │ -│ ┌────────────────────────────────────────────┐ │ -│ │ 👤 👥 🎓 🔧 │ │ -│ │ Solo Team Learning Refactor │ │ -│ └────────────────────────────────────────────┘ │ -│ │ -│ [Expanded Magic Card - Selected Role] │ -│ ┌──────────────────────────────────────────────┐ │ -│ │ [Spotlight Effect Active] │ │ -│ │ │ │ -│ │ Solo Developers │ │ -│ │ [Avatar Circles - User Count] │ │ -│ │ +2,500 │ │ -│ │ │ │ -│ │ [Animated List - Benefits] │ │ -│ │ ✓ Never lose context between sessions │ │ -│ │ ✓ Build on past decisions automatically │ │ -│ │ ✓ Remember why you made each choice │ │ -│ │ │ │ -│ │ [Highlighter on key benefits] │ │ -│ └──────────────────────────────────────────────┘ │ -│ │ -│ [Confetti when selecting "your" role] │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Dock** (Role Selector) -```jsx -const roles = [ - { id: 'solo', icon: '👤', label: 'Solo Developers' }, - { id: 'team', icon: '👥', label: 'Team Projects' }, - { id: 'learning', icon: '🎓', label: 'Learning & Experiments' }, - { id: 'refactor', icon: '🔧', label: 'Large Refactors' } -]; - - - {roles.map((role) => ( - selectRole(role.id)} - className={selectedRole === role.id ? 'scale-125' : ''} - > -
    {role.icon}
    - {role.label} -     - ))} -     -``` - -**Magic Card** (Expanded Role Details) -```jsx -const useCases = { - solo: { - title: 'Solo Developers', - userCount: 2500, - gradient: { from: '#3b82f6', to: '#8b5cf6' }, - benefits: [ - 'Never lose context between coding sessions', - 'Build on past decisions automatically', - 'Remember why you made each choice', - 'Track your learning journey over time' - ] - }, - team: { - title: 'Team Projects', - userCount: 1200, - gradient: { from: '#10b981', to: '#3b82f6' }, - benefits: [ - 'Share architectural knowledge across sessions', - 'Maintain consistency in code patterns', - 'Document decisions as they happen', - 'Onboard new team members with context' - ] - }, - learning: { - title: 'Learning & Experiments', - userCount: 1800, - gradient: { from: '#f59e0b', to: '#ec4899' }, - benefits: [ - 'Track what you tried and what worked', - 'Build a personal knowledge base', - 'Learn from past mistakes', - 'See your progress over time' - ] - }, - refactor: { - title: 'Large Refactors', - userCount: 900, - gradient: { from: '#8b5cf6', to: '#ec4899' }, - benefits: [ - 'Remember what you changed across multiple sessions', - 'Track progress on multi-day tasks', - 'Maintain context through interruptions', - 'Reference old implementations easily' - ] - } -}; - - -

    - {currentUseCase.title} -

    - - - - - {currentUseCase.benefits.map((benefit, index) => ( -
    - -

    - - {highlightKeyPhrase(benefit)} - -

    -
    - ))} -     -     -``` - -**Confetti** (Selection Celebration) -```jsx -{justSelected && ( - -)} -``` - -#### Interactive Behavior -1. Dock icons magnify on hover (macOS-style) -2. Click icon → Card expands with selected role details -3. Magic Card spotlight follows cursor -4. Avatar Circles show user count for that role -5. Animated List reveals benefits sequentially -6. Key phrases highlighted in benefits -7. **Confetti celebration when role selected** (delight moment!) -8. Consider: "This is me!" button that triggers extra confetti - -#### Implementation Notes -- Dock provides familiar, intuitive interface -- Smooth transitions between role selections (300ms) -- Avatar Circles update count with animation -- Confetti fires once per selection -- Consider adding a quiz: "Which role fits you?" → confetti on result -- Track which roles are most popular (analytics) -- Ensure dock works well on touch devices -- Mobile: Dock might need to be grid instead of horizontal - ---- - -### Section 11: FAQ - -**Winning Concept**: "Scratch to Answer" (Score: 42/50) - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ [Section Heading] │ -│ FAQ │ -│ │ -│ [Morphing Text - Common Concerns] │ -│ "Cost?" → "Speed?" → "Privacy?" → "Storage?" │ -│ │ -│ ┌──────────────────┬──────────────────┐ │ -│ │ [Scratch Card] │ [Scratch Card] │ │ -│ │ ┌──────────────┐ │ ┌──────────────┐ │ │ -│ │ │ Does this │ │ │ How much does│ │ │ -│ │ │ slow down │ │ │ it cost? │ │ │ -│ │ │ Claude? │ │ │ │ │ │ -│ │ │ │ │ │ [Scratch to │ │ │ -│ │ │ [Scratch to │ │ │ reveal] │ │ │ -│ │ │ reveal] │ │ │ │ │ │ -│ │ └──────────────┘ │ └──────────────┘ │ │ -│ └──────────────────┴──────────────────┘ │ -│ │ -│ [6 Question Cards Total - 2x3 Grid] │ -│ │ -│ [Revealed cards show Magic Card with Confetti] │ -│ │ -│ [Pulsating Button - "More Questions?"] │ -└─────────────────────────────────────────────────────┘ -``` - -#### Component Specifications - -**Morphing Text** (Common Concerns) -```jsx - -``` - -**FAQ Data** -```javascript -const faqs = [ - { - question: 'Does this slow down Claude?', - answer: 'No. Memory processing happens in the background via PM2 worker service. Claude responds instantly. Zero impact on response time.', - important: false - }, - { - question: 'How much does it cost?', - answer: 'Minimal. Memory compression uses your chosen model (default: Sonnet 4.5). Typical cost: $0.01-0.05 per coding session.', - important: false - }, - { - question: 'Where is data stored?', - answer: 'Locally in ~/.claude-mem/claude-mem.db on your machine. Fully private. Never leaves your computer. You have complete control.', - important: true, // Triggers confetti - highlight: 'Fully private. Never leaves your computer.' - }, - { - question: 'Can I search my memories?', - answer: 'Yes! 7 specialized search tools available through Claude. Search by file, concept, type, date range, or full-text query.', - important: false - }, - { - question: 'Does it work with existing projects?', - answer: 'Yes. claude-mem starts learning immediately when installed. No configuration needed. Works with any project.', - important: false - }, - { - question: 'What if I want to forget something?', - answer: 'Delete observations directly from the SQLite database, or start fresh by removing ~/.claude-mem/claude-mem.db.', - important: false - } -]; -``` - -**Scratch To Reveal FAQ Cards** -```jsx -
    - {faqs.map((faq, index) => ( -
    - handleReveal(index, faq.important)} - > - -

    - {faq.question} -

    - -

    - {faq.highlight ? ( - - {faq.highlight} - - ) : ( - faq.answer - )} -

    -     -     - - {revealed[index] && faq.important && ( - - )} -
    - ))} -
    -``` - -**Pulsating Button** (More Questions) -```jsx - window.location.href = 'https://github.com/thedotmack/claude-mem/issues'} -> - More Questions? Ask on GitHub - -``` - -#### Interactive Behavior -1. Questions visible on scratch surface -2. User scratches card to reveal answer -3. When 45% scratched → answer revealed -4. Revealed card shows Magic Card beneath with answer -5. **Important answers (privacy) trigger Confetti celebration** -6. Highlighter emphasizes critical information -7. Track which questions get scratched first (analytics) - -#### Implementation Notes -- Scratch surfaces need good contrast for question text -- Answer text should be easily readable when revealed -- Confetti fires only for "important" questions (privacy, security) -- Consider adding a "Reveal All" button for accessibility -- Scratch works on touch and mouse -- Mobile: Single column layout -- Ensure keyboard navigation alternative to scratching -- Consider fade-in animation for revealed cards - ---- - -## BONUS: Testimonials Section - -**Concept**: "Social Proof Marquee" - -#### Layout -``` -┌─────────────────────────────────────────────────────┐ -│ What Developers Say │ -│ │ -│ [Marquee - 3D Mode - Continuous Scroll] │ -│ ┌────────────────────────────────────────────────┐ │ -│ │ │ │ -│ │ [Magic Card 1] [Magic Card 2] [Magic Card 3]│ │ -│ │ "I used to "It's like "The search is │ │ -│ │ spend 10min having a incredible." │ │ -│ │ every morning teammate..." │ │ -│ │ explaining" │ │ -│ │ │ │ -│ │ [Shine Border on featured testimonial] │ │ -│ └────────────────────────────────────────────────┘ │ -│ │ -│ [Avatar Circles - Total Developers] │ -│ +5,000 │ -│ │ -│ [Highlighter on impactful quotes] │ -└─────────────────────────────────────────────────────┘ -``` - -#### Implementation -```jsx - - {testimonials.map((testimonial, index) => ( - - {testimonial.featured && ( - - )} - -

    - " - {testimonial.highlight} - {testimonial.rest}" -

    - -
    - -
    -

    {testimonial.name}

    -

    {testimonial.role}

    -
    -
    -     - ))} -     - - -``` - ---- - -## Global Design System - -### Color Palette -```javascript -const colors = { - primary: { - blue: '#3b82f6', - purple: '#8b5cf6', - indigo: '#6366f1' - }, - success: { - green: '#10b981', - emerald: '#059669' - }, - warning: { - orange: '#f59e0b', - amber: '#f59e0b' - }, - error: { - red: '#ef4444', - rose: '#f43f5e' - }, - neutral: { - gray900: '#0a0f1e', - gray800: '#1a1a2e', - gray700: '#2a2a3e', - gray600: '#3a3a4e', - gray400: '#8a8a9e', - gray200: '#cacade' - } -}; -``` - -### Typography -```javascript -const typography = { - hero: 'text-6xl font-bold', - h1: 'text-5xl font-bold', - h2: 'text-4xl font-bold', - h3: 'text-3xl font-bold', - h4: 'text-2xl font-semibold', - body: 'text-base leading-relaxed', - small: 'text-sm', - code: 'font-mono text-sm bg-gray-900 px-2 py-1 rounded' -}; -``` - -### Spacing -```javascript -const spacing = { - sectionPadding: 'py-20 px-6', - cardPadding: 'p-6', - cardGap: 'gap-6', - stackSpacing: 'space-y-12' -}; -``` - -### Animation Timings -```javascript -const animations = { - fast: '200ms', - normal: '300ms', - slow: '500ms', - stagger: '150ms', - typing: '30-50ms per character', - morphDuration: '2500-3000ms' -}; -``` - ---- - -## Performance Optimization - -### Lazy Loading Strategy -1. **Above the fold** (Hero): Load immediately -2. **Near viewport**: Preload when within 200px -3. **Below fold**: Lazy load on scroll -4. **Interactive elements**: Load on user interaction - -### Component Loading Priority -``` -Priority 1 (Immediate): -- Grid Beams (Hero background) -- Morphing Text (Hero headline) -- Orbiting Circles (Hero visualization) - -Priority 2 (Fast): -- Safari mockups (Before/After) -- Text Animate (Typing effects) -- Border Beam (Highlights) - -Priority 3 (Lazy): -- Scratch To Reveal (Load on viewport) -- Confetti (Load on demand) -- Particles (Load when section visible) -``` - -### Optimization Techniques -1. **Code splitting**: Load Magic UI components on demand -2. **Image optimization**: Use WebP, lazy load images -3. **Animation throttling**: Reduce motion for `prefers-reduced-motion` -4. **Intersection Observer**: Trigger animations on scroll -5. **Debounce**: Scratch events, hover effects - ---- - -## Accessibility Guidelines - -### WCAG 2.1 AA Compliance - -**Keyboard Navigation** -- All interactive elements focusable -- Tab order logical -- Skip links for section navigation -- Escape key dismisses modals/overlays - -**Screen Readers** -```jsx -// Scratch To Reveal alternative - -
    - {answer} -
    -     - -// Animation alternatives - - {/* Visual morphing text */} - -``` - -**Color Contrast** -- Minimum 4.5:1 for normal text -- Minimum 3:1 for large text -- Test with tools like axe, Lighthouse - -**Motion Preferences** -```css -@media (prefers-reduced-motion: reduce) { - * { - animation-duration: 0.01ms !important; - transition-duration: 0.01ms !important; - } - - /* Disable confetti, particles */ - .confetti, .particles { - display: none; - } -} -``` - -**Focus Indicators** -```css -:focus-visible { - outline: 2px solid #3b82f6; - outline-offset: 2px; -} -``` - ---- - -## Responsive Design Breakpoints - -### Mobile First Approach - -**Breakpoints** -```javascript -const breakpoints = { - mobile: '0px', // 0-640px - tablet: '640px', // 640-1024px - desktop: '1024px', // 1024-1536px - wide: '1536px' // 1536px+ -}; -``` - -### Section Adaptations - -**Hero** -- Mobile: Stack vertically, reduce orbiting circles -- Tablet: Maintain layout, smaller circles -- Desktop: Full experience - -**Before/After** -- Mobile: Stack vertically (Before on top, After below) -- Tablet: Side by side with smaller Safari mockups -- Desktop: Full side-by-side - -**Real Examples (Timeline)** -- Mobile: Vertical timeline, tap to expand -- Tablet: Horizontal timeline, smaller orbits -- Desktop: Full arc timeline with orbits - -**Installation** -- Mobile: Full-width terminal, stack steps -- Tablet: Maintain layout, smaller terminal -- Desktop: Full experience - -**Use Cases (Dock)** -- Mobile: 2x2 grid instead of dock -- Tablet: Horizontal dock, smaller icons -- Desktop: Full dock with magnification - ---- - -## Analytics & Tracking - -### Key Metrics to Track - -**Engagement** -- Section scroll depth -- Time spent per section -- Interactive element usage (scratch cards, dock clicks) -- Confetti trigger count - -**Conversion** -- Installation section CTR -- Copy button clicks -- GitHub link clicks -- "Get Started" button clicks - -**User Behavior** -- Which use case selected most -- Which FAQ questions scratched first -- Which examples viewed longest -- Search demo interaction rate - -### Implementation -```javascript -// Example event tracking -const trackEvent = (category, action, label) => { - if (typeof gtag !== 'undefined') { - gtag('event', action, { - event_category: category, - event_label: label - }); - } -}; - -// Usage - { - trackEvent('CTA', 'click', 'Get Started Hero'); - // ... navigation - }} -> - Get Started - -``` - ---- - -## Technical Implementation Notes - -### Dependencies -```json -{ - "dependencies": { - "react": "^18.0.0", - "next": "^14.0.0", - "magic-ui": "latest", - "tailwindcss": "^3.4.0", - "framer-motion": "^10.0.0" - } -} -``` - -### Installation -```bash -# Install Magic UI -npm install magic-ui - -# Install required components -npx shadcn-ui@latest add morphing-text -npx shadcn-ui@latest add orbiting-circles -npx shadcn-ui@latest add scratch-to-reveal -npx shadcn-ui@latest add safari -npx shadcn-ui@latest add arc-timeline -npx shadcn-ui@latest add grid-beams -npx shadcn-ui@latest add magic-card -npx shadcn-ui@latest add border-beam -npx shadcn-ui@latest add shine-border -npx shadcn-ui@latest add dock -npx shadcn-ui@latest add confetti -npx shadcn-ui@latest add pulsating-button -npx shadcn-ui@latest add aurora-text -npx shadcn-ui@latest add highlighter -npx shadcn-ui@latest add animated-list -npx shadcn-ui@latest add text-animate -npx shadcn-ui@latest add marquee -npx shadcn-ui@latest add avatar-circles -``` - -### File Structure -``` -landing-page/ -├── components/ -│ ├── sections/ -│ │ ├── Hero.tsx -│ │ ├── BeforeAfter.tsx -│ │ ├── RealExamples.tsx -│ │ ├── HowItWorks.tsx -│ │ ├── WhatGetsRemembered.tsx -│ │ ├── PowerfulSearch.tsx -│ │ ├── TheNumbers.tsx -│ │ ├── Installation.tsx -│ │ ├── UnderTheHood.tsx -│ │ ├── UseCases.tsx -│ │ └── FAQ.tsx -│ ├── ui/ -│ │ └── [Magic UI components] -│ └── shared/ -│ ├── SectionWrapper.tsx -│ └── Container.tsx -├── lib/ -│ ├── constants.ts -│ ├── data.ts -│ └── utils.ts -├── public/ -│ ├── images/ -│ └── icons/ -└── pages/ - └── index.tsx -``` - ---- - -## Testing Checklist - -### Browser Testing -- [ ] Chrome (latest) -- [ ] Firefox (latest) -- [ ] Safari (latest) -- [ ] Edge (latest) -- [ ] Mobile Safari (iOS) -- [ ] Chrome Mobile (Android) - -### Device Testing -- [ ] iPhone (Safari) -- [ ] iPad (Safari) -- [ ] Android phone (Chrome) -- [ ] Android tablet (Chrome) -- [ ] Desktop (1920x1080) -- [ ] Desktop (2560x1440) - -### Functionality Testing -- [ ] All animations trigger correctly -- [ ] Scratch-to-reveal works on touch and mouse -- [ ] Confetti fires on correct events -- [ ] Copy buttons work -- [ ] Dock magnification works -- [ ] Timeline navigation works -- [ ] All links functional -- [ ] Performance acceptable (<3s LCP) - -### Accessibility Testing -- [ ] Keyboard navigation works -- [ ] Screen reader friendly -- [ ] Color contrast passes WCAG AA -- [ ] Focus indicators visible -- [ ] Reduced motion respected -- [ ] Alt text on all images - ---- - -## Launch Checklist - -### Pre-Launch -- [ ] Content finalized and proofread -- [ ] All components tested in isolation -- [ ] Full page tested on all browsers -- [ ] Performance optimized (Lighthouse score >90) -- [ ] SEO meta tags added -- [ ] Open Graph images created -- [ ] Analytics tracking implemented -- [ ] A/B testing variants prepared - -### Launch Day -- [ ] Deploy to production -- [ ] Verify all links work -- [ ] Test on real devices -- [ ] Monitor analytics -- [ ] Check for console errors -- [ ] Social media announcements ready - -### Post-Launch -- [ ] Monitor conversion rates -- [ ] Gather user feedback -- [ ] Iterate based on data -- [ ] Create marketing assets (screenshots, videos) -- [ ] Document learnings - ---- - -## Summary: Why This Design Works - -### Storytelling Through Interaction -Every section uses components to **demonstrate** rather than **describe**: -- **Hero**: Orbiting circles show what gets remembered -- **Before/After**: Fading vs persisting shows the difference -- **Examples**: Timeline shows progression across sessions -- **Pipeline**: Layered stack shows architecture hierarchy -- **Features**: Scratch-to-reveal makes discovery engaging -- **Search**: Live demo shows actual capability -- **Metrics**: Progress bars visualize transformation -- **Installation**: Typing effect shows realistic process -- **Architecture**: Depth shows layered system -- **Use Cases**: Dock lets users find themselves -- **FAQ**: Scratching makes learning fun - -### Delight at Every Turn -- **Confetti** celebrates milestones (installation complete, finding your use case, revealing important answers) -- **Pulsating buttons** draw attention to actions -- **Magic cards** with spotlights make content feel premium -- **Border beams** guide attention -- **Morphing text** keeps content dynamic - -### Intuitive Understanding -- **Familiar patterns** (Safari browser, dock, terminal) -- **Visual metaphors** (orbits for data flow, layers for architecture) -- **Progressive disclosure** (scratch to reveal, animated lists) -- **Clear hierarchy** (section headings, consistent spacing) - -### Conversion Optimized -- **Low friction** (copy buttons, clear steps) -- **Social proof** (avatar circles, testimonials) -- **Value demonstration** (metrics, examples, search) -- **Multiple CTAs** (hero, installation, bottom) - ---- - -**Total Component Count**: 17 unique Magic UI components -**Average Section Score**: 43.5/50 (87%) -**Highest Scoring Sections**: -1. Use Cases (46/50) - Highest delight -2. The Numbers (45/50) - Best storytelling -3. Before/After, Real Examples, Search, Installation, Under The Hood (all 44/50) - -**Implementation Timeline**: 2-3 weeks for full build with polish -**Estimated Performance**: Lighthouse score 85-95 with optimizations -**Predicted Conversion Lift**: 30-50% vs plain text landing page diff --git a/LANDING.md b/LANDING.md deleted file mode 100644 index a7960f95..00000000 --- a/LANDING.md +++ /dev/null @@ -1,297 +0,0 @@ -# Claude Never Forgets - -**Give Claude a memory that spans your entire project.** - ---- - -## The Problem - -``` -You: "Remember that bug we fixed last Tuesday with the auth flow?" -Claude: "I don't have access to previous conversations..." -``` - -Every `/clear` wipes Claude's memory. Every new session starts from zero. You repeat yourself constantly. - -**Until now.** - ---- - -## What Changes - -### Before claude-mem -```typescript -// Monday: You debug an issue -You: "Why is the database connection failing?" -Claude: [Helps you fix it] - -// Wednesday: Similar issue appears -You: "The database is timing out again" -Claude: "Let me investigate..." [Starts from scratch] -``` - -### After claude-mem -```typescript -// Monday: You debug an issue -You: "Why is the database connection failing?" -Claude: [Helps you fix it] -✓ Remembers: connection pool exhaustion pattern - -// Wednesday: Similar issue appears -You: "The database is timing out again" -Claude: "Based on Monday's session, this looks like the same - connection pool issue. Let me check the pool size config..." -``` - -Claude **remembers**. Claude **learns**. Claude gets **better** over time. - ---- - -## Real Examples - -### 1. **Context Across Sessions** - -**Without claude-mem:** -``` -Session 1: "We use Redux for state management" -Session 2: "What state management do you use?" ❌ -``` - -**With claude-mem:** -``` -Session 1: "We use Redux for state management" -Session 2: Claude already knows you use Redux ✓ - Suggests Redux patterns automatically ✓ - References your store structure ✓ -``` - -### 2. **Architectural Memory** - -**Your third session of the day:** -``` -You: "Add a new API endpoint for user preferences" - -Claude: "I see from previous sessions that: -- Your API follows REST conventions in src/api/ -- You use Zod for validation -- Auth middleware is required for user routes -- You prefer async/await over promises - -I'll create the endpoint following these patterns..." -``` - -**No explaining. No repeating. Just building.** - -### 3. **Bug Pattern Recognition** - -``` -Week 1: Fixed race condition in webhook handler -Week 2: Different race condition in event processor - -Claude: "This looks similar to the webhook race condition - we fixed last week. The same solution should work..." -``` - ---- - -## How It Works - -``` -┌─────────────────┐ -│ You code with │ -│ Claude today │ -└────────┬────────┘ - │ - ▼ -┌─────────────────────────────┐ -│ claude-mem captures & │ -│ compresses everything │ -│ into structured memories │ -└────────┬────────────────────┘ - │ - ▼ -┌─────────────────────────────┐ -│ Tomorrow, Claude starts │ -│ with full context of │ -│ your project history │ -└─────────────────────────────┘ -``` - -**Automatic. Zero effort. Always on.** - ---- - -## What Gets Remembered - -✓ **Decisions**: "Why did we choose this architecture?" -✓ **Bugs Fixed**: "How did we solve this before?" -✓ **Code Patterns**: "What's our convention for this?" -✓ **File Changes**: "What did we modify last session?" -✓ **Refactorings**: "What was the old implementation?" -✓ **Dependencies**: "Which libraries are we using?" - -Everything Claude does with you gets compressed into **searchable, reusable memory**. - ---- - -## Powerful Search - -Ask Claude to search your project history: - -``` -You: "Find all the database migrations we did" -Claude: [Searches across all sessions] - "I found 7 database-related changes: - - March 15: Added user_preferences table - - March 12: Migration for OAuth tokens - - March 8: Index optimization on sessions - ..." - -You: "What decisions did we make about authentication?" -Claude: [Retrieves decision observations] - "We decided to use JWT tokens because..." -``` - -7 specialized search tools. Instant recall. Full project history. - ---- - -## The Numbers - -| Metric | Before | After | -|--------|--------|-------| -| Context repetition | Every session | Never | -| Onboarding time | 5-10 min per session | 0 seconds | -| Bug re-investigation | Common | Rare | -| Architectural questions | "What did we decide?" | Claude already knows | -| Code pattern consistency | Manual enforcement | Automatic | - ---- - -## Installation - -### Quick Start (2 minutes) - -```bash -# 1. Clone and install -git clone https://github.com/thedotmack/claude-mem.git -cd claude-mem - -# 2. Add to Claude Code -/plugin marketplace add .claude-plugin/marketplace.json - -# 3. Install -/plugin install claude-mem -``` - -**Done.** Claude now has memory. - ---- - -## Configuration - -Choose your AI model (controls cost vs. quality of memory compression): - -```bash -./claude-mem-settings.sh -``` - -**Models:** -- `claude-haiku-4-5` - Fast & cheap -- `claude-sonnet-4-5` - Balanced (default) ✓ -- `claude-opus-4` - Maximum quality - ---- - -## Under The Hood - -**Simple architecture, powerful results:** - -1. **Hooks** capture every tool Claude uses -2. **Worker service** compresses observations with AI -3. **SQLite database** stores structured memories -4. **MCP server** makes everything searchable -5. **Context injection** gives Claude the right memories at the right time - -**Zero maintenance. Runs in the background. Just works.** - ---- - -## Use Cases - -### Solo Developers -- Never lose context between coding sessions -- Build on past decisions automatically -- Remember why you made each choice - -### Team Projects -- Share architectural knowledge across sessions -- Maintain consistency in code patterns -- Document decisions as they happen - -### Learning & Experiments -- Track what you tried and what worked -- Build a personal knowledge base -- Learn from past mistakes - -### Large Refactors -- Remember what you changed across multiple sessions -- Track progress on multi-day tasks -- Maintain context through interruptions - ---- - -## What Developers Say - -> *"I used to spend 10 minutes every morning explaining my project to Claude. Now it just knows."* - -> *"It's like having a teammate who was actually there for every line of code."* - -> *"The search is incredible. I can ask about decisions we made weeks ago."* - ---- - -## FAQ - -**Does this slow down Claude?** -No. Memory processing happens in the background. Claude responds instantly. - -**How much does it cost?** -Minimal. Memory compression uses your chosen model (default: Sonnet 4.5). Typical cost: $0.01-0.05 per coding session. - -**Where is data stored?** -Locally in `~/.claude-mem/claude-mem.db`. Fully private. Never leaves your machine. - -**Can I search my memories?** -Yes. 7 specialized search tools available through Claude. - -**Does it work with existing projects?** -Yes. Starts learning immediately when installed. - -**What if I want to forget something?** -Delete observations directly from the SQLite database, or start fresh by removing the DB file. - ---- - -## Get Started - -```bash -git clone https://github.com/thedotmack/claude-mem.git -cd claude-mem -/plugin marketplace add .claude-plugin/marketplace.json -/plugin install claude-mem -``` - -**Give Claude a memory. Transform how you code.** - ---- - -## Learn More - -- [Technical Documentation](./CLAUDE.md) -- [GitHub Repository](https://github.com/thedotmack/claude-mem) -- [Report Issues](https://github.com/thedotmack/claude-mem/issues) - -**License**: AGPL-3.0 -**Version**: 4.1.0 -**Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack)) diff --git a/PLAN-USER-PROMPT-STORAGE.md b/PLAN-USER-PROMPT-STORAGE.md deleted file mode 100644 index edebcefe..00000000 --- a/PLAN-USER-PROMPT-STORAGE.md +++ /dev/null @@ -1,246 +0,0 @@ -# Plan: Store Raw User Prompts for Full Context Search - -## Problem - -Claude-mem currently only captures tool executions (via PostToolUse hook), not the user's actual instructions and requests. This creates a gap: - -- We can see WHAT Claude did (observations) -- We can see SUMMARIES of what happened (session_summaries) -- We CANNOT see what the user actually said/requested - -**Real Example:** -User repeatedly asked to "remove session validation" with increasing frustration over multiple prompts. The memory system captured the final implementation but not the conversation where the user had to convince Claude 3-4 times. - -## Solution - -Store ALL raw user prompts in a dedicated table with full-text search capability. - -## Database Schema Changes - -### 1. Create `user_prompts` table - -```sql -CREATE TABLE user_prompts ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - sdk_session_id TEXT NOT NULL, - prompt_number INTEGER NOT NULL, - prompt_text TEXT NOT NULL, - created_at TEXT NOT NULL, - created_at_epoch INTEGER NOT NULL, - FOREIGN KEY(sdk_session_id) REFERENCES sdk_sessions(sdk_session_id) ON DELETE CASCADE -); - -CREATE INDEX idx_user_prompts_sdk_session ON user_prompts(sdk_session_id); -CREATE INDEX idx_user_prompts_created ON user_prompts(created_at_epoch DESC); -CREATE INDEX idx_user_prompts_prompt_number ON user_prompts(prompt_number); -``` - -### 2. Create FTS5 virtual table for full-text search - -```sql -CREATE VIRTUAL TABLE user_prompts_fts USING fts5( - prompt_text, - content='user_prompts', - content_rowid='id' -); -``` - -### 3. Create triggers to sync FTS5 - -```sql -CREATE TRIGGER user_prompts_ai AFTER INSERT ON user_prompts BEGIN - INSERT INTO user_prompts_fts(rowid, prompt_text) - VALUES (new.id, new.prompt_text); -END; - -CREATE TRIGGER user_prompts_ad AFTER DELETE ON user_prompts BEGIN - INSERT INTO user_prompts_fts(user_prompts_fts, rowid, prompt_text) - VALUES('delete', old.id, old.prompt_text); -END; - -CREATE TRIGGER user_prompts_au AFTER UPDATE ON user_prompts BEGIN - INSERT INTO user_prompts_fts(user_prompts_fts, rowid, prompt_text) - VALUES('delete', old.id, old.prompt_text); - INSERT INTO user_prompts_fts(rowid, prompt_text) - VALUES (new.id, new.prompt_text); -END; -``` - -## Code Changes - -### 1. Update schema migration - -**File:** `src/services/sqlite/SessionStore.ts` - -Add the user_prompts table creation to the schema initialization (look for the `CREATE TABLE` statements in the constructor). - -### 2. Add method to save user prompts - -**File:** `src/services/sqlite/SessionStore.ts` - -```typescript -/** - * Save a user prompt - */ -saveUserPrompt(sdkSessionId: string, promptNumber: number, promptText: string): number { - const now = new Date(); - const nowEpoch = now.getTime(); - - const stmt = this.db.prepare(` - INSERT INTO user_prompts - (sdk_session_id, prompt_number, prompt_text, created_at, created_at_epoch) - VALUES (?, ?, ?, ?, ?) - `); - - const result = stmt.run(sdkSessionId, promptNumber, promptText, now.toISOString(), nowEpoch); - return result.lastInsertRowid as number; -} -``` - -### 3. Update new-hook to save user prompts - -**File:** `src/hooks/new.ts` - -After creating/getting the session and incrementing prompt counter, save the raw prompt: - -```typescript -// Around line 37, after incrementPromptCounter -const sessionDbId = db.createSDKSession(session_id, project, prompt); -const promptNumber = db.incrementPromptCounter(sessionDbId); - -// Get sdk_session_id for foreign key -const session = db.findAnySDKSession(session_id); -if (session?.sdk_session_id) { - db.saveUserPrompt(session.sdk_session_id, promptNumber, prompt); -} - -console.error(`[new-hook] Session ${sessionDbId}, prompt #${promptNumber}`); -``` - -**Note:** We need the sdk_session_id (not just sessionDbId) for the foreign key. May need to adjust the logic to handle prompts before SDK session is fully initialized. - -### 4. Add SessionSearch methods - -**File:** `src/services/sqlite/SessionSearch.ts` - -```typescript -/** - * Search user prompts with full-text search - */ -searchUserPrompts(query: string, options: SearchOptions = {}): UserPrompt[] { - const { limit = 20, offset = 0 } = options; - - const stmt = this.db.prepare(` - SELECT - up.id, - up.sdk_session_id, - up.prompt_number, - up.prompt_text, - up.created_at, - up.created_at_epoch - FROM user_prompts_fts fts - JOIN user_prompts up ON fts.rowid = up.id - WHERE user_prompts_fts MATCH ? - ORDER BY rank - LIMIT ? OFFSET ? - `); - - return stmt.all(query, limit, offset) as UserPrompt[]; -} - -/** - * Get all prompts for a session - */ -getUserPromptsBySession(sdkSessionId: string): UserPrompt[] { - const stmt = this.db.prepare(` - SELECT - id, - sdk_session_id, - prompt_number, - prompt_text, - created_at, - created_at_epoch - FROM user_prompts - WHERE sdk_session_id = ? - ORDER BY prompt_number ASC - `); - - return stmt.all(sdkSessionId) as UserPrompt[]; -} -``` - -Add the `UserPrompt` type: - -```typescript -interface UserPrompt { - id: number; - sdk_session_id: string; - prompt_number: number; - prompt_text: string; - created_at: string; - created_at_epoch: number; -} -``` - -### 5. Add MCP search tool - -**File:** `src/servers/search-server.ts` - -Add a new tool `search_user_prompts`: - -```typescript -{ - name: 'search_user_prompts', - description: 'Search raw user prompts with full-text search. Use this to find what the user actually said/requested across all sessions.', - inputSchema: zodToJsonSchema(z.object({ - query: z.string().describe('Search query for FTS5 full-text search'), - limit: z.number().optional().default(20).describe('Maximum results'), - offset: z.number().optional().default(0).describe('Results to skip'), - })) -} -``` - -And implement the handler. - -## Benefits - -1. **Full context reconstruction:** See exact user language, frustration level, repeated requests -2. **Pattern detection:** Identify when Claude isn't listening (user repeats same request) -3. **Improved summaries:** AI can reference actual user words, not just observations -4. **Debugging:** Trace from user request → Claude actions → outcomes -5. **Search across time:** "How many times did user ask for X feature?" - -## Testing - -1. Create a new session and submit several prompts -2. Query `user_prompts` table to verify they're saved -3. Test FTS5 search: `SELECT * FROM user_prompts_fts WHERE user_prompts_fts MATCH 'validation'` -4. Test MCP tool: `/claude-mem search_user_prompts "remove validation"` -5. Verify prompt_number increments correctly -6. Test cascade delete: delete a session, verify prompts are deleted - -## Migration Notes - -- This is a NEW table, no data migration needed -- Existing sessions won't have historical prompts (that's fine) -- FTS5 triggers will auto-populate as new prompts arrive - -## Open Questions - -1. **sdk_session_id timing:** New-hook runs BEFORE worker initializes SDK session. Need to either: - - Save prompts with sessionDbId initially, update with sdk_session_id later - - OR use sessionDbId as the foreign key instead - -2. **Storage size:** User prompts can be large. Consider max length or compression? - -3. **Privacy:** User prompts may contain sensitive info. Document this clearly. - -## Implementation Order - -1. Add schema to SessionStore constructor -2. Add saveUserPrompt method to SessionStore -3. Add search methods to SessionSearch -4. Update new-hook to save prompts -5. Add MCP tool to search-server -6. Test end-to-end -7. Update CLAUDE.md documentation diff --git a/README.md b/README.md index e40d34f7..60d542cf 100644 --- a/README.md +++ b/README.md @@ -33,22 +33,30 @@ Restart Claude Code. Context from previous sessions will automatically appear in ## Documentation +📚 **[View Full Documentation](docs/)** - Browse markdown docs on GitHub + +💻 **Local Preview**: Run Mintlify docs locally: +```bash +cd docs +npx mintlify dev +``` + ### Getting Started -- **[Installation Guide](docs/installation.md)** - Quick start & advanced installation -- **[Usage Guide](docs/usage/getting-started.md)** - How Claude-Mem works automatically -- **[MCP Search Tools](docs/usage/search-tools.md)** - Query your project history +- **[Installation Guide](docs/installation.mdx)** - Quick start & advanced installation +- **[Usage Guide](docs/usage/getting-started.mdx)** - How Claude-Mem works automatically +- **[MCP Search Tools](docs/usage/search-tools.mdx)** - Query your project history ### Architecture -- **[Overview](docs/architecture/overview.md)** - System components & data flow -- **[Hooks](docs/architecture/hooks.md)** - 5 lifecycle hooks explained -- **[Worker Service](docs/architecture/worker-service.md)** - HTTP API & PM2 management -- **[Database](docs/architecture/database.md)** - SQLite schema & FTS5 search -- **[MCP Search](docs/architecture/mcp-search.md)** - 7 search tools & examples +- **[Overview](docs/architecture/overview.mdx)** - System components & data flow +- **[Hooks](docs/architecture/hooks.mdx)** - 5 lifecycle hooks explained +- **[Worker Service](docs/architecture/worker-service.mdx)** - HTTP API & PM2 management +- **[Database](docs/architecture/database.mdx)** - SQLite schema & FTS5 search +- **[MCP Search](docs/architecture/mcp-search.mdx)** - 7 search tools & examples ### Configuration & Development -- **[Configuration](docs/configuration.md)** - Environment variables & settings -- **[Development](docs/development.md)** - Building, testing, contributing -- **[Troubleshooting](docs/troubleshooting.md)** - Common issues & solutions +- **[Configuration](docs/configuration.mdx)** - Environment variables & settings +- **[Development](docs/development.mdx)** - Building, testing, contributing +- **[Troubleshooting](docs/troubleshooting.mdx)** - Common issues & solutions --- @@ -82,7 +90,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in 3. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search 4. **7 MCP Search Tools** - Query historical context with citations -See [Architecture Overview](docs/architecture/overview.md) for details. +See [Architecture Overview](docs/architecture/overview.mdx) for details. --- @@ -106,7 +114,7 @@ search_user_prompts with query="add dark mode" get_recent_context with limit=5 ``` -See [MCP Search Tools Guide](docs/usage/search-tools.md) for detailed examples. +See [MCP Search Tools Guide](docs/usage/search-tools.mdx) for detailed examples. --- @@ -170,7 +178,7 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history. - `CLAUDE_MEM_WORKER_PORT` - Worker port (default: 37777) - `CLAUDE_MEM_DATA_DIR` - Data directory override (dev only) -See [Configuration Guide](docs/configuration.md) for details. +See [Configuration Guide](docs/configuration.mdx) for details. --- @@ -193,7 +201,7 @@ npm run worker:start npm run worker:logs ``` -See [Development Guide](docs/development.md) for detailed instructions. +See [Development Guide](docs/development.mdx) for detailed instructions. --- @@ -205,7 +213,7 @@ See [Development Guide](docs/development.md) for detailed instructions. - Database issues → `sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"` - Search not working → Check FTS5 tables exist -See [Troubleshooting Guide](docs/troubleshooting.md) for complete solutions. +See [Troubleshooting Guide](docs/troubleshooting.mdx) for complete solutions. --- @@ -219,7 +227,7 @@ Contributions are welcome! Please: 4. Update documentation 5. Submit a Pull Request -See [Development Guide](docs/development.md) for contribution workflow. +See [Development Guide](docs/development.mdx) for contribution workflow. --- diff --git a/context/architecture/REFACTOR-PLAN.md b/context/architecture/v3-to-v4.md similarity index 99% rename from context/architecture/REFACTOR-PLAN.md rename to context/architecture/v3-to-v4.md index 3514d18c..d2fbe56e 100644 --- a/context/architecture/REFACTOR-PLAN.md +++ b/context/architecture/v3-to-v4.md @@ -1,4 +1,6 @@ -# Claude-Mem Architecture Refactor Plan +# Claude-Mem Architecture v3 to v4 Plan (✅ Completed) + +This file exists as a reference to explain the path forward from v3 to v4. ## Core Purpose diff --git a/context/magic-ui/components-catalog.md b/context/magic-ui/components-catalog.md deleted file mode 100644 index 54f38493..00000000 --- a/context/magic-ui/components-catalog.md +++ /dev/null @@ -1,283 +0,0 @@ -# Magic UI Components Catalog - -Complete catalog of Magic UI components with descriptions and use cases. - -## Animation Components - -### 1. **Animated List** -- **Purpose**: Animates list items sequentially with delay -- **Use Case**: Showcasing events, notifications, feature lists -- **Key Props**: `delay` (ms between items) -- **Effect**: Staggered reveal animation - -### 2. **Text Animate** -- **Purpose**: Sophisticated text animation effects -- **Animation Types**: - - `blurIn` - Characters fade from blur - - `slideUp` - Words slide up - - `scaleUp` - Text scales up - - `fadeIn` - Lines fade in - - `slideLeft` - Characters slide from left -- **Animate By**: `character`, `word`, `text`, `line` -- **Use Case**: Hero headlines, feature announcements, storytelling -- **Customization**: Delay, duration, custom motion variants - -### 3. **Flip Text** -- **Purpose**: Vertical flip animation for text -- **Key Props**: `duration`, `delayMultiple`, custom variants -- **Use Case**: Eye-catching headlines, call-to-actions - -### 4. **Morphing Text** -- **Purpose**: Dynamic text transitions between multiple strings -- **Key Props**: `texts` array (strings to morph between) -- **Use Case**: Dynamic value propositions, rotating benefits - -### 5. **Word Rotate** -- **Purpose**: Vertical rotation of words -- **Key Props**: `words` (string array), `duration` (2500ms default) -- **Use Case**: Rotating feature names, dynamic headlines - -### 6. **Aurora Text** -- **Purpose**: Beautiful aurora text effect -- **Key Props**: `colors` array, `speed` multiplier -- **Default Colors**: `["#FF0080", "#7928CA", "#0070F3", "#38bdf8"]` -- **Use Case**: Premium headlines, brand emphasis - -## Visual Effect Components - -### 7. **Orbiting Circles** -- **Purpose**: Circles moving in orbit along circular paths -- **Key Props**: - - `radius` (orbit size) - - `duration` (animation speed) - - `reverse` (direction) - - `delay`, `path` (show orbit path) - - `iconSize`, `speed` -- **Use Case**: Technology visualization, ecosystem diagrams, feature satellites - -### 8. **Particles** -- **Purpose**: Animated particle background with depth and interactivity -- **Use Case**: Hero sections, immersive backgrounds - -### 9. **Confetti** -- **Purpose**: Celebration confetti effect -- **Key Props**: - - `particleCount`, `angle`, `spread` - - `startVelocity`, `decay`, `gravity` - - `colors`, `shapes` (square, circle, star) - - `origin` point -- **Includes**: `ConfettiButton` wrapper component -- **Use Case**: Success states, milestones, achievements - -### 10. **Border Beam** -- **Purpose**: Animated beam effect along borders -- **Key Props**: `reverse`, spring animations -- **Use Case**: Card highlights, section emphasis - -### 11. **Shine Border** -- **Purpose**: Animated shining border effect -- **Key Props**: `color` array, `borderWidth`, `duration` -- **Use Case**: Premium cards, CTAs, feature boxes - -### 12. **Magic Card** -- **Purpose**: Spotlight effect following mouse cursor with border highlights -- **Key Props**: - - `gradientSize` (200 default) - - `gradientColor` (#262626 default) - - `gradientOpacity` (0.8) - - `gradientFrom`/`gradientTo` (border colors) -- **Use Case**: Interactive feature cards, pricing tables - -## Background Components - -### 13. **Grid Beams** -- **Purpose**: Dynamic grid background with animated light beams -- **Key Props**: - - `gridSize` (40px default) - - `gridColor` (rgba) - - `rayCount` (15 default) - - `rayOpacity` (0.35) - - `raySpeed`, `rayLength` (45vh) - - `gridFadeStart`/`gridFadeEnd` (%) - - `backgroundColor` -- **Use Case**: Hero sections, feature backgrounds, immersive layouts - -### 14. **Warp Background** -- **Purpose**: Warped perspective grid effect -- **Key Props**: - - `perspective` (depth) - - `beamsPerSide` (4 default) - - `beamSize` (thickness) - - `beamDuration` (speed) - - `gridColor` -- **Use Case**: Futuristic hero sections, tech-focused pages - -### 15. **Dot Pattern** -- **Purpose**: Customizable dotted background pattern (SVG) -- **Key Props**: `width`, `height`, `cx`, `cy`, `cr` (dot radius) -- **Effects**: Supports glow effects -- **Use Case**: Subtle backgrounds, section dividers - -## Interactive Components - -### 16. **Dock** -- **Purpose**: macOS-style dock with magnification effect -- **Key Props**: - - `iconMagnification` (zoom amount) - - `iconDistance` (hover range) - - `direction` (middle, start, end) -- **Child Component**: `DockIcon` -- **Use Case**: Navigation, tool showcases, social links - -### 17. **Scratch To Reveal** -- **Purpose**: Interactive scratch-off effect revealing hidden content -- **Key Props**: - - `width`, `height` - - `minScratchPercentage` (50 default, completion threshold) - - `onComplete` callback - - `gradientColors` -- **Use Case**: Interactive reveals, gamification, teasers - -### 18. **Highlighter** -- **Purpose**: Animated text highlighting and underlining -- **Key Props**: - - `color` - - `strokeWidth` - - `action` (underline, highlight) - - `animationDuration` - - `iterations`, `padding` -- **Use Case**: Emphasis on key phrases, call-outs - -## Layout/Display Components - -### 19. **Marquee** -- **Purpose**: Scrolling content (horizontal or vertical) -- **Key Props**: - - `reverse` (direction) - - `pauseOnHover` - - `vertical` (orientation) - - `repeat` (count) -- **Effects**: 3D perspective option -- **Use Case**: Testimonials, logo clouds, infinite scrollers - -### 20. **Safari** -- **Purpose**: Safari browser mockup for showcasing -- **Key Props**: - - `url` (address bar) - - `imageSrc` or `videoSrc` - - `width` (1203 default), `height` (753) - - `mode` (default, simple) -- **Use Case**: Product demos, website previews - -### 21. **Bento Grid** -- **Purpose**: Grid layout for organizing content -- **Use Case**: Feature showcases, portfolios - -### 22. **Avatar Circles** -- **Purpose**: Overlapping circles of avatars -- **Key Props**: `numPeople` (99 default, shown in last circle) -- **Use Case**: Social proof, team displays, user counts - -## Timeline Components - -### 23. **Arc Timeline** -- **Purpose**: Curved timeline visualizing milestones -- **Key Props**: - - `data` (array of {time, title}) - - `arcConfig`: - - `circleWidth` (5000 default) - - `angleBetweenMinorSteps` (0.35) - - `lineCountFillBetweenSteps` (10) - - `boundaryPlaceholderLinesCount` (50) - - `defaultActiveStep` ({time, stepIndex}) -- **Use Case**: Project roadmaps, product evolution, version history - -## Button Components - -### 24. **Shiny Button** -- **Purpose**: Button with shiny effect -- **Features**: Dark/light mode support -- **Use Case**: Primary CTAs, important actions - -### 25. **Pulsating Button** -- **Purpose**: Button with pulsing wave animation -- **Key Props**: `pulseColor` (RGB), `duration` -- **Use Case**: Attention-grabbing CTAs, urgent actions - -### 26. **Rainbow Button** -- **Purpose**: Rainbow gradient button effect -- **Variants**: Default, Outline -- **Use Case**: Premium CTAs, playful actions - -## Theme Components - -### 27. **Animated Theme Toggler** -- **Purpose**: Smooth animated light/dark mode toggle -- **Built With**: Tailwind CSS -- **Use Case**: Theme switching UI - ---- - -## Installation - -```bash -# Via CLI (recommended) -npx shadcn-ui@latest add [component-name] - -# Manual installation -npm install magicui -# or -yarn add magicui -``` - -## Component Categories Summary - -| Category | Components | Best For | -|----------|-----------|----------| -| **Text Animation** | Animated List, Text Animate, Flip Text, Morphing Text, Word Rotate, Aurora Text | Headlines, feature lists, dynamic content | -| **Visual Effects** | Orbiting Circles, Particles, Confetti, Border Beam, Shine Border, Magic Card | Visual interest, interactivity, emphasis | -| **Backgrounds** | Grid Beams, Warp Background, Dot Pattern | Hero sections, immersive layouts | -| **Interactive** | Dock, Scratch To Reveal, Highlighter | User engagement, gamification | -| **Layout** | Marquee, Safari, Bento Grid, Avatar Circles | Content organization, showcases | -| **Timeline** | Arc Timeline | Roadmaps, history, progression | -| **Buttons** | Shiny Button, Pulsating Button, Rainbow Button | CTAs, actions | -| **Utility** | Animated Theme Toggler | UI controls | - -## Design Philosophy - -Magic UI components focus on: -- **Delight**: Unexpected animations that create joy -- **Fluidity**: Smooth, natural motion -- **Performance**: Optimized for web performance -- **Flexibility**: Highly customizable via props -- **Modern**: Built with React, Tailwind CSS, Framer Motion - -## Use Case Recommendations by Landing Page Section - -### Hero Sections -- Grid Beams or Warp Background (background) -- Aurora Text or Morphing Text (headline) -- Pulsating Button or Rainbow Button (CTA) -- Orbiting Circles (tech visualization) - -### Feature Showcases -- Bento Grid (layout) -- Magic Card (individual features) -- Animated List (feature details) -- Highlighter (emphasis) - -### Social Proof -- Marquee (testimonials/logos) -- Avatar Circles (user counts) - -### Product Demos -- Safari (browser mockups) -- Border Beam or Shine Border (emphasis) - -### Roadmaps/Progress -- Arc Timeline (milestones) - -### Interactive Elements -- Scratch To Reveal (teasers) -- Dock (navigation/tools) -- Confetti (celebrations) diff --git a/context/magic-ui/creative-ideas.md b/context/magic-ui/creative-ideas.md deleted file mode 100644 index 5a0b9650..00000000 --- a/context/magic-ui/creative-ideas.md +++ /dev/null @@ -1,471 +0,0 @@ -# Magic UI Landing Page Creative Ideas - -Creative applications of Magic UI components for each section of the claude-mem landing page. - -## Section 1: HERO - "Claude Never Forgets" - -### Idea 1: "Fading Memory" Effect ⭐ WINNER -**Components**: Morphing Text, Grid Beams, Orbiting Circles, Scratch To Reveal - -**Vision**: -- **Headline**: Morphing Text rotating between: - - "Claude Never Forgets" - - "Claude Always Remembers" - - "Claude Learns Forever" -- **Background**: Grid Beams in blue/purple gradient representing the "memory grid" -- **Central Visual**: Orbiting Circles around a central "brain/database" icon - - Inner orbit: File icons (representing code files) - - Middle orbit: Lightbulb icons (decisions) - - Outer orbit: Bug icons (fixes) -- **Problem Statement**: Scratch To Reveal overlay - - User must scratch to reveal: "Every /clear wipes Claude's memory" - - Makes the pain point visceral and interactive -- **CTA**: Pulsating Button "Give Claude a Memory" - -### Idea 2: "Memory Timeline" Hero -**Components**: Warp Background, Arc Timeline, Aurora Text, Word Rotate - -**Vision**: -- Warp Background creating perspective depth -- Arc Timeline showing "Session 1 → Session 2 → Session 3" with memories persisting across -- Aurora Text for main headline with flowing gradient -- Word Rotate cycling pain points: "Repeating" → "Explaining" → "Re-discovering" → "Forgetting" - -### Idea 3: "Brain Storage" Visualization -**Components**: Particles, Magic Card, Highlighter, Pulsating Button - -**Vision**: -- Particles background (subtle, neuron-like firing) -- Central Magic Card with spotlight effect containing headline -- Highlighter emphasizing "Never" and "Forgets" with animated underlines -- Pulsating Button for CTA with urgency - ---- - -## Section 2: BEFORE/AFTER Comparison - -### Idea 1: "Split Screen Wipe" ⭐ WINNER -**Components**: Safari, Text Animate, Border Beam, Scratch To Reveal - -**Vision**: -- Two Safari browser mockups side by side -- **Left (Before)**: Conversation fades/blurs out showing memory loss -- **Right (After)**: Sharp, persistent content with Border Beam highlighting -- Text Animate with slideUp for conversations appearing sequentially -- Optional: Scratch To Reveal over "Before" side to uncover the painful reality - -### Idea 2: "Memory Decay Visualization" -**Components**: Text Animate, Shine Border, Magic Card, Animated Theme Toggler - -**Vision**: -- Before side: Text with progressive fade-out animation (opacity decreasing) -- After side: Text with Shine Border, glowing persistently -- Magic Card on After side with spotlight following mouse -- Animated Theme Toggler metaphorically switching "forgetting" → "remembering" - -### Idea 3: "Conversation Replay" -**Components**: Animated List, Border Beam, Highlighter - -**Vision**: -- Animated List showing conversation history -- Before: List items fade out and disappear sequentially -- After: List items persist, Border Beam appears on referenced items -- Highlighter underlining key persistent information on After side - ---- - -## Section 3: REAL EXAMPLES (3 Scenarios) - -### Idea 1: "Tabbed Experience" -**Components**: Bento Grid, Magic Card, Text Animate, Flip Text, Confetti - -**Vision**: -- Bento Grid layout with 3 Magic Cards (one per scenario) -- Each card has spotlight effect on hover -- Text Animate (blurIn) for code examples appearing -- Flip Text for headings revealing scenario names -- Confetti burst when clicking through to third example (pattern recognized!) - -### Idea 2: "Timeline Story" ⭐ WINNER -**Components**: Arc Timeline, Orbiting Circles, Highlighter, Animated List - -**Vision**: -- Arc Timeline showing progression: "Monday Session" → "Wednesday Session" -- Each timeline node expands to show the scenario details -- Orbiting Circles around active node showing: - - Files involved (icons in orbit) - - Decisions made (decision icons) - - Bugs fixed (bug icons) -- Highlighter emphasizing key remembered details in the expanded content -- Animated List revealing the bulleted "Claude remembers" items - -### Idea 3: "Memory Card Flip" -**Components**: Scratch To Reveal, Magic Card, Pulsating Button, Word Rotate - -**Vision**: -- Three cards with Scratch To Reveal overlay -- Scratch to reveal what Claude remembers from previous sessions -- Magic Card underneath with gradient borders -- Pulsating Button to cycle through scenarios -- Word Rotate showing memory types: "Patterns" → "Decisions" → "Context" → "Architecture" - ---- - -## Section 4: HOW IT WORKS (Pipeline) - -### Idea 1: "Animated Data Flow" -**Components**: Magic Card, Orbiting Circles, Border Beam, Text Animate, Particles - -**Vision**: -- Three connected Magic Cards showing pipeline stages: - 1. "You code with Claude today" - 2. "claude-mem captures & compresses" - 3. "Tomorrow, Claude starts with context" -- Orbiting Circles representing data flowing between stages -- Border Beam animating along connections between cards -- Text Animate (slideUp) for each stage description on scroll -- Particles flowing from one stage to the next - -### Idea 2: "Arc Timeline as Process" -**Components**: Arc Timeline, Orbiting Circles, Warp Background, Animated List, Shine Border - -**Vision**: -- Arc Timeline showing 5 steps of memory system -- Each node has Orbiting Circles showing components (hooks, worker, DB, MCP, context) -- Warp Background creating depth -- Animated List revealing sub-bullets under each stage -- Shine Border on active/hovered stage - -### Idea 3: "Layered Depth Model" ⭐ WINNER -**Components**: Grid Beams, Magic Card, Border Beam, Morphing Text, Highlighter - -**Vision**: -- Grid Beams background representing the "storage layer" -- Three floating Magic Cards in z-space (perspective/depth): - - Top layer: "Hooks capture" - - Middle layer: "AI compresses" - - Bottom layer: "Database stores" -- Arrows with Border Beam animation showing data flow downward -- Morphing Text showing state transformation: "Capturing" → "Compressing" → "Storing" → "Retrieving" -- Highlighter emphasizing "Automatic. Zero effort. Always on." - ---- - -## Section 5: WHAT GETS REMEMBERED (Feature List) - -### Idea 1: "Checkbox Delight" -**Components**: Animated List, Text Animate, Highlighter, Confetti, Magic Card - -**Vision**: -- Animated List of 6 checkmark items -- Each item appears with Text Animate (blurIn by character) -- Highlighter underlining key words: "Decisions", "Bugs Fixed", "Code Patterns", etc. -- Confetti burst when all items are visible (celebration of completeness) -- Magic Card container with subtle spotlight effect - -### Idea 2: "Memory Bank Slots" ⭐ WINNER -**Components**: Bento Grid, Scratch To Reveal, Shine Border, Orbiting Circles, Pulsating Button - -**Vision**: -- Bento Grid of 6 cards (one per memory type) -- Each card has Scratch To Reveal to discover what gets saved (gamification!) -- Shine Border appears around revealed cards -- Orbiting Circles showing example icons around each card type -- Pulsating indicator on most important memory types - -### Idea 3: "Collector Animation" -**Components**: Magic Card, Border Beam, Flip Text, Aurora Text, Dot Pattern - -**Vision**: -- Six Magic Cards arranged in grid -- Border Beam cascading through cards in sequence -- Each card flips (Flip Text) to reveal icon + description -- Aurora Text for section heading -- Dot Pattern background with subtle glow on active items - ---- - -## Section 6: POWERFUL SEARCH - -### Idea 1: "Live Search Demo" ⭐ WINNER -**Components**: Safari, Text Animate, Animated List, Highlighter, Border Beam, Morphing Text - -**Vision**: -- Safari browser mockup showing search interface -- Text Animate typing out search queries with realistic timing: - - "Find all database migrations..." - - "What decisions about authentication..." -- Animated List revealing search results sequentially -- Highlighter emphasizing matched keywords in results -- Border Beam around result cards -- Morphing Text cycling search types: "Migrations" → "Decisions" → "Patterns" → "Bugs" - -### Idea 2: "Search Radar" -**Components**: Orbiting Circles, Magic Card, Particles, Text Animate, Grid Beams - -**Vision**: -- Orbiting Circles representing different search dimensions: - - Inner orbit: File search - - Middle orbit: Concept search - - Outer orbit: Type/date filters -- Central Magic Card with search query -- Particles radiating outward to show search happening -- Results appear with Text Animate (slideUp) -- Grid Beams background representing indexed database - -### Idea 3: "Memory Retrieval Visualization" -**Components**: Warp Background, Aurora Text, Magic Card, Shine Border, Dock, Confetti - -**Vision**: -- Warp Background creating depth into "memory storage" -- Search query in Aurora Text -- Seven Magic Cards (one per search tool) with Shine Border -- Dock component at bottom showing 7 search tool icons -- Confetti when "perfect match" is found - ---- - -## Section 7: THE NUMBERS (Metrics Table) - -### Idea 1: "Counting Animation" -**Components**: Safari, Text Animate, Aurora Text, Confetti, Border Beam - -**Vision**: -- Safari mockup showing comparison table -- Text Animate for each metric value counting up -- "Before" values in faded text -- "After" values with Aurora Text effect (glowing) -- Confetti when hovering over dramatic improvements -- Border Beam highlighting entire "After" column - -### Idea 2: "Progress Bar Transformation" ⭐ WINNER -**Components**: Magic Card, Morphing Text, Shine Border, Pulsating Button - -**Vision**: -- Five Magic Cards, one per metric -- Animated progress bars showing transformation: - - Before (low/red) → After (high/green) - - Visual representation of improvement -- Morphing Text cycling through metrics -- Shine Border on cards with biggest improvements -- Pulsating Button: "See the Difference" - -### Idea 3: "Flip Cards Reveal" -**Components**: Scratch To Reveal, Magic Card, Highlighter, Animated List - -**Vision**: -- Five cards with Scratch To Reveal -- Scratch "Before" to reveal "After" metrics -- Each card has Magic Card spotlight effect -- Highlighter emphasizing: "Never", "0 seconds", "Rare" -- Animated List showing additional benefits below table - ---- - -## Section 8: INSTALLATION (Quick Start) - -### Idea 1: "Copy-Paste Delight" ⭐ WINNER -**Components**: Safari, Text Animate, Shiny Button, Confetti, Animated List, Highlighter - -**Vision**: -- Safari mockup showing terminal window -- Text Animate typing out commands with realistic timing (typewriter effect) -- Shiny Button next to each command for copy -- Confetti celebration when installation completes -- Animated List showing 3 steps with checkmarks appearing -- Highlighter emphasizing "2 minutes" - -### Idea 2: "Progress Stepper" -**Components**: Arc Timeline, Border Beam, Magic Card, Pulsating Button, Word Rotate - -**Vision**: -- Arc Timeline with 3 nodes: Clone → Add → Install -- Each step expands to show code when active -- Border Beam connecting steps as they complete -- Magic Card for code blocks with spotlight -- Pulsating Button for "Get Started" -- Word Rotate: "Simple" → "Fast" → "Easy" → "Done" - -### Idea 3: "Interactive Terminal" -**Components**: Grid Beams, Safari, Text Animate, Orbiting Circles, Rainbow Button, Shine Border - -**Vision**: -- Grid Beams background (tech aesthetic) -- Safari terminal mockup -- Text Animate simulating command execution -- Orbiting Circles showing installed components appearing -- Rainbow Button for final "Installation Complete" CTA -- Shine Border around success message - ---- - -## Section 9: UNDER THE HOOD (Architecture) - -### Idea 1: "System Diagram" -**Components**: Bento Grid, Magic Card, Orbiting Circles, Border Beam, Dot Pattern, Text Animate, Highlighter - -**Vision**: -- Bento Grid showing 5 architecture components: - - Hooks, Worker, Database, MCP, Context Injection -- Each grid cell is a Magic Card with spotlight -- Orbiting Circles showing data flow between components -- Border Beam animating along connections -- Dot Pattern background -- Text Animate for each component description -- Highlighter on "Zero maintenance. Just works." - -### Idea 2: "Layered Stack" ⭐ WINNER -**Components**: Magic Card, Warp Background, Morphing Text, Particles, Shine Border - -**Vision**: -- Five Magic Cards stacked with perspective (z-depth) -- Each layer slides out on scroll to reveal architecture: - 1. Hooks (top) - 2. Worker Service - 3. SQLite Database (center) - 4. MCP Server - 5. Context Injection (bottom) -- Warp Background creating depth -- Morphing Text showing active layer: "Hooks" → "Worker" → "SQLite" → "MCP" → "Context" -- Particles flowing between layers -- Shine Border on active layer - -### Idea 3: "Technical Orbits" -**Components**: Orbiting Circles, Grid Beams, Magic Card, Text Animate - -**Vision**: -- Central "SQLite DB" icon -- Orbiting Circles representing different systems: - - Inner orbit: 5 hooks (SessionStart, UserPrompt, PostTool, Summary, SessionEnd) - - Middle orbit: Worker service (PM2 process) - - Outer orbit: MCP server (7 search tools) - - Farthest orbit: Context injection -- Grid Beams background -- Magic Card for each orbit explanation -- Text Animate (slideUp) for technical details - ---- - -## Section 10: USE CASES (User Types) - -### Idea 1: "User Journey Cards" -**Components**: Bento Grid, Magic Card, Avatar Circles, Animated List, Flip Text, Border Beam - -**Vision**: -- Four Magic Cards in Bento Grid layout -- Each card has different gradient colors (gradientFrom/To) -- Avatar Circles showing user type icon -- Animated List of benefits per user type -- Flip Text for headings revealing user types -- Border Beam highlighting active/hovered card - -### Idea 2: "Role Selector" ⭐ WINNER -**Components**: Dock, Magic Card, Text Animate, Highlighter, Confetti - -**Vision**: -- Dock component with 4 icons representing user types: - - Solo Developer icon - - Team icon - - Learning/Student icon - - Large Refactor icon -- Click icon to expand that use case -- Magic Card expands with spotlight effect -- Text Animate revealing use case details -- Highlighter emphasizing key benefits -- Confetti celebration when selecting "your" use case (engagement!) - -### Idea 3: "Story Scenarios" -**Components**: Arc Timeline, Safari, Orbiting Circles, Morphing Text, Shine Border, Animated List - -**Vision**: -- Arc Timeline showing progression for each user type -- Safari mockup showing actual usage scenario -- Orbiting Circles around timeline nodes showing features being used -- Morphing Text cycling through user types -- Shine Border on selected use case -- Animated List showing specific benefits - ---- - -## Section 11: FAQ - -### Idea 1: "Expandable Cards" -**Components**: Magic Card, Text Animate, Border Beam, Highlighter, Dot Pattern, Animated List - -**Vision**: -- Six Magic Cards with questions visible -- Click to expand with Text Animate (blurIn) -- Border Beam appears on expanded card -- Highlighter emphasizing key answer points -- Dot Pattern background -- Animated List for multi-point answers - -### Idea 2: "Scratch to Answer" ⭐ WINNER -**Components**: Scratch To Reveal, Confetti, Magic Card, Morphing Text - -**Vision**: -- Questions visible, answers hidden under scratch surface -- Scratch To Reveal to see answers (highly engaging!) -- Confetti on revealing particularly important answers (e.g., "Fully private") -- Magic Card container with spotlight -- Morphing Text cycling through common concerns: "Cost?" → "Speed?" → "Privacy?" → "Storage?" - -### Idea 3: "Interactive Q&A" -**Components**: Bento Grid, Border Beam, Shine Border, Text Animate, Pulsating Button, Avatar Circles - -**Vision**: -- Bento Grid of question cards -- Hover triggers Border Beam -- Click expands with Shine Border -- Text Animate typing out answers -- Pulsating Button for "More Questions?" -- Avatar Circles showing "5,000+ developers trust claude-mem" - ---- - -## BONUS: Testimonials Section (Not in Original) - -### Idea 1: "Social Proof Marquee" -**Components**: Marquee (3D), Magic Card, Avatar Circles, Highlighter, Shine Border - -**Vision**: -- Marquee component in 3D mode scrolling developer testimonials -- Each testimonial in a Magic Card -- Avatar Circles showing total developer count -- Highlighter on impactful quote fragments -- Shine Border around featured testimonial - ---- - -## Component Usage Summary - -| Component | Times Used (Winners) | Primary Purpose | -|-----------|---------------------|-----------------| -| **Magic Card** | 9 | Spotlight effects, containers | -| **Text Animate** | 7 | Typing effects, reveals | -| **Border Beam** | 6 | Connections, highlights | -| **Highlighter** | 6 | Emphasis on key text | -| **Animated List** | 5 | Sequential reveals | -| **Confetti** | 5 | Celebrations, milestones | -| **Shine Border** | 5 | Premium emphasis | -| **Morphing Text** | 4 | Dynamic headlines | -| **Orbiting Circles** | 4 | Data flow, ecosystems | -| **Safari** | 4 | Browser mockups | -| **Scratch To Reveal** | 4 | Interactive discovery | -| **Pulsating Button** | 4 | CTAs | -| **Grid Beams** | 3 | Tech backgrounds | -| **Warp Background** | 3 | Depth, perspective | -| **Arc Timeline** | 2 | Progress, history | -| **Dock** | 1 | Navigation selector | -| **Aurora Text** | 1 | Premium headlines | -| **Bento Grid** | 1 | Layout organization | - -## Design Principles - -1. **Show, Don't Tell**: Use animations to demonstrate concepts (memory persistence, data flow) -2. **Interactive Discovery**: Scratch-to-reveal and interactive elements engage users -3. **Visual Metaphors**: Orbiting circles for data flow, layers for architecture -4. **Celebration**: Confetti at key moments creates joy -5. **Progressive Disclosure**: Animated lists and timelines reveal information naturally -6. **Spatial Depth**: Warp backgrounds and z-space create dimensional understanding -7. **Consistent Magic**: Reuse components (Magic Card, Border Beam) for cohesion diff --git a/context/magic-ui/idea-rankings.md b/context/magic-ui/idea-rankings.md deleted file mode 100644 index 0ad6e864..00000000 --- a/context/magic-ui/idea-rankings.md +++ /dev/null @@ -1,389 +0,0 @@ -# Landing Page Ideas - Ranked Analysis - -Ranking criteria (1-10 scale): -1. **Creativity**: How novel and unexpected is the approach? -2. **Storytelling**: How effectively does it communicate the value? -3. **Intuitive**: How easily will users understand it? -4. **Feasibility**: How practical is implementation? -5. **Delight**: How much joy does it create? - ---- - -## HERO SECTION Rankings - -### Idea 1: "Fading Memory" Effect ⭐ WINNER (42/50) -- **Creativity**: 9/10 - Scratch-to-reveal pain point is unexpected -- **Storytelling**: 9/10 - Morphing text and orbiting circles tell complete story -- **Intuitive**: 8/10 - Orbiting content makes memory concept clear -- **Feasibility**: 7/10 - Multiple complex components need coordination -- **Delight**: 9/10 - Interactive scratch creates engagement - -**Why it wins**: The scratch-to-reveal pain point makes the problem visceral. Orbiting circles create immediate visual understanding of what gets remembered. - -### Idea 2: "Memory Timeline" Hero (39/50) -- **Creativity**: 7/10 -- **Storytelling**: 8/10 -- **Intuitive**: 9/10 -- **Feasibility**: 8/10 -- **Delight**: 7/10 - -### Idea 3: "Brain Storage" Visualization (36/50) -- **Creativity**: 6/10 -- **Storytelling**: 7/10 -- **Intuitive**: 7/10 -- **Feasibility**: 9/10 -- **Delight**: 7/10 - ---- - -## BEFORE/AFTER COMPARISON Rankings - -### Idea 1: "Split Screen Wipe" ⭐ WINNER (44/50) -- **Creativity**: 8/10 - Clean comparison approach -- **Storytelling**: 10/10 - Side-by-side is the clearest possible comparison -- **Intuitive**: 10/10 - Immediately obvious what's different -- **Feasibility**: 8/10 - Safari mockups are well-supported -- **Delight**: 8/10 - Fade vs persist is satisfying - -**Why it wins**: Safari browser mockups provide immediate familiarity. The contrast between fading (Before) and persistent with Border Beam (After) is crystal clear storytelling. - -### Idea 2: "Memory Decay Visualization" (40/50) -- **Creativity**: 9/10 -- **Storytelling**: 9/10 -- **Intuitive**: 8/10 -- **Feasibility**: 7/10 -- **Delight**: 7/10 - -### Idea 3: "Conversation Replay" (40/50) -- **Creativity**: 7/10 -- **Storytelling**: 8/10 -- **Intuitive**: 9/10 -- **Feasibility**: 9/10 -- **Delight**: 7/10 - ---- - -## REAL EXAMPLES Rankings - -### Idea 2: "Timeline Story" ⭐ WINNER (44/50) -- **Creativity**: 9/10 - Arc timeline for session progression is novel -- **Storytelling**: 10/10 - Timeline naturally shows progression over time -- **Intuitive**: 9/10 - Timeline metaphor is universally understood -- **Feasibility**: 7/10 - Complex interaction between timeline and orbiting elements -- **Delight**: 9/10 - Orbiting context around nodes is magical - -**Why it wins**: Arc Timeline naturally communicates the "across sessions" aspect. Orbiting circles showing related context (files, decisions, bugs) is brilliant visual storytelling. - -### Idea 1: "Tabbed Experience" (41/50) -- **Creativity**: 7/10 -- **Storytelling**: 8/10 -- **Intuitive**: 9/10 -- **Feasibility**: 9/10 -- **Delight**: 8/10 - -### Idea 3: "Memory Card Flip" (35/50) -- **Creativity**: 8/10 -- **Storytelling**: 7/10 -- **Intuitive**: 6/10 -- **Feasibility**: 6/10 -- **Delight**: 8/10 - ---- - -## HOW IT WORKS Rankings - -### Idea 3: "Layered Depth Model" ⭐ WINNER (43/50) -- **Creativity**: 9/10 - Spatial depth for understanding layers is clever -- **Storytelling**: 9/10 - Visual depth communicates layered architecture -- **Intuitive**: 10/10 - Layers immediately convey hierarchy and flow -- **Feasibility**: 6/10 - Z-space perspective requires careful implementation -- **Delight**: 9/10 - Morphing text showing transformation is satisfying - -**Why it wins**: Depth/perspective creates intuitive understanding of the layered architecture. Morphing text showing state transformation ("Capturing" → "Storing") tells the story perfectly. - -### Idea 1: "Animated Data Flow" (42/50) -- **Creativity**: 8/10 -- **Storytelling**: 9/10 -- **Intuitive**: 9/10 -- **Feasibility**: 8/10 -- **Delight**: 8/10 - -### Idea 2: "Arc Timeline as Process" (37/50) -- **Creativity**: 7/10 -- **Storytelling**: 8/10 -- **Intuitive**: 8/10 -- **Feasibility**: 7/10 -- **Delight**: 7/10 - ---- - -## WHAT GETS REMEMBERED Rankings - -### Idea 2: "Memory Bank Slots" ⭐ WINNER (41/50) -- **Creativity**: 9/10 - Memory bank metaphor with scratch-to-reveal -- **Storytelling**: 8/10 - Discovery process tells the story -- **Intuitive**: 8/10 - Bank slot metaphor is clear -- **Feasibility**: 7/10 - Six scratch-to-reveal elements need optimization -- **Delight**: 9/10 - Gamification through scratching is highly engaging - -**Why it wins**: Scratch-to-reveal gamification makes exploring features fun. Discovering what gets saved creates memorable engagement. - -### Idea 3: "Collector Animation" (41/50 - tied) -- **Creativity**: 8/10 -- **Storytelling**: 8/10 -- **Intuitive**: 9/10 -- **Feasibility**: 8/10 -- **Delight**: 8/10 - -### Idea 1: "Checkbox Delight" (40/50) -- **Creativity**: 6/10 -- **Storytelling**: 7/10 -- **Intuitive**: 9/10 -- **Feasibility**: 10/10 -- **Delight**: 8/10 - ---- - -## POWERFUL SEARCH Rankings - -### Idea 1: "Live Search Demo" ⭐ WINNER (44/50) -- **Creativity**: 7/10 - Straightforward but effective -- **Storytelling**: 10/10 - Actually showing search in action is perfect -- **Intuitive**: 10/10 - Real search demo is immediately clear -- **Feasibility**: 9/10 - Safari + Text Animate + Animated List is achievable -- **Delight**: 8/10 - Watching search happen is satisfying - -**Why it wins**: Showing actual search with real queries and results is the most effective storytelling. Users immediately understand the capability. - -### Idea 2: "Search Radar" (39/50) -- **Creativity**: 9/10 -- **Storytelling**: 8/10 -- **Intuitive**: 7/10 -- **Feasibility**: 6/10 -- **Delight**: 9/10 - -### Idea 3: "Memory Retrieval Visualization" (38/50) -- **Creativity**: 8/10 -- **Storytelling**: 7/10 -- **Intuitive**: 8/10 -- **Feasibility**: 8/10 -- **Delight**: 7/10 - ---- - -## THE NUMBERS Rankings - -### Idea 2: "Progress Bar Transformation" ⭐ WINNER (45/50) -- **Creativity**: 8/10 - Progress bars are familiar but effective -- **Storytelling**: 10/10 - Visual transformation from bad to good is powerful -- **Intuitive**: 10/10 - Everyone understands progress bars -- **Feasibility**: 8/10 - Animated progress bars are well-supported -- **Delight**: 9/10 - Watching bars transform is satisfying - -**Why it wins**: Visual transformation of progress bars (red/low → green/high) is incredibly effective storytelling. Everyone intuitively understands the improvement. - -### Idea 1: "Counting Animation" (42/50) -- **Creativity**: 7/10 -- **Storytelling**: 9/10 -- **Intuitive**: 9/10 -- **Feasibility**: 9/10 -- **Delight**: 8/10 - -### Idea 3: "Flip Cards Reveal" (39/50) -- **Creativity**: 8/10 -- **Storytelling**: 8/10 -- **Intuitive**: 7/10 -- **Feasibility**: 7/10 -- **Delight**: 9/10 - ---- - -## INSTALLATION Rankings - -### Idea 1: "Copy-Paste Delight" ⭐ WINNER (44/50) -- **Creativity**: 7/10 - Simple but right -- **Storytelling**: 8/10 - Shows exactly what to do -- **Intuitive**: 10/10 - Terminal + copy buttons is universal pattern -- **Feasibility**: 10/10 - Very achievable -- **Delight**: 9/10 - Confetti celebration seals the deal - -**Why it wins**: Simplicity wins for installation instructions. Confetti celebration when done creates satisfying completion. - -### Idea 2: "Progress Stepper" (42/50) -- **Creativity**: 8/10 -- **Storytelling**: 9/10 -- **Intuitive**: 9/10 -- **Feasibility**: 8/10 -- **Delight**: 8/10 - -### Idea 3: "Interactive Terminal" (41/50) -- **Creativity**: 9/10 -- **Storytelling**: 8/10 -- **Intuitive**: 8/10 -- **Feasibility**: 7/10 -- **Delight**: 9/10 - ---- - -## UNDER THE HOOD Rankings - -### Idea 2: "Layered Stack" ⭐ WINNER (44/50) -- **Creativity**: 9/10 - Layers with z-depth is clever -- **Storytelling**: 9/10 - Stacking shows dependency hierarchy -- **Intuitive**: 10/10 - Stack metaphor is perfect for architecture -- **Feasibility**: 7/10 - Perspective effects require work -- **Delight**: 9/10 - Slides revealing layers is satisfying - -**Why it wins**: Layered stack with perspective visually explains the architecture hierarchy perfectly. Each layer sliding out to reveal itself tells the dependency story. - -### Idea 3: "Technical Orbits" (43/50) -- **Creativity**: 10/10 -- **Storytelling**: 8/10 -- **Intuitive**: 9/10 -- **Feasibility**: 8/10 -- **Delight**: 8/10 - -### Idea 1: "System Diagram" (40/50) -- **Creativity**: 7/10 -- **Storytelling**: 8/10 -- **Intuitive**: 9/10 -- **Feasibility**: 9/10 -- **Delight**: 7/10 - ---- - -## USE CASES Rankings - -### Idea 2: "Role Selector" ⭐ WINNER (46/50) -- **Creativity**: 9/10 - Dock as role selector is novel -- **Storytelling**: 9/10 - Interactive selection tells personalized stories -- **Intuitive**: 10/10 - Dock interface is familiar and clear -- **Feasibility**: 8/10 - Dock + expanding cards is achievable -- **Delight**: 10/10 - Confetti for "your" use case is pure joy - -**Why it wins**: Interactive Dock selector with confetti when you find "your" use case creates personal connection and delight. Highest delight score overall! - -### Idea 3: "Story Scenarios" (41/50) -- **Creativity**: 8/10 -- **Storytelling**: 10/10 -- **Intuitive**: 8/10 -- **Feasibility**: 7/10 -- **Delight**: 8/10 - -### Idea 1: "User Journey Cards" (40/50) -- **Creativity**: 7/10 -- **Storytelling**: 8/10 -- **Intuitive**: 9/10 -- **Feasibility**: 9/10 -- **Delight**: 7/10 - ---- - -## FAQ Rankings - -### Idea 2: "Scratch to Answer" ⭐ WINNER (42/50) -- **Creativity**: 9/10 - Making FAQ interactive is fresh -- **Storytelling**: 8/10 - Discovery process engages -- **Intuitive**: 8/10 - Scratch metaphor is understood -- **Feasibility**: 7/10 - Multiple scratch elements need optimization -- **Delight**: 10/10 - Scratching makes FAQs fun! - -**Why it wins**: Scratch-to-reveal makes FAQs engaging instead of boring. Confetti on important answers (like "Fully private") creates moments of delight. - -### Idea 3: "Interactive Q&A" (41/50) -- **Creativity**: 7/10 -- **Storytelling**: 8/10 -- **Intuitive**: 9/10 -- **Feasibility**: 9/10 -- **Delight**: 8/10 - -### Idea 1: "Expandable Cards" (40/50) -- **Creativity**: 6/10 -- **Storytelling**: 7/10 -- **Intuitive**: 10/10 -- **Feasibility**: 10/10 -- **Delight**: 7/10 - ---- - -## Overall Component Winners - -### Most Effective Components -1. **Magic Card** (9 winning sections) - Versatile spotlight effects -2. **Text Animate** (7 sections) - Essential for reveals and typing effects -3. **Border Beam** (6 sections) - Perfect for connections and highlights -4. **Scratch To Reveal** (4 sections) - Highest delight factor -5. **Confetti** (5 sections) - Celebration moments - -### Highest Delight Components -1. Scratch To Reveal - 10/10 in FAQ, 9/10 in Features -2. Confetti - Creates joy at key moments -3. Dock - 10/10 for use case selection -4. Orbiting Circles - 9/10 for data visualization - -### Best Storytelling Components -1. Arc Timeline - Perfect for progression narratives -2. Safari - Immediately familiar, great for demos -3. Progress Bars - Universal understanding of improvement -4. Layered Stack - Architecture hierarchy storytelling - ---- - -## Implementation Priority - -### High Priority (Core Experience) -1. **Hero** - First impression is critical -2. **Before/After** - Core value proposition -3. **Installation** - Conversion point -4. **The Numbers** - Proof of value - -### Medium Priority (Supporting Narrative) -1. **Real Examples** - Concrete use cases -2. **How It Works** - Understanding the system -3. **Powerful Search** - Feature highlight - -### Lower Priority (Deep Dive) -1. **What Gets Remembered** - Feature details -2. **Under The Hood** - Technical deep dive -3. **Use Cases** - Audience segmentation -4. **FAQ** - Support content - ---- - -## Technical Considerations - -### Performance Concerns -- **Scratch To Reveal**: 4 instances across page - needs optimization -- **Orbiting Circles**: Multiple orbits can be CPU intensive -- **Particles**: Use sparingly, can impact performance -- **Z-space/Perspective**: May have cross-browser issues - -### Accessibility Considerations -- **Scratch To Reveal**: Needs keyboard alternative -- **Confetti**: Should respect `prefers-reduced-motion` -- **Animations**: All should be pausable/stoppable -- **Color Contrast**: Aurora/gradient text needs testing - -### Browser Compatibility -- **Safari Component**: Meta - using Safari to show Safari -- **Grid Beams/Warp**: Check WebGL support -- **Perspective transforms**: Test in Firefox, Safari - ---- - -## Final Winning Lineup - -1. **Hero**: Fading Memory (42/50) -2. **Before/After**: Split Screen Wipe (44/50) -3. **Real Examples**: Timeline Story (44/50) -4. **How It Works**: Layered Depth Model (43/50) -5. **What Gets Remembered**: Memory Bank Slots (41/50) -6. **Powerful Search**: Live Search Demo (44/50) -7. **The Numbers**: Progress Bar Transformation (45/50) ⭐ HIGHEST SCORE -8. **Installation**: Copy-Paste Delight (44/50) -9. **Under The Hood**: Layered Stack (44/50) -10. **Use Cases**: Role Selector (46/50) ⭐ HIGHEST DELIGHT -11. **FAQ**: Scratch to Answer (42/50) - -**Average Score**: 43.5/50 (87%) -**Total Delight**: 94/110 (85%) diff --git a/context/temp/PHASE1-COMPLETE.md b/context/temp/PHASE1-COMPLETE.md deleted file mode 100644 index 2bbba357..00000000 --- a/context/temp/PHASE1-COMPLETE.md +++ /dev/null @@ -1,134 +0,0 @@ -# Phase 1 Implementation - Complete ✅ - -Phase 1 of the REFACTOR-PLAN.md has been successfully implemented and tested. - -## What Was Implemented - -### 1. Database Schema (Migration 004) -Created four new tables to support the SDK agent architecture: - -- **`sdk_sessions`** - Tracks SDK streaming sessions -- **`observation_queue`** - Message queue for pending observations -- **`observations`** - Stores extracted observations from SDK -- **`session_summaries`** - Stores structured session summaries - -All tables include proper indexes for performance and foreign key constraints for data integrity. - -### 2. Shared Database Layer -Created `HooksDatabase` class ([src/services/sqlite/HooksDatabase.ts](src/services/sqlite/HooksDatabase.ts)) that provides: - -- Simple, synchronous database operations for hooks -- No complex logic - just basic CRUD operations -- Optimized SQLite settings (WAL mode, foreign keys enabled) -- Methods for all hook operations: - - `getRecentSummaries()` - Retrieve session context - - `createSDKSession()` - Initialize new session - - `queueObservation()` - Add observation to queue - - `storeObservation()` - Save SDK observations - - `storeSummary()` - Save session summaries - - And more... - -### 3. Hook Functions -Implemented all four hook functions in [src/hooks/](src/hooks/): - -#### **context.ts** - SessionStart Hook -- Shows user recent session context on startup -- Formats summaries in markdown for Claude -- Exits silently if no context or errors occur - -#### **save.ts** - PostToolUse Hook -- Queues tool observations for SDK processing -- Skips low-value tools (TodoWrite, ListMcpResourcesTool) -- Non-blocking - returns immediately - -#### **new.ts** - UserPromptSubmit Hook -- Initializes SDK session in database -- Prepares for SDK worker spawn (TODO in Phase 2) -- Non-blocking - returns immediately - -#### **summary.ts** - Stop Hook -- Queues FINALIZE message for SDK -- Signals SDK to generate session summary -- Non-blocking - returns immediately - -### 4. CLI Integration -Added four new commands to [src/bin/cli.ts](src/bin/cli.ts:227-274): - -```bash -claude-mem context # SessionStart hook -claude-mem new # UserPromptSubmit hook -claude-mem save # PostToolUse hook -claude-mem summary # Stop hook -``` - -All commands read JSON input from stdin and execute the corresponding hook function. - -### 5. Testing -Created comprehensive test suite ([test-phase1.ts](test-phase1.ts)) that validates: - -- ✅ Database schema migration 004 applied correctly -- ✅ All four tables exist -- ✅ SDK session creation and retrieval -- ✅ Observation queue operations -- ✅ Observation and summary storage -- ✅ Session status transitions - -**All tests pass! 🎉** - -## What's Left for Phase 2 - -The foundation is complete. Next steps: - -1. **SDK Worker Process** - Implement the background agent that: - - Polls observation queue - - Sends observations to Claude SDK - - Parses XML responses (`` and `` blocks) - - Stores results in database - -2. **SDK Prompts** - Implement the three prompt builders: - - `buildInitPrompt()` - Initialize SDK agent - - `buildObservationPrompt()` - Send tool observation - - `buildFinalizePrompt()` - Request session summary - -3. **Process Management** - Update [src/hooks/new.ts](src/hooks/new.ts:35-42) to spawn SDK worker as detached process - -4. **End-to-End Testing** - Test with real Claude Code session - -## File Changes - -### New Files -- [src/services/sqlite/HooksDatabase.ts](src/services/sqlite/HooksDatabase.ts) - Shared database layer -- [src/hooks/context.ts](src/hooks/context.ts) - SessionStart hook -- [src/hooks/save.ts](src/hooks/save.ts) - PostToolUse hook -- [src/hooks/new.ts](src/hooks/new.ts) - UserPromptSubmit hook -- [src/hooks/summary.ts](src/hooks/summary.ts) - Stop hook -- [src/hooks/index.ts](src/hooks/index.ts) - Exports -- [test-phase1.ts](test-phase1.ts) - Test suite - -### Modified Files -- [src/services/sqlite/migrations.ts](src/services/sqlite/migrations.ts:205-315) - Added migration 004 -- [src/services/sqlite/index.ts](src/services/sqlite/index.ts:13) - Exported HooksDatabase -- [src/bin/cli.ts](src/bin/cli.ts:227-274) - Added hook commands - -## Verification - -To verify Phase 1 implementation: - -```bash -# Build -bun run build - -# Run tests -bun test-phase1.ts - -# Check hook commands exist -./dist/claude-mem.min.js --help | grep -A 1 'context\|new\|save\|summary' -``` - -All should pass without errors. - -## Next Steps - -Ready to proceed to Phase 2: **SDK Worker Implementation** - -The architecture is sound, the database layer is working, and all hook functions are ready to integrate with the SDK worker process. diff --git a/context/temp/PHASE2-COMPLETE.md b/context/temp/PHASE2-COMPLETE.md deleted file mode 100644 index 1a202694..00000000 --- a/context/temp/PHASE2-COMPLETE.md +++ /dev/null @@ -1,175 +0,0 @@ -# Phase 2 Implementation Complete - -## Summary - -Phase 2 of the SDK Worker Process has been successfully implemented. This phase adds the background agent architecture that processes tool observations and generates session summaries. - -## Implementation Date - -October 15, 2025 - -## Files Created - -### 1. SDK Prompts Module -- **File**: [src/sdk/prompts.ts](src/sdk/prompts.ts) -- **Purpose**: Generates prompts for the Claude Agent SDK -- **Functions**: - - `buildInitPrompt()` - Initialize the memory agent - - `buildObservationPrompt()` - Send tool observations to agent - - `buildFinalizePrompt()` - Request session summary - -### 2. XML Parser Module -- **File**: [src/sdk/parser.ts](src/sdk/parser.ts) -- **Purpose**: Parse XML responses from SDK agent -- **Functions**: - - `parseObservations()` - Extract observation blocks - - `parseSummary()` - Extract session summary -- **Features**: - - Validates observation types (decision, bugfix, feature, refactor, discovery) - - Validates all required summary fields - - Handles file arrays in summaries - - No external dependencies (uses regex) - -### 3. SDK Worker Process -- **File**: [src/sdk/worker.ts](src/sdk/worker.ts) -- **Purpose**: Background agent that processes observations -- **Features**: - - Runs as detached background process - - Uses Claude Agent SDK streaming input mode - - Polls observation queue every 1 second - - Parses and stores observations and summaries - - Handles graceful shutdown via FINALIZE message - - Automatic error handling and session status updates - -### 4. SDK Index Module -- **File**: [src/sdk/index.ts](src/sdk/index.ts) -- **Purpose**: Export all SDK module functionality - -### 5. Test Suite -- **File**: [test-phase2.ts](test-phase2.ts) -- **Coverage**: - - SDK prompt generation (3 tests) - - XML observation parsing (4 tests) - - XML summary parsing (4 tests) - - Database integration (3 tests) -- **Result**: ✅ All 14 tests passing - -## Files Modified - -### 1. newHook Implementation -- **File**: [src/hooks/new.ts](src/hooks/new.ts:38-61) -- **Changes**: - - Uncommented SDK worker spawn code - - Added worker path resolution (dev vs production) - - Spawns worker as detached process with stdio: 'ignore' - - Worker receives session DB ID as argument - -## Architecture Validation - -### SDK Worker Flow -1. ✅ newHook spawns worker as detached process -2. ✅ Worker loads session from database -3. ✅ Worker initializes SDK agent with streaming input -4. ✅ Worker polls observation queue continuously -5. ✅ Worker sends observations to SDK agent -6. ✅ Worker parses XML responses -7. ✅ Worker stores observations and summaries -8. ✅ Worker handles FINALIZE message -9. ✅ Worker updates session status - -### Data Flow -``` -User Prompt → newHook → Create SDK Session → Spawn Worker - ↓ - Initialize SDK Agent - ↓ - ← Poll Observation Queue - ↓ - Send Observations to SDK - ↓ - ← Parse XML Response - ↓ - Store in Database - ↓ - Wait for FINALIZE - ↓ - Generate Summary → Exit -``` - -## Test Results - -```bash -$ bun test ./test-phase2.ts - -✅ SDK Prompts (3 tests) - ✅ should build init prompt with all required sections - ✅ should build observation prompt with tool details - ✅ should build finalize prompt with session context - -✅ XML Parser (8 tests) - ✅ parseObservations - ✅ should parse single observation - ✅ should parse multiple observations - ✅ should skip observations with invalid types - ✅ should handle observations with surrounding text - ✅ parseSummary - ✅ should parse complete summary with all fields - ✅ should handle empty file arrays - ✅ should return null if required fields are missing - ✅ should return null if no summary block found - -✅ HooksDatabase Integration (3 tests) - ✅ should store and retrieve observations - ✅ should store and retrieve summaries - ✅ should queue and process observations - -14 pass, 0 fail, 53 expect() calls -Ran 14 tests across 1 file. [60.00ms] -``` - -## Build Verification - -```bash -$ npm run build - -📌 Version: 3.9.16 -✓ Bun detected -✓ Cleaned dist directory -✓ Bundle created -✓ Shebang added -✓ Made executable -✅ Build complete! (344.57 KB) -``` - -## Success Criteria - -All Phase 2 success criteria have been met: - -- [x] SDK worker runs as detached process -- [x] Worker polls observation queue continuously -- [x] Worker sends observations to Claude SDK -- [x] Worker parses `` and `` XML correctly -- [x] Worker stores results in database using HooksDatabase -- [x] Worker handles FINALIZE message and exits gracefully -- [x] All tests pass -- [x] No blocking of main Claude Code session - -## Known Limitations - -1. **Bundled CLI**: The worker process is currently bundled into the main CLI. For production use, we may want to extract it as a separate executable. -2. **No logging**: Worker runs with `stdio: 'ignore'` for non-blocking behavior. Consider adding file-based logging for debugging. - -## Next Steps - -Phase 2 is complete and ready for integration testing with a real Claude Code session. The next phase would involve: - -1. Testing the full end-to-end flow with actual tool observations -2. Implementing the `saveHook` to queue observations -3. Implementing the `summaryHook` to send FINALIZE message -4. Verifying the context hook retrieves summaries correctly - -## Related Documentation - -- [REFACTOR-PLAN.md](REFACTOR-PLAN.md) - Original refactor plan -- [PHASE1-COMPLETE.md](PHASE1-COMPLETE.md) - Phase 1 completion -- [PHASE2-PROMPT.md](PHASE2-PROMPT.md) - Phase 2 implementation requirements diff --git a/context/temp/PHASE2-PROMPT.md b/context/temp/PHASE2-PROMPT.md deleted file mode 100644 index 4dd68f48..00000000 --- a/context/temp/PHASE2-PROMPT.md +++ /dev/null @@ -1,118 +0,0 @@ -# Phase 2 Implementation Prompt - -Use this prompt to start a new chat for Phase 2 implementation: - ---- - -## Context - -I'm implementing a refactor of the claude-mem memory system based on [REFACTOR-PLAN.md](REFACTOR-PLAN.md). - -**Phase 1 is complete** (see [PHASE1-COMPLETE.md](PHASE1-COMPLETE.md)): -- ✅ Database schema with migration 004 -- ✅ HooksDatabase shared layer -- ✅ All four hook functions (context, new, save, summary) -- ✅ CLI integration and tests passing - -## Task - -Implement **Phase 2: SDK Worker Process** - -According to [REFACTOR-PLAN.md](REFACTOR-PLAN.md#2-userpromptsubmit-hook) (lines 296-423), I need to: - -1. **Create SDK Worker Process** (`src/sdk/worker.ts`) - - Uses Agent SDK streaming input mode - - AsyncIterable message generator that: - - Yields initial prompt - - Polls observation_queue table - - Yields observation prompts - - Handles FINALIZE message - - Parses SDK responses for `` and `` XML blocks - - Stores results using HooksDatabase methods - -2. **Create SDK Prompts** (`src/sdk/prompts.ts`) - - `buildInitPrompt()` - Initialize agent (see REFACTOR-PLAN.md:537-595) - - `buildObservationPrompt()` - Send tool observation (see REFACTOR-PLAN.md:601-634) - - `buildFinalizePrompt()` - Request summary (see REFACTOR-PLAN.md:640-692) - -3. **Create XML Parser** (`src/sdk/parser.ts`) - - Parse `` blocks with `` and `` - - Parse `` blocks with 8 required fields - - Extract file arrays from `` child elements - -4. **Update newHook** ([src/hooks/new.ts](src/hooks/new.ts:35-42)) - - Uncomment SDK worker spawn code - - Pass session ID to worker - - Detached process with stdio: 'ignore' - -5. **Test End-to-End** - - Create test that simulates full lifecycle - - Verify observations are queued, processed, and stored - - Verify summary generation works - -## Key Requirements - -From [REFACTOR-PLAN.md](REFACTOR-PLAN.md): - -- Use `@anthropic-ai/claude-agent-sdk` query function with streaming input mode -- Model: `claude-sonnet-4-5` -- Use `disallowedTools: ['Glob', 'Grep', 'ListMcpResourcesTool', 'WebSearch']` -- Message generator yields `{ role: "user", content: string }` objects -- Capture SDK session ID from system init message -- Poll observation queue every 1 second -- Use AbortController for graceful cancellation -- Parse XML with a library (not regex) - suggest fast-xml-parser -- Store observations and summaries using HooksDatabase methods - -## Architecture Reference - -The SDK worker is a **synthesis engine** that: -- Receives tool observations (not raw data) -- Extracts meaningful insights -- Stores atomic observations in SQLite -- Generates structured summaries at session end - -See [REFACTOR-PLAN.md](REFACTOR-PLAN.md#visual-overview) (lines 69-119) for the full architecture diagram. - -## Files to Create - -1. `src/sdk/worker.ts` - Main SDK worker process -2. `src/sdk/prompts.ts` - Prompt builders -3. `src/sdk/parser.ts` - XML response parser -4. `src/sdk/index.ts` - Exports -5. `test-phase2.ts` - End-to-end tests - -## Files to Modify - -1. [src/hooks/new.ts](src/hooks/new.ts:35-42) - Spawn worker process -2. [package.json](package.json) - May need to add fast-xml-parser dependency - -## Testing Strategy - -1. Unit tests for prompts (verify prompt structure) -2. Unit tests for parser (verify XML parsing) -3. Integration test for worker (mock SDK responses) -4. End-to-end test (simulate full observation → summary flow) - -## Success Criteria - -- [ ] SDK worker runs as detached process -- [ ] Worker polls observation queue continuously -- [ ] Worker sends observations to Claude SDK -- [ ] Worker parses `` and `` XML correctly -- [ ] Worker stores results in database using HooksDatabase -- [ ] Worker handles FINALIZE message and exits gracefully -- [ ] All tests pass -- [ ] No blocking of main Claude Code session - -## Notes - -- Keep hooks fast and non-blocking (they already are) -- SDK worker is fire-and-forget background process -- Use HooksDatabase methods (already implemented in Phase 1) -- Follow the exact prompt formats from REFACTOR-PLAN.md -- Use proper TypeScript types from Agent SDK - ---- - -**Start with:** Create the SDK prompts module first, then the parser, then the worker. Test each piece before integrating. diff --git a/context/temp/PHASE3-COMPLETE.md b/context/temp/PHASE3-COMPLETE.md deleted file mode 100644 index c0a09dfc..00000000 --- a/context/temp/PHASE3-COMPLETE.md +++ /dev/null @@ -1,271 +0,0 @@ -# Phase 3 Implementation Complete ✅ - -## Summary - -Phase 3 of the claude-mem architecture refactor has been successfully completed. This phase integrated all hook functions with the database layer and validated the complete end-to-end lifecycle through comprehensive testing. - -## Implementation Date - -October 15, 2025 - -## What Was Implemented - -### 1. Hook Integration Verification - -All four hook functions were verified to be working correctly with the database layer: - -#### **[contextHook](src/hooks/context.ts)** - SessionStart Hook -- ✅ Retrieves recent session summaries from database -- ✅ Formats summaries in markdown for Claude consumption -- ✅ Handles missing summaries gracefully -- ✅ Only runs on startup (skips resume) -- ✅ Fast, non-blocking operation (< 50ms) - -#### **[newHook](src/hooks/new.ts)** - UserPromptSubmit Hook -- ✅ Creates SDK session record in database -- ✅ Spawns SDK worker as detached background process -- ✅ Handles duplicate sessions gracefully -- ✅ Fast, non-blocking operation (< 50ms) -- ✅ Returns immediately with suppressed output - -#### **[saveHook](src/hooks/save.ts)** - PostToolUse Hook -- ✅ Queues tool observations to database -- ✅ Filters out low-value tools (TodoWrite, ListMcpResourcesTool) -- ✅ Handles missing sessions gracefully -- ✅ Fast, non-blocking operation (< 50ms) -- ✅ Stores JSON-stringified tool input/output - -#### **[summaryHook](src/hooks/summary.ts)** - Stop Hook -- ✅ Sends FINALIZE message to observation queue -- ✅ Triggers SDK worker to generate session summary -- ✅ Handles missing sessions gracefully -- ✅ Fast, non-blocking operation (< 50ms) - -### 2. Comprehensive Test Suite - -Created two new comprehensive test files: - -#### **[test-phase3-integration.ts](test-phase3-integration.ts)** -Tests individual hook database integration: -- ✅ Session management (create, find, update, complete) -- ✅ Observation queue (queue, retrieve, process, FINALIZE) -- ✅ Observations storage (store and retrieve) -- ✅ Summaries (store and retrieve, project isolation) -- **9 tests, all passing** - -#### **[test-phase3-e2e.ts](test-phase3-e2e.ts)** -Tests complete session lifecycle: -- ✅ Full lifecycle: new → save → summary → context -- ✅ Performance requirements (< 50ms per operation) -- ✅ Interrupted sessions (observations remain in queue) -- ✅ Multiple concurrent projects (project isolation) -- **4 tests, all passing** - -### 3. Database Integration - -All hooks correctly use the [HooksDatabase](src/services/sqlite/HooksDatabase.ts) layer: -- ✅ Simple, synchronous database operations -- ✅ Foreign key constraints enforced -- ✅ Proper session lifecycle management -- ✅ Atomic operations with WAL mode -- ✅ No complex logic in hooks (delegated to SDK worker) - -### 4. CLI Commands - -All four CLI commands verified working: -- ✅ `claude-mem context` - [src/bin/cli.ts:228-234](src/bin/cli.ts#L228-L234) -- ✅ `claude-mem new` - [src/bin/cli.ts:237-243](src/bin/cli.ts#L237-L243) -- ✅ `claude-mem save` - [src/bin/cli.ts:246-252](src/bin/cli.ts#L246-L252) -- ✅ `claude-mem summary` - [src/bin/cli.ts:255-261](src/bin/cli.ts#L255-L261) - -All commands: -- Read JSON from stdin -- Execute corresponding hook function -- Return proper JSON response -- Exit with code 0 - -## Test Results - -### All Tests Passing -```bash -Phase 1: ✅ Database schema and HooksDatabase tests -Phase 2: ✅ 14 tests (SDK prompts, parser, database integration) -Phase 3: ✅ 13 tests (9 integration + 4 e2e) -Total: ✅ 27+ tests passing -``` - -### Performance Validation -``` -Average operation time: 0.04ms (well under 50ms requirement) -Maximum operation time: 1.60ms (well under 100ms threshold) -``` - -### Build Verification -```bash -✅ Build complete! (344.57 KB) - Output: dist/claude-mem.min.js -``` - -## Architecture Validation - -### ✅ Complete Hook Lifecycle - -``` -1. SessionStart (contextHook) - ↓ Retrieves recent summaries from database - ↓ Formats for Claude consumption - ↓ -2. UserPromptSubmit (newHook) - ↓ Creates SDK session - ↓ Spawns background SDK worker - ↓ -3. PostToolUse (saveHook) - ↓ Queues observations - ↓ SDK worker polls queue - ↓ SDK processes observations - ↓ SDK stores meaningful insights - ↓ -4. Stop (summaryHook) - ↓ Sends FINALIZE message - ↓ SDK generates structured summary - ↓ SDK stores summary in database - ↓ -5. Next SessionStart - ↓ New context retrieved - ⟲ Cycle repeats -``` - -### ✅ Non-Blocking Requirements - -All hooks meet the < 50ms performance requirement: -- **contextHook**: Retrieves summaries (simple SELECT query) -- **newHook**: Creates session + spawns detached process -- **saveHook**: Inserts into queue (simple INSERT) -- **summaryHook**: Inserts FINALIZE message (simple INSERT) - -SDK worker runs in background independently of main session. - -### ✅ Error Handling - -All hooks handle errors gracefully: -- Database errors → log + continue -- Missing sessions → silently continue -- Process spawn failures → log + continue -- Never block Claude Code session - -### ✅ Data Integrity - -Foreign key constraints enforce referential integrity: -- Observations reference SDK sessions -- Summaries reference SDK sessions -- Queue items reference SDK sessions -- Sessions reference Claude sessions - -## Success Criteria Met - -All Phase 3 success criteria have been achieved: - -- [x] saveHook queues observations to database -- [x] summaryHook sends FINALIZE message -- [x] contextHook retrieves and formats summaries -- [x] End-to-end test passes (full lifecycle) -- [x] All hooks respond in < 50ms -- [x] Worker processes observations and generates summary -- [x] CLI commands work correctly -- [x] All tests pass (27+ tests) -- [x] Build succeeds (344.57 KB) -- [x] Database foreign key constraints enforced -- [x] Multiple concurrent projects supported -- [x] Interrupted sessions handled gracefully - -## Files Modified - -### Hook Implementations (Already Complete) -- [src/hooks/context.ts](src/hooks/context.ts) - SessionStart hook -- [src/hooks/save.ts](src/hooks/save.ts) - PostToolUse hook -- [src/hooks/new.ts](src/hooks/new.ts) - UserPromptSubmit hook -- [src/hooks/summary.ts](src/hooks/summary.ts) - Stop hook - -### Test Files Created -- [test-phase3-integration.ts](test-phase3-integration.ts) - Hook database integration tests -- [test-phase3-e2e.ts](test-phase3-e2e.ts) - End-to-end lifecycle tests - -### CLI Integration (Already Complete) -- [src/bin/cli.ts](src/bin/cli.ts) - CLI commands for all hooks - -## Install Flow Updates - -### ✅ CLI-Based Hook Architecture - -Updated the install flow to use the new CLI-based architecture: - -**Before (Old Architecture):** -- Installed hook template files (`session-start.js`, etc.) -- Copied shared helper modules -- Configured settings.json to point to hook files - -**After (New Architecture):** -- Hooks are CLI commands: `claude-mem context`, `claude-mem new`, `claude-mem save`, `claude-mem summary` -- Settings.json configured directly with CLI commands -- No separate hook files needed -- Simpler installation and maintenance - -**Updated Install Steps:** -```javascript -settings.hooks.SessionStart = [{ type: "command", command: "claude-mem context", timeout: 180 }] -settings.hooks.Stop = [{ type: "command", command: "claude-mem summary", timeout: 60 }] -settings.hooks.UserPromptSubmit = [{ type: "command", command: "claude-mem new", timeout: 60 }] -settings.hooks.PostToolUse = [{ type: "command", command: "claude-mem save", timeout: 180, matcher: "*" }] -``` - -**Benefits:** -- ✅ Single source of truth (CLI implementation) -- ✅ No hook file synchronization issues -- ✅ Easier debugging (just test CLI commands) -- ✅ Simpler installation process -- ✅ Better maintainability - -## Related Documentation - -- [REFACTOR-PLAN.md](REFACTOR-PLAN.md) - Complete architecture plan -- [PHASE1-COMPLETE.md](PHASE1-COMPLETE.md) - Database & HooksDatabase layer -- [PHASE2-COMPLETE.md](PHASE2-COMPLETE.md) - SDK worker process -- **PHASE3-COMPLETE.md** (this document) - Hook integration & testing - -## Next Steps - -Phase 3 is complete! The claude-mem system is now ready for real-world testing with actual Claude Code sessions. - -### Recommended Next Actions - -1. **Manual Testing** - - Configure hooks in `~/.config/claude-code/settings.json` - - Run a real Claude Code session - - Verify observations are queued - - Verify summaries are generated - - Verify context is injected on next session - -2. **Monitoring & Debugging** - - Add file-based logging to SDK worker - - Monitor `~/.claude-mem/claude-mem.db` for data - - Check observation queue processing - - Verify summary generation - -3. **Future Enhancements** - - Extract SDK worker as separate executable (not bundled) - - Add resumption support for interrupted SDK sessions - - Implement retry logic for failed observations - - Add telemetry and error reporting - - Optimize database queries with additional indexes - -## Conclusion - -Phase 3 successfully completes the claude-mem architecture refactor. All three phases are now complete: - -- ✅ **Phase 1**: Database schema and shared layer -- ✅ **Phase 2**: SDK worker process and prompts -- ✅ **Phase 3**: Hook integration and end-to-end testing - -The system is architecturally sound, fully tested, and ready for production use! - -🎉 **Refactor Complete!** 🎉 diff --git a/docs/architecture/database.md b/docs/architecture/database.mdx similarity index 98% rename from docs/architecture/database.md rename to docs/architecture/database.mdx index 7bac88bc..a859f83d 100644 --- a/docs/architecture/database.md +++ b/docs/architecture/database.mdx @@ -1,3 +1,8 @@ +--- +title: "Database Architecture" +description: "SQLite schema, FTS5 search, and data storage" +--- + # Database Architecture Claude-Mem uses SQLite 3 with the better-sqlite3 native module for persistent storage and FTS5 for full-text search. diff --git a/docs/architecture/hooks.md b/docs/architecture/hooks.mdx similarity index 98% rename from docs/architecture/hooks.md rename to docs/architecture/hooks.mdx index 42b5e016..d103382f 100644 --- a/docs/architecture/hooks.md +++ b/docs/architecture/hooks.mdx @@ -1,3 +1,8 @@ +--- +title: "Plugin Hooks" +description: "5 lifecycle hooks that power Claude-Mem" +--- + # Plugin Hooks Claude-Mem integrates with Claude Code through 5 lifecycle hooks that capture events and inject context. diff --git a/docs/architecture/mcp-search.md b/docs/architecture/mcp-search.mdx similarity index 98% rename from docs/architecture/mcp-search.md rename to docs/architecture/mcp-search.mdx index e617705b..7dbc80f1 100644 --- a/docs/architecture/mcp-search.md +++ b/docs/architecture/mcp-search.mdx @@ -1,3 +1,8 @@ +--- +title: "MCP Search Server" +description: "7 search tools with examples and usage patterns" +--- + # MCP Search Server Claude-Mem includes a Model Context Protocol (MCP) server that exposes 7 specialized search tools for querying stored observations and sessions. diff --git a/docs/architecture/overview.md b/docs/architecture/overview.mdx similarity index 95% rename from docs/architecture/overview.md rename to docs/architecture/overview.mdx index d949f5f1..fc633cec 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.mdx @@ -1,3 +1,8 @@ +--- +title: "Architecture Overview" +description: "System components and data flow in Claude-Mem" +--- + # Architecture Overview ## System Components @@ -148,13 +153,13 @@ claude-mem/ ## Component Details ### 1. Plugin Hooks -See [hooks.md](hooks.md) for detailed hook documentation. +See [Plugin Hooks](/architecture/hooks) for detailed hook documentation. ### 2. Worker Service -See [worker-service.md](worker-service.md) for HTTP API and endpoints. +See [Worker Service](/architecture/worker-service) for HTTP API and endpoints. ### 3. Database Layer -See [database.md](database.md) for schema and FTS5 search. +See [Database Architecture](/architecture/database) for schema and FTS5 search. ### 4. MCP Search Server -See [mcp-search.md](mcp-search.md) for search tools and examples. +See [MCP Search Server](/architecture/mcp-search) for search tools and examples. diff --git a/docs/architecture/worker-service.md b/docs/architecture/worker-service.mdx similarity index 98% rename from docs/architecture/worker-service.md rename to docs/architecture/worker-service.mdx index f2e59581..7e586cda 100644 --- a/docs/architecture/worker-service.md +++ b/docs/architecture/worker-service.mdx @@ -1,3 +1,8 @@ +--- +title: "Worker Service" +description: "HTTP API and PM2 process management" +--- + # Worker Service The worker service is a long-running HTTP API built with Express.js and managed by PM2. It processes observations through the Claude Agent SDK separately from hook execution to prevent timeout issues. diff --git a/docs/configuration.md b/docs/configuration.mdx similarity index 96% rename from docs/configuration.md rename to docs/configuration.mdx index bdf16398..71364fe8 100644 --- a/docs/configuration.md +++ b/docs/configuration.mdx @@ -1,3 +1,8 @@ +--- +title: "Configuration" +description: "Environment variables and settings for Claude-Mem" +--- + # Configuration ## Environment Variables @@ -293,6 +298,6 @@ If port 37777 is already in use: ## Next Steps -- [Architecture Overview](architecture/overview.md) - Understand the system -- [Troubleshooting](troubleshooting.md) - Common issues -- [Development](development.md) - Building from source +- [Architecture Overview](architecture/overview) - Understand the system +- [Troubleshooting](troubleshooting) - Common issues +- [Development](development) - Building from source diff --git a/docs/development.md b/docs/development.mdx similarity index 97% rename from docs/development.md rename to docs/development.mdx index 934ad2f2..e3be0df3 100644 --- a/docs/development.md +++ b/docs/development.mdx @@ -1,3 +1,8 @@ +--- +title: "Development" +description: "Build from source, run tests, and contribute to Claude-Mem" +--- + # Development Guide ## Building from Source @@ -552,6 +557,6 @@ rm -rf plugin/scripts/*.js plugin/scripts/*.cjs ## Next Steps -- [Architecture Overview](architecture/overview.md) - Understand the system -- [Configuration](configuration.md) - Customize Claude-Mem -- [Troubleshooting](troubleshooting.md) - Common issues +- [Architecture Overview](architecture/overview) - Understand the system +- [Configuration](configuration) - Customize Claude-Mem +- [Troubleshooting](troubleshooting) - Common issues diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 00000000..ecf8d7be --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,70 @@ +{ + "$schema": "https://mintlify.com/schema.json", + "name": "Claude-Mem", + "logo": { + "dark": "/logo/dark.svg", + "light": "/logo/light.svg" + }, + "favicon": "/favicon.svg", + "colors": { + "primary": "#3B82F6", + "light": "#EFF6FF", + "dark": "#1E40AF", + "background": { + "dark": "#0F172A", + "light": "#FFFFFF" + } + }, + "topbarLinks": [ + { + "name": "GitHub", + "url": "https://github.com/thedotmack/claude-mem" + } + ], + "topbarCtaButton": { + "name": "Install", + "url": "https://github.com/thedotmack/claude-mem#quick-start" + }, + "tabs": [ + { + "name": "Documentation", + "url": "/" + }, + { + "name": "Architecture", + "url": "/architecture" + } + ], + "navigation": [ + { + "group": "Get Started", + "pages": [ + "introduction", + "installation", + "usage/getting-started", + "usage/search-tools" + ] + }, + { + "group": "Configuration & Development", + "pages": [ + "configuration", + "development", + "troubleshooting" + ] + }, + { + "group": "Architecture", + "pages": [ + "architecture/overview", + "architecture/hooks", + "architecture/worker-service", + "architecture/database", + "architecture/mcp-search" + ] + } + ], + "footerSocials": { + "github": "https://github.com/thedotmack/claude-mem" + } +} diff --git a/docs/installation.md b/docs/installation.mdx similarity index 86% rename from docs/installation.md rename to docs/installation.mdx index bde593b0..ca68c56a 100644 --- a/docs/installation.md +++ b/docs/installation.mdx @@ -1,3 +1,8 @@ +--- +title: "Installation" +description: "Install Claude-Mem plugin for persistent memory across sessions" +--- + # Installation Guide ## Quick Start @@ -99,10 +104,10 @@ v4.0.0 introduces breaking changes: - **MCP Search Server**: 7 new search tools with full-text search and citations - **Enhanced Architecture**: Improved plugin integration and data organization -See [CHANGELOG.md](../CHANGELOG.md) for complete details. +See [CHANGELOG](https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md) for complete details. ## Next Steps -- [Getting Started Guide](usage/getting-started.md) - Learn how Claude-Mem works automatically -- [MCP Search Tools](usage/search-tools.md) - Query your project history -- [Configuration](configuration.md) - Customize Claude-Mem behavior +- [Getting Started Guide](usage/getting-started) - Learn how Claude-Mem works automatically +- [MCP Search Tools](usage/search-tools) - Query your project history +- [Configuration](configuration) - Customize Claude-Mem behavior diff --git a/docs/introduction.mdx b/docs/introduction.mdx new file mode 100644 index 00000000..47d7b772 --- /dev/null +++ b/docs/introduction.mdx @@ -0,0 +1,96 @@ +--- +title: "Introduction" +description: "Persistent memory compression system for Claude Code" +--- + +# Claude-Mem + +**Persistent memory compression system for Claude Code** + +Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect. + +## Quick Start + +Start a new Claude Code session in the terminal and enter the following commands: + +```bash +/plugin marketplace add thedotmack/claude-mem +/plugin install claude-mem +``` + +Restart Claude Code. Context from previous sessions will automatically appear in new sessions. + +## Key Features + +- 🧠 **Persistent Memory** - Context survives across sessions +- 🔍 **7 Search Tools** - Query your project history via MCP +- 🤖 **Automatic Operation** - No manual intervention required +- 📊 **FTS5 Search** - Fast full-text search across observations +- 🔗 **Citations** - Reference past decisions with `claude-mem://` URIs + +## How It Works + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Session Start → Inject context from last 10 sessions │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ User Prompts → Create session, save user prompts │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ Tool Executions → Capture observations (Read, Write, etc.) │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ Worker Processes → Extract learnings via Claude Agent SDK │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ Session Ends → Generate summary, ready for next session │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Core Components:** +1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd +2. **Worker Service** - HTTP API on port 37777 managed by PM2 +3. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search +4. **7 MCP Search Tools** - Query historical context with citations + +See [Architecture Overview](architecture/overview) for details. + +## System Requirements + +- **Node.js**: 18.0.0 or higher +- **Claude Code**: Latest version with plugin support +- **PM2**: Process manager (bundled - no global install required) +- **SQLite 3**: For persistent storage (bundled) + +## What's New in v4.2.3 + +**Security:** +- Fixed FTS5 injection vulnerability in search functions +- Added comprehensive test suite with 332 injection attack tests + +**Fixes:** +- Fixed ESM/CJS compatibility for getDirname function +- Fixed Windows PowerShell compatibility in SessionStart hook +- Cross-platform dependency installation now works on Windows, macOS, and Linux + +## Next Steps + + + + Quick start & advanced installation + + + Learn how Claude-Mem works automatically + + + System components & data flow + + + Query your project history + + diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdx similarity index 97% rename from docs/troubleshooting.md rename to docs/troubleshooting.mdx index 099ff583..c142dccb 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.mdx @@ -1,3 +1,8 @@ +--- +title: "Troubleshooting" +description: "Common issues and solutions for Claude-Mem" +--- + # Troubleshooting Guide ## Worker Service Issues @@ -664,6 +669,6 @@ If none of these solutions work: ## Next Steps -- [Configuration](configuration.md) - Customize Claude-Mem -- [Development](development.md) - Build from source -- [Architecture](architecture/overview.md) - Understand the system +- [Configuration](configuration) - Customize Claude-Mem +- [Development](development) - Build from source +- [Architecture](architecture/overview) - Understand the system diff --git a/docs/usage/getting-started.md b/docs/usage/getting-started.mdx similarity index 92% rename from docs/usage/getting-started.md rename to docs/usage/getting-started.mdx index bbb16225..4f36e9ba 100644 --- a/docs/usage/getting-started.md +++ b/docs/usage/getting-started.mdx @@ -1,3 +1,8 @@ +--- +title: "Getting Started" +description: "Learn how Claude-Mem works automatically in the background" +--- + # Getting Started with Claude-Mem ## Automatic Operation @@ -166,6 +171,6 @@ When you use `/clear`, the session doesn't end - it continues with a new prompt ## Next Steps -- [MCP Search Tools](search-tools.md) - Learn how to search your project history -- [Architecture Overview](../architecture/overview.md) - Understand how it works -- [Troubleshooting](../troubleshooting.md) - Common issues and solutions +- [MCP Search Tools](/usage/search-tools) - Learn how to search your project history +- [Architecture Overview](/architecture/overview) - Understand how it works +- [Troubleshooting](/troubleshooting) - Common issues and solutions diff --git a/docs/usage/search-tools.md b/docs/usage/search-tools.mdx similarity index 96% rename from docs/usage/search-tools.md rename to docs/usage/search-tools.mdx index 3f9e1cb9..94bf08de 100644 --- a/docs/usage/search-tools.md +++ b/docs/usage/search-tools.mdx @@ -1,3 +1,8 @@ +--- +title: "MCP Search Tools" +description: "Query your project history with 7 specialized search tools" +--- + # MCP Search Tools Usage Once claude-mem is installed as a plugin, 7 search tools become available in your Claude Code sessions for querying project history. @@ -416,6 +421,6 @@ search_sessions with query="[YOUR PROJECT NAME]" and orderBy="date_desc" ## Next Steps -- [MCP Search Architecture](../architecture/mcp-search.md) - Technical details -- [Database Schema](../architecture/database.md) - Understanding the data -- [Getting Started](getting-started.md) - Automatic operation +- [MCP Search Architecture](/architecture/mcp-search) - Technical details +- [Database Schema](/architecture/database) - Understanding the data +- [Getting Started](/usage/getting-started) - Automatic operation