claude-mem 2.0.2

package/LICENSE

@@ -0,0 +1,31 @@
+CLAUDE-MEM SOFTWARE LICENSE
+
+Copyright (c) 2024 Alex Newman (@thedotmack). All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software in its compiled/distributed form via npm, to use the software
+for any purpose, subject to the following conditions:
+
+1. USE RIGHTS: You may use the claude-mem CLI tool for personal or commercial
+   purposes without restriction.
+
+2. NO SOURCE CODE RIGHTS: This license does NOT grant access to source code,
+   modification rights, or redistribution rights. The software is provided
+   as-is in its compiled form only.
+
+3. NO REVERSE ENGINEERING: You may not reverse engineer, decompile, or
+   disassemble the software.
+
+4. NO REDISTRIBUTION: You may not redistribute, repackage, or resell this
+   software. Users must install it from the official npm registry.
+
+5. NO WARRANTY: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
+   OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+   THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For questions about this license, contact: thedotmack@gmail.com

package/README.md

@@ -0,0 +1,79 @@
+# Claude Memory System
+
+**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
+
+```bash
+# Install globally
+npm install -g claude-mem
+
+# Or use with npx (no install needed)
+npx claude-mem install
+```
+
+## Quick Start
+
+1. **Install the hooks into Claude Code:**
+```bash
+claude-mem install
+```
+
+2. **Restart Claude Code** to load the new hooks
+
+3. **Use `/compact` in Claude Code** to trigger memory compression
+
+4. **Start new sessions** with automatic context loading
+
+## Commands
+
+- `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
+
+## How It Works
+
+1. When you use `/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
+
+## Requirements
+
+- Node.js 18.0 or higher
+- Claude Code installed
+- MCP memory server (automatically configured during install)
+
+## Storage
+
+Your compressed memories are stored in:
+- `~/.claude-mem/index/` - Searchable index
+- `~/.claude-mem/archives/` - Original transcripts
+- `~/.claude-mem/hooks/` - Integration scripts
+
+## Feedback
+
+Please report issues or feedback at: https://github.com/thedotmack/claude-mem/issues
+
+## License
+
+This software is free to use but is NOT open source. See LICENSE file for details.
+
+---
+
+*Built with ❤️ for the Claude Code community*

package/hooks/pre-compact.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+/**
+ * 🔑 LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits
+ * 
+ * OFFICIAL DOCS: Claude Code Hooks API v2025
+ * Last Verified: 2025-08-31
+ * @see https://docs.anthropic.com/en/docs/claude-code/hooks
+ * 
+ * Claude Memory System - Pre-Compact Hook
+ * 
+ * CRITICAL REQUIREMENTS:
+ * - Hook responses MUST use 'continue' field (boolean)
+ * - When continue is false, MUST provide 'stopReason' field
+ * - DO NOT use 'decision' or 'reason' fields (deprecated pattern)
+ * - PreCompact hooks DO NOT support hookSpecificOutput field
+ * - Exit codes: 0=success, 1=error shown to user, 2=error with stderr shown
+ * 
+ * Valid Response Format:
+ * Success: { "continue": true }
+ * Failure: { "continue": false, "stopReason": "error message" }
+ * 
+ * @docs-ref: Official hook response format specification
+ * @see https://docs.anthropic.com/claude-code/hooks#response-format
+ */
+
+import { spawn } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { readFileSync, existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Load configuration to get the CLI command name
+let cliCommand = 'claude-mem';  // Default fallback
+const configPath = join(__dirname, 'config.json');
+if (existsSync(configPath)) {
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    cliCommand = config.cliCommand || 'claude-mem';
+  } catch (e) {
+    // Fallback to default if config read fails
+  }
+}
+
+async function preCompactHook() {
+  let input = '';
+  
+  // Read JSON input from stdin
+  process.stdin.on('data', chunk => {
+    input += chunk;
+  });
+  
+  process.stdin.on('end', async () => {
+    try {
+      const data = JSON.parse(input);
+      const transcriptPath = data.transcript_path;
+      
+      if (!transcriptPath) {
+        // Output error in Claude Code expected format
+        // @docs-ref: continue: false with stopReason for blocking operations
+        console.log(JSON.stringify({
+          continue: false,
+          stopReason: "No transcript path provided"
+        }));
+        process.exit(2); // Exit 2 tells Claude Code to show error
+      }
+      
+      // Call the CLI compress command using configured name
+      const compressor = spawn(cliCommand, ['compress', transcriptPath], {
+        stdio: ['ignore', 'pipe', 'pipe'] // Capture output instead of inherit
+      });
+      
+      let stdout = '';
+      let stderr = '';
+      
+      compressor.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+      
+      compressor.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+      
+      compressor.on('close', (code) => {
+        if (code !== 0) {
+          // Check if it's the Claude Code executable error
+          if (stderr.includes('Claude Code executable not found')) {
+            // This is expected when running outside Claude Code context
+            // Just output success since we can't compress without Claude SDK
+            // @docs-ref: PreCompact hooks should only use continue field, not hookSpecificOutput
+            console.log(JSON.stringify({
+              continue: true,
+              suppressOutput: true,
+              systemMessage: "Memory compression skipped - Claude SDK not available in this context"
+            }));
+            process.exit(0);
+          } else {
+            // Real error - report it
+            // @docs-ref: Use continue: false with stopReason for errors
+            console.log(JSON.stringify({
+              continue: false,
+              stopReason: `Compression failed: ${stderr}`
+            }));
+            process.exit(2);
+          }
+        } else {
+          // Success! Output confirmation
+          // @docs-ref: PreCompact hooks should only use continue field for success
+          console.log(JSON.stringify({
+            continue: true,
+            suppressOutput: true,
+            systemMessage: "Memory compression completed successfully"
+          }));
+          process.exit(0);
+        }
+      });
+      
+      compressor.on('error', (error) => {
+        // @docs-ref: Use continue: false with stopReason for errors
+        console.log(JSON.stringify({
+          continue: false,
+          stopReason: `Failed to start compression: ${error.message}`
+        }));
+        process.exit(2);
+      });
+      
+    } catch (error) {
+      // @docs-ref: Use continue: false with stopReason for errors
+      console.log(JSON.stringify({
+        continue: false,
+        stopReason: `Hook error: ${error.message}`
+      }));
+      process.exit(2);
+    }
+  });
+}
+
+preCompactHook();

package/hooks/session-end.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+
+/**
+ * 🔑 LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits
+ * 
+ * OFFICIAL DOCS: Claude Code SessionEnd Hook v2025
+ * Last Verified: 2025-08-31
+ * @see https://docs.anthropic.com/en/docs/claude-code/hooks
+ * 
+ * Claude Memory System - Session End Hook
+ * Triggers compression when session ends with reason 'clear'
+ * 
+ * SessionEnd Hook Payload:
+ * {
+ *   "session_id": "string",
+ *   "transcript_path": "string",
+ *   "cwd": "string",
+ *   "hook_event_name": "SessionEnd",
+ *   "reason": "exit" | "clear" | "error" | ...
+ * }
+ * 
+ * Valid Response Format:
+ * Success: { "continue": true }
+ * Success with message: { "continue": true, "systemMessage": "string" }
+ * Failure: { "continue": false, "stopReason": "error message" }
+ * 
+ * Note: SessionEnd hooks should generally always return continue: true
+ * to avoid blocking session termination.
+ * 
+ * @docs-ref: SessionEnd hook should not block session ending
+ * @see https://docs.anthropic.com/claude-code/hooks#sessionend
+ */
+
+import { spawn } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { readFileSync, existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Load configuration to get the CLI command name
+let cliCommand = 'claude-mem';  // Default fallback
+const configPath = join(__dirname, 'config.json');
+if (existsSync(configPath)) {
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    cliCommand = config.cliCommand || 'claude-mem';
+  } catch (e) {
+    // Fallback to default if config read fails
+  }
+}
+
+async function sessionEndHook() {
+  let input = '';
+  
+  // Read JSON input from stdin
+  process.stdin.on('data', chunk => {
+    input += chunk;
+  });
+  
+  process.stdin.on('end', async () => {
+    try {
+      const data = JSON.parse(input);
+      const { reason, transcript_path, session_id } = data;
+      
+      // Only proceed if reason is 'clear'
+      if (reason !== 'clear') {
+        // For other reasons, just continue without action
+        // @docs-ref: SessionEnd hooks should not use hookSpecificOutput
+        console.log(JSON.stringify({
+          continue: true
+        }));
+        process.exit(0);
+      }
+      
+      // Validate transcript path
+      if (!transcript_path) {
+        // @docs-ref: SessionEnd should not block session ending
+        // Just continue even if we can't compress
+        console.log(JSON.stringify({
+          continue: true,
+          systemMessage: "Warning: No transcript path provided for compression"
+        }));
+        process.exit(0);
+      }
+      
+      // Call the CLI compress command (same as pre-compact)
+      const compressor = spawn(cliCommand, ['compress', transcript_path], {
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+      
+      let stdout = '';
+      let stderr = '';
+      
+      compressor.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+      
+      compressor.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+      
+      compressor.on('close', (code) => {
+        if (code !== 0) {
+          // Check if it's the Claude Code executable error
+          if (stderr.includes('Claude Code executable not found')) {
+            // This is expected when running outside Claude Code context
+            // @docs-ref: SessionEnd hooks should not use hookSpecificOutput
+            console.log(JSON.stringify({
+              continue: true,
+              suppressOutput: true
+            }));
+            process.exit(0);
+          } else {
+            // Real error - report it but allow session to end
+            // @docs-ref: Always allow session to end, use systemMessage for errors
+            console.log(JSON.stringify({
+              continue: true,
+              systemMessage: `Memory compression failed: ${stderr}`
+            }));
+            process.exit(0);
+          }
+        } else {
+          // Success! Memory compressed before session clear
+          // @docs-ref: SessionEnd hooks should not use hookSpecificOutput
+          console.log(JSON.stringify({
+            continue: true,
+            suppressOutput: true,
+            systemMessage: "Memory compressed successfully before session clear"
+          }));
+          process.exit(0);
+        }
+      });
+      
+      compressor.on('error', (error) => {
+        // Report error but allow session to end
+        // @docs-ref: Always allow session to end, use systemMessage for errors
+        console.log(JSON.stringify({
+          continue: true,
+          systemMessage: `Failed to start compression: ${error.message}`
+        }));
+        process.exit(0);
+      });
+      
+    } catch (error) {
+      // Report error but allow session to end
+      // @docs-ref: Always allow session to end, use systemMessage for errors
+      console.log(JSON.stringify({
+        continue: true,
+        systemMessage: `Hook error: ${error.message}`
+      }));
+      process.exit(0);
+    }
+  });
+}
+
+sessionEndHook();

package/hooks/session-start.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+/**
+ * 🔑 LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits
+ * 
+ * OFFICIAL DOCS: Claude Code SessionStart Hook v2025
+ * Last Verified: 2025-08-31
+ * @see https://docs.anthropic.com/en/docs/claude-code/hooks
+ * 
+ * SessionStart Hook Payload:
+ * {
+ *   "session_id": "string",
+ *   "transcript_path": "string",
+ *   "hook_event_name": "SessionStart",
+ *   "source": "startup" | "compact" | "vscode" | "web"
+ * }
+ * 
+ * The 'source' field indicates how the session was initiated:
+ * - "startup": New session started normally
+ * - "compact": Session started after compaction
+ * - "vscode": Session initiated from VS Code
+ * - "web": Session initiated from web interface
+ * 
+ * Valid Response Format:
+ * Success without context: { "continue": true }
+ * Success with context: {
+ *   "continue": true,
+ *   "hookSpecificOutput": {
+ *     "hookEventName": "SessionStart",
+ *     "additionalContext": "string"  // Context to add to session
+ *   }
+ * }
+ * Failure: { "continue": false, "stopReason": "error message" }
+ * 
+ * @docs-ref: SessionStart supports hookSpecificOutput.additionalContext
+ * @see https://docs.anthropic.com/claude-code/hooks#sessionstart
+ */
+
+import { spawn } from 'child_process';
+import { join, dirname, basename } from 'path';
+import { fileURLToPath } from 'url';
+import { readFileSync, existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Load configuration to get the CLI command name
+let cliCommand = 'claude-mem';  // Default fallback
+const configPath = join(__dirname, 'config.json');
+if (existsSync(configPath)) {
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    cliCommand = config.cliCommand || 'claude-mem';
+  } catch (e) {
+    // Fallback to default if config read fails
+  }
+}
+
+async function sessionStartHook() {
+  let input = '';
+  
+  // Read JSON input from stdin
+  process.stdin.on('data', chunk => {
+    input += chunk;
+  });
+  
+  process.stdin.on('end', async () => {
+    try {
+      const data = JSON.parse(input);
+      
+      /**
+       * @docs-ref: SessionStart payload includes 'source' field, not 'reason'
+       * See: https://docs.anthropic.com/en/docs/claude-code/hooks#sessionstart
+       * 
+       * The 'source' field indicates the session start context:
+       * - 'startup': New session (load context)
+       * - 'compact': Session after compaction (may want to load context)
+       * - 'vscode': VS Code initiated session
+       * - 'web': Web interface initiated session
+       * 
+       * Note: Based on official docs, there is no 'continue' value for source.
+       * The previous check for 'reason === continue' was incorrect.
+       * We now skip context loading only for 'compact' source, as this
+       * indicates the session is continuing after compaction.
+       */
+      if (data.source === 'compact') {  // ✅ Correctly check 'source' field per official docs
+        // @docs-ref: For compact source, skip loading context as session is continuing
+        console.log(JSON.stringify({
+          continue: true
+          // No additional context needed for compact continuation
+        }));
+        process.exit(0);
+      }
+      
+      // Extract project name from transcript path if available
+      let projectName = null;
+      if (data.transcript_path) {
+        const dir = dirname(data.transcript_path);
+        const dirName = basename(dir);
+        
+        // Extract project name from directory pattern
+        if (dirName.includes('-Scripts-')) {
+          const parts = dirName.split('-Scripts-');
+          if (parts.length > 1) {
+            projectName = parts[1];
+          }
+        } else {
+          projectName = dirName;
+        }
+        
+        // Sanitize project name to match what compression uses
+        // This ensures we match the exact project name in the index
+        if (projectName) {
+          projectName = projectName.replace(/[^a-zA-Z0-9]/g, '_');
+        }
+      }
+      
+      // Build command to run
+      const args = ['load-context', '--format', 'session-start'];
+      
+      // Add project filter if we have a project name
+      if (projectName) {
+        args.push('--project', projectName);
+      }
+      
+      // Call the CLI load-context command directly
+      // Use the configured CLI command name (claude-mem)
+      // This ensures we use the correct version with full summaries
+      const loader = spawn(cliCommand, args, {
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+      
+      let stdout = '';
+      let stderr = '';
+      
+      loader.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+      
+      loader.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+      
+      loader.on('close', (code) => {
+        if (code !== 0) {
+          // If load-context fails, just continue without context
+          // This could happen if no index exists yet
+          // @docs-ref: Always return valid response format
+          console.log(JSON.stringify({
+            continue: true
+          }));
+          process.exit(0);
+        }
+        
+        // Output the formatted context for Claude to see using proper JSON format
+        // @docs-ref: SessionStart supports hookSpecificOutput.additionalContext
+        if (stdout && stdout.trim()) {
+          console.log(JSON.stringify({
+            continue: true,
+            hookSpecificOutput: {
+              hookEventName: "SessionStart",
+              additionalContext: stdout
+            }
+          }));
+        } else {
+          // No context to add, just continue
+          console.log(JSON.stringify({
+            continue: true
+          }));
+        }
+        
+        process.exit(0);
+      });
+      
+      loader.on('error', () => {
+        // If there's an error running the command, continue without context
+        // We don't want to break the session start
+        // @docs-ref: Always return valid response format
+        console.log(JSON.stringify({
+          continue: true
+        }));
+        process.exit(0);
+      });
+      
+    } catch (error) {
+      // Any errors, just continue without additional context
+      // @docs-ref: Always return valid response format
+      console.log(JSON.stringify({
+        continue: true
+      }));
+      process.exit(0);
+    }
+  });
+}
+
+sessionStartHook();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "claude-mem",
+  "version": "2.0.2",
+  "description": "Memory compression system for Claude Code - persist context across sessions",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "memory",
+    "compression",
+    "knowledge-graph",
+    "transcript",
+    "cli"
+  ],
+  "author": "Alex Newman",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedotmack/claude-mem.git"
+  },
+  "homepage": "https://github.com/thedotmack/claude-mem#readme",
+  "bugs": {
+    "url": "https://github.com/thedotmack/claude-mem/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "claude-mem": "claude-mem"
+  },
+  "files": [
+    "claude-mem",
+    "hooks",
+    "src"
+  ]
+}