claude-mem/README_WINDOWS.md

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 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):

# 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):

# 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 -Command "irm https://astral.sh/uv/install.ps1 | iex"

Unix/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Installation Steps

1. Install claude-mem globally

npm install -g claude-mem

2. Run the installer

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:

# 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:

# 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:

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

claude-mem status

2. Run diagnostics

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:

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:

   claude-mem doctor
   

2. Check logs:

   claude-mem logs
   

   Or view directly:

   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

# 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.