From 58a9554bb3392dd261791a21f1bc217c1e1844c0 Mon Sep 17 00:00:00 2001 From: Alex Newman Date: Wed, 15 Oct 2025 20:13:04 -0400 Subject: [PATCH] feat: Complete Phase 1 implementation with database schema, shared layer, and hook functions - Created new tables for SDK sessions and observations - Implemented HooksDatabase for CRUD operations - Developed four hook functions: context, new, save, and summary - Added CLI commands for each hook - Established comprehensive test suite with all tests passing feat: Complete Phase 2 implementation with SDK worker process and XML parsing - Developed SDK prompts for initializing and processing observations - Implemented XML parser for SDK responses - Created SDK worker process to handle background observation processing - Verified integration with HooksDatabase and added tests for all components feat: Complete Phase 3 integration with comprehensive testing and validation - Verified all hook functions with database integration - Created integration and end-to-end tests for session lifecycle - Ensured non-blocking operations and performance requirements met - Updated CLI commands for hook architecture and installation flow - Documented success criteria and next steps for real-world testing --- README_WINDOWS.md | 265 ------------------ .../architecture/REFACTOR-PLAN.md | 0 .../temp/PHASE1-COMPLETE.md | 0 .../temp/PHASE2-COMPLETE.md | 0 .../temp/PHASE2-PROMPT.md | 0 .../temp/PHASE3-COMPLETE.md | 0 6 files changed, 265 deletions(-) delete mode 100644 README_WINDOWS.md rename REFACTOR-PLAN.md => context/architecture/REFACTOR-PLAN.md (100%) rename PHASE1-COMPLETE.md => context/temp/PHASE1-COMPLETE.md (100%) rename PHASE2-COMPLETE.md => context/temp/PHASE2-COMPLETE.md (100%) rename PHASE2-PROMPT.md => context/temp/PHASE2-PROMPT.md (100%) rename PHASE3-COMPLETE.md => context/temp/PHASE3-COMPLETE.md (100%) diff --git a/README_WINDOWS.md b/README_WINDOWS.md deleted file mode 100644 index ddada417..00000000 --- a/README_WINDOWS.md +++ /dev/null @@ -1,265 +0,0 @@ -# Windows Installation Guide - -## Overview - -Claude-mem now includes **experimental Windows support** as of v3.10.0 (October 2025). The cross-platform architecture uses the [Platform utility](/src/utils/platform.ts) for handling Windows-specific differences. - -## System Requirements - -- **Windows 10/11** (64-bit recommended) -- **Node.js** >= 18.0.0 -- **PowerShell** 5.1 or later (for hook execution) -- **Claude Code** with MCP support -- **npm** package manager - -**Note**: Bun (>=1.0.0) is only required for development work on claude-mem itself, not for running it. - -## Known Windows-Specific Differences - -### 1. Hook Execution -- **Unix/macOS**: Hooks execute via `/bin/sh` -- **Windows**: Hooks execute via `powershell` - -All hooks are `.js` files that work on both platforms through Node.js. - -### 2. Path Handling -Windows paths use backslashes (`\`) but Node.js normalizes these automatically. The data directory is located at: -``` -C:\Users\YourUsername\.claude-mem\ -``` - -### 3. File Permissions -- **Unix/macOS**: Hook files get `chmod 755` permissions -- **Windows**: Permission setting is a no-op (not needed) - -### 4. Smart Trash™ Alias -The Smart Trash feature creates shell aliases differently: - -**Windows (PowerShell)**: -```powershell -# claude-mem smart trash alias -function rm { claude-mem trash $args } -``` - -PowerShell profiles are located at: -- `Documents\PowerShell\Microsoft.PowerShell_profile.ps1` -- `Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1` - -**Unix/macOS (Bash/Zsh)**: -```bash -# claude-mem smart trash alias -alias rm='claude-mem trash' -``` - -### 5. UV Package Manager Installation -The installer automatically installs `uv` using platform-specific methods: - -**Windows**: -```powershell -powershell -Command "irm https://astral.sh/uv/install.ps1 | iex" -``` - -**Unix/macOS**: -```bash -curl -LsSf https://astral.sh/uv/install.sh | sh -``` - -## Installation Steps - -### 1. Install claude-mem globally - -```powershell -npm install -g claude-mem -``` - -### 2. Run the installer - -```powershell -claude-mem install -``` - -The installer will: -1. ✅ Create directory structure at `C:\Users\YourUsername\.claude-mem\` -2. ✅ Install UV package manager via PowerShell -3. ✅ Install Chroma MCP server for vector database -4. ✅ Add CLAUDE.md instructions to `C:\Users\YourUsername\.claude\` -5. ✅ Install slash commands (save.md, remember.md, claude-mem.md) -6. ✅ Install memory hooks with PowerShell execution support -7. ✅ Configure Claude Code settings - -### 3. Restart Claude Code - -After installation, restart Claude Code to activate the memory system. - -## Windows-Specific Caveats - -### PowerShell Execution Policy -If hooks fail to execute, you may need to adjust your PowerShell execution policy: - -```powershell -# Check current policy -Get-ExecutionPolicy - -# Allow local scripts (choose one): -Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -# OR for more security: -Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -``` - -### Path Environment Variable -After installing UV, you may need to restart PowerShell or update your PATH: - -```powershell -# Add to PATH if needed -$env:PATH = "$env:USERPROFILE\.cargo\bin;$env:PATH" -``` - -The installer attempts to set this automatically, but it only affects the current process. - -### Better-SQLite3 Native Module -The hooks use `better-sqlite3` for database access, which requires native compilation: -- The installer runs `npm install` in the hooks directory -- If this fails, hooks may still work if `better-sqlite3` is globally available -- Build errors are silently ignored to prevent installation failure - -If you see database errors in logs: -```powershell -cd $env:USERPROFILE\.claude-mem\hooks -npm install better-sqlite3 --build-from-source -``` - -## File Locations on Windows - -| Component | Windows Path | -|-----------|-------------| -| Data directory | `C:\Users\YourUsername\.claude-mem\` | -| ChromaDB | `C:\Users\YourUsername\.claude-mem\chroma\` | -| SQLite database | `C:\Users\YourUsername\.claude-mem\claude-mem.db` | -| Hooks | `C:\Users\YourUsername\.claude-mem\hooks\` | -| Archives | `C:\Users\YourUsername\.claude-mem\archives\` | -| Trash | `C:\Users\YourUsername\.claude-mem\trash\` | -| CLAUDE.md | `C:\Users\YourUsername\.claude\CLAUDE.md` | -| Settings | `C:\Users\YourUsername\AppData\Roaming\Claude\settings.json` | -| Commands | `C:\Users\YourUsername\.claude\commands\` | - -## Testing Your Installation - -### 1. Check installation status -```powershell -claude-mem status -``` - -### 2. Run diagnostics -```powershell -claude-mem doctor -``` - -This will verify: -- ✅ Directory structure -- ✅ Hook configuration -- ✅ Database accessibility -- ✅ MCP server integration - -### 3. Test memory storage -Start Claude Code and have a brief conversation. Then check: -```powershell -claude-mem status -``` - -You should see memory counts increase. - -### 4. Search memories -In Claude Code, ask: -``` -Search my memories for [your topic] -``` - -Claude should use the `mcp__claude-mem__chroma_query_documents` tool automatically. - -## Known Issues & Limitations - -### ⚠️ PowerShell Profile Creation -- **Issue**: PowerShell profiles may not exist by default -- **Impact**: Smart Trash alias installation creates profile directories -- **Status**: Installer handles this automatically - -### ⚠️ Native Module Compilation -- **Issue**: `better-sqlite3` requires build tools -- **Impact**: May need Visual Studio Build Tools installed -- **Workaround**: Installer attempts silent installation; manually rebuild if needed - -### ⚠️ Path Case Sensitivity -- **Issue**: Windows paths are case-insensitive but ChromaDB metadata stores exact case -- **Impact**: Path comparisons may fail in edge cases -- **Status**: Generally works fine; use consistent casing - -## Getting Help - -If you encounter Windows-specific issues: - -1. **Run diagnostics**: - ```powershell - claude-mem doctor - ``` - -2. **Check logs**: - ```powershell - claude-mem logs - ``` - Or view directly: - ```powershell - type $env:USERPROFILE\.claude-mem\logs\*.log - ``` - -3. **Verify hook execution**: - Check Claude Code's hook output for errors during session start/stop - -4. **Report issues**: - - Include `claude-mem doctor` output - - Include relevant logs - - Specify Windows version and PowerShell version - - File at: https://github.com/thedotmack/claude-mem/issues - -## Development on Windows - -If you're developing claude-mem on Windows: - -### Prerequisites -- Install Bun (Windows support is experimental): https://bun.sh/ -- Install Git for Windows -- Install Visual Studio Build Tools for native modules - -### Build Commands -```powershell -# Install dependencies -npm install - -# Build minified bundle -npm run build - -# Link for local testing -bun link - -# Reinstall with latest build -claude-mem install --force -``` - -**Note**: Some npm scripts use Unix-style paths and may not work on Windows. Core development is recommended on Unix/macOS systems. - -## Summary - -✅ **Works on Windows**: -- Memory capture via streaming hooks -- ChromaDB semantic search -- SQLite metadata storage -- MCP server integration -- All CLI commands -- Smart Trash™ system -- Automatic context loading - -⚠️ **May Require Extra Setup**: -- PowerShell execution policy -- Visual Studio Build Tools for native modules -- Manual PATH configuration - -The core claude-mem functionality is fully operational on Windows, with the memory capture, storage, and retrieval systems working identically to Unix/macOS. diff --git a/REFACTOR-PLAN.md b/context/architecture/REFACTOR-PLAN.md similarity index 100% rename from REFACTOR-PLAN.md rename to context/architecture/REFACTOR-PLAN.md diff --git a/PHASE1-COMPLETE.md b/context/temp/PHASE1-COMPLETE.md similarity index 100% rename from PHASE1-COMPLETE.md rename to context/temp/PHASE1-COMPLETE.md diff --git a/PHASE2-COMPLETE.md b/context/temp/PHASE2-COMPLETE.md similarity index 100% rename from PHASE2-COMPLETE.md rename to context/temp/PHASE2-COMPLETE.md diff --git a/PHASE2-PROMPT.md b/context/temp/PHASE2-PROMPT.md similarity index 100% rename from PHASE2-PROMPT.md rename to context/temp/PHASE2-PROMPT.md diff --git a/PHASE3-COMPLETE.md b/context/temp/PHASE3-COMPLETE.md similarity index 100% rename from PHASE3-COMPLETE.md rename to context/temp/PHASE3-COMPLETE.md