airkjw/claude-mem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add initial documentation for Claude-Mem plugin

Browse Source 
- Created docs structure including introduction, installation, troubleshooting, and usage guides.
- Added detailed installation instructions with quick start and advanced options.
- Documented the automatic operation of Claude-Mem and its session management features.
- Introduced MCP search tools with usage examples and query strategies.
- Provided troubleshooting steps for common issues related to worker service, hooks, database, and search tools.
- Included system requirements and upgrade notes for transitioning from v3.x to v4.0.0.
This commit is contained in:
Alex Newman
2025-10-24 18:04:03 -04:00
parent 12149470a2
commit 8b4c962e62
25 changed files with 272 additions and 4548 deletions
Download Patch File Download Diff File Expand all files Collapse all files
context/architecture/REFACTOR-PLAN.md → context/architecture/v3-to-v4.md
+3 -1
View File
@@ -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
context/magic-ui/components-catalog.md
-283
View File
@@ -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)
context/magic-ui/creative-ideas.md
-471
View File
@@ -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
context/magic-ui/idea-rankings.md
-389
View File
@@ -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%)
context/temp/PHASE1-COMPLETE.md
-134
View File
@@ -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 (`<observation>` and `<summary>` 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.
context/temp/PHASE2-COMPLETE.md
-175
View File
@@ -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 `<observation>` and `<summary>` 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
context/temp/PHASE2-PROMPT.md
-118
View File
@@ -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 `<observation>` and `<summary>` 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 `<observation>` blocks with `<type>` and `<text>`
- Parse `<summary>` blocks with 8 required fields
- Extract file arrays from `<file>` 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 `<observation>` and `<summary>` 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.
context/temp/PHASE3-COMPLETE.md
-271
View File
@@ -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!** 🎉