claude-mem 3.3.7 → 3.3.9

package/README.md

@@ -2,77 +2,214 @@
 
 **Truth + Context = Clarity**
 
-A professional CLI tool that transforms Claude Code conversation transcripts into a persistent, searchable knowledge graph. Never lose valuable context from your AI-assisted development sessions again.
-
-## What is Claude-Mem?
-
-Claude Memory System automatically:
-- 🗜️ **Compresses** your Claude Code conversations into structured knowledge
-- 🔍 **Extracts** key components, patterns, decisions, and fixes
-- 📚 **Archives** sessions for future reference
-- 🚀 **Loads** relevant context when you start new sessions
-- ⚡ **Integrates** seamlessly with Claude Code via hooks
-
-## Installation
-
+A revolutionary memory system that transforms your Claude Code conversations into a persistent, intelligent knowledge base. Never lose valuable insights, code patterns, or debugging solutions again. Your AI assistant finally has a memory that spans across all your projects and sessions.
+
+## 🚀 Why Claude-Mem?
+
+### The Problem We Solve
+- **Lost Context**: Starting every Claude Code session from scratch
+- **Repeated Explanations**: Re-describing your codebase and architecture repeatedly  
+- **Fragmented Knowledge**: Valuable insights scattered across hundreds of conversations
+- **Context Switching**: Losing progress when switching between projects or devices
+- **Knowledge Decay**: Brilliant solutions forgotten and re-discovered multiple times
+
+### The Claude-Mem Solution
+Transform your Claude Code experience from forgetful to persistent, from isolated sessions to connected knowledge, from starting over to building upon previous insights.
+
+## ✨ Key Features
+
+### 🧠 **Intelligent Memory Compression**
+- Automatically extracts key learnings from your Claude Code conversations
+- Identifies patterns, architectural decisions, and breakthrough moments
+- Compresses hours of conversation into searchable, actionable knowledge
+- Uses advanced AI analysis to understand context and significance
+
+### 🔄 **Seamless Integration**
+- **One-command setup**: `claude-mem install` and you're ready
+- **Zero friction**: Works invisibly in the background
+- **Automatic triggers**: Memory compression on `/compact` and `/clear`
+- **Instant context loading**: New sessions start with relevant memories
+
+### 🎯 **Smart Context Loading**
+- Loads relevant memories when starting new sessions
+- Project-aware context selection
+- Semantic search finds related knowledge across all sessions
+- Prevents re-explaining the same concepts repeatedly
+
+### 📚 **Comprehensive Knowledge Base**
+- Stores technical implementations, bug fixes, and solutions
+- Captures design patterns and architectural decisions
+- Remembers tool configurations and setup procedures
+- Archives complete conversation transcripts for detailed reference
+
+### 🔍 **Powerful Search & Retrieval**
+- Vector-based semantic search finds related concepts
+- Keyword search for specific terms and technologies
+- Project filtering to focus on relevant memories
+- Time-based filtering to find recent insights
+
+## 🛠 Installation & Setup
+
+### Quick Install
 ```bash
 # Install globally
 npm install -g claude-mem
 
-# Or use with npx (no install needed)
+# Set up Claude Code integration
+claude-mem install
+
+# Restart Claude Code to activate
+```
+
+### Alternative Installation
+```bash
+# Use without installing globally
 npx claude-mem install
 ```
 
-## Quick Start
+### Verification
+```bash
+# Check installation status
+claude-mem status
+```
+
+## 💻 How It Works
 
-1. **Install the hooks into Claude Code:**
+### The Memory Lifecycle
+
+1. **🎬 Session Start**: Claude-mem loads relevant context from your knowledge base
+2. **💬 Active Session**: You work normally in Claude Code - no changes needed
+3. **🗜️ Memory Compression**: Use `/compact` or `/clear` to trigger intelligent compression
+4. **🧠 Knowledge Extraction**: AI analysis extracts key learnings and patterns
+5. **💾 Persistent Storage**: Memories stored in searchable vector database
+6. **🔄 Context Ready**: Next session starts with relevant memories loaded
+
+### Technical Architecture
+
+- **Vector Database**: ChromaDB for semantic search and storage
+- **MCP Integration**: Model Context Protocol for Claude Code communication
+- **AI Analysis**: Advanced prompt engineering for knowledge extraction
+- **Local Storage**: All data stored locally in `~/.claude-mem/`
+
+## 📋 Commands Reference
+
+### Core Commands
 ```bash
-claude-mem install
+claude-mem install          # Set up Claude Code integration
+claude-mem status           # Check system status and configuration
+claude-mem load-context     # View and search stored memories
+claude-mem logs             # View system logs and debug information
+claude-mem uninstall       # Remove Claude Code hooks
+```
+
+### Advanced Usage
+```bash
+claude-mem compress <file>  # Manually compress a transcript file
+claude-mem restore          # Restore from backups
+claude-mem trash-view       # View deleted files (Smart Trash feature)
+```
+
+## 📁 Storage Structure
+
+Your claude-mem data is organized in `~/.claude-mem/`:
+
+```
+~/.claude-mem/
+├── index/           # ChromaDB vector database
+├── archives/        # Original conversation transcripts  
+├── hooks/           # Claude Code integration scripts
+├── trash/           # Smart Trash (deleted files)
+└── logs/            # System logs and debug information
 ```
 
-2. **Restart Claude Code** to load the new hooks
+## 🌟 Real-World Benefits
+
+### For Individual 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 Teams (Coming Soon)
+- **Shared Knowledge**: Team-wide memory accessible to all members
+- **Onboarding Acceleration**: New team members access collective knowledge
+- **Best Practices**: Capture and share proven solutions
+- **Institutional Memory**: Prevent knowledge loss when team members leave
+
+## 🚀 Coming Soon: Cloud Sync
 
-3. **Use `/clear` and `/compact` in Claude Code** to trigger memory compression
+### Individual Plan ($9.95/month)
+- **Multi-device sync**: Access your memories on any device
+- **Cloud backup**: Never lose your knowledge base
+- **Enhanced search**: Advanced filtering and semantic search
+- **API access**: Integrate with your own tools and workflows
 
-4. **Start new sessions** with automatic context loading
+### Team Plan ($29.95/month, 3+ seats)
+- **Shared memories**: Team-wide knowledge base
+- **Role-based access**: Control what memories are shared
+- **Admin dashboard**: Manage team members and usage
+- **Priority support**: Direct access to our engineering team
 
-## Commands
+[**Join the waitlist**](https://claude-mem.ai) for early access to cloud features.
 
-- `claude-mem install` - Set up Claude Code integration
-- `claude-mem status` - Check system status
-- `claude-mem compress <transcript>` - Manually compress a transcript
-- `claude-mem load-context` - View stored memories
-- `claude-mem logs` - View system logs
-- `claude-mem uninstall` - Remove Claude Code hooks
+## 🛡️ Privacy & Security
 
-## How It Works
+- **Local-first**: All data stored locally by default
+- **No tracking**: We don't collect or transmit your conversations
+- **Your data**: You own and control your knowledge base
+- **Open architecture**: ChromaDB and MCP are open standards
 
-1. When you use `/clear` or `/compact` in Claude Code, claude-mem automatically compresses your conversation
-2. Entities (components, patterns, fixes, etc.) are extracted and stored
-3. When you start a new Claude Code session, relevant context is automatically loaded
-4. Your knowledge base grows smarter with each session
+## 🆘 Troubleshooting
 
-## Requirements
+### Common Issues
 
-- Node.js 18.0 or higher
-- Claude Code installed
-- MCP memory server (automatically configured during install)
+**Hook not triggering?**
+```bash
+claude-mem status    # Check installation
+claude-mem install --force   # Reinstall hooks
+```
 
-## Storage
+**Context not loading?**
+```bash
+claude-mem load-context   # Verify memories exist
+claude-mem logs           # Check for errors
+```
 
-Your compressed memories are stored in:
-- `~/.claude-mem/index/` - Searchable index
-- `~/.claude-mem/archives/` - Original transcripts
-- `~/.claude-mem/hooks/` - Integration scripts
+**Performance issues?**
+```bash
+# ChromaDB maintenance (if needed)
+claude-mem status    # Check memory usage
+```
 
-## License
+## 🔧 Requirements
 
-This software is free to use but is NOT open source. See LICENSE file for details.
+- **Node.js**: 18.0 or higher
+- **Claude Code**: Latest version recommended
+- **Storage**: ~100MB for typical usage
+- **Memory**: 2GB RAM minimum for large knowledge bases
 
-## Support
+## 📞 Support & Community
+
+- **Documentation**: Complete guides at [claude-mem.ai/docs](https://claude-mem.ai/docs)
+- **Issues**: Report bugs at [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
+- **Feature Requests**: [GitHub Discussions](https://github.com/thedotmack/claude-mem/discussions)
+- **Community**: Join our [Discord](https://discord.gg/claude-mem) for tips and discussions
+
+## 📄 License
+
+This software is free to use but is NOT open source. See [LICENSE](LICENSE) file for complete terms.
+
+---
+
+## 🎯 Ready to Transform Your Claude Code Experience?
+
+```bash
+npm install -g claude-mem
+claude-mem install
+```
 
-For issues or questions, visit: https://github.com/thedotmack/claude-mem/issues
+**Your AI assistant is about to get a lot smarter.** 🧠✨
 
 ---
 
-*Built with ❤️ for the Claude Code community*
+*Built with ❤️ for developers who believe AI assistants should remember and learn from every conversation.*

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// <Block> 1.1 ====================================
+// CLI Dependencies and Imports Setup
+// Natural pattern: Import what you need before using it
+import { Command } from 'commander';
+import { PACKAGE_NAME, PACKAGE_VERSION, PACKAGE_DESCRIPTION } from '../shared/config.js';
+// Import command handlers
+import { compress } from '../commands/compress.js';
+import { install } from '../commands/install.js';
+import { uninstall } from '../commands/uninstall.js';
+import { status } from '../commands/status.js';
+import { logs } from '../commands/logs.js';
+import { loadContext } from '../commands/load-context.js';
+import { trash } from '../commands/trash.js';
+import { restore } from '../commands/restore.js';
+const program = new Command();
+// </Block> =======================================
+// <Block> 1.2 ====================================
+// Program Configuration
+// Natural pattern: Configure program metadata first
+program
+    .name(PACKAGE_NAME)
+    .description(PACKAGE_DESCRIPTION)
+    .version(PACKAGE_VERSION);
+// </Block> =======================================
+// <Block> 1.3 ====================================
+// Compress Command Definition
+// Natural pattern: Define command with its options and handler
+// Compress command
+program
+    .command('compress [transcript]')
+    .description('Compress a Claude Code transcript into memory')
+    .option('--output <path>', 'Output directory for compressed files')
+    .option('--dry-run', 'Show what would be compressed without doing it')
+    .option('-v, --verbose', 'Show detailed output')
+    .action(compress);
+// </Block> =======================================
+// <Block> 1.4 ====================================
+// Install Command Definition
+// Natural pattern: Define command with its options and handler
+// Install command
+program
+    .command('install')
+    .description('Install Claude Code hooks for automatic compression')
+    .option('--user', 'Install for current user (default)')
+    .option('--project', 'Install for current project only')
+    .option('--local', 'Install to custom local directory')
+    .option('--path <path>', 'Custom installation path (with --local)')
+    .option('--timeout <ms>', 'Hook execution timeout in milliseconds', '180000')
+    .option('--skip-mcp', 'Skip Chroma MCP server installation')
+    .option('--force', 'Force installation even if already installed')
+    .action(install);
+// </Block> =======================================
+// <Block> 1.5 ====================================
+// Uninstall Command Definition
+// Natural pattern: Define command with its options and handler
+// Uninstall command
+program
+    .command('uninstall')
+    .description('Remove Claude Code hooks')
+    .option('--user', 'Remove from user settings (default)')
+    .option('--project', 'Remove from project settings')
+    .option('--all', 'Remove from both user and project settings')
+    .action(uninstall);
+// </Block> =======================================
+// <Block> 1.6 ====================================
+// Status Command Definition
+// Natural pattern: Define command with its handler
+// Status command
+program
+    .command('status')
+    .description('Check installation status of Claude Memory System')
+    .action(status);
+// </Block> =======================================
+// <Block> 1.7 ====================================
+// Logs Command Definition
+// Natural pattern: Define command with its options and handler
+// Logs command
+program
+    .command('logs')
+    .description('View claude-mem operation logs')
+    .option('--debug', 'Show debug logs only')
+    .option('--error', 'Show error logs only')
+    .option('--tail [n]', 'Show last n lines', '50')
+    .option('--follow', 'Follow log output')
+    .action(logs);
+// </Block> =======================================
+// <Block> 1.8 ====================================
+// Load-Context Command Definition
+// Natural pattern: Define command with its options and handler
+// Load-context command
+program
+    .command('load-context')
+    .description('Load compressed memories for current session')
+    .option('--project <name>', 'Filter by project name')
+    .option('--count <n>', 'Number of memories to load', '10')
+    .option('--raw', 'Output raw JSON instead of formatted text')
+    .option('--format <type>', 'Output format: json, session-start, or default')
+    .action(loadContext);
+// </Block> =======================================
+// <Block> 1.9 ====================================
+// Trash and Restore Commands Definition
+// Natural pattern: Define commands for safe file operations
+// Trash command with subcommands
+const trashCmd = program
+    .command('trash')
+    .description('Manage trash bin for safe file deletion')
+    .argument('[files...]', 'Files to move to trash')
+    .option('-r, --recursive', 'Remove directories recursively')
+    .option('-R', 'Remove directories recursively (same as -r)')
+    .option('-f, --force', 'Suppress errors for nonexistent files')
+    .action(async (files, options) => {
+    // If no files provided, show help
+    if (!files || files.length === 0) {
+        trashCmd.outputHelp();
+        return;
+    }
+    // Map -R to recursive
+    if (options.R)
+        options.recursive = true;
+    await trash(files, {
+        force: options.force,
+        recursive: options.recursive
+    });
+});
+// Trash view subcommand
+trashCmd
+    .command('view')
+    .description('View contents of trash bin')
+    .action(async () => {
+    const { viewTrash } = await import('../commands/trash-view.js');
+    await viewTrash();
+});
+// Trash empty subcommand
+trashCmd
+    .command('empty')
+    .description('Permanently delete all files in trash')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .action(async (options) => {
+    const { emptyTrash } = await import('../commands/trash-empty.js');
+    await emptyTrash(options);
+});
+// Restore command
+program
+    .command('restore')
+    .description('Restore files from trash interactively')
+    .action(restore);
+// </Block> =======================================
+// <Block> 1.10 ===================================  
+// Hook Commands for Binary Distribution
+// Internal commands called by hook wrappers
+program
+    .command('hook:pre-compact', { hidden: true })
+    .description('Internal pre-compact hook handler')
+    .action(async () => {
+    const { preCompactHook } = await import('../commands/hooks.js');
+    await preCompactHook();
+});
+program
+    .command('hook:session-start', { hidden: true })
+    .description('Internal session-start hook handler')
+    .action(async () => {
+    const { sessionStartHook } = await import('../commands/hooks.js');
+    await sessionStartHook();
+});
+program
+    .command('hook:session-end', { hidden: true })
+    .description('Internal session-end hook handler')
+    .action(async () => {
+    const { sessionEndHook } = await import('../commands/hooks.js');
+    await sessionEndHook();
+});
+// </Block> =======================================
+// <Block> 1.11 ===================================
+// CLI Execution
+// Natural pattern: After defining all commands, parse and execute
+// Parse arguments and execute
+program.parse();
+// </Block> =======================================

package/dist/commands/compress.d.ts

@@ -0,0 +1,2 @@
+import { OptionValues } from 'commander';
+export declare function compress(transcript?: string, options?: OptionValues): Promise<void>;

package/dist/commands/compress.js

@@ -0,0 +1,27 @@
+import { basename } from 'path';
+import { createLoadingMessage, createCompletionMessage, createOperationSummary, createUserFriendlyError } from '../prompts/templates/context/ContextTemplates.js';
+export async function compress(transcript, options = {}) {
+    console.log(createLoadingMessage('compressing'));
+    if (!transcript) {
+        console.log(createUserFriendlyError('Compression', 'No transcript file provided', 'Please provide a path to a transcript file'));
+        return;
+    }
+    try {
+        const startTime = Date.now();
+        // Import and run compression
+        const { TranscriptCompressor } = await import('../core/compression/TranscriptCompressor.js');
+        const compressor = new TranscriptCompressor({
+            verbose: options.verbose || false
+        });
+        const sessionId = options.sessionId || basename(transcript, '.jsonl');
+        const archivePath = await compressor.compress(transcript, sessionId);
+        const duration = Date.now() - startTime;
+        console.log(createCompletionMessage('Compression', undefined, `Session archived as ${basename(archivePath)}`));
+        console.log(createOperationSummary('compress', { count: 1, duration, details: `Session: ${sessionId}` }));
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.log(createUserFriendlyError('Compression', errorMessage, 'Check that the transcript file exists and you have write permissions'));
+        throw error; // Re-throw to maintain existing error handling behavior
+    }
+}

package/dist/commands/hooks.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hook command handlers for binary distribution
+ * These execute the actual hook logic embedded in the binary
+ */
+/**
+ * Pre-compact hook handler
+ * Runs compression on the Claude Code transcript
+ */
+export declare function preCompactHook(): Promise<void>;
+/**
+ * Session-start hook handler
+ * Loads context for the new session
+ */
+export declare function sessionStartHook(): Promise<void>;
+/**
+ * Session-end hook handler
+ * Compresses session transcript when ending with /clear
+ */
+export declare function sessionEndHook(): Promise<void>;

package/dist/commands/hooks.js

@@ -0,0 +1,131 @@
+/**
+ * Hook command handlers for binary distribution
+ * These execute the actual hook logic embedded in the binary
+ */
+import { compress } from './compress.js';
+import { loadContext } from './load-context.js';
+/**
+ * Pre-compact hook handler
+ * Runs compression on the Claude Code transcript
+ */
+export async function preCompactHook() {
+    try {
+        // Read hook data from stdin (Claude Code sends JSON)
+        let inputData = '';
+        // Set up stdin to read data
+        process.stdin.setEncoding('utf8');
+        // Collect all input data
+        for await (const chunk of process.stdin) {
+            inputData += chunk;
+        }
+        // Parse the JSON input
+        let transcriptPath;
+        if (inputData) {
+            try {
+                const hookData = JSON.parse(inputData);
+                transcriptPath = hookData.transcript_path;
+            }
+            catch (parseError) {
+                // If JSON parsing fails, treat the input as a direct path
+                transcriptPath = inputData.trim();
+            }
+        }
+        // Fallback to environment variable or command line argument
+        if (!transcriptPath) {
+            transcriptPath = process.env.TRANSCRIPT_PATH || process.argv[2];
+        }
+        if (!transcriptPath) {
+            console.log('🗜️ Compressing session transcript...');
+            console.log('❌ No transcript path provided to pre-compact hook');
+            console.log('Hook data received:', inputData || 'none');
+            console.log('Environment TRANSCRIPT_PATH:', process.env.TRANSCRIPT_PATH || 'not set');
+            console.log('Command line args:', process.argv.slice(2));
+            return;
+        }
+        // Run compression with the transcript path
+        await compress(transcriptPath, { dryRun: false });
+    }
+    catch (error) {
+        console.error('Pre-compact hook failed:', error.message);
+        process.exit(1);
+    }
+}
+/**
+ * Session-start hook handler
+ * Loads context for the new session
+ */
+export async function sessionStartHook() {
+    try {
+        // Read hook data from stdin (Claude Code sends JSON)
+        let inputData = '';
+        // Set up stdin to read data
+        process.stdin.setEncoding('utf8');
+        // Collect all input data
+        for await (const chunk of process.stdin) {
+            inputData += chunk;
+        }
+        // Parse the JSON input to get the current working directory
+        let project;
+        if (inputData) {
+            try {
+                const hookData = JSON.parse(inputData);
+                // Extract project name from cwd if provided
+                if (hookData.cwd) {
+                    const pathParts = hookData.cwd.split('/');
+                    project = pathParts[pathParts.length - 1];
+                }
+            }
+            catch (parseError) {
+                // If JSON parsing fails, continue without project filtering
+                console.error('Failed to parse session-start hook data:', parseError);
+            }
+        }
+        // If no project from hook data, try to get from current working directory
+        if (!project) {
+            const pathParts = process.cwd().split('/');
+            project = pathParts[pathParts.length - 1];
+        }
+        // Load context with session-start format and project filtering
+        await loadContext({ format: 'session-start', count: '10', project });
+    }
+    catch (error) {
+        console.error('Session-start hook failed:', error.message);
+        process.exit(1);
+    }
+}
+/**
+ * Session-end hook handler
+ * Compresses session transcript when ending with /clear
+ */
+export async function sessionEndHook() {
+    try {
+        // Read hook data from stdin (Claude Code sends JSON)
+        let inputData = '';
+        // Set up stdin to read data
+        process.stdin.setEncoding('utf8');
+        // Collect all input data
+        for await (const chunk of process.stdin) {
+            inputData += chunk;
+        }
+        // Parse the JSON input to check the reason for session end
+        if (inputData) {
+            try {
+                const hookData = JSON.parse(inputData);
+                // If reason is "clear", compress the session transcript before it's deleted
+                if (hookData.reason === 'clear' && hookData.transcript_path) {
+                    console.log('🗜️ Compressing current session before /clear...');
+                    await compress(hookData.transcript_path, { dryRun: false });
+                }
+            }
+            catch (parseError) {
+                // If JSON parsing fails, log but don't fail the hook
+                console.error('Failed to parse hook data:', parseError);
+            }
+        }
+        console.log('Session ended successfully');
+    }
+    catch (error) {
+        console.error('Session-end hook failed:', error.message);
+        process.exit(1);
+    }
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,2 @@
+import { OptionValues } from 'commander';
+export declare function install(options?: OptionValues): Promise<void>;