airkjw/claude-mem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update CHANGELOG.md for v8.2.0

Browse Source 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alex Newman
2025-12-25 21:52:21 -05:00
parent 4282d03e9e
commit 3d31c6e46d
1 changed files with 151 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+151 -108
View File
@@ -4,116 +4,159 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [8.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](https://docs.claude-mem.ai/usage/gemini-provider) 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](https://x.com/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
## [8.1.0] - 2025-12-25 ## [8.1.0] - 2025-12-25
## Summary ## The 3-Month Battle Against Complexity
This minor release brings significant architectural improvements focused on **explicit user control**, **simplified session management**, and **enhanced worker reliability**. The automatic recovery system has been replaced with a manual recovery approach, giving users complete control over when observations are reprocessed. **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.**
## Breaking Changes ---
**Manual Recovery Replaces Automatic Recovery** ## What Actually Happened
- Worker no longer automatically reprocesses stuck observations on startup
- Users must explicitly trigger recovery via CLI tool or HTTP API Every Claude Code hook receives a session ID. That's all you need.
- Prevents unexpected duplicate observations and processing
- See the new Manual Recovery documentation for migration guide But Claude built an entire redundant session management system on top:
- An `sdk_sessions` table with status tracking, port assignment, and prompt counting
**Removed Cleanup Hook** - 11 methods in `SessionStore` to manage this artificial complexity
- `cleanup-hook.ts` and `plugin/scripts/cleanup-hook.js` have been removed - Auto-creation logic scattered across 3 locations
- Hook behavior was moved to session completion handler - A cleanup hook that "completed" sessions at the end
**Hook Timeout Increased** **Why?** Because it seemed "robust." Because "what if the session doesn't exist?"
- Default hook timeout changed from 5000ms to 120000ms
- Accommodates longer-running operations during startup But the edge cases didn't exist. Hooks ALWAYS provide session IDs. The "defensive" code was solving imaginary problems while creating real ones.
## New Features ---
**Queue Management API** ## The Pattern of Failure
- `GET /api/pending-queue` - View processing queue status, stuck messages, and session work
- `POST /api/pending-queue/process` - Manually trigger recovery with session limits Every time a bug appeared, Claude's instinct was to **ADD** more code:
- Detailed queue statistics including stuck detection (>5 minute threshold)
| Bug | What Claude Added | What Should Have Happened |
**CLI Recovery Tool** |-----|------------------|--------------------------|
- `bun scripts/check-pending-queue.ts` - Interactive queue inspection and recovery | Race conditions | Auto-create fallbacks | Delete the auto-create logic |
- `--process` flag for non-interactive mode | Duplicate observations | Validation layers | Delete the code path allowing duplicates |
- `--limit N` to control sessions processed per batch | UNIQUE constraint violations | Try-catch with fallbacks | Use `INSERT OR IGNORE` (5 characters) |
- npm scripts: `npm run queue:check` and `npm run queue:process` | Session not found | Silent auto-creation | **FAIL LOUDLY** (it's a hook bug) |
**Data Routes API** ---
- New DataRoutes module for queue management endpoints
- Session-aware pending work tracking ## The 7+ Failed Attempts
## Bug Fixes - **Nov 4**: "Always store session data regardless of pre-existence." Complexity planted.
- **Nov 11**: `INSERT OR IGNORE` recognized. But complexity documented, not removed.
**Observation Timestamps Fixed** - **Nov 21**: Duplicate observations bug. Fixed. Then broken again by endless mode.
- Corrected timestamp handling throughout the observation lifecycle - **Dec 5**: "6 hours of work delivered zero value." User requests self-audit.
- Fixed `created_at_epoch` preservation in database operations - **Dec 20**: "Phase 2: Eliminated Race Conditions" — felt like progress. Complexity remained.
- **Dec 24**: Finally, forced deletion.
**Enhanced Worker Reliability**
- Added error handlers to Chroma sync operations (prevents crashes on timeout) The user stated "hooks provide session IDs, no extra management needed" **seven times** across months. Claude didn't listen.
- Version mismatch now logs warning instead of force-restarting worker
- Improved polling mechanism with increased retries and reduced interval ---
## Refactoring ## The Fix
**Simplified Session Management** ### Deleted (984 lines):
- Removed 279 lines of complexity from SessionStore - 11 `SessionStore` methods: `incrementPromptCounter`, `getPromptCounter`, `setWorkerPort`, `getWorkerPort`, `markSessionCompleted`, `markSessionFailed`, `reactivateSession`, `findActiveSDKSession`, `findAnySDKSession`, `updateSDKSessionId`
- `createSDKSession` simplified to pure `INSERT OR IGNORE` - Auto-create logic from `storeObservation` and `storeSummary`
- Removed auto-create logic from `storeObservation` and `storeSummary` - The entire cleanup hook (was aborting SDK agent and causing data loss)
- Deleted 11 unused session management methods - 117 lines from `worker-utils.ts`
- `prompt_number` now derived from `user_prompts` count
### What remains (~10 lines):
**Simplified Worker Utils** ```javascript
- Removed 117 lines of legacy code createSDKSession(sessionId) {
- Removed PM2 cleanup logic db.run('INSERT OR IGNORE INTO sdk_sessions (...) VALUES (...)');
- Streamlined `ensureWorkerRunning` function return db.query('SELECT id FROM sdk_sessions WHERE ...').get(sessionId);
}
**SDK Agent Improvements** ```
- Removed complex session creation retry logic
- Cleaner prompt number retrieval from SessionRoutes **That's it.**
## Documentation ---
**New Manual Recovery Guide** (`docs/public/usage/manual-recovery.mdx`) ## Behavior Change
- Complete 450-line guide for recovery workflows
- Interactive CLI usage examples - **Before:** Missing session? Auto-create silently. Bug hidden.
- HTTP API integration examples - **After:** Missing session? Storage fails. Bug visible immediately.
- Troubleshooting stuck messages
- Cron job and monitoring script examples ---
**Enhanced Troubleshooting** (`docs/public/troubleshooting.mdx`) ## New Tools
- Added 195 lines of manual recovery troubleshooting
- Queue state explanations Since we're now explicit about recovery instead of silently papering over problems:
- Direct database inspection queries
- `GET /api/pending-queue` - See what's stuck
**Updated Development Guide** - `POST /api/pending-queue/process` - Manually trigger recovery
- Changed testing philosophy to emphasize real-world testing - `npm run queue:check` / `npm run queue:process` - CLI equivalents
- Added manual testing workflow documentation
- Queue health verification procedures ---
**Worker Service Docs Updated** ## Dependencies
- Documented 22 HTTP endpoints (up from 20) - Upgraded `@anthropic-ai/claude-agent-sdk` from `^0.1.67` to `^0.1.76`
- Queue management endpoint documentation
---
## Dependencies
**PR #437:** https://github.com/thedotmack/claude-mem/pull/437
- Upgraded `@anthropic-ai/claude-agent-sdk` from `^0.1.67` to `^0.1.76`
*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.*
## New Scripts
- `scripts/check-pending-queue.ts` - CLI tool for queue management
- `scripts/fix-all-timestamps.ts` - Timestamp correction utility
- `scripts/fix-corrupted-timestamps.ts` - Corrupted timestamp repair
- `scripts/investigate-timestamps.ts` - Timestamp debugging tool
- `scripts/validate-timestamp-logic.ts` - Timestamp validation
- `scripts/verify-timestamp-fix.ts` - Post-fix verification
## Migration Guide
1. **After upgrading**: Run `bun scripts/check-pending-queue.ts` to check for stuck messages
2. **If messages found**: Run `bun scripts/check-pending-queue.ts --process` to recover
3. **Optional**: Add recovery to your workflow (cron job, pre-shutdown script)
4. **Note**: Automatic recovery no longer happens - you must trigger it manually
## [8.0.6] - 2025-12-24 ## [8.0.6] - 2025-12-24