claude-mem-windows

Windows-compatible persistent memory for Claude Code. A drop-in replacement for claude-mem that works reliably on Windows without Bun runtime issues.

Overview

claude-mem-windows provides a robust Model Context Protocol (MCP) server that enables Claude Code to maintain persistent, searchable memory of observations, decisions, and tool usage across sessions. Built with Node.js and SQLite, it emphasizes reliability on Windows while remaining fully compatible with macOS and Linux.

Features

• Full-text Search (FTS5) - BM25-ranked search across all observations with snippet extraction
• Session Management - Track observations within projects and sessions with decision capture
• Timeline Context - Retrieve chronological context around specific observations
• Windows-Optimized - Uses SQLite WAL mode for reliable concurrent access on Windows
• Observation Types - Six observation categories:
  • tool_use - Records of tool invocations
  • learning - Technical discoveries and patterns learned
  • decision - Architectural and design decisions
  • error - Error conditions and how they were resolved
  • preference - User preferences for tools, frameworks, patterns (NEW in v2)
  • pattern - Success/failure patterns for analysis (NEW in v2)
• Automatic Learning - Learns from corrections, preferences, and command outcomes
• Importance Scoring - Ranks memories by usage frequency and recency (0-100 scale)
• Smart Context Injection - Automatically provides relevant context at session start
• Pattern Recognition - Tracks success and failure rates for tools and commands
• Preference Tracking - Records user preferences with alternatives for future guidance
• Automatic Cleanup - Removes stale memories based on age and importance threshold
• Memory Analytics - Statistics on memory usage, patterns, and session history
• Metadata Support - Store arbitrary JSON metadata with each observation
• MCP Standard - Implements Model Context Protocol for seamless Claude integration
• Input Validation - Zod schemas ensure data integrity

Installation

Prerequisites

• Node.js 18 or later
• npm or yarn package manager
• Windows: Visual Studio Build Tools (for better-sqlite3 native compilation)
  • Download from: https://visualstudio.microsoft.com/downloads/
  • Choose "Visual Studio Build Tools" and install C++ build tools

Steps

1. Clone or copy the repository

   git clone <repository-url> claude-mem-windows
   cd claude-mem-windows
   

2. Install dependencies

   npm install
   

3. Build TypeScript

   npm run build
   

   The compiled JavaScript will be in the dist/ directory.

4. Verify installation (optional)

   npm run test
   

   This runs a comprehensive test suite covering all database operations.

Quick Start

Running the Server

Start the MCP server:

npm start

The server will initialize the database at ~/.claude-mem-windows/memory.db and listen for MCP requests.

Configuration with Claude Code

Add claude-mem-windows to your Claude Code MCP configuration.

Option 1: Edit .claude.json directly

Add to your ~/.claude.json (create if it doesn't exist):

{
  "mcpServers": {
    "claude-mem-windows": {
      "command": "node",
      "args": ["/absolute/path/to/claude-mem-windows/dist/index.js"]
    }
  }
}

Option 2: Use Claude CLI

If you have Claude CLI installed:

claude mcp add claude-mem-windows -- node /absolute/path/to/dist/index.js

Important: Use absolute paths, not relative paths. On Windows, forward slashes or escaped backslashes both work.

MCP Tools

The server exposes four tools that Claude can invoke to interact with memory:

search

Search memory with full-text search and BM25 ranking.

Parameters:

• query (string, required) - Search query
• limit (number, optional, default: 10) - Maximum results to return
• type (string, optional) - Filter by observation type: tool_use, learning, decision, or error
• dateStart (string, optional) - Start date (ISO format: 2025-01-26T10:30:00Z)
• dateEnd (string, optional) - End date (ISO format)
• project (string, optional) - Filter by project name

Response: Returns array of search results with:

• id - Observation ID
• type - Observation type
• content - Snippet of matching content (with search terms highlighted)
• created_at - Creation timestamp
• score - BM25 relevance score (lower is better)

Example:

Search for "database optimization" across all observations
Parameters: { "query": "database optimization", "limit": 5 }

timeline

Get chronological context around a specific observation.

Parameters:

• anchor (number, required) - Observation ID to center timeline around
• depth_before (number, optional, default: 5) - Number of observations to retrieve before anchor
• depth_after (number, optional, default: 5) - Number of observations to retrieve after anchor
• project (string, optional) - Filter by project name

Response: Returns array of observations in chronological order, centered around the anchor.

Use Cases:

• Understand context: "What was I working on before this decision?"
• Track progression: "What changed after this error?"
• Session replay: "Show me the sequence of events around this discovery"

Example:

Get 10 observations around observation ID 42
Parameters: { "anchor": 42, "depth_before": 5, "depth_after": 5 }

get_observations

Fetch full details for specific observation IDs.

Parameters:

• ids (array of numbers, required) - Observation IDs to retrieve

Response: Returns array of observations with full details including metadata:

• id - Observation ID
• session_id - Session this observation belongs to
• type - Observation type
• content - Full observation content
• metadata - JSON metadata object (if provided)
• created_at - Creation timestamp

Use Cases:

• Retrieve detailed content from search results
• Get metadata attached to observations
• Batch fetch multiple observations

Example:

Get full details for observations 1, 5, and 9
Parameters: { "ids": [1, 5, 9] }

add_observation

Manually add an observation to memory.

Parameters:

• type (string, required) - One of: tool_use, learning, decision, error
• content (string, required) - Observation content
• metadata (object, optional) - Arbitrary JSON metadata

Response:

{
  "id": <new_observation_id>,
  "success": true
}

Use Cases:

• Capture non-automatic observations
• Document decisions made during the session
• Record errors and their solutions
• Store custom metadata for later analysis

Example:

Record a design decision with alternatives
Parameters: {
  "type": "decision",
  "content": "Chose recursive descent parser over AST builder",
  "metadata": {
    "alternatives": ["AST builder", "Pratt parser"],
    "reasoning": "Better error recovery",
    "team": "parser-squad"
  }
}

Database Schema

Claude-mem-windows uses SQLite with the following schema:

Tables

sessions

• id (TEXT PRIMARY KEY) - Unique session identifier
• project (TEXT) - Project name
• started_at (DATETIME) - Session start timestamp
• ended_at (DATETIME NULL) - Session end timestamp (null if ongoing)

observations

• id (INTEGER PRIMARY KEY) - Auto-incrementing observation ID
• session_id (TEXT FK) - Reference to parent session
• type (TEXT CHECK) - One of: tool_use, learning, decision, error
• content (TEXT) - Main observation content
• metadata (TEXT) - JSON metadata (nullable)
• created_at (DATETIME) - Creation timestamp

Virtual Tables

observations_fts

• FTS5 virtual table for full-text search with BM25 ranking
• Automatically kept in sync with observations table via triggers
• Uses Unicode 61 tokenization with Porter stemming

Indexes

The schema includes indexes on frequently queried fields:

• idx_observations_session - Fast queries by session
• idx_observations_type - Fast queries by observation type
• idx_observations_created - Fast timestamp-based queries
• idx_sessions_project - Fast session lookup by project

Triggers

Automatic triggers maintain FTS5 synchronization:

• observations_ai - Insert trigger
• observations_au - Update trigger
• observations_ad - Delete trigger

Database Location

The database file is stored at:

• Linux/macOS: ~/.claude-mem-windows/memory.db
• Windows: %USERPROFILE%\.claude-mem-windows\memory.db

The directory is automatically created if it doesn't exist.

Associated WAL files (Write-Ahead Log) for concurrent access:

• memory.db-wal
• memory.db-shm

Development

Project Structure

claude-mem-windows/
├── src/
│   ├── index.ts       # MCP server implementation
│   ├── database.ts    # SQLite database layer
│   └── test-db.ts     # Test suite
├── dist/              # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Building from Source

npm run build

Compiles TypeScript in src/ to JavaScript in dist/.

Development Mode

npm run dev

Runs npm run build followed by npm start - useful for testing changes.

Testing

npm test

Runs the comprehensive test suite (src/test-db.ts) which validates:

• Session creation and management
• Observation insertion and retrieval
• Full-text search functionality
• Timeline extraction
• Batch observation fetching
• Date-based filtering
• Metadata handling

The test suite creates a temporary database, exercises all APIs, and cleans up after itself.

Configuration

Customizing Database Location

You can specify a custom database path when initializing the MCP server by modifying src/index.ts:

// Default: ~/.claude-mem-windows/memory.db
this.db = new MemoryDB();

// Custom path:
this.db = new MemoryDB('/path/to/custom/memory.db');

SQLite Pragmas

The database applies these pragmas for Windows compatibility:

• journal_mode = WAL - Write-Ahead Logging for better concurrent access
• synchronous = NORMAL - Balance between safety and performance
• foreign_keys = ON - Enforce referential integrity

These settings are optimized for Windows but work on all platforms.

Integration with Claude Code

Once configured, claude-mem-windows tools are available to Claude during conversations:

Examples

Searching for previous decisions:

Claude: I'll search for previous architectural decisions about caching.
Tool: search query="cache architecture decision" type="decision"

Getting context:

Claude: Let me see what happened around this error.
Tool: timeline anchor=42 depth_before=3 depth_after=3

Recording a new decision:

Claude: I'll document this design choice.
Tool: add_observation type="decision" content="Use Redis for session caching"
      metadata={"reasoning": "Lower latency", "alternatives": ["Memcached"]}

Troubleshooting

Issue: "Module not found: better-sqlite3"

Solution: Rebuild native modules

npm install --build-from-source

Issue: Cannot find ~/.claude-mem-windows

Solution: This directory is created automatically on first run. If it's not created:

1. Ensure the server runs successfully: npm start
2. Check home directory permissions
3. Verify Node.js can write to home directory

Issue: Server fails to start on Windows

Possible causes:

1. Visual Studio Build Tools not installed
2. Node.js installation is corrupted
3. Port already in use

Solutions:

• Install Visual Studio Build Tools
• Reinstall Node.js
• Check that no other process is using stdio

Issue: Search returns no results

Troubleshooting:

1. Verify observations exist: Check ~/.claude-mem-windows/memory.db
2. Try simpler search queries
3. Use get_observations with IDs from previous searches
4. Check observation type matches (if filtered)

Differences from Original claude-mem

Feature	claude-mem	claude-mem-windows v2
Runtime	Bun	Node.js 18+
Search Backend	Chroma + Vector DB	SQLite FTS5
Architecture	Worker service	Direct database access
Windows Support	Limited	Optimized (WAL mode)
Setup Complexity	Complex	Simple (npm install)
Cross-platform	Yes	Yes (better on Windows)
Cold start time	Slower	Faster
Auto context injection	Yes	Yes
Correction learning	Yes	Yes
Preference tracking	No	Yes
Success/failure patterns	No	Yes
Importance scoring	No	Yes
Automatic cleanup	No	Yes
Number of tools	4	10
Session decision capture	No	Yes

Performance Characteristics

• Search: O(log N) with FTS5 BM25 ranking
• Timeline: O(1) fixed-size context window
• Insertion: O(log N) with index maintenance
• Memory: ~5-10 MB per 10,000 observations

Tested with:

• 50,000+ observations
• 100+ concurrent searches
• Batches of 1,000+ insertions

License

MIT

Contributing

Contributions are welcome! Areas for enhancement:

• Additional observation types
• Integration hooks for auto-capture
• Web UI for memory exploration
• Performance optimizations for very large datasets
• Export/import functionality

Please submit pull requests with tests and documentation.

Support

For issues or questions:

1. Check the Troubleshooting section above
2. Review test cases in src/test-db.ts for API examples
3. Examine logs from server output
4. File an issue with reproduction steps

What's New in v2.0

• Automatic Learning from Corrections - Detects when users say "actually", "no", or "instead" and learns from corrections
• User Preference Tracking - Records preferences for tools, frameworks, patterns, and workflows
• Success/Failure Pattern Recognition - Tracks which commands succeed and which fail, boosting successful approaches
• Smart Context Injection - Automatically injects relevant learned context at session start
• Importance-Based Memory Ranking - Prioritizes frequently used and recently updated memories
• Automatic Cleanup - Removes stale memories older than configurable retention period

How It Learns

Claude-mem-windows v2 captures learnings automatically through multiple touchpoints:

1. SessionStart

When a new session begins, the system automatically:

• Retrieves relevant project context based on current directory
• Injects learned preferences for the current project
• Loads recent success patterns to guide decision-making
• Provides chronological context from previous sessions

2. PostToolUse

After Claude invokes a tool:

• Captures tool name, parameters, and outcome (success/failure)
• Records execution time and error details if applicable
• Tags with project and session context
• Updates success/failure pattern counters

3. UserPromptSubmit

When the user provides feedback or corrections:

• Detects correction patterns: "actually", "no", "instead", "don't do that"
• Detects preference patterns: "I prefer X over Y", "always use", "never use"
• Extracts the corrected approach or preference
• Stores with user confirmation for future guidance

4. SessionEnd

When a session concludes:

• Updates session completion records
• Calculates session duration and tool usage statistics
• Promotes high-value learnings based on session outcomes
• Schedules cleanup of low-value observations

MCP Tools

The server now exposes ten tools (four original + six new) for memory interaction:

Original Tools

search

Search memory with full-text search and BM25 ranking.

Parameters:

• query (string, required) - Search query
• limit (number, optional, default: 10) - Maximum results to return
• type (string, optional) - Filter by observation type: tool_use, learning, decision, error, preference, pattern
• dateStart (string, optional) - Start date (ISO format: 2025-01-26T10:30:00Z)
• dateEnd (string, optional) - End date (ISO format)
• project (string, optional) - Filter by project name

Response: Returns array of search results with:

• id - Observation ID
• type - Observation type
• content - Snippet of matching content (with search terms highlighted)
• created_at - Creation timestamp
• score - BM25 relevance score (lower is better)
• importance - Importance score (0-100) for v2 learnings

Example:

Search for "database optimization" across all observations
Parameters: { "query": "database optimization", "limit": 5 }

timeline

Get chronological context around a specific observation.

Parameters:

• anchor (number, required) - Observation ID to center timeline around
• depth_before (number, optional, default: 5) - Number of observations to retrieve before anchor
• depth_after (number, optional, default: 5) - Number of observations to retrieve after anchor
• project (string, optional) - Filter by project name

Response: Returns array of observations in chronological order, centered around the anchor.

Use Cases:

• Understand context: "What was I working on before this decision?"
• Track progression: "What changed after this error?"
• Session replay: "Show me the sequence of events around this discovery"

Example:

Get 10 observations around observation ID 42
Parameters: { "anchor": 42, "depth_before": 5, "depth_after": 5 }

get_observations

Fetch full details for specific observation IDs.

Parameters:

• ids (array of numbers, required) - Observation IDs to retrieve

Response: Returns array of observations with full details including metadata:

• id - Observation ID
• session_id - Session this observation belongs to
• type - Observation type
• content - Full observation content
• metadata - JSON metadata object (if provided)
• created_at - Creation timestamp
• importance - Importance ranking for v2 observations

Use Cases:

• Retrieve detailed content from search results
• Get metadata attached to observations
• Batch fetch multiple observations

Example:

Get full details for observations 1, 5, and 9
Parameters: { "ids": [1, 5, 9] }

add_observation

Manually add an observation to memory.

Parameters:

• type (string, required) - One of: tool_use, learning, decision, error, preference, pattern
• content (string, required) - Observation content
• metadata (object, optional) - Arbitrary JSON metadata

Response:

{
  "id": <new_observation_id>,
  "success": true
}

Use Cases:

• Capture non-automatic observations
• Document decisions made during the session
• Record errors and their solutions
• Store custom metadata for later analysis

Example:

Record a design decision with alternatives
Parameters: {
  "type": "decision",
  "content": "Chose recursive descent parser over AST builder",
  "metadata": {
    "alternatives": ["AST builder", "Pratt parser"],
    "reasoning": "Better error recovery",
    "team": "parser-squad"
  }
}

New Tools (v2.0)

get_preferences

Retrieve learned user preferences for the current project.

Parameters:

• project (string, optional) - Project name (defaults to current)
• category (string, optional) - Filter by category: tool, framework, pattern, workflow
• limit (number, optional, default: 20) - Maximum preferences to return

Response: Returns array of preferences with:

• id - Preference ID
• category - Preference category
• preference - The preferred approach
• alternatives - What was rejected in favor of this preference
• usage_count - How many times this preference has been applied
• last_used - Most recent usage timestamp

Example:

Get all tool preferences for current project
Parameters: { "category": "tool", "limit": 10 }

get_patterns

Retrieve success and failure patterns for tools and commands.

Parameters:

• project (string, optional) - Project name (defaults to current)
• status (string, optional) - Filter by success or failure
• tool_name (string, optional) - Filter by tool name
• limit (number, optional, default: 20) - Maximum patterns to return

Response: Returns array of patterns with:

• id - Pattern ID
• tool_name - Tool or command name
• pattern - Description of the pattern
• success_count - Number of successful executions
• failure_count - Number of failed executions
• success_rate - Percentage of successful uses (0-100)
• last_seen - Most recent observation of this pattern

Example:

Get all failing patterns for npm
Parameters: { "tool_name": "npm", "status": "failure" }

add_preference

Record a learned user preference.

Parameters:

• category (string, required) - One of: tool, framework, pattern, workflow
• preference (string, required) - The preferred approach
• alternatives (array, optional) - What this replaces
• metadata (object, optional) - Additional context

Response:

{
  "id": <preference_id>,
  "success": true,
  "message": "Preference recorded"
}

Example:

Record that user prefers Vitest over Jest
Parameters: {
  "category": "tool",
  "preference": "Vitest",
  "alternatives": ["Jest", "Mocha"]
}

get_context

Retrieve relevant project context automatically injected at session start.

Parameters:

• project (string, optional) - Project name (defaults to current)
• include_preferences (boolean, optional, default: true) - Include user preferences
• include_patterns (boolean, optional, default: true) - Include success/failure patterns
• include_recent (boolean, optional, default: true) - Include recent observations
• limit (number, optional, default: 5) - Max items per category

Response: Returns object with:

{
  "project": "project-name",
  "preferences": [...],
  "patterns": [...],
  "recent_observations": [...],
  "last_session": {
    "date": "2025-01-26T10:30:00Z",
    "observations_count": 42,
    "key_decisions": [...]
  }
}

Example:

Get full context for session start
Parameters: { "include_preferences": true, "include_patterns": true }

get_stats

Retrieve memory statistics and usage analytics.

Parameters:

• project (string, optional) - Project name (defaults to current)
• time_window (string, optional) - Time range: week, month, year, all

Response: Returns statistics object:

{
  "total_observations": 1250,
  "by_type": {
    "tool_use": 450,
    "learning": 320,
    "decision": 180,
    "error": 200,
    "preference": 50,
    "pattern": 50
  },
  "sessions_count": 25,
  "average_session_length": "42 minutes",
  "most_common_tools": [...],
  "recent_patterns": [...],
  "db_size_mb": 15.2,
  "memory_retention_days": 90
}

Example:

Get memory statistics for the last month
Parameters: { "time_window": "month" }

cleanup

Remove stale observations based on age and usage.

Parameters:

• older_than_days (number, optional, default: 90) - Remove observations older than N days
• type (string, optional) - Only clean specific type
• min_importance (number, optional, default: 10) - Keep observations with importance >= N
• dry_run (boolean, optional, default: false) - Show what would be deleted without deleting

Response:

{
  "deleted_count": 45,
  "freed_space_mb": 2.3,
  "dry_run": false
}

Example:

Dry run: see what would be cleaned
Parameters: { "older_than_days": 60, "dry_run": true }

Automatic Learning

Claude-mem-windows v2 learns continuously through pattern recognition and user feedback:

Correction Detection

When you provide feedback on Claude's suggestions, the system learns:

User says: "Actually, let's use Postgres instead of MySQL" System captures: Preference for PostgreSQL over MySQL with decision context

User says: "No, that command didn't work last time" System captures: Failure pattern for that command with parameters

User says: "Instead of importing, let's export" System captures: Correction to approach with reasoning

Preference Extraction

The system automatically detects preferences:

User says: "I prefer TypeScript for all services" System captures: Framework preference with project scope

User says: "Always run tests before committing" System captures: Workflow preference with order dependency

Error Tracking

Failed commands are analyzed and remembered:

Tool: npm install --save-dev webpack
Status: FAILURE (permission denied)
Captured: npm install failures related to permissions in this directory
Future suggestion: Use sudo or check directory permissions

Success Tracking

Working approaches get boosted:

Tool: npm run build
Status: SUCCESS (completed in 2.3s)
Captured: npm run build pattern succeeds consistently
Future suggestion: This is a known working approach
Importance: BOOSTED (now scored 85/100)

Database Schema

Claude-mem-windows uses SQLite with an extended schema for v2 features:

Tables

sessions

• id (TEXT PRIMARY KEY) - Unique session identifier
• project (TEXT) - Project name
• started_at (DATETIME) - Session start timestamp
• ended_at (DATETIME NULL) - Session end timestamp
• observations_count (INTEGER) - Number of observations in session
• key_decisions (TEXT JSON) - Notable decisions from session

observations

• id (INTEGER PRIMARY KEY) - Auto-incrementing observation ID
• session_id (TEXT FK) - Reference to parent session
• type (TEXT CHECK) - One of: tool_use, learning, decision, error, preference, pattern
• content (TEXT) - Main observation content
• metadata (TEXT) - JSON metadata
• created_at (DATETIME) - Creation timestamp
• updated_at (DATETIME) - Last update timestamp
• importance (INTEGER 0-100) - Importance score for prioritization

preferences (NEW in v2)

• id (INTEGER PRIMARY KEY) - Preference ID
• project (TEXT) - Project this preference applies to
• category (TEXT) - One of: tool, framework, pattern, workflow
• preference (TEXT) - The preferred approach
• alternatives (TEXT JSON) - What was rejected
• usage_count (INTEGER) - Times applied
• created_at (DATETIME) - When preference was learned
• last_used (DATETIME) - Most recent application

patterns (NEW in v2)

• id (INTEGER PRIMARY KEY) - Pattern ID
• project (TEXT) - Project this pattern applies to
• tool_name (TEXT) - Tool or command name
• pattern (TEXT) - Description of observed pattern
• success_count (INTEGER) - Successful executions
• failure_count (INTEGER) - Failed executions
• last_seen (DATETIME) - Most recent observation
• metadata (TEXT JSON) - Additional details

Version History

2.0.0 (Current)

• Automatic learning from corrections and preferences
• Success/failure pattern recognition and tracking
• Smart context injection at session start
• Importance-based memory ranking
• Six new MCP tools (get_preferences, get_patterns, add_preference, get_context, get_stats, cleanup)
• Extended observation types (preference, pattern)
• Automatic stale memory cleanup
• Enhanced session tracking with decision capture

1.0.0

• Initial release
• MCP server with four tools
• SQLite FTS5 backend
• Windows-optimized configuration
• Comprehensive test suite
• Full documentation