claude-mem/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

[Unreleased]

[5.0.0] - 2025-11-03

BREAKING CHANGES

• Python dependency for optimal performance: While the plugin works without Python, installing Python 3.8+ and the Chroma MCP server unlocks semantic search capabilities. Without Python, the system falls back to SQLite FTS5 keyword search.
• Search behavior changes: Search queries now prioritize semantic relevance when Chroma is available, then apply temporal ordering. Keyword-only queries may return different results than v4.x.
• Worker service changes: Worker now initializes ChromaSync on startup. If Chroma MCP is unavailable, worker continues with FTS5-only mode but logs a warning.

Added

• Hybrid Search Architecture: Combines ChromaDB semantic search with SQLite temporal/metadata filtering
  • Chroma vector database for semantic similarity (top 100 matches)
  • 90-day temporal recency window for relevant results
  • SQLite hydration in chronological order
  • Graceful fallback to FTS5 when Chroma unavailable
• ChromaSync Service: Automatic vector database synchronization
  • Syncs observations, session summaries, and user prompts to Chroma
  • Splits large text fields into multiple vectors for better granularity
  • Maintains metadata for filtering (project, type, concepts, files)
  • Background sync process via worker service
• get_timeline_by_query Tool: Natural language timeline search with dual modes
  • Auto mode: Automatically uses top search result as timeline anchor
  • Interactive mode: Shows top N results for manual anchor selection
  • Combines semantic search discovery with timeline context retrieval
• User Prompt Semantic Search: Raw user prompts now indexed in Chroma for semantic discovery
• Enhanced MCP Tools: All 8 existing search tools now support hybrid search
  • search_observations - Now uses semantic + temporal hybrid algorithm
  • search_sessions - Semantic search across session summaries
  • search_user_prompts - Semantic search across raw prompts
  • find_by_concept, find_by_file, find_by_type - Enhanced with semantic capabilities
  • get_recent_context - Unchanged (temporal only)
  • get_context_timeline - Unchanged (anchor-based temporal)

Changed

• Search Server: Expanded from ~500 to ~1,500 lines with hybrid search implementation
• Worker Service: Now initializes ChromaSync and handles Chroma MCP lifecycle
• Search Pipeline: Now follows semantic-first strategy with temporal ordering

  Query → Chroma Semantic Search (top 100) → 90-day Filter → SQLite Hydration (temporal order) → Results
  

• Worker Resilience: Worker no longer crashes when Chroma MCP unavailable; gracefully falls back to FTS5

Fixed

• Critical temporal filtering bug: Fixed deduplication and date range filtering in search results
• User prompt formatting bug: Corrected field reference in search result formatting
• Worker crash prevention: Worker now handles missing Chroma MCP gracefully instead of crashing

Technical Details

• New files:
  • src/services/sync/ChromaSync.ts (738 lines) - Vector database sync service
  • experiment/chroma-search-test.ts - Comprehensive hybrid search testing
  • experiment/chroma-sync-experiment.ts - Vector sync validation
  • docs/chroma-search-completion-plan.md - Implementation planning
  • FEATURE_PLAN_HYBRID_SEARCH.md - Feature specification
  • IMPLEMENTATION_STATUS.md - Testing and validation results
• Modified files:
  • src/servers/search-server.ts (+995 lines) - Hybrid search algorithm implementation
  • src/services/worker-service.ts (+136 lines) - ChromaSync integration
  • src/services/sqlite/SessionStore.ts (+276 lines) - Enhanced timeline queries
  • src/hooks/context-hook.ts - Type legend improvements
• Validation: 1,390 observations synced to 8,279 vector documents
• Performance: Semantic search with 90-day window returns results in <200ms

[4.3.1] - 2025-10-26

Fixed

• SessionStart hook context injection: Fixed context not being injected into new sessions due to npm output pollution
  • Changed npm loglevel from --loglevel=error to --loglevel=silent in plugin/hooks/hooks.json
  • npm install stdout/stderr was polluting hook JSON output, preventing proper context injection
  • Hook now produces clean JSON output for reliable context injection
• Hooks architecture consolidation: Removed wrapper layer to simplify codebase
  • Removed src/bin/hooks/* wrapper files
  • Consolidated hook logic directly into src/hooks/*-hook.ts files
  • Fixed double shebang issues (esbuild now adds shebang during build)

Technical Details

• Modified: plugin/hooks/hooks.json (line 25: npm install verbosity)
• Removed: All files in src/bin/hooks/ directory
• Root cause: npm stderr/stdout interfering with hook's JSON hookSpecificOutput format

[4.3.0] - 2025-10-25

Added

• Progressive Disclosure Context: Enhanced context hook with layered memory retrieval system
  • Layer 1 (Index): Observation titles, token costs, and type indicators at session start
  • Layer 2 (Details): Full narratives retrieved on-demand via MCP search
  • Layer 3 (Perfect Recall): Source code and original transcripts
  • Context hook now displays observations in table format with ID, timestamp, type indicator, title, and token count
  • Type indicators: 🔴 (critical/gotcha), 🟤 (decision), 🔵 (informational/how-it-works)
  • Progressive disclosure instructions guide Claude on when to fetch full observation details vs. reading code
  • Token counts (~200-500 per observation) help Claude make informed retrieval decisions
• Agent Skills documentation: Added comprehensive documentation on creating and using Claude Code agent skills
• Version bump skill: Added automated version bump management skill for streamlined releases
• Memory toggle feature planning: Added design document for future pause/resume recording capability

Changed

• Enhanced session summary handling: Improved timeline rendering and summary organization
• Improved context hook output: Added structured timeline with session grouping and observation details
• Context token cost: Increased from ~800 tokens to ~2,500 tokens for richer observation index

Fixed

• Cross-platform path detection: Removed hardcoded macOS-specific paths for project and Claude Code executable (fixes #23)
  • Removed hardcoded paths in context hook, worker service, and SDK integration
  • Now uses dynamic path resolution for cross-platform compatibility
  • Affects: src/hooks/context.ts, src/services/worker-service.ts, src/sdk/worker.ts

[4.2.11] - 2025-10-25

Fixed

• Cross-platform Claude path detection: Fixed SDK auto-detection failure by implementing explicit which/where command execution
  • SDK's automatic Claude path detection was returning undefined
  • Unix/macOS: Uses which claude command to find executable
  • Windows: Uses where claude command (works in both CMD and PowerShell)
  • Fallback to CLAUDE_CODE_PATH environment variable if set
  • Handles Windows multiple results by taking first match
  • Worker now logs discovered path for debugging: "Found Claude executable: /path/to/claude"

Technical Details

• Added findClaudePath() helper function using child_process.execSync
• Platform detection via process.platform === 'win32' to choose appropriate command
• Updated src/sdk/worker.ts and src/services/worker-service.ts with explicit path detection
• Both files now pass pathToClaudeCodeExecutable: claudePath to SDK query

[4.2.10] - 2025-10-25

Fixed

• Windows compatibility: Removed hardcoded macOS-specific Claude executable path that prevented worker service from running on Windows
  • Removed hardcoded path: /Users/alexnewman/.nvm/versions/node/v24.5.0/bin/claude
  • Removed pathToClaudeCodeExecutable parameter from SDK query() calls
  • SDK now automatically detects Claude Code executable path on all platforms
  • Affects: src/sdk/worker.ts, src/services/worker-service.ts, plugin/scripts/worker-service.cjs

[4.2.3] - 2025-10-23

Security

• FTS5 injection vulnerability fix: Added proper escaping to prevent SQL injection attacks in search functions
  • Implemented double-quote escaping for FTS5 full-text search queries
  • Added comprehensive test suite with 332 new tests covering injection scenarios
  • Affects: search_observations, search_sessions, search_user_prompts MCP tools

Fixed

• ESM/CJS compatibility: Fixed getDirname function to work in both ESM (hooks) and CJS (worker) contexts
  • Detects context using typeof __dirname !== 'undefined'
  • Falls back to fileURLToPath(import.meta.url) for ESM modules
  • Resolves path resolution issues across different module systems
• Windows PowerShell compatibility: Fixed SessionStart hook error on Windows systems
  • Replaced bash-specific test command [ with standard cross-platform npm install
  • Simplified hook command to use idempotent npm install (fast when dependencies exist)
  • Dependencies install from root package.json in marketplace folder

Changed

• SessionStart hook command: Now uses cd ... && npm install --prefer-offline --no-audit --no-fund --loglevel=error && node context-hook.js
  • Removed bash-specific conditional check
  • npm install is fast (~500ms) and idempotent when dependencies already exist
  • Works cross-platform on Windows, macOS, and Linux

[4.2.1] - 2025-10-22

Added

• Summary skip logic: Summaries now skip when work is already covered, banter/trivial requests, or no meaningful observations
  • New "WHEN NOT TO SUMMARIZE" section in buildSummaryPrompt guides SDK to avoid duplicate/trivial summaries
  • Parser detects <skip_summary reason="..."/> format and logs reason
  • Prevents duplicate summaries like the three "restore 6 types" summaries observed in session d9137878

Fixed

• Observation type validation: Parser now validates all 6 observation types (bugfix, feature, refactor, change, discovery, decision) instead of only 3

Changed

• Chronological summary guidance: Summaries now explicitly instructed to capture "what happened in THIS prompt" rather than re-summarizing previous work

[4.1.1] - 2025-10-21

Removed

• advanced_search tool: Removed redundant MCP tool that provided no functionality beyond calling search_observations + search_sessions

Fixed

• MCP search limit bug: Fixed findByConcept, findByType, and findByFile methods to properly respect limit/offset parameters
• Type contamination in concepts: Added parser validation to prevent observation types from being added to concepts array
• Token limit warnings: Added guidance in tool descriptions to start with 3-5 results to avoid MCP token limits

Changed

• Simplified MCP API: Reduced from 7 to 6 search tools by removing the redundant advanced_search
• Improved search prompts: Enhanced type and concept constraint language in SDK prompts to prevent AI contamination

[4.1.0] - 2025-10-21

Changed

• Graceful session cleanup: Cleanup hook now marks sessions as completed instead of sending DELETE requests to worker
• Natural worker shutdown: Workers now finish pending operations (like summary generation) before terminating
• Restored MCP search server: Re-enabled full-text search capabilities from backup

Fixed

• Session summaries no longer interrupted by aggressive cleanup during session end
• Workers can now complete final operations before shutdown

[4.0.2] - 2025-10-19

Changed

• PM2 bundled as dependency: Moved pm2 from devDependencies to dependencies for out-of-the-box functionality
• Worker scripts use local PM2: All npm worker scripts now use npx pm2 to ensure local binary is used
• Worker startup uses local PM2: Worker auto-start now uses node_modules/.bin/pm2 instead of global pm2

Fixed

• Fail loudly on missing dependencies: Worker startup now throws explicit errors when bundled pm2 is missing instead of silently falling back
• Better error messages: Clear actionable error messages guide users to run npm install when dependencies are missing
• Removed silent fallback: Eliminated silent degradation that masked "works on my machine" installation failures

Documentation

• Updated README system requirements to reflect pm2 is bundled with plugin (no global install required)

[4.0.0] - 2025-10-18

BREAKING CHANGES

• Data directory moved to plugin location: Database and worker files now stored in ${CLAUDE_PLUGIN_ROOT}/data/ instead of ~/.claude-mem/
• Fresh start required: No automatic migration from v3.x databases. Users must start fresh with v4.0.0
• Worker auto-starts: Worker service now starts automatically on SessionStart hook, no manual PM2 commands needed

Added

• MCP Search Server: 6 specialized search tools with FTS5 full-text search capabilities
  • search_observations - Full-text search across observation titles, narratives, facts, and concepts
  • search_sessions - Full-text search across session summaries, requests, and learnings
  • find_by_concept - Find observations tagged with specific concepts
  • find_by_file - Find observations and sessions that reference specific file paths
  • find_by_type - Find observations by type (decision, bugfix, feature, refactor, discovery, change)
  • advanced_search - Combined search with filters across observations and sessions
• Citation support: All search results include claude-mem:// URI citations for referencing specific observations and sessions
• Automatic worker startup: Worker service now starts automatically in SessionStart hook
• Plugin data directory: Full integration with Claude Code plugin system using CLAUDE_PLUGIN_ROOT

Changed

• Worker service architecture: HTTP REST API with PM2 management for long-running background service
• Data directory priority: CLAUDE_PLUGIN_ROOT/data > CLAUDE_MEM_DATA_DIR > ~/.claude-mem (fallback for dev)
• Port file location: Worker port file now stored in plugin data directory
• Session continuity: Automatic context injection from last 3 sessions on startup
• Package structure: Reorganized to properly distribute plugin/, dist/, and src/ directories

Fixed

• Context hook now uses proper hookSpecificOutput JSON format for SessionStart
• Added missing process.exit(0) calls in all hook entry points
• Worker service now ensures data directory exists before writing port file
• Improved error handling and graceful degradation across all components

[3.7.1] - 2025-09-17

Added

• SQLite storage backend with session, memory, overview, and diagnostics management
• Mintlify documentation site with searchable interface and comprehensive guides
• Context7 MCP integration for documentation retrieval

Changed

• Session-start overviews to display chronologically from oldest to newest

Fixed

• Migration index parsing bug that prevented JSONL records from importing to SQLite

[3.6.10] - 2025-09-16

Added

• Claude Code statusline integration for real-time memory status
• MCP memory tools server providing compress, stats, search, and overview commands
• Concept documentation explaining memory compression and context loading

Fixed

• Corrected integration architecture to use hooks instead of MCP SDK

[3.6.9] - 2025-09-14

Added

• Display current date and time at the top of session-start hook output for better temporal context

Changed

• Enhanced session-start hook formatting with emoji icons and separator lines for improved readability

[3.6.8] - 2025-09-14

Fixed

• Fixed publish command failing when no version-related memories exist for changelog generation

[3.6.6] - 2025-09-14

Fixed

• Resolved compaction errors when processing large conversation histories by reducing chunk size limits to stay within Claude's context window

[3.6.5] - 2025-09-14

Changed

• Session groups now display in chronological order (most recent first)

Fixed

• Improved CLI path detection for cross-platform compatibility

[3.6.4] - 2025-09-13

Changed

• Update save documentation to include allowed-tools and description metadata fields

Removed

• Remove deprecated markdown to JSONL migration script

[3.6.3] - 2025-09-11

Changed

• Updated changelog generation prompts to use date strings in query text for temporal filtering

Fixed

• Resolved changelog timestamp filtering by using semantic search instead of metadata queries, enabling proper date-based searches
• Corrected install.ts search instructions to remove misleading metadata filtering guidance that caused 'Error finding id' errors

[3.6.2] - 2025-09-10

Added

• Visual feedback to changelog command showing current version, next version, and number of overviews being processed
• Generate changelog for specific versions using --generate flag with npm publish time boundaries
• Introduce 'Who Wants To Be a Memoryonaire?' trivia game that generates personalized questions from your stored memories
• Add interactive terminal UI with lifelines (50:50, Phone-a-Friend, Audience Poll) and cross-platform audio support
• Implement permanent question caching with --regenerate flag for instant game loading
• Enable hybrid vector search to discover related memory chains during question generation

Changed

• Changelog regeneration automatically removes old entries from JSONL file when using --generate or --historical flags
• Switch to direct JSONL file loading for instant memory access without API calls
• Optimize AI generation with faster 'sonnet' model for improved performance
• Reduce memory query limit from 100 to 50 to prevent token overflow

Fixed

• Changelog command now uses npm publish timestamps exclusively for accurate version time ranges
• Resolved timestamp filtering issues with Chroma database by leveraging semantic search with embedded dates
• Resolve game hanging at startup due to confirmation loop
• Fix memory integration bypass that prevented questions from using actual stored memories
• Consolidate 500+ lines of duplicate code for better maintainability

[3.6.1] - 2025-09-10

Changed

• Refactored pre-compact hook to work independently without status line updates

Removed

• Removed status line integration and ccstatusline configuration support

[3.5.5] - 2025-09-10

Changed

• Standardized GitHub release naming to lowercase 'claude-mem vX.X.X' format for consistent branding