claude-mem 3.3.7 → 3.3.9

package/docs/STATUS.md

@@ -0,0 +1,155 @@
+# App Status Audit Template
+
+This is the template for what each system in claude-mem actually does and its current status.
+
+## Core Systems Status
+
+### [X] Hooks
+
+**Pre-Compact Hook** (`hooks/pre-compact.js`)
+[X] Triggers when `/compact` command is run in Claude Code
+[X] Receives transcript path from Claude Code
+[X] Spawns compression subprocess
+[X] Waits for compression to complete
+[X] Returns continue:true to allow compaction
+[] Has excessive defensive validation (35 lines) violating Make It Work First manifesto
+
+**Session Start Hook** (`hooks/session-start.js`)  
+[X] Triggers when new Claude Code session starts
+[X] Loads context from embedded Weaviate
+[X] Returns context in hookSpecificOutput
+[X] Context may be empty if no memories stored
+[X] Perfect manifesto compliance - clean direct execution
+
+**Session End Hook** (`hooks/session-end.js`)
+[X] Triggers when Claude Code session ends
+[X] Currently placeholder - just returns continue:true
+[X] Does not trigger compression (removed in cleanup)
+[X] Perfect minimal placeholder implementation
+
+### [X] CLI Commands
+
+**Compress Command** (`src/commands/compress.ts`)
+[X] Accepts transcript file path
+[X] Creates TranscriptCompressor instance
+[X] Runs compression via Claude SDK
+[X] Stores in embedded Weaviate
+[X] Creates archive in ~/.claude-mem/archives/
+[X] Good manifesto compliance - direct execution
+
+**Load Context Command** (`src/commands/load-context.ts`)
+[X] Reads memory index file
+[X] Filters by project if specified
+[X] Returns formatted context
+[X] Supports JSON and session-start formats
+[X] Simple direct implementation
+
+**Install Command** (`src/commands/install.ts`)
+[X] Creates ~/.claude-mem directory structure
+[X] Copies hooks to correct location  
+[X] Sets up MCP server configuration
+[X] Installs embedded Weaviate dependencies
+[X] Supports user/project/local scopes
+[] Has code duplication issues (DRY violations)
+
+**Status Command** (`src/commands/status.ts`)
+[X] Shows installation status
+[X] Displays hook configuration
+[X] Shows compressed archives count
+[X] Verifies runtime environment
+[X] Comprehensive diagnostic tool
+
+### [X] Storage Backend
+
+**Embedded Weaviate** (`src/utils/weaviate-mcp-adapter.ts`)
+[X] Auto-starts on port 6666
+[X] No external dependencies
+[X] Stores entities and relations
+[X] Hybrid search (semantic + keyword)
+[X] Persists data between sessions
+[X] Exponential backoff retry logic
+[X] Advanced query parsing
+
+**MCP Server** (`src/mcp-server.ts`)
+[X] Implements Model Context Protocol
+[X] Exposes memory management tools (4 tools)
+[X] Works with Claude Code MCP integration
+[X] Stdio transport for Claude Code
+[X] Proper error handling
+
+### [X] Compression Pipeline
+
+**TranscriptCompressor** (`src/utils/TranscriptCompressor.ts`)
+[X] Reads JSONL transcripts
+[X] Uses Claude SDK to analyze
+[X] Extracts entities and relations
+[X] Stores in Weaviate
+[X] Creates archives
+[X] Sophisticated prompt engineering
+[X] Tool chain extraction
+
+## Known Issues
+
+1. ~~**Pre-compact hook validation fortress**: 35 lines of defensive code violating manifesto~~ ✅ FIXED
+2. **Error visibility**: Errors often silent due to "no blockers" philosophy
+3. **Testing infrastructure**: All tests removed in commit 31c67e5 - NO ACTIVE TESTS
+4. **Code duplication**: Significant DRY violations in install.ts and TranscriptCompressor
+5. **Architectural confusion**: Multiple interfaces/clients for same functionality
+6. **Client interface duplication**: Three different ways to access WeaviateMCPAdapter
+7. ~~**Logic flow issues**: Defensive JSON parsing and nested conditionals~~ ✅ FIXED
+8. ~~**Migrate command**: Unused mock implementation~~ ✅ DELETED
+
+## Testing
+
+**NO ACTIVE TESTS - All test infrastructure removed in commit 31c67e5**
+
+Previously had comprehensive testing (now deleted):
+- Hook simulation tests
+- Unit tests with 100% coverage
+- Security vulnerability testing
+- Performance testing
+- Integration testing
+
+Remaining test dependencies in package.json should be removed.
+
+## Environment Requirements
+
+- Node.js 18+
+- Bun (for development)
+- Claude Code SDK (for compression)
+- JWT_SECRET environment variable (for MCP)
+
+## The Truth About /compact
+
+When you run `/compact` in Claude Code:
+1. Claude Code triggers pre-compact hook
+2. Hook receives transcript_path in JSON via stdin
+3. Hook performs excessive 35-line path validation (violates manifesto)
+4. Hook spawns `claude-mem compress [transcript]`
+5. Compression runs using TranscriptCompressor with Claude SDK
+6. Hook returns `{continue: true, suppressOutput: true}` 
+7. Claude Code proceeds with compaction
+
+**Current Status**: Functional but over-engineered with defensive validation.
+
+## Audit Summary
+
+### Working Systems:
+- ✅ All three hooks functional (pre-compact needs refactoring)
+- ✅ All CLI commands operational
+- ✅ Embedded Weaviate fully implemented
+- ✅ MCP server properly integrated
+- ✅ Compression pipeline sophisticated and working
+
+### Major Issues Found:
+- ❌ Pre-compact hook has fortress validation pattern
+- ❌ Zero test coverage (all tests deleted)
+- ❌ Significant code duplication (DRY violations)
+- ❌ Architectural confusion with multiple client interfaces
+- ❌ Logic flow issues with defensive coding throughout
+
+### Manifesto Compliance:
+- Session hooks: ⭐ Perfect examples
+- Pre-compact hook: ❌ Major violation
+- CLI commands: ✅ Generally good
+- Overall: Mixed - documentation preaches simplicity but code is defensive

package/docs/chroma-backend-migration.md

@@ -0,0 +1,161 @@
+# Chroma Backend Migration Plan
+
+## Goal
+Replace the entire Weaviate-based claude-mem backend with Chroma MCP, installed as "claude-mem" for namespacing. Use Chroma MCP directly without any adapter code.
+
+## Current Architecture
+```
+Claude → claude-mem MCP Server → Weaviate Adapter → Embedded Weaviate
+```
+- Complex: 1,782 lines in weaviate-mcp-adapter.ts
+- Local embedding generation via @xenova/transformers
+- Embedded Weaviate binary management
+- Custom MCP server implementation
+
+## New Architecture  
+```
+Claude → Chroma MCP (installed as "claude-mem")
+```
+- Simple: Direct usage of Chroma MCP tools
+- Chroma handles all embeddings internally
+- No custom code needed
+- Namespaced as `mcp__claude-mem__*` tools
+
+## Migration Steps
+
+### 1. Install Chroma MCP as "claude-mem"
+Add Chroma MCP with our namespace to the user's MCP configuration:
+```bash
+claude mcp add claude-mem -- uvx chroma-mcp --client-type persistent --data-dir ~/.claude-mem/chroma
+```
+
+### 2. Update CLAUDE.md Instructions
+Update the memory instructions to use our namespaced tools:
+- `mcp__claude-mem__chroma_add_documents` for storing memories
+- `mcp__claude-mem__chroma_query_documents` for searching memories
+- `mcp__claude-mem__chroma_get_documents` for retrieving specific memories
+- `mcp__claude-mem__chroma_list_collections` for viewing collections
+
+### 3. Update Analysis Prompt Templates
+Modify `/src/prompts/templates/analysis/analysisTemplates.ts` to:
+- Change output format from entity/relation structure to document format
+- Format memories as natural language descriptions with metadata
+- Align with Chroma's document model expectations
+- Example change:
+  ```typescript
+  // Old format (entities/relations)
+  {
+    entities: [...],
+    relations: [...]
+  }
+  
+  // New format (documents for Chroma)
+  {
+    memories: [
+      {
+        document: "Natural language description",
+        metadata: { type, tags, context }
+      }
+    ]
+  }
+  ```
+
+### 4. Remove All Backend Code
+Since we're using Chroma MCP directly:
+- Remove `/src/storage/adapters/weaviate-mcp-adapter.ts`
+- Remove `/src/embeddings/` directory
+- Remove `/src/bin/mcp-server.ts` and `/src/bin/mcp-server-cli.ts`
+- Update install command to just add Chroma MCP
+
+### 5. Update Memory Prompt Format
+
+#### Storing Memories (in CLAUDE.md)
+```markdown
+When you learn something worth remembering, store it:
+mcp__claude-mem__chroma_add_documents({
+  collection_name: "claude_memories",
+  documents: ["Natural language description of what you learned"],
+  ids: ["memory_" + timestamp],
+  metadatas: [{
+    type: "component/pattern/decision/fix/etc",
+    context: "what you were working on",
+    tags: "relevant,keywords"
+  }]
+})
+```
+
+#### Searching Memories (in CLAUDE.md)
+```markdown
+To recall relevant information:
+mcp__claude-mem__chroma_query_documents({
+  collection_name: "claude_memories",
+  query_texts: ["what you're looking for"],
+  n_results: 10,
+  where: { type: "component" } // optional filtering
+})
+```
+
+### 6. Simplify Installation
+Update `/src/commands/install.ts` to:
+- Output only: `claude mcp add claude-mem -- uvx chroma-mcp --client-type persistent --data-dir ~/.claude-mem/chroma`
+- Remove all Weaviate binary download logic
+- Remove embedding model downloads
+- Remove database initialization
+
+### 7. Files to Remove (After Testing)
+**Backend Code:**
+- `/src/storage/adapters/weaviate-mcp-adapter.ts` (1,782 lines)
+- `/src/embeddings/` (entire directory)
+- `/src/bin/mcp-server.ts` 
+- `/src/bin/mcp-server-cli.ts`
+
+**Documentation:**
+- `/docs/reference/weaviate-concepts.md`
+- `/docs/reference/embedded-weaviate.md`
+
+**Dependencies in package.json:**
+- `weaviate-ts-embedded`
+- `@xenova/transformers`
+- All embedding-related packages
+
+### 8. Files to Keep/Update
+- `/src/commands/install.ts` - Simplified to output install command
+- `CLAUDE.md` - Updated with Chroma MCP instructions
+- `README.md` - Simplified installation docs
+
+## Testing Checklist
+1. Run: `claude mcp add claude-mem -- uvx chroma-mcp --client-type persistent --data-dir ~/.claude-mem/chroma`
+2. Test storing a memory:
+   ```javascript
+   mcp__claude-mem__chroma_add_documents({
+     collection_name: "claude_memories",
+     documents: ["Test memory: The auth system uses OAuth2"],
+     ids: ["test_1"],
+     metadatas: [{ type: "test", tags: "auth,oauth" }]
+   })
+   ```
+3. Test searching:
+   ```javascript
+   mcp__claude-mem__chroma_query_documents({
+     collection_name: "claude_memories",
+     query_texts: ["authentication"],
+     n_results: 5
+   })
+   ```
+4. Verify persistence across Claude sessions
+5. Confirm namespacing works (tools show as `mcp__claude-mem__*`)
+
+## Implementation Notes
+- The project name "claude-mem" remains the same
+- We're essentially replacing our custom MCP server with Chroma MCP
+- All memory operations happen through Chroma's document model
+- Collection name: `claude_memories` (single collection for all memories)
+- Metadata fields: type, context, tags, timestamp, etc.
+
+## End Result
+- **Installation**: One command
+- **Code to maintain**: Minimal (just install helper)
+- **Memory storage**: Natural language documents with metadata
+- **Tool namespace**: `mcp__claude-mem__*`
+- **Data location**: `~/.claude-mem/chroma`
+- **Complexity**: Reduced by ~2000 lines of code

package/docs/landing-page-outline.md

@@ -0,0 +1,287 @@
+# Claude-Mem.ai Landing Page Outline
+
+## Hero Section
+### Headline
+"Your AI Assistant Finally Has a Memory"
+
+### Subheadline
+"Transform Claude Code from forgetful to brilliant. Never explain your project twice. Build knowledge that grows with every conversation."
+
+### Primary CTA
+"Get Started Free" → Free installation instructions
+
+### Secondary CTA
+"Join Cloud Waitlist" → Coming soon cloud plans
+
+### Hero Visual
+- Animation showing conversation → compression → memory → context loading
+- Dashboard preview showing organized memories
+- Developer working seamlessly across sessions
+
+## Problem Statement Section
+### Headline
+"Every Developer Knows This Pain"
+
+### Pain Points (with icons)
+1. **The Groundhog Day Effect**: Starting every Claude session from scratch
+2. **Lost Breakthroughs**: Brilliant solutions buried in forgotten conversations
+3. **Context Switching Nightmare**: Re-explaining your entire codebase repeatedly
+4. **Knowledge Decay**: Solutions discovered and forgotten multiple times
+5. **Team Silos**: Each developer's insights trapped in their own sessions
+
+### Visual
+Split-screen showing "Before" (frustrated developer) vs "After" (efficient workflow)
+
+## Solution Overview
+### Headline
+"Meet Claude-Mem: Your Persistent AI Knowledge Base"
+
+### Key Benefits
+1. **Intelligent Memory**: AI automatically extracts and stores key insights
+2. **Seamless Integration**: One command setup, zero friction
+3. **Smart Context**: Relevant memories loaded automatically
+4. **Cross-Project Learning**: Knowledge that spans all your work
+5. **Team Sharing** (coming soon): Collective intelligence for your team
+
+### Demo Video
+Screen recording showing:
+- Installation (`claude-mem install`)
+- Working session with Claude Code
+- Memory compression with `/compact`
+- New session with automatic context loading
+
+## Features Deep Dive
+### How It Works
+1. **Install Once, Benefit Forever**
+   - Single command setup
+   - Automatic Claude Code integration
+   - No configuration needed
+
+2. **Invisible Intelligence**
+   - Triggers automatically on `/compact` and `/clear`
+   - AI analyzes conversations for key insights
+   - Stores patterns, solutions, and decisions
+
+3. **Context That Follows You**
+   - Smart memory retrieval
+   - Project-aware context loading
+   - Semantic search across all sessions
+
+### Technical Features
+- **Local-First Architecture**: Your data stays on your machine
+- **Vector Database**: ChromaDB for semantic search
+- **MCP Integration**: Native Claude Code protocol support
+- **AI-Powered Analysis**: Advanced prompt engineering for extraction
+
+## Pricing Section
+### Headline
+"Choose Your Claude-Mem Experience"
+
+### Free (Open Source)
+**$0 Forever**
+- ✅ Complete local installation
+- ✅ Unlimited memory storage
+- ✅ All core features
+- ✅ Community support
+- ✅ Local ChromaDB
+- ❌ Multi-device sync
+- ❌ Cloud backup
+- ❌ Team sharing
+
+**CTA**: "Install Now" → Free installation guide
+
+### Individual Cloud Plan
+**$9.95/month**
+*Coming Soon - Join Waitlist*
+- ✅ Everything in Free
+- ✅ Multi-device synchronization
+- ✅ Cloud backup & restore
+- ✅ Enhanced search capabilities
+- ✅ API access
+- ✅ Priority support
+- ✅ 100,000 vectors stored
+- ✅ 10,000 API requests/month
+
+**CTA**: "Join Waitlist" → PayPal subscription setup
+
+### Team Plan
+**$29.95/month** *(minimum 3 seats)*
+*Coming Soon - Join Waitlist*
+- ✅ Everything in Individual
+- ✅ Shared team memories
+- ✅ Role-based access control
+- ✅ Admin dashboard
+- ✅ Team usage analytics
+- ✅ 500,000 vectors per seat
+- ✅ 50,000 API requests/month per seat
+- ✅ White-label options
+
+**CTA**: "Contact Sales" → Team consultation form
+
+### Payment Processing
+All cloud plans use **PayPal** for subscription management:
+- Secure payment processing
+- Easy cancellation
+- Automatic billing
+- Multiple payment methods
+- International support
+
+## Installation Guide Section
+### Headline
+"Get Started in 60 Seconds"
+
+### Step-by-Step Guide
+```bash
+# 1. Install claude-mem
+npm install -g claude-mem
+
+# 2. Set up Claude Code integration
+claude-mem install
+
+# 3. Restart Claude Code
+
+# 4. Start building your knowledge base!
+```
+
+### Prerequisites
+- Node.js 18.0+
+- Claude Code installed
+- 2GB RAM recommended
+
+### Verification
+```bash
+# Check everything is working
+claude-mem status
+```
+
+## Use Cases & Benefits
+### For Solo Developers
+- **Faster Problem Solving**: Find solutions you've used before instantly
+- **Knowledge Accumulation**: Build expertise that persists across projects
+- **Context Continuity**: Pick up where you left off, even weeks later
+- **Pattern Recognition**: See how you've solved similar problems before
+
+### For Development Teams
+- **Shared Intelligence**: Team-wide knowledge accessible to all
+- **Faster Onboarding**: New developers access collective wisdom
+- **Best Practice Capture**: Proven solutions automatically documented
+- **Institutional Memory**: Knowledge persists beyond team changes
+
+### Real User Stories
+> "I used to spend 20 minutes explaining my architecture every time I started a new Claude session. Now it just knows." - Sarah, Full-Stack Developer
+
+> "Our team has built up 6 months of shared knowledge. New hires are productive on day one." - Mike, Engineering Manager
+
+> "I found a bug fix I wrote 3 months ago in seconds. Would have taken hours to recreate." - Alex, Senior Developer
+
+## Technical Deep Dive (Optional Expandable Section)
+### Architecture
+- **Vector Database**: ChromaDB for semantic search
+- **AI Analysis**: GPT-4 powered conversation analysis
+- **Storage**: Local SQLite + JSON archives
+- **Integration**: Model Context Protocol (MCP)
+
+### Security & Privacy
+- **Local-First**: All data on your machine by default
+- **No Tracking**: We don't see your conversations
+- **Open Standards**: Built on MCP and ChromaDB
+- **Your Data**: Complete ownership and control
+
+### Advanced Features
+- **Smart Trash**: Recoverable file deletion
+- **Project Isolation**: Separate memories per project
+- **Semantic Search**: Find concepts, not just keywords
+- **Tool Chain Analysis**: Understands multi-step workflows
+
+## FAQ Section
+### Common Questions
+
+**Q: How is this different from just saving chat logs?**
+A: Claude-mem uses AI to extract the important insights, patterns, and solutions from your conversations, then makes them searchable and automatically loads relevant context in new sessions.
+
+**Q: Does this work with other AI assistants?**
+A: Currently built specifically for Claude Code, but we're exploring support for other platforms.
+
+**Q: What about privacy?**
+A: By default, everything stays local on your machine. Cloud plans are opt-in with full transparency about what's stored.
+
+**Q: Can I try before buying cloud features?**
+A: Absolutely! The free version is fully functional. Cloud plans add sync and team features.
+
+**Q: How much storage does it use?**
+A: Typical usage is 50-100MB. Large teams might use 1-2GB.
+
+## Social Proof Section
+### GitHub Stats
+- ⭐ X Stars
+- 🍴 X Forks  
+- 📦 X Weekly Downloads
+- 🐛 X Issues Resolved
+
+### Community
+- 💬 Discord Community: X Members
+- 📰 Newsletter: X Subscribers
+- 🐦 Twitter: X Followers
+
+## Footer
+### Links
+- Documentation
+- GitHub Repository
+- Community Discord
+- Support
+- Privacy Policy
+- Terms of Service
+
+### Contact
+- Email: hello@claude-mem.ai
+- Twitter: @claudemem
+- Discord: claude-mem.ai/discord
+
+### Newsletter Signup
+"Get updates on cloud features and new releases"
+
+## Technical Implementation Notes
+
+### PayPal Integration
+- Use PayPal Subscriptions API
+- Webhook handling for subscription events
+- Customer portal for plan management
+- Automatic renewal and cancellation
+- Support for multiple currencies
+
+### Analytics & Tracking
+- Privacy-focused analytics (no personal data)
+- Conversion tracking for waitlist signups
+- A/B testing framework for messaging
+- Performance monitoring
+
+### SEO Optimization
+- Keywords: claude code memory, AI assistant memory, conversation persistence
+- Meta descriptions and titles optimized
+- Schema markup for products/pricing
+- Fast loading times (<3s)
+
+### Responsive Design
+- Mobile-first approach
+- Tablet optimization
+- Desktop experience
+- Progressive enhancement
+
+## Content Strategy
+### Blog Post Ideas
+1. "Why AI Assistants Need Memory"
+2. "Building a Knowledge Base from Your Code Conversations"
+3. "The Future of AI-Assisted Development"
+4. "Case Study: 10x Productivity with Persistent Context"
+
+### Video Content
+1. Setup and installation demo
+2. Real-world workflow examples
+3. Team collaboration features
+4. Technical deep dive for developers
+
+### Community Building
+1. Discord server for users
+2. GitHub discussions for feature requests
+3. Newsletter for updates and tips
+4. Twitter for quick updates and engagement

package/docs/multi-platform-builds.md

@@ -0,0 +1,96 @@
+# Multi-Platform Build Guide
+
+This project now supports building binaries for multiple platforms using Bun's cross-compilation capabilities.
+
+## Supported Platforms
+
+- **Windows x64**: `claude-mem.exe`
+- **Linux x64**: `claude-mem-linux` 
+- **Linux ARM64**: `claude-mem-linux-arm64`
+- **macOS ARM64**: `claude-mem-macos-arm64`
+- **macOS x64**: `claude-mem-macos-x64`
+
+## Building
+
+### Build All Platforms
+
+To build binaries for all supported platforms:
+
+```bash
+npm run build:multiplatform
+```
+
+This will create binaries in the `releases/binaries/` directory.
+
+### Build for NPM Package
+
+To build a complete npm package with all platform binaries:
+
+```bash
+npm run publish
+```
+
+This creates a package in `releases/npm-package/` that includes:
+- Platform detection wrapper script
+- All platform-specific binaries
+- Hooks and configuration files
+
+## How Platform Detection Works
+
+The npm package includes a Node.js wrapper script (`claude-mem`) that:
+
+1. Detects the current platform using `process.platform` and `process.arch`
+2. Maps the platform to the appropriate binary filename
+3. Executes the correct binary with all command-line arguments
+
+### Platform Mapping
+
+| Platform | Architecture | Binary Filename |
+|----------|-------------|------------------|
+| Windows | x64 | `claude-mem.exe` |
+| Linux | x64 | `claude-mem-linux` |
+| Linux | arm64/aarch64 | `claude-mem-linux-arm64` |
+| macOS | arm64 | `claude-mem-macos-arm64` |
+| macOS | x64 | `claude-mem-macos-x64` |
+
+## Usage
+
+After installation via npm, users can run:
+
+```bash
+npx claude-mem --help
+```
+
+The wrapper will automatically select and execute the correct binary for their platform.
+
+## Troubleshooting
+
+### Unsupported Platform Error
+
+If you see an "Unsupported platform" error, check that your platform/architecture combination is in the supported list above.
+
+### Binary Not Found Error
+
+This indicates the platform detection worked, but the expected binary file is missing from the package. This shouldn't happen with properly built packages.
+
+## Development
+
+### Adding New Platforms
+
+To add support for new platforms:
+
+1. Add the platform to the `PLATFORMS` array in `scripts/build-multiplatform.sh`
+2. Update the platform detection logic in `scripts/claude-mem-wrapper.js`
+3. Update this documentation
+
+### Testing Binaries
+
+Test that a specific binary works:
+
+```bash
+# Test Linux binary
+./releases/binaries/claude-mem-linux --help
+
+# Test Windows binary (on Windows or with Wine)
+./releases/binaries/claude-mem.exe --help
+```