- Implemented a new skill-based search approach, replacing MCP search tools to reduce session start context from ~2,500 tokens to ~250 tokens.
- Added 10 new HTTP API endpoints to the worker service for various search functionalities.
- Created a new search skill with detailed instructions and examples for users.
- Removed MCP search server references and updated documentation to reflect the new skill-based approach.
- Enhanced context handling in the context hook to conditionally display the most recent summary based on observations.
- Introduced comprehensive documentation for Agent Skills, including creation, management, and best practices.
Improvements:
- Context hook now displays 'investigated' and 'learned' fields from session summaries
- Enhanced SQL query to SELECT these fields from database
- Added color-coded display formatting (blue for investigated, yellow for learned)
- Updated TypeScript types to include nullable investigated and learned fields
Technical changes:
- Updated src/hooks/context-hook.ts to query and display new fields
- Updated built plugin/scripts/context-hook.js
- Bumped version to 5.2.2 in all metadata files
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* feat: Enhance session and summary handling
- Update SQL query in SessionStore to exclude null or empty projects.
- Add 'investigated' field to Summary interface for better tracking.
- Modify App component to handle pagination more efficiently based on current filters.
- Update SummaryCard to display the 'investigated' field if present.
- Refactor usePagination hook to reset pagination state when filters change.
- Adjust mergeAndDeduplicateByProject function to ensure it only merges unfiltered data.
* refactor: address PR feedback - remove redundancies and fix dependency cycles
Fixes based on PR #70 review feedback:
Required:
- Fixed useEffect dependency cycle in App.tsx (removed handleLoadMore from deps)
Recommended:
- Removed redundant filter detection from App.tsx (usePagination handles this)
- Removed redundant stateRef update effect from usePagination.ts
- Simplified mergeAndDeduplicateByProject by removing defensive validation
- Removed unused imports (useRef, useEffect)
All changes follow CLAUDE.md principles: DRY, fail-fast, no defensive programming.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Reset paginated data arrays when filter changes
Critical fix for data mixing bug identified in PR review follow-up.
Problem:
When filter changes, usePagination correctly resets its offset to 0, but
the paginated state arrays (observations, summaries, prompts) were NOT
being reset. This caused data from different projects to mix together
because setState appends to the existing array.
Example:
- User views Project A: [A1, A2, A3]
- User switches to Project B
- API fetches [B1, B2, B3]
- setState does: [...prev, ...new] = [A1, A2, A3, B1, B2, B3] ❌
Solution:
Added a separate useEffect that resets all three paginated arrays when
currentFilter changes. This happens BEFORE handleLoadMore fetches new
data, ensuring clean state for the new filter.
Files changed:
- src/ui/viewer/App.tsx: Added useEffect to reset arrays on filter change
- plugin/ui/viewer-bundle.js: Built UI bundle
Testing:
1. Select Project A, verify data loads
2. Switch to Project B
3. Verify ONLY Project B data is shown (no mixing)
4. Switch back to "All Projects"
5. Verify all data appears correctly
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: Combine filter change useEffect hooks for guaranteed order
Merged two separate useEffect hooks into one to:
1. Guarantee execution order (reset THEN load)
2. Reduce complexity (one hook instead of two)
3. Make intent clearer with single comment
Before:
- useEffect #1: handleLoadMore() on filter change
- useEffect #2: Reset arrays on filter change
- React could run these in any order
After:
- Single useEffect: Reset arrays THEN handleLoadMore()
- Execution order is now guaranteed
Files changed:
- src/ui/viewer/App.tsx: Combined useEffect hooks
- plugin/ui/viewer-bundle.js: Built UI bundle
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
- Introduced comprehensive API reference for the TypeScript Agent SDK.
- Documented installation instructions for the SDK.
- Detailed the main functions: `query()`, `tool()`, and `createSdkMcpServer()`.
- Defined various types including `Options`, `Query`, `AgentDefinition`, and more.
- Included message types and their structures, such as `SDKMessage`, `SDKAssistantMessage`, and `SDKUserMessage`.
- Explained hook types and their usage within the SDK.
- Provided detailed documentation for tool input and output types.
- Added sections on permission types and other relevant types for better clarity.
- Introduced WorkerService class to handle HTTP requests and manage sessions.
- Added endpoints for health check, session management, and data retrieval.
- Integrated ChromaSync for background data synchronization.
- Implemented SSE for real-time updates to connected clients.
- Added error handling and logging throughout the service.
- Cached Claude executable path for improved performance.
- Included settings management for user configuration.
- Established database interactions for session and observation management.
- Removed fragile PM2 string parsing and replaced with direct PM2 restart logic.
- Eliminated silent error handling in worker-utils.ts for better error visibility.
- Extracted duplicated session auto-creation logic into a new helper method getOrCreateSession() in worker-service.ts.
- Centralized configuration values and replaced magic numbers with named constants.
- Updated health check logic to ensure worker is restarted if unhealthy.
- Removed unnecessary getWorkerPort() wrapper function.
- Improved overall code quality and maintainability by applying DRY and YAGNI principles.
* Add viewer HTML for claude-mem with live stream and settings interface
- Implemented a responsive layout with left and right columns for observations and settings.
- Added status indicators for connection state.
- Integrated server-sent events (SSE) for real-time updates on observations and summaries.
- Created dynamic project filter dropdown based on available observations.
- Developed settings section for environment variables and worker stats.
- Included functionality to save settings and load current stats from the server.
- Enhanced UI with custom styles for better user experience.
* Remove draft implementation plan for v5.1 web UI
* feat: Implement viewer UI with sidebar, feed, and settings management
- Add main viewer template (HTML) with styling for dark mode.
- Create App component to manage state and render Header, Feed, and Sidebar.
- Implement Feed component to display observations and summaries with filtering.
- Develop Header component for project selection and connection status.
- Create ObservationCard and SummaryCard components for displaying individual items.
- Implement Sidebar for settings management and displaying worker/database stats.
- Add hooks for managing SSE connections, settings, and stats fetching.
- Define types for observations, summaries, settings, and stats.
* Enhance UI components and improve layout
- Updated padding and layout for the feed and card components in viewer.html, viewer-template.html, and viewer.html to improve visual spacing and alignment.
- Increased card margins and padding for better readability and aesthetics.
- Adjusted font sizes, weights, and line heights for card titles and subtitles to enhance text clarity and hierarchy.
- Added a new feed-content class to center the feed items and limit their maximum width.
- Modified the Header component to improve the settings icon's SVG structure for better rendering.
- Enhanced the Sidebar component by adding a close button with an SVG icon, improving user experience for closing settings.
- Updated the Sidebar component's props to include an onClose function for handling sidebar closure.
* feat: Add user prompts feature with UI integration
- Implemented a new method in SessionStore to retrieve recent user prompts.
- Updated WorkerService to fetch and broadcast user prompts to clients.
- Enhanced the Feed component to display user prompts alongside observations and summaries.
- Created a new PromptCard component for rendering individual user prompts.
- Modified useSSE hook to handle new prompt events and processing status.
- Updated viewer templates and styles to accommodate the new prompts feature.
* feat: Add project filtering and pagination for observations
- Implemented `getAllProjects` method in `SessionStore` to retrieve unique projects from the database.
- Added `/api/observations` endpoint in `WorkerService` for paginated observations fetching.
- Enhanced `App` component to manage paginated observations and integrate with the new API.
- Updated `Feed` component to support infinite scrolling and loading more observations.
- Modified `Header` to display processing status.
- Refactored `PromptCard` to remove unnecessary processing indicator.
- Introduced `usePagination` hook to handle pagination logic for observations.
- Updated `useSSE` hook to include projects in the state.
- Adjusted types to accommodate new project data.
* Refactor viewer build process and remove deprecated HTML template
- Updated build-viewer.js to copy HTML template to build output with improved logging.
- Removed src/ui/viewer.html as it is no longer needed.
- Enhanced App component to merge observations while removing duplicates using useMemo.
- Improved Feed component to utilize a ref for onLoadMore callback and adjusted infinite scroll logic.
- Updated Sidebar component to use default settings from constants and removed redundant formatting functions.
- Refactored usePagination hook to streamline loading logic and prevent concurrent requests.
- Updated useSSE hook to use centralized API endpoints and improved reconnection logic.
- Refactored useSettings and useStats hooks to utilize constants for API endpoints and timing.
- Introduced ErrorBoundary component for better error handling in the viewer.
- Centralized API endpoint paths, default settings, timing constants, and UI-related constants into dedicated files.
- Added utility functions for formatting uptime and bytes for consistent display across components.
* feat: Enhance session management and pagination for user prompts, summaries, and observations
- Added project field to user prompts in the database and API responses.
- Implemented new API endpoints for fetching summaries and prompts with pagination.
- Updated WorkerService to handle new endpoints and filter results by project.
- Modified App component to manage paginated data for prompts and summaries.
- Refactored Feed component to remove unnecessary filtering and handle combined data.
- Improved usePagination hook to support multiple data types and project filtering.
- Adjusted useSSE hook to only load projects initially, with data fetched via pagination.
- Updated types to include project information for user prompts.
* feat: add SummarySkeleton component and data utility for merging items
- Introduced SummarySkeleton component for displaying loading state in the UI.
- Implemented mergeAndDeduplicateByProject utility function to merge real-time and paginated data while removing duplicates based on project filtering.
* Enhance UI and functionality of the viewer component
- Updated sidebar transition effects to use translate3d for improved performance.
- Added a sidebar header with title and connection status indicators.
- Modified the PromptCard to display project name instead of prompt number.
- Introduced a GitHub and X (Twitter) link in the header for easy access.
- Improved styling for setting descriptions and card hover effects.
- Enhanced Sidebar component to include connection status and updated layout.
* fix: reduce timeout for worker health checks and ensure proper responsiveness
- Updated new-hook.js, save-hook.js, and summary-hook.js to enhance logging and session handling.
- Simplified session auto-creation logic in worker-service.ts to prioritize observation data preservation.
- Added a blocking wait in ensureWorkerRunning function to prevent race conditions during worker startup.
- Improved error handling and logging consistency across hooks.
- Refactored logging functionality in summary-hook.js to improve clarity and consistency.
- Added checks in worker-utils.ts to prevent unnecessary restarts of the worker service, ensuring it only starts if not already running.
- Updated `save-hook.js`, `summary-hook.js`, `context-hook.ts`, `new-hook.ts`, and `save-hook.ts` to include a call to `ensureWorkerRunning()` at the beginning of their main functions. This ensures that the worker is active before any operations are performed.
- Cleaned up import statements in the affected files to include the new utility function from `worker-utils.js`.
- Minor adjustments to logging and error handling to improve robustness and clarity.
- Removed ensureWorkerRunning calls from multiple hooks (cleanup, context, new, save, summary) to streamline code and avoid unnecessary checks.
- Introduced fixed port usage for worker communication across hooks.
- Enhanced error handling in newHook, saveHook, and summaryHook to provide clearer messages for worker connection issues.
- Updated worker service to start without health checks, relying on PM2 for management.
- Cached Claude executable path to optimize repeated calls.
- Improved logging for better traceability of worker actions and errors.
- Added `getObservationById` method to retrieve observations by ID in SessionStore.
- Introduced `getSessionSummariesByIds` and `getUserPromptsByIds` methods for fetching session summaries and user prompts by IDs.
- Developed `getTimelineAroundTimestamp` and `getTimelineAroundObservation` methods to provide a unified timeline of observations, sessions, and prompts around a specified anchor point.
- Enhanced ChromaSync to format and sync user prompts, including a new `syncUserPrompt` method.
- Updated WorkerService to sync the latest user prompt to Chroma after updating the worker port.
- Created tests for timeline querying and MCP handler logic to ensure functionality.
- Documented the implementation plan for user prompts and timeline context tool in the Chroma search completion plan.
Changes:
- Updated legend to show only observation types (bugfix, feature, refactor, change, discovery, decision)
- Mapped each type to a color dot emoji (🔴 bugfix, 🟢 feature, 🔵 refactor, ⚪ change, 🟡 discovery, 🟤 decision)
- Removed concept-based filtering and icon selection
- Simplified progressive disclosure instructions to reference types instead of concepts
- All observations now shown in timeline (no concept filtering)
Technical details:
- Modified: src/hooks/context-hook.ts:203-207 (legend)
- Modified: src/hooks/context-hook.ts:210-223 (progressive disclosure text)
- Modified: src/hooks/context-hook.ts:344-369 (icon mapping switched from concepts to types)
- Modified: src/hooks/context-hook.ts:168-173 (removed concept filtering)
- Rebuilt: plugin/scripts/context-hook.js
Rationale: Types are mutually exclusive and core to categorization, while concepts are multi-select metadata better accessed through MCP search tools. This simplifies the display and reduces visual noise.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changes:
- Renamed src/hooks/stderr-test-hook.ts to user-message-hook.ts
- Updated user-message-hook with production-ready messaging
- Updated scripts/build-hooks.js to build user-message-hook
- Updated plugin/hooks/hooks.json to reference user-message-hook.js
- Cleaned up old stderr-test-hook.js files
- Built and deployed user-message-hook.js to plugin directory
This hook displays context information to users via stderr, which is
currently the only way to show messages in Claude Code UI. It runs in
parallel with context-hook during SessionStart.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Removed bin/hooks/ wrapper layer
- Moved all hook logic into consolidated hooks/*-hook.ts files
- Each hook now handles its own stdin/stdout/JSON wrapping
- Removed ALL try-catch blocks from context-hook (let errors surface)
- Updated build script to reference new src/hooks/ paths
- Reduced from 12+ files to 6 hook files
This simplifies the architecture and makes debugging actually possible.
- Wrap stdin event handler in try/catch to catch async errors
- Output errors to stdout so Claude can see them
- Show input preview and stack trace for debugging
- Remove outer try/catch that wasn't catching async errors
- Updated logic to retrieve recent summaries and observations, focusing on the last 4 summaries for better context.
- Simplified the extraction of unique session IDs from the recent summaries.
- Enhanced the timeline rendering to include both observations and summaries, grouped by day and file.
- Removed redundant queries for recent summaries and observations, streamlining the data retrieval process.
- Improved output formatting for better readability, including color-coded sections and clearer headers.
- Added detailed display of the most recent session's completed status and next steps.
- Introduced new helper functions for parsing JSON, formatting dates, and estimating token counts.
- Implemented retrieval of recent session IDs and observations from the database.
- Added filtering of observations based on key concepts for a more relevant timeline.
- Enhanced output formatting to include a chronological timeline of recent activities grouped by day and file.
- Included a legend for better understanding of the timeline icons.
- Displayed recent session summaries with improved formatting and details.
- Added footer instructions for accessing records via MCP search.
Critical bugfix for NOT NULL constraint violation.
Problem:
- Worker service calls getSessionById(sessionDbId) to fetch session data
- Worker then uses dbSession.claude_session_id to create ActiveSession
- But getSessionById was NOT selecting claude_session_id from database
- Result: claudeSessionId = undefined in worker
- Caused: "NOT NULL constraint failed: sdk_sessions.claude_session_id" errors
- Impact: Observations and summaries couldn't be stored
Root cause:
- SessionStore.getSessionById() SQL query missing claude_session_id column
- Line 710-713: "SELECT id, sdk_session_id, project, user_prompt"
- Should be: "SELECT id, claude_session_id, sdk_session_id, project, user_prompt"
Fix:
- Added claude_session_id to SELECT query in getSessionById
- Updated return type to include claude_session_id: string
- Now worker correctly receives claude_session_id from database
- Session ID from hook flows properly through entire system
Files changed:
- src/services/sqlite/SessionStore.ts (getSessionById method)
Testing:
- Build succeeded
- Ready for PM2 restart and live testing
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Critical Bugfix:
- Fixed overly defensive observation validation blocking observations from being saved
- Parser now NEVER skips observations - always saves them
- Invalid or missing type defaults to "change" (generic catch-all type)
- Removed validation requiring title, subtitle, and narrative fields
- Prevents critical data loss - partial observations better than no observations
Impact:
- Before: Missing title, subtitle, OR narrative caused entire observation to be discarded
- After: ALL observations preserved regardless of field completeness
- Even partial observations contain valuable data: concepts, files_read, files_modified, facts
- LLMs make mistakes - system must be resilient and save everything
- Consistent with v4.2.5 summary fix
Technical changes:
- Updated src/sdk/parser.ts:52-67 to never skip observations
- Uses "change" as fallback type for invalid/missing types (no schema change)
- Updated ParsedObservation interface to allow null for title, subtitle, narrative
- Updated SessionStore.storeObservation signature to accept nullable fields
- Updated built worker-service.cjs
- Bumped version to 4.2.6 in all metadata files
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Improvements to SessionStart context hook file display:
1. **Remove redundant files**: Files in "Modified" list are now excluded from "Read" list
- Prevents duplication when a file was both read and modified
- Reduces token usage by eliminating redundant information
2. **Use relative paths**: Convert absolute paths to project-relative paths
- Example: /Users/alexnewman/Scripts/claude-mem/src/hooks/context.ts → src/hooks/context.ts
- Significantly reduces token consumption in context injection
- Makes file references more readable and portable
Implementation:
- Added toRelativePath() helper function to convert paths
- Added filesModifiedSet.forEach(file => filesReadSet.delete(file)) to remove duplicates
- Applied to both files_read and files_modified when building Sets
Impact: Reduces token usage in Tier 1 summaries (most recent session) where file lists are displayed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
New structure (10 sessions total):
- Tier 3 (oldest 6): Request + Date only
- Tier 2 (middle 3): Request + Learned + Completed + Date
- Tier 1 (most recent): Full verbosity (all fields)
This provides cleaner, more focused context with less redundancy.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Introduces three-tier verbosity system to reduce redundancy and improve token efficiency:
Tier 1 (Most Recent - Position -1):
- Full verbosity with all fields shown
- Request, Learned, Completed, Next Steps, Files Read, Files Modified, Date
Tier 2 (Recent - Positions -2 to -5):
- Medium verbosity, skips Files Read (less actionable)
- Request, Learned, Completed, Next Steps, Files Modified, Date
Tier 3 (Older - Positions -6 to -30):
- Compact index with just Learned + citation link
- Format: Learned + [Details: claude-mem://session/{id}]
- Enables lazy-loading via MCP search tools
Changes:
- Increased LIMIT from 10 to 30 sessions
- Added position-based formatting logic in loop
- Token reduction: ~30% fewer tokens (~2,150 vs ~3,000)
- History expansion: 3x more sessions (30 vs 10)
Benefits:
- Reduced redundancy through natural information gradient
- More context breadth without token explosion
- MCP search becomes expansion mechanism for deeper dives
- Aligns with core philosophy: compression for efficiency, expansion on demand
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Updated contextHook to query session_summaries directly instead of using sdk_sessions table.
- Removed unnecessary complexity in output formatting, focusing on recent summaries for the project.
- Enhanced file reading and modification tracking by parsing observations directly.
- Made the database connection public in SessionStore for easier access.
- Added functionality to automatically create a session record in the database if it does not exist when storing observations or session summaries.
- Updated `storeObservation` and `storeSummary` methods to include checks for existing session records and insert new records as needed.
- Added logging for auto-created session records for better traceability.
- Added functionality to save raw user prompts for full-text search in the newHook function.
- Introduced new search endpoint 'search_user_prompts' to retrieve user prompts using FTS5.
- Created UserPromptRow and UserPromptSearchResult types for handling user prompt data.
- Implemented searchUserPrompts method in SessionSearch class to perform FTS5 queries.
- Created user_prompts table with FTS5 support and necessary triggers for data synchronization.
- Updated SessionStore to include methods for saving user prompts and managing the new table.
Root cause: Hooks provide session_id as the source of truth. We were adding
unnecessary validation (checking if sessions exist, checking status, etc.)
which caused 409 conflicts when continuing sessions after /exit.
Changes:
1. worker-service.ts: Removed 409 "Session already exists" check in handleInit
2. SessionStore.ts: Made createSDKSession idempotent using INSERT OR IGNORE
3. new-hook.ts: Simplified to just call createSDKSession - no findActiveSDKSession,
no reactivateSession logic, no status management
4. save-hook.ts: Removed session validation, use fixed port instead of session.worker_port
5. summary-hook.ts: Removed session validation, use fixed port instead of session.worker_port
Philosophy: Hooks manage lifecycle, we just save data with whatever session_id
they give us. No validation, no status checks, no guessing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changed summary prompts to generate discrete per-request summaries instead of cumulative session summaries. This provides better chronological memory where each summary is a clean unit representing one request/response cycle.
Changes:
- Renamed buildFinalizePrompt() to buildSummaryPrompt() in src/sdk/prompts.ts
- Updated prompt text to focus on "THIS REQUEST" rather than "this session"
- Updated all import and function call sites in worker-service.ts and worker.ts
- Added IMPORTANT warning to emphasize request-level scope
Expected behavior: Each summary will now describe only what happened during that specific request, eliminating cumulative recaps.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Updated contextHook to support colorized output for terminal and JSON format for hooks.
- Introduced ANSI color codes for improved readability in terminal output.
- Modified the output structure to include session details with color formatting.
- Added a new method in SessionStore to aggregate files read and modified from observations for a session.
- Improved error handling for JSON parsing of file data in the new method.
Alex Newman