v9.0.0 - Live Context System

🚀 Live Context System

Version 9.0.0 introduces the Live Context System - a major new capability that provides folder-level activity context through auto-generated CLAUDE.md files.

✨ New Features

Live Context System

• Folder CLAUDE.md Files: Each directory now gets an auto-generated CLAUDE.md file containing a chronological timeline of recent development activity
• Activity Timelines: Tables show observation ID, time, type, title, and estimated token cost for relevant work in each folder
• Worktree Support: Proper detection of git worktrees with project-aware filtering to show only relevant observations per worktree
• Configurable Limits: Control observation count via CLAUDE_MEM_CONTEXT_OBSERVATIONS setting

Modular Architecture Refactor

• Service Layer Decomposition: Major refactoring from monolithic worker-service to modular domain services
• SQLite Module Extraction: Database operations split into dedicated modules (observations, sessions, summaries, prompts, timeline)
• Context Builder System: New modular context generation with TimelineRenderer, FooterRenderer, and ObservationCompiler
• Error Handler Centralization: Unified Express error handling via ErrorHandler module

SDK Agent Improvements

• Session Resume: Memory sessions can now resume across Claude conversations using SDK session IDs
• Memory Session ID Tracking: Proper separation of content session IDs from memory session IDs
• Response Processor Refactor: Cleaner message handling and observation extraction

🔧 Improvements

Windows Stability

• Fixed Windows PowerShell variable escaping in hook execution
• Improved IPC detection for Windows managed mode
• Better PATH handling for Bun and uv on Windows

Settings & Configuration

• Auto-Creation: Settings file automatically created with defaults on first run
• Worker Host Configuration: CLAUDE_MEM_WORKER_HOST setting for custom worker endpoints
• Settings validation with helpful error messages

MCP Tools

• Standardized naming: "MCP tools" terminology instead of "mem-search skill"
• Improved tool descriptions for better Claude integration
• Context injection API now supports worktree parameter

📚 Documentation

• New Folder Context Files documentation page
• Worktree Support section explaining git worktree behavior
• Updated architecture documentation reflecting modular refactor
• v9.0 release notes in introduction page

🐛 Bug Fixes

• Fixed stale session resume crash when SDK session is orphaned
• Fixed logger serialization bug causing silent ChromaSync failures
• Fixed CLAUDE.md path resolution in worktree environments
• Fixed date preservation in folder timeline generation
• Fixed foreign key constraint issues in observation storage
• Resolved multiple TypeScript type errors across codebase

🗑️ Removed

• Deprecated context-generator.ts (functionality moved to modular system)
• Obsolete queue analysis documents
• Legacy worker wrapper scripts

---

Full Changelog: v8.5.10...v9.0.0

🤖 Generated with Claude Code

v8.5.10

Bug Fixes

• #545: Fixed formatTool crash when parsing non-JSON tool inputs (e.g., raw Bash commands)
• #544: Fixed terminology in context hints - changed "mem-search skill" to "MCP tools"
• #557: Settings file now auto-creates with defaults on first run (no more "module loader" errors)
• #543: Fixed hook execution by switching runtime from node to bun (resolves bun:sqlite issues)

Code Quality

• Fixed circular dependency between Logger and SettingsDefaultsManager
• Added 72 integration tests for critical coverage gaps
• Cleaned up mock-heavy tests causing module cache pollution

Full Changelog

See PR #558 for complete details and diagnostic reports.

v8.5.9

What's New

Context Header Timestamp

The context injection header now displays the current date and time, making it easier to understand when context was generated.

Example: [claude-mem] recent context, 2026-01-04 2:46am EST

This appears in both terminal (colored) output and markdown format, including empty state messages.

---

Full Changelog: v8.5.8...v8.5.9

v8.5.8

Bug Fixes

• #511: Add gemini-3-flash model to GeminiAgent with proper rate limits and validation
• #517: Fix Windows process management by replacing PowerShell with WMIC (fixes Git Bash/WSL compatibility)
• #527: Add Apple Silicon Homebrew paths (/opt/homebrew/bin) for bun and uv detection
• #531: Remove duplicate type definitions from export-memories.ts using shared bridge file

Tests

• Added regression tests for PR #542 covering Gemini model support, WMIC parsing, Apple Silicon paths, and export type refactoring

Documentation

• Added detailed analysis reports for GitHub issues #511, #514, #517, #520, #527, #531, #532

v8.5.7

Modular Architecture Refactor

This release refactors the monolithic service architecture into focused, single-responsibility modules with comprehensive test coverage.

Architecture Improvements

• SQLite Repositories (src/services/sqlite/) - Modular repositories for sessions, observations, prompts, summaries, and timeline
• Worker Agents (src/services/worker/agents/) - Extracted response processing, error handling, and session cleanup
• Search Strategies (src/services/worker/search/) - Modular search with Chroma, SQLite, and Hybrid strategies plus orchestrator
• Context Generation (src/services/context/) - Separated context building, token calculation, formatters, and renderers
• Infrastructure (src/services/infrastructure/) - Graceful shutdown, health monitoring, and process management
• Server (src/services/server/) - Express server setup, middleware, and error handling

Test Coverage

• 595 tests across 36 test files
• 1,120 expect() assertions
• Coverage for SQLite repos, worker agents, search, context, infrastructure, and server modules

Session ID Refactor

• Aligned tests with NULL-based memory session initialization pattern
• Updated SESSION_ID_ARCHITECTURE.md documentation

Other Improvements

• Added missing logger imports to 34 files for better observability
• Updated esbuild and MCP SDK to latest versions
• Removed bun.lock from version control

Full Changelog: v8.5.6...v8.5.7

v8.5.6

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

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: v8.5.4...v8.5.5

v8.5.4

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

🛡️ 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: v8.5.2...v8.5.3

v8.5.2 - SDK Agent Memory Leak Fix

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!