airkjw/claude-mem

Fork 0

Files

T

Alex Newman 2f900b681f docs: update CHANGELOG.md for v8.5.6

2026-01-03 21:26:34 -05:00

54 KiB

Raw Blame History

Changelog

All notable changes to claude-mem.

[v8.5.6] - 2026-01-04

Major Architectural Refactoring

Decomposes monolithic services into modular, maintainable components:

Worker Service

Extracted infrastructure (GracefulShutdown, HealthMonitor, ProcessManager), server layer (ErrorHandler, Middleware, Server), and integrations (CursorHooksInstaller)

Context Generator

Split into ContextBuilder, ContextConfigLoader, ObservationCompiler, TokenCalculator, formatters (Color/Markdown), and section renderers (Header/Footer/Summary/Timeline)

Search System

Extracted SearchOrchestrator, ResultFormatter, TimelineBuilder, and strategy pattern (Chroma/SQLite/Hybrid search strategies) with dedicated filters (Date/Project/Type)

Agent System

Extracted shared logic into ResponseProcessor, ObservationBroadcaster, FallbackErrorHandler, and SessionCleanupHelper

SQLite Layer

Decomposed SessionStore into domain modules (observations, prompts, sessions, summaries, timeline) with proper type exports

Bug Fixes

Fixed duplicate observation storage bug (observations stored multiple times when messages were batched)
Added duplicate observation cleanup script for production database remediation
Fixed FOREIGN KEY constraint and missing failed_at_epoch column issues

Coming Next

Comprehensive test suite in a new PR, targeting v8.6.0

🤖 Generated with Claude Code

[v8.5.5] - 2026-01-03

Improved Error Handling and Logging

This patch release enhances error handling and logging across all worker services for better debugging and reliability.

Changes

Enhanced Error Logging: Improved error context across SessionStore, SearchManager, SDKAgent, GeminiAgent, and OpenRouterAgent
SearchManager: Restored error handling for Chroma calls with improved logging
SessionStore: Enhanced error logging throughout database operations
Bug Fix: Fixed critical bug where memory_session_id could incorrectly equal content_session_id
Hooks: Streamlined error handling and loading states for better maintainability

Investigation Reports

Added detailed analysis documents for generator failures and observation duplication regressions

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v8.5.4...v8.5.5

[v8.5.4] - 2026-01-02

Bug Fixes

Chroma Connection Error Handling

Fixed a critical bug in ChromaSync where connection-related errors were misinterpreted as missing collections. The ensureCollection() method previously caught ALL errors and assumed they meant the collection doesn't exist, which caused connection errors to trigger unnecessary collection creation attempts. Now connection-related errors like "Not connected" are properly distinguished and re-thrown immediately, preventing false error handling paths and inappropriate fallback behavior.

Removed Dead last_user_message Code

Cleaned up dead code related to last_user_message handling in the summary flow. This field was being extracted from transcripts but never used anywhere - in Claude Code transcripts, "user" type messages are mostly tool_results rather than actual user input, and the user's original request is already stored in the user_prompts table. Removing this unused field eliminates confusing warnings like "Missing last_user_message when queueing summary". Changes span summary-hook, SessionRoutes, SessionManager, interface definitions, and all agent implementations.

Improvements

Enhanced Error Handling Across Services

Comprehensive improvement to error handling across 8 core services:

BranchManager - Now logs recovery checkout failures
PaginationHelper - Logs when file paths are plain strings instead of valid JSON
SDKAgent - Enhanced logging for Claude executable detection failures
SearchManager - Logs plain string handling for files read and edited
paths.ts - Improved logging for git root detection failures
timeline-formatting - Enhanced JSON parsing errors with input previews
transcript-parser - Logs summary of parse errors after processing
ChromaSync - Logs full error context before attempting collection creation

Error Handling Documentation & Tooling

Created error-handling-baseline.txt establishing baseline error handling practices
Documented error handling anti-pattern rules in CLAUDE.md
Added detect-error-handling-antipatterns.ts script to identify empty catch blocks, improper logging practices, and oversized try-catch blocks

New Features

Console Filter Bar with Log Parsing

Implemented interactive log filtering in the viewer UI:

Structured Log Parsing - Extracts timestamp, level, component, correlation ID, and message content using regex pattern matching
Level Filtering - Toggle visibility for DEBUG, INFO, WARN, ERROR log levels
Component Filtering - Filter by 9 component types: HOOK, WORKER, SDK, PARSER, DB, SYSTEM, HTTP, SESSION, CHROMA
Color-Coded Rendering - Visual distinction with component-specific icons and log level colors
Special Message Detection - Recognizes markers like → (dataIn), ← (dataOut), ✓ (success), ✗ (failure), ⏱ (timing), [HAPPY-PATH]
Smart Auto-Scroll - Maintains scroll position when reviewing older logs
Responsive Design - Filter bar adapts to smaller screens

[v8.5.3] - 2026-01-02

🛡️ Error Handling Hardening & Developer Tools

Version 8.5.3 introduces comprehensive error handling improvements that prevent silent failures and reduce debugging time from hours to minutes. This release also adds new developer tools for queue management and log monitoring.

🔴 Critical Error Handling Improvements

The Problem

A single overly-broad try-catch block caused a 10-hour debugging session by silently swallowing errors. This pattern was pervasive throughout the codebase, creating invisible failure modes.

The Solution

Automated Anti-Pattern Detection (scripts/detect-error-handling-antipatterns.ts)

Detects 7 categories of error handling anti-patterns
Enforces zero-tolerance policy for empty catch blocks
Identifies large try-catch blocks (>10 lines) that mask specific errors
Flags missing error logging that causes silent failures
Supports approved overrides with justification comments
Exit code 1 if critical issues detected (enforceable in CI)

New Error Handling Standards (Added to CLAUDE.md)

5-Question Pre-Flight Checklist: Required before writing any try-catch
1. What SPECIFIC error am I catching?
2. Show documentation proving this error can occur
3. Why can't this error be prevented?
4. What will the catch block DO?
5. Why shouldn't this error propagate?
Forbidden Patterns: Empty catch, catch without logging, large try blocks, promise catch without handlers
Allowed Patterns: Specific errors, logged failures, minimal scope, explicit recovery
Meta-Rule: Uncertainty triggers research, NOT try-catch

Fixes Applied

Wave 1: Empty Catch Blocks (5 files)

import-xml-observations.ts - Log skipped invalid JSON
bun-path.ts - Log when bun not in PATH
cursor-utils.ts - Log failed registry reads & corrupt MCP config
worker-utils.ts - Log failed health checks

Wave 2: Promise Catches on Critical Paths (8 locations)

worker-service.ts - Background initialization failures
SDKAgent.ts - Session processor errors (2 locations)
GeminiAgent.ts - Finalization failures (2 locations)
OpenRouterAgent.ts - Finalization failures (2 locations)
SessionManager.ts - Generator promise failures

Wave 3: Comprehensive Audit (29 catch blocks)

Added logging to 16 catch blocks (UI, servers, worker, routes, services)
Documented 13 intentional exceptions with justification comments
All patterns now follow error handling guidelines with appropriate log levels

Approved Override System

For justified exceptions (performance-critical paths, expected failures), use:

// [APPROVED OVERRIDE]: Brief technical justification
try {
  // code
} catch {
  // allowed exception
}

Progress: 163 anti-patterns → 26 approved overrides (84% reduction in silent failures)

🗂️ Queue Management Features

New Commands

npm run queue:clear - Interactive removal of failed messages
npm run queue:clear -- --all - Clear all messages (pending, processing, failed)
npm run queue:clear -- --force - Non-interactive mode

HTTP API Endpoints

DELETE /api/pending-queue/failed - Remove failed messages
DELETE /api/pending-queue/all - Complete queue reset

Failed messages exceed max retry count and remain for debugging. These commands provide clean queue maintenance.

🪵 Developer Console (Chrome DevTools Style)

UI Improvements

Bottom drawer console (slides up from bottom-left corner)
Draggable resize handle for height adjustment
Auto-refresh toggle (2s interval)
Clear logs button with confirmation
Monospace font (SF Mono/Monaco/Consolas)
Minimum height: 150px, adjustable to window height - 100px

API Endpoints

GET /api/logs - Fetch last 1000 lines of current day's log
DELETE /api/logs - Clear current log file

Logs viewer accessible via floating console button in UI.

📚 Architecture Documentation

Session ID Architecture (docs/SESSION_ID_ARCHITECTURE.md)

Comprehensive documentation of 1:1 session mapping guarantees
19 validation tests proving UNIQUE constraints and resume consistency
Documents single-transition vulnerability (application-level enforcement)
Complete reference for session lifecycle management

📊 Impact Summary

Debugging Time: 10 hours → minutes (proper error visibility)
Test Coverage: +19 critical architecture validation tests
Silent Failures: 84% reduction (163 → 26 approved exceptions)
Protection: Automated detection prevents regression
Developer UX: Console logs, queue management, comprehensive docs

🔧 Technical Details

Files Changed: 25+ files across error handling, queue management, UI, and documentation

Critical Path Protection These files now have strict error propagation (no catch-and-continue):

SDKAgent.ts
GeminiAgent.ts
OpenRouterAgent.ts
SessionStore.ts
worker-service.ts

Build Verification: All changes tested, build successful

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v8.5.2...v8.5.3

[v8.5.2] - 2025-12-31

Bug Fixes

Fixed SDK Agent Memory Leak (#499)

Fixed a critical memory leak where Claude SDK child processes were never terminated after sessions completed. Over extended usage, this caused hundreds of orphaned processes consuming 40GB+ of RAM.

Root Cause:

When the SDK agent generator completed naturally (no more messages to process), the AbortController was never aborted
Child processes spawned by the Agent SDK remained running indefinitely
Sessions stayed in memory (by design for future events) but underlying processes were never cleaned up

Fix:

Added proper cleanup to SessionRoutes finally block
Now calls abortController.abort() when generator completes with no pending work
Creates new AbortController when crash recovery restarts generators
Ensures cleanup happens even if recovery logic fails

Impact:

Prevents orphaned claude processes from accumulating
Eliminates multi-gigabyte memory leaks during normal usage
Maintains crash recovery functionality with proper resource cleanup

Thanks to @yonnock for the detailed bug report and investigation in #499!

[v8.5.1] - 2025-12-30

Bug Fix

Fixed: Migration 17 column rename failing for databases in intermediate states (#481)

Problem

Migration 17 renamed session ID columns but used a single check to determine if ALL tables were migrated. This caused errors for databases in partial migration states:

no such column: sdk_session_id (when columns already renamed)
table observations has no column named memory_session_id (when not renamed)

Solution

Rewrote migration 17 to check each table individually before renaming
Added safeRenameColumn() helper that handles all edge cases gracefully
Handles all database states: fresh, old, and partially migrated

Who was affected

Users upgrading from pre-v8.2.6 versions
Users whose migration was interrupted (crash, restart, etc.)
Users who restored database from backup

🤖 Generated with Claude Code

[v8.5.0] - 2025-12-30

Cursor Support Now Available 🎉

This is a major release introducing full Cursor IDE support. Claude-mem now works with Cursor, bringing persistent AI memory to Cursor users with or without a Claude Code subscription.

Highlights

Give Cursor persistent memory. Every Cursor session starts fresh - your AI doesn't remember what it worked on yesterday. Claude-mem changes that. Your agent builds cumulative knowledge about your codebase, decisions, and patterns over time.

Works Without Claude Code

You can now use claude-mem with Cursor using free AI providers:

Gemini (recommended): 1,500 free requests/day, no credit card required
OpenRouter: Access to 100+ models including free options
Claude SDK: For Claude Code subscribers

Cross-Platform Support

Full support for all major platforms:

macOS: Bash scripts with jq and curl
Linux: Same toolchain as macOS
Windows: Native PowerShell scripts, no WSL required

New Features

Interactive Setup Wizard (`bun run cursor:setup`)

A guided installer that:

Detects your environment (Claude Code present or not)
Helps you choose and configure an AI provider
Installs Cursor hooks automatically
Starts the worker service
Verifies everything is working

Cursor Lifecycle Hooks

Complete hook integration with Cursor's native hook system:

session-init.sh/.ps1 - Session start with context injection
user-message.sh/.ps1 - User prompt capture
save-observation.sh/.ps1 - Tool usage logging
save-file-edit.sh/.ps1 - File edit tracking
session-summary.sh/.ps1 - Session end summary
context-inject.sh/.ps1 - Load relevant history

Context Injection via `.cursor/rules`

Relevant past context is automatically injected into Cursor sessions via the .cursor/rules/claude-mem-context.mdc file, giving your AI immediate awareness of prior work.

Project Registry

Multi-project support with automatic project detection:

Projects registered in ~/.claude-mem/cursor-projects.json
Context automatically scoped to current project
Works across multiple workspaces simultaneously

MCP Search Tools

Full MCP server integration for Cursor:

search - Find observations by query, date, type
timeline - Get context around specific observations
get_observations - Fetch full details for filtered IDs

New Commands

Command	Description
`bun run cursor:setup`	Interactive setup wizard
`bun run cursor:install`	Install Cursor hooks
`bun run cursor:uninstall`	Remove Cursor hooks
`bun run cursor:status`	Check hook installation status

Documentation

Full documentation available at docs.claude-mem.ai/cursor:

Cursor Integration Overview
Gemini Setup Guide (free tier)
OpenRouter Setup Guide
Troubleshooting

Getting Started

For Cursor-Only Users (No Claude Code)

git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem && bun install && bun run build
bun run cursor:setup

For Claude Code Users

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
claude-mem cursor install

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v8.2.10...v8.5.0

[v8.2.10] - 2025-12-30

Bug Fixes

Auto-restart worker on version mismatch (#484): When the plugin updates but the worker was already running on the old version, the worker now automatically restarts instead of failing with 400 errors.

Changes

/api/version endpoint now returns the built-in version (compiled at build time) instead of reading from disk
worker-service start command checks for version mismatch and auto-restarts if needed
Downgraded hook version mismatch warning to debug logging (now handled by auto-restart)

Thanks @yungweng for the detailed bug report!

[v8.2.9] - 2025-12-29

Bug Fixes

Worker Service: Remove file-based locking and improve Windows stability
- Replaced file-based locking with health-check-first approach for cleaner mutual exclusion
- Removed AbortSignal.timeout() calls to reduce Bun libuv assertion errors on Windows
- Added 500ms shutdown delays on Windows to prevent zombie ports
- Reduced hook timeout values for improved responsiveness
- Increased worker readiness polling duration from 5s to 15s

Internal Changes

Updated worker CLI scripts to reference worker-service.cjs directly
Simplified hook command configurations

[v8.2.8] - 2025-12-29

Bug Fixes

Fixed orphaned chroma-mcp processes during shutdown (#489)
- Added graceful shutdown handling with signal handlers registered early in WorkerService lifecycle
- Ensures ChromaSync subprocess cleanup even when interrupted during initialization
- Removes PID file during shutdown to prevent stale process tracking

Technical Details

This patch release addresses a race condition where SIGTERM/SIGINT signals arriving during ChromaSync initialization could leave orphaned chroma-mcp processes. The fix moves signal handler registration from the start() method to the constructor, ensuring cleanup handlers exist throughout the entire initialization lifecycle.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v8.2.7...v8.2.8

[v8.2.7] - 2025-12-29

What's Changed

Token Optimizations

Simplified MCP server tool definitions for reduced token usage
Removed outdated troubleshooting and mem-search skill documentation
Enhanced search parameter descriptions for better clarity
Streamlined MCP workflows for improved efficiency

This release significantly reduces the token footprint of the plugin's MCP tools and documentation.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v8.2.6...v8.2.7

[v8.2.6] - 2025-12-29

What's Changed

Bug Fixes & Improvements

Session ID semantic renaming for clarity (content_session_id, memory_session_id)
Queue system simplification with unified processing logic
Memory session ID capture for agent resume functionality
Comprehensive test suite for session ID refactoring

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v8.2.5...v8.2.6

[v8.2.5] - 2025-12-28

Bug Fixes

Logger: Enhanced Error object handling in debug mode to prevent empty JSON serialization
ChromaSync: Refactored DatabaseManager to initialize ChromaSync lazily, removing background backfill on startup
SessionManager: Simplified message handling and removed linger timeout that was blocking completion

Technical Details

This patch release addresses several issues discovered after the session continuity fix:

Logger now properly serializes Error objects with stack traces in debug mode
ChromaSync initialization is now lazy to prevent silent failures during startup
Session linger timeout removed to eliminate artificial 5-second delays on session completion

Full changelog: https://github.com/thedotmack/claude-mem/compare/v8.2.4...v8.2.5

[v8.2.4] - 2025-12-28

Patch release v8.2.4

[v8.2.3] - 2025-12-27

Bug Fixes

Fix worker port environment variable in smart-install script
Implement file-based locking mechanism for worker operations to prevent race conditions
Fix restart command references in documentation (changed from claude-mem restart to npm run worker:restart)

[v8.2.2] - 2025-12-27

What's Changed

Features

Add OpenRouter provider settings and documentation
Add modal footer with save button and status indicators
Implement self-spawn pattern for background worker execution

Bug Fixes

Resolve critical error handling issues in worker lifecycle
Handle Windows/Unix kill errors in orphaned process cleanup
Validate spawn pid before writing PID file
Handle process exit in waitForProcessesExit filter
Use readiness endpoint for health checks instead of port check
Add missing OpenRouter and Gemini settings to settingKeys array

Other Changes

Enhance error handling and validation in agents and routes
Delete obsolete process management files (ProcessManager, worker-wrapper, worker-cli)
Update hooks.json to use worker-service.cjs CLI
Add comprehensive tests for hook constants and worker spawn functionality

[v8.2.1] - 2025-12-27

🔧 Worker Lifecycle Hardening

This patch release addresses critical bugs discovered during PR review of the self-spawn pattern introduced in 8.2.0. The worker daemon now handles edge cases robustly across both Unix and Windows platforms.

🐛 Critical Bug Fixes

Process Exit Detection Fixed

The waitForProcessesExit function was crashing when processes exited during monitoring. The process.kill(pid, 0) call throws when a process no longer exists, which was not being caught. Now wrapped in try/catch to correctly identify exited processes.

Spawn PID Validation

The worker daemon now validates that spawn() actually returned a valid PID before writing to the PID file. Previously, spawn failures could leave invalid PID files that broke subsequent lifecycle operations.

Cross-Platform Orphan Cleanup

Unix: Replaced single kill command with individual process.kill() calls wrapped in try/catch, so one already-exited process doesn't abort cleanup of remaining orphans
Windows: Wrapped taskkill calls in try/catch for the same reason

Health Check Reliability

Changed waitForHealth to use the /api/readiness endpoint (returns 503 until fully initialized) instead of just checking if the port is in use. Callers now wait for actual worker readiness, not just network availability.

🔄 Refactoring

Code Consolidation (-580 lines)

Deleted obsolete process management infrastructure that was replaced by the self-spawn pattern:

src/services/process/ProcessManager.ts (433 lines) - PID management now in worker-service
src/cli/worker-cli.ts (81 lines) - CLI handling now in worker-service
src/services/worker-wrapper.ts (157 lines) - Replaced by --daemon flag

Updated Hook Commands

All hooks now use worker-service.cjs CLI directly instead of the deleted worker-cli.js.

⏱️ Timeout Adjustments

Increased timeouts throughout for compatibility with slow systems:

Component	Before	After
Default hook timeout	120s	300s
Health check timeout	1s	30s
Health check retries	15	300
Context initialization	30s	300s
MCP connection	15s	300s
PowerShell commands	5s	60s
Git commands	30s	300s
NPM install	120s	600s
Hook worker commands	30s	180s

🧪 Testing

Added comprehensive test suites:

tests/hook-constants.test.ts - Validates timeout configurations
tests/worker-spawn.test.ts - Tests worker CLI and health endpoints

🛡️ Additional Robustness

PID validation in restart command (matches start command behavior)
Try/catch around forceKillProcess() for graceful shutdown
Try/catch around getChildProcesses() for Windows failures
Improved logging for PID file operations and HTTP shutdown

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v8.2.0...v8.2.1

[v8.2.0] - 2025-12-26

🚀 Gemini API as Alternative AI Provider

This release introduces Google Gemini API as an alternative to the Claude Agent SDK for observation extraction. This gives users flexibility in choosing their AI backend while maintaining full feature parity.

✨ New Features

Gemini Provider Integration

New GeminiAgent: Complete implementation using Gemini's REST API for observation and summary extraction
Provider selection: Choose between Claude or Gemini directly in the Settings UI
API key management: Configure via UI or GEMINI_API_KEY environment variable
Multi-turn conversations: Full conversation history tracking for context-aware extraction

Supported Gemini Models

gemini-2.5-flash-preview-05-20 (default)
gemini-2.5-pro-preview-05-06
gemini-2.0-flash
gemini-2.0-flash-lite

Rate Limiting

Built-in rate limiting for Gemini free tier (15 RPM) and paid tier (1000 RPM)
Configurable via gemini_has_billing setting in the UI

Resilience Features

Graceful fallback: Automatically falls back to Claude SDK if Gemini is selected but no API key is configured
Hot-swap providers: Switch between Claude and Gemini without restarting the worker
Empty response handling: Messages properly marked as processed even when Gemini returns empty responses (prevents stuck queue states)
Timestamp preservation: Recovered backlog messages retain their original timestamps

🎨 UI Improvements

Spinning favicon: Visual indicator during observation processing
Provider status: Clear indication of which AI provider is active

📚 Documentation

New Gemini Provider documentation with setup guide and troubleshooting

⚙️ New Settings

Setting	Values	Description
`CLAUDE_MEM_PROVIDER`	`claude` \| `gemini`	AI provider for observation extraction
`CLAUDE_MEM_GEMINI_API_KEY`	string	Gemini API key
`CLAUDE_MEM_GEMINI_MODEL`	see above	Gemini model to use
`gemini_has_billing`	boolean	Enable higher rate limits for paid accounts

🙏 Contributor Shout-out

Huge thanks to Alexander Knigge (@AlexanderKnigge) for contributing the Gemini provider implementation! This feature significantly expands claude-mem's flexibility and gives users more choice in their AI backend.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v8.1.0...v8.2.0

[v8.1.0] - 2025-12-25

The 3-Month Battle Against Complexity

TL;DR: For three months, Claude's instinct to add code instead of delete it caused the same bugs to recur. What should have been 5 lines of code became ~1000 lines, 11 useless methods, and 7+ failed "fixes." The timestamp corruption that finally broke things was just a symptom. The real achievement: 984 lines of code deleted.

What Actually Happened

Every Claude Code hook receives a session ID. That's all you need.

But Claude built an entire redundant session management system on top:

An sdk_sessions table with status tracking, port assignment, and prompt counting
11 methods in SessionStore to manage this artificial complexity
Auto-creation logic scattered across 3 locations
A cleanup hook that "completed" sessions at the end

Why? Because it seemed "robust." Because "what if the session doesn't exist?"

But the edge cases didn't exist. Hooks ALWAYS provide session IDs. The "defensive" code was solving imaginary problems while creating real ones.

The Pattern of Failure

Every time a bug appeared, Claude's instinct was to ADD more code:

Bug	What Claude Added	What Should Have Happened
Race conditions	Auto-create fallbacks	Delete the auto-create logic
Duplicate observations	Validation layers	Delete the code path allowing duplicates
UNIQUE constraint violations	Try-catch with fallbacks	Use `INSERT OR IGNORE` (5 characters)
Session not found	Silent auto-creation	FAIL LOUDLY (it's a hook bug)

The 7+ Failed Attempts

Nov 4: "Always store session data regardless of pre-existence." Complexity planted.
Nov 11: INSERT OR IGNORE recognized. But complexity documented, not removed.
Nov 21: Duplicate observations bug. Fixed. Then broken again by endless mode.
Dec 5: "6 hours of work delivered zero value." User requests self-audit.
Dec 20: "Phase 2: Eliminated Race Conditions" — felt like progress. Complexity remained.
Dec 24: Finally, forced deletion.

The user stated "hooks provide session IDs, no extra management needed" seven times across months. Claude didn't listen.

The Fix

Deleted (984 lines):

11 SessionStore methods: incrementPromptCounter, getPromptCounter, setWorkerPort, getWorkerPort, markSessionCompleted, markSessionFailed, reactivateSession, findActiveSDKSession, findAnySDKSession, updateSDKSessionId
Auto-create logic from storeObservation and storeSummary
The entire cleanup hook (was aborting SDK agent and causing data loss)
117 lines from worker-utils.ts

What remains (~10 lines):

createSDKSession(sessionId) {
  db.run('INSERT OR IGNORE INTO sdk_sessions (...) VALUES (...)');
  return db.query('SELECT id FROM sdk_sessions WHERE ...').get(sessionId);
}

That's it.

Behavior Change

Before: Missing session? Auto-create silently. Bug hidden.
After: Missing session? Storage fails. Bug visible immediately.

New Tools

Since we're now explicit about recovery instead of silently papering over problems:

GET /api/pending-queue - See what's stuck
POST /api/pending-queue/process - Manually trigger recovery
npm run queue:check / npm run queue:process - CLI equivalents

Dependencies

Upgraded @anthropic-ai/claude-agent-sdk from ^0.1.67 to ^0.1.76

PR #437: https://github.com/thedotmack/claude-mem/pull/437

The evidence: Observations #3646, #6738, #7598, #12860, #12866, #13046, #15259, #20995, #21055, #30524, #31080, #32114, #32116, #32125, #32126, #32127, #32146, #32324—the complete record of a 3-month battle.

[v8.0.6] - 2025-12-24

Bug Fixes

Add error handlers to Chroma sync operations to prevent worker crashes on timeout (#428)

This patch release improves stability by adding proper error handling to Chroma vector database sync operations, preventing worker crashes when sync operations timeout.

[v8.0.5] - 2025-12-24

Bug Fixes

Context Loading: Fixed observation filtering for non-code modes, ensuring observations are properly retrieved across all mode types

Technical Details

Refactored context loading logic to differentiate between code and non-code modes, resolving issues where mode-specific observations were filtered by stale settings.

[v8.0.4] - 2025-12-23

Changes

Changed worker start script

🤖 Generated with Claude Code

[v8.0.3] - 2025-12-23

Fix critical worker crashes on startup (v8.0.2 regression)

[v8.0.2] - 2025-12-23

New "chill" remix of code mode for users who want fewer, more selective observations.

Features

code--chill mode: A behavioral variant that produces fewer observations
- Only records things "painful to rediscover" - shipped features, architectural decisions, non-obvious gotchas
- Skips routine work, straightforward implementations, and obvious changes
- Philosophy: "When in doubt, skip it"

Documentation

Updated modes.mdx with all 28 language modes (was 10)
Added Code Mode Variants section documenting chill mode

Usage

Set in ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_MODE": "code--chill"
}

[v8.0.1] - 2025-12-23

🎨 UI Improvements

Header Redesign: Moved documentation and X (Twitter) links from settings modal to main header for better accessibility
Removed Product Hunt Badge: Cleaned up header layout by removing the Product Hunt badge
Icon Reorganization: Reordered header icons for improved UX flow (Docs → X → Discord → GitHub)

🤖 Generated with Claude Code

[v8.0.0] - 2025-12-23

🌍 Major Features

Mode System: Context-aware observation capture tailored to different workflows

Code Development mode (default): Tracks bugfixes, features, refactors, and more
Email Investigation mode: Optimized for email analysis workflows
Extensible architecture for custom domains

28 Language Support: Full multilingual memory

Arabic, Bengali, Chinese, Czech, Danish, Dutch, Finnish, French, German, Greek
Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Polish
Portuguese (Brazilian), Romanian, Russian, Spanish, Swedish, Thai, Turkish
Ukrainian, Vietnamese
All observations, summaries, and narratives generated in your chosen language

Inheritance Architecture: Language modes inherit from base modes

Consistent observation types across languages
Locale-specific output while maintaining structural integrity
JSON-based configuration for easy customization

🔧 Technical Improvements

ModeManager: Centralized mode loading and configuration validation
Dynamic Prompts: SDK prompts now adapt based on active mode
Mode-Specific Icons: Observation types display contextual icons/emojis per mode
Fail-Fast Error Handling: Complete removal of silent failures across all layers

📚 Documentation

New docs/public/modes.mdx documenting the mode system
28 translated README files for multilingual community support
Updated configuration guide for mode selection

🔨 Breaking Changes

None - Mode system is fully backward compatible
Default mode is 'code' (existing behavior)
Settings: New CLAUDE_MEM_MODE option (defaults to 'code')

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.4.5...v8.0.0 View PR: https://github.com/thedotmack/claude-mem/pull/412

[v7.4.5] - 2025-12-21

Bug Fixes

Fix missing formatDateTime import in SearchManager that broke get_context_timeline mem-search function

🤖 Generated with Claude Code

[v7.4.4] - 2025-12-21

What's Changed

Code quality: comprehensive nonsense audit cleanup (20 issues) by @thedotmack in #400

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.4.3...v7.4.4

[v7.4.3] - 2025-12-20

Added Discord notification script for release announcements.

Added

scripts/discord-release-notify.js - Posts formatted release notifications to Discord using webhook URL from .env
npm run discord:notify <version> - New npm script to trigger Discord notifications
Updated version-bump skill workflow to include Discord notification step

Configuration

Set DISCORD_UPDATES_WEBHOOK in your .env file to enable release notifications.

🤖 Generated with Claude Code

[v7.4.2] - 2025-12-20

Patch release v7.4.2

Changes

Refactored worker commands from npm scripts to claude-mem CLI
Added path alias script
Fixed Windows worker stop/restart reliability (#395)
Simplified build commands section in CLAUDE.md

[v7.4.1] - 2025-12-19

Bug Fixes

MCP Server: Redirect logs to stderr to preserve JSON-RPC protocol (#396)
- MCP uses stdio transport where stdout is reserved for JSON-RPC messages
- Console.log was writing startup logs to stdout, causing Claude Desktop to parse log lines as JSON and fail

[v7.4.0] - 2025-12-18

What's New

MCP Tool Token Reduction

Optimized MCP tool definitions for reduced token consumption in Claude Code sessions through progressive parameter disclosure.

Changes:

Streamlined MCP tool schemas with minimal inline definitions
Added get_schema() tool for on-demand parameter documentation
Enhanced worker API with operation-based instruction loading

This release improves session efficiency by reducing the token overhead of MCP tool definitions while maintaining full functionality through progressive disclosure.

🤖 Generated with Claude Code

[v7.3.9] - 2025-12-18

Fixes

Fix MCP server compatibility and web UI path resolution

This patch release addresses compatibility issues with the MCP server and resolves path resolution problems in the web UI.

[v7.3.8] - 2025-12-18

Security Fix

Added localhost-only protection for admin endpoints to prevent DoS attacks when worker service is bound to 0.0.0.0 for remote UI access.

Changes

Created requireLocalhost middleware to restrict admin endpoints
Applied to /api/admin/restart and /api/admin/shutdown
Returns 403 Forbidden for non-localhost requests

Security Impact

Prevents unauthorized shutdown/restart of worker service when exposed on network.

Fixes security concern raised in #368.

[v7.3.7] - 2025-12-17

Windows Platform Stabilization

This patch release includes comprehensive improvements for Windows platform stability and reliability.

Key Improvements

Worker Readiness Tracking: Added /api/readiness endpoint with MCP/SDK initialization flags to prevent premature connection attempts
Process Tree Cleanup: Implemented recursive process enumeration on Windows to prevent zombie socket processes
Bun Runtime Migration: Migrated worker wrapper from Node.js to Bun for consistency and reliability
Centralized Project Name Utility: Consolidated duplicate project name extraction logic with Windows drive root handling
Enhanced Error Messages: Added platform-aware logging and detailed Windows troubleshooting guidance
Subprocess Console Hiding: Standardized windowsHide: true across all child process spawns to prevent console window flashing

Technical Details

Worker service tracks MCP and SDK readiness states separately
ChromaSync service properly tracks subprocess PIDs for Windows cleanup
Worker wrapper uses Bun runtime with enhanced socket cleanup via process tree enumeration
Increased timeouts on Windows platform (30s worker startup, 10s hook timeouts)
Logger utility includes platform and PID information for better debugging

This represents a major reliability improvement for Windows users, eliminating common issues with worker startup failures, orphaned processes, and zombie sockets.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.3.6...v7.3.7

[v7.3.6] - 2025-12-17

Bug Fixes

Enhanced SDKAgent response handling and message processing

[v7.3.5] - 2025-12-17

What's Changed

fix(windows): solve zombie port problem with wrapper architecture by @ToxMox in https://github.com/thedotmack/claude-mem/pull/372
chore: bump version to 7.3.5 by @thedotmack in https://github.com/thedotmack/claude-mem/pull/375

New Contributors

@ToxMox made their first contribution in https://github.com/thedotmack/claude-mem/pull/372

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.3.4...v7.3.5

[v7.3.4] - 2025-12-17

Patch release for bug fixes and minor improvements

[v7.3.3] - 2025-12-16

What's Changed

Remove all better-sqlite3 references from codebase (#357)

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.3.2...v7.3.3

[v7.3.2] - 2025-12-16

🪟 Windows Console Fix

Fixes blank console windows appearing for Windows 11 users during claude-mem operations.

What Changed

Windows: Uses PowerShell Start-Process -WindowStyle Hidden to properly hide worker process
Security: Added PowerShell string escaping to follow security best practices
Unix/Mac: No changes (continues to work as before)

Root Cause

The issue was caused by a Node.js limitation where windowsHide: true doesn't work with detached: true in child_process.spawn(). This affects both Bun and Node.js since Bun inherits Node.js process spawning semantics.

See: https://github.com/nodejs/node/issues/21825

Security Note

While all paths in the PowerShell command are application-controlled (not user input), we've added proper escaping to follow security best practices. If an attacker could modify bun installation paths or plugin directories, they would already have full filesystem access including the database.

Fixes #304 (Multiple visible console windows)
Merged PR #339
Testing documented in PR #315

Breaking Changes

None - fully backward compatible.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.3.1...v7.3.2

[v7.3.1] - 2025-12-16

🐛 Bug Fixes

Pending Messages Cleanup (Issue #353)

Fixed unbounded database growth in the pending_messages table by implementing proper cleanup logic:

Content Clearing: markProcessed() now clears tool_input and tool_response when marking messages as processed, preventing duplicate storage of transcript data that's already saved in observations
Count-Based Retention: cleanupProcessed() now keeps only the 100 most recent processed messages for UI display, deleting older ones automatically
Automatic Cleanup: Cleanup runs automatically after processing messages in SDKAgent.processSDKResponse()

What This Fixes

Prevents database from growing unbounded with duplicate transcript content
Keeps metadata (tool_name, status, timestamps) for recent messages
Maintains UI functionality while optimizing storage

Technical Details

Files Modified:

src/services/sqlite/PendingMessageStore.ts - Cleanup logic implementation
src/services/worker/SDKAgent.ts - Periodic cleanup calls

Database Behavior:

Pending/processing messages: Keep full transcript data (needed for processing)
Processed messages: Clear transcript, keep metadata only (observations already saved)
Retention: Last 100 processed messages for UI feedback

Fixes #353 - Observations not being saved
Part of the pending messages persistence feature (from PR #335)

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.3.0...v7.3.1

[v7.3.0] - 2025-12-16

Features

Table-based search output: Unified timeline formatting with cleaner, more organized presentation of search results grouped by date and file
Simplified API: Removed unused format parameter from MCP search tools for cleaner interface
Shared formatting utilities: Extracted common timeline formatting logic into reusable module
Batch observations endpoint: Added /api/observations/batch endpoint for efficient retrieval of multiple observations by ID array

Changes

Default model upgrade: Changed default model from Haiku to Sonnet for better observation quality
Removed fake URIs: Replaced claude-mem:// pseudo-protocol with actual HTTP API endpoints for citations

Bug Fixes

Fixed undefined debug function calls in MCP server
Fixed skillPath variable scoping bug in instructions endpoint
Extracted magic numbers to named constants for better code maintainability

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.2.4...v7.3.0

[v7.2.4] - 2025-12-15

What's Changed

Documentation

Updated endless mode setup instructions with improved configuration guidance for better user experience

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.2.3...v7.2.4

[v7.2.3] - 2025-12-15

Bug Fixes

Fix MCP server failures on plugin updates: Add 2-second pre-restart delay in ensureWorkerVersionMatches() to give files time to sync before killing the old worker. This prevents the race condition where the worker restart happened too quickly after plugin file updates, causing "Worker service connection failed" errors.

Changes

Add PRE_RESTART_SETTLE_DELAY constant (2000ms) to hook-constants.ts
Add delay before ProcessManager.restart() call in worker-utils.ts
Fix pre-existing bug where port variable was undefined in error logging

🤖 Generated with Claude Code

[v7.2.2] - 2025-12-15

Changes

Refactor: Consolidate mem-search skill, remove desktop-skill duplication
- Delete separate desktop-skill/ directory (was outdated)
- Generate mem-search.zip during build from plugin/skills/mem-search/
- Update docs with correct MCP tool list and new download path
- Single source of truth for Claude Desktop skill

[v7.2.1] - 2025-12-14

Translation Script Enhancements

This release adds powerful enhancements to the README translation system, supporting 35 languages with improved efficiency and caching.

What's New

Translation Script Improvements:

Caching System: Smart .translation-cache.json tracks content hashes to skip re-translating unchanged content
Parallel Processing: --parallel <n> flag enables concurrent translations for faster execution
Force Re-translation: --force flag to override cache when needed
Tier-Based Scripts: Organized translation workflows by language priority
- npm run translate:tier1 - 7 major languages (Chinese, Japanese, Korean, etc.)
- npm run translate:tier2 - 8 strong tech scene languages (Hebrew, Arabic, Russian, etc.)
- npm run translate:tier3 - 7 emerging markets (Vietnamese, Indonesian, Thai, etc.)
- npm run translate:tier4 - 6 additional languages (Italian, Greek, Hungarian, etc.)
- npm run translate:all - All 35 languages sequentially
Better Output Handling: Automatically strips markdown code fences if Claude wraps output
Translation Disclaimer: Adds community correction notice at top of translated files
Performance: Uses Bun runtime for faster execution

Supported Languages (35 Total)

Arabic, Bengali, Brazilian Portuguese, Bulgarian, Chinese (Simplified), Chinese (Traditional), Czech, Danish, Dutch, Estonian, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese

Breaking Changes

None - fully backward compatible.

Installation

# Update via npm
npm install -g claude-mem@7.2.1

# Or reinstall plugin
claude plugin install thedotmack/claude-mem

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.2.0...v7.2.1

[v7.2.0] - 2025-12-14

🎉 New Features

Automated Bug Report Generator

Added comprehensive bug report tool that streamlines issue reporting with AI assistance:

Command: npm run bug-report
🌎 Multi-language Support: Write in ANY language, auto-translates to English
📊 Smart Diagnostics: Automatically collects:
- Version information (claude-mem, Claude Code, Node.js, Bun)
- Platform details (OS, version, architecture)
- Worker status (running state, PID, port, uptime, stats)
- Last 50 lines of logs (worker + silent debug)
- Database info and configuration settings
🤖 AI-Powered: Uses Claude Agent SDK to generate professional GitHub issues
📝 Interactive: Multiline input support with intuitive prompts
🔒 Privacy-Safe:
- Auto-sanitizes all file paths (replaces home directory with ~)
- Optional --no-logs flag to exclude logs
⚡ Streaming Progress: Real-time character count and animated spinner
🌐 One-Click Submit: Auto-opens GitHub with pre-filled title and body

Usage

From the plugin directory:

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

Plugin Paths:

macOS/Linux: ~/.claude/plugins/marketplaces/thedotmack
Windows: %USERPROFILE%\.claude\plugins\marketplaces\thedotmack

Options:

npm run bug-report --no-logs    # Skip logs for privacy
npm run bug-report --verbose    # Show all diagnostics
npm run bug-report --help       # Show help

📚 Documentation

Updated README with bug report section and usage instructions
Enhanced GitHub issue template to feature automated tool
Added platform-specific directory paths

🔧 Technical Details

Files Added:

scripts/bug-report/cli.ts - Interactive CLI entry point
scripts/bug-report/index.ts - Core logic with Agent SDK integration
scripts/bug-report/collector.ts - System diagnostics collector

Files Modified:

package.json - Added bug-report script
README.md - New Bug Reports section
.github/ISSUE_TEMPLATE/bug_report.md - Updated with automated tool instructions

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.1.15...v7.2.0

[v7.1.15] - 2025-12-14

🐛 Bug Fixes

Worker Service Initialization

Fixed 404 error on /api/context/inject during worker startup
Route is now registered immediately instead of after database initialization
Prevents race condition on fresh installs and restarts
Added integration test for early context inject route access

Technical Details

The context hook was failing with Cannot GET /api/context/inject because the route was registered only after database initialization completed. This created a race condition where the hook could attempt to access the endpoint before it existed.

Implementation:

Added initializationComplete Promise to track async background initialization
Register /api/context/inject route immediately in setupRoutes()
Early handler blocks requests until initialization resolves (30s timeout)
Route handler duplicates logic from SearchRoutes.handleContextInject by design to prevent 404s

Testing:

Added integration test verifying route registration and timeout handling

Fixes #305 Related: PR #310

[v7.1.14] - 2025-12-14

Enhanced Error Handling & Logging

This patch release improves error message quality and logging across the claude-mem system.

Error Message Improvements

Standardized Hook Error Handling

Created shared error handlers (handleFetchError, handleWorkerError) for consistent error messages
Platform-aware restart instructions (macOS, Linux, Windows) with correct commands
Migrated all hooks (context, new, save, summary) to use standardized handlers
Enhanced error logging with actionable context before throwing restart instructions

ChromaSync Error Standardization

Consistent client initialization checks across all methods
Enhanced error messages with troubleshooting steps and restart instructions
Better context about which operation failed

Worker Service Improvements

Enhanced version endpoint error logging with status codes and response text
Improved worker restart error messages with PM2 commands
Better context in all worker-related error scenarios

Bug Fixes

Issue #260: Fixed happy_path_error__with_fallback misuse in save-hook causing false "Missing cwd" errors
Removed unnecessary happy_path_error calls from SDKAgent that were masking real error messages
Cleaned up migration logging to use console.log instead of console.error for non-error events

Logging Improvements

Timezone-Aware Timestamps

Worker logs now use local machine timezone instead of UTC
Maintains same format (YYYY-MM-DD HH:MM:SS.mmm) but reflects local time
Easier debugging and log correlation with system events
Enhanced worker-cli logging output format

Test Coverage

Added comprehensive test suites:

tests/error-handling/hook-error-logging.test.ts - 12 tests for hook error handler behavior
tests/services/chroma-sync-errors.test.ts - ChromaSync error message consistency
tests/integration/hook-execution-environments.test.ts - Bun PATH resolution across shells
docs/context/TEST_AUDIT_2025-12-13.md - Comprehensive audit report

Files Changed

27 files changed: 1,435 additions, 200 deletions

What's Changed

Standardize and enhance error handling across hooks and worker service by @thedotmack in #295
Timezone-aware logging for worker service and CLI
Complete build with all plugin files included

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.1.12...v7.1.14

🤖 Generated with Claude Code

[v7.1.13] - 2025-12-14

Enhanced Error Handling & Logging

This patch release improves error message quality and logging across the claude-mem system.

Error Message Improvements

Standardized Hook Error Handling

Created shared error handlers (handleFetchError, handleWorkerError) for consistent error messages
Platform-aware restart instructions (macOS, Linux, Windows) with correct commands
Migrated all hooks (context, new, save, summary) to use standardized handlers
Enhanced error logging with actionable context before throwing restart instructions

ChromaSync Error Standardization

Consistent client initialization checks across all methods
Enhanced error messages with troubleshooting steps and restart instructions
Better context about which operation failed

Worker Service Improvements

Enhanced version endpoint error logging with status codes and response text
Improved worker restart error messages with PM2 commands
Better context in all worker-related error scenarios

Bug Fixes

Issue #260: Fixed happy_path_error__with_fallback misuse in save-hook causing false "Missing cwd" errors
Removed unnecessary happy_path_error calls from SDKAgent that were masking real error messages
Cleaned up migration logging to use console.log instead of console.error for non-error events

Logging Improvements

Timezone-Aware Timestamps

Worker logs now use local machine timezone instead of UTC
Maintains same format (YYYY-MM-DD HH:MM:SS.mmm) but reflects local time
Easier debugging and log correlation with system events

Test Coverage

Added comprehensive test suites:

tests/error-handling/hook-error-logging.test.ts - 12 tests for hook error handler behavior
tests/services/chroma-sync-errors.test.ts - ChromaSync error message consistency
tests/integration/hook-execution-environments.test.ts - Bun PATH resolution across shells
docs/context/TEST_AUDIT_2025-12-13.md - Comprehensive audit report

Files Changed

27 files changed: 1,435 additions, 200 deletions

What's Changed

Standardize and enhance error handling across hooks and worker service by @thedotmack in #295
Timezone-aware logging for worker service

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v7.1.12...v7.1.13

🤖 Generated with Claude Code

54 KiB Raw Blame History

Changelog

[v8.5.6] - 2026-01-04

Major Architectural Refactoring

Worker Service

Context Generator

Search System

Agent System

SQLite Layer

Bug Fixes

Coming Next

[v8.5.5] - 2026-01-03

Improved Error Handling and Logging

Changes

Investigation Reports

[v8.5.4] - 2026-01-02

Bug Fixes

Chroma Connection Error Handling

Removed Dead last_user_message Code

Improvements

Enhanced Error Handling Across Services

Error Handling Documentation & Tooling

New Features

Console Filter Bar with Log Parsing

[v8.5.3] - 2026-01-02

🛡️ Error Handling Hardening & Developer Tools

🔴 Critical Error Handling Improvements

The Problem

The Solution

Fixes Applied

Approved Override System

🗂️ Queue Management Features

🪵 Developer Console (Chrome DevTools Style)

📚 Architecture Documentation

📊 Impact Summary

🔧 Technical Details

[v8.5.2] - 2025-12-31

Bug Fixes

Fixed SDK Agent Memory Leak (#499)

[v8.5.1] - 2025-12-30

Bug Fix

Problem

Solution

Who was affected

[v8.5.0] - 2025-12-30

Cursor Support Now Available 🎉

Highlights

Works Without Claude Code

Cross-Platform Support

New Features

Interactive Setup Wizard (bun run cursor:setup)

Cursor Lifecycle Hooks

Context Injection via .cursor/rules

Project Registry

MCP Search Tools

New Commands

Documentation

Getting Started

For Cursor-Only Users (No Claude Code)

For Claude Code Users

[v8.2.10] - 2025-12-30

Bug Fixes

Changes

[v8.2.9] - 2025-12-29

Bug Fixes

Internal Changes

[v8.2.8] - 2025-12-29

Bug Fixes

Technical Details

[v8.2.7] - 2025-12-29

What's Changed

Token Optimizations

[v8.2.6] - 2025-12-29

What's Changed

Bug Fixes & Improvements

[v8.2.5] - 2025-12-28

Bug Fixes

Technical Details

[v8.2.4] - 2025-12-28

[v8.2.3] - 2025-12-27

54 KiB

Raw Blame History

Interactive Setup Wizard (`bun run cursor:setup`)

Context Injection via `.cursor/rules`