- Created comprehensive installation guide detailing quick start, system requirements, and advanced installation steps.
- Developed troubleshooting guide addressing common issues with worker service, hooks, database, and search tools.
- Introduced getting started documentation explaining automatic operation, session summaries, and context injection.
- Added detailed usage instructions for MCP search tools, including query examples and advanced filtering techniques.
- Changed the title of the summary prompt to "THIS REQUEST'S SUMMARY" for better context.
- Revised instructions to focus on summarizing what was built/fixed/deployed/configured, rather than the observation process.
- Clarified when not to summarize, emphasizing conversational requests and trivial inquiries.
- Updated examples to better illustrate good summary practices.
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>
Added "WHEN NOT TO SUMMARIZE" section to buildSummaryPrompt that instructs the SDK to skip creating summaries for:
- Work already covered in previous prompts (prevents duplicates)
- Conversational banter with no deliverables
- Trivial requests (questions, status checks)
- Meta-discussions about memory system without shipped changes
Implementation:
- src/sdk/prompts.ts: Added WHEN NOT TO SUMMARIZE section with <skip_summary> output format
- src/sdk/parser.ts: Added skip_summary detection before parsing full summary XML
- src/sdk/parser.ts: Fixed observation type validation to include all 6 types (bugfix, feature, refactor, change, discovery, decision)
This should eliminate the duplicate summaries like the three "restore 6 types" summaries we saw for session d9137878.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Patch release confirming the effectiveness of prompt engineering changes that prevent meta-referential observations.
Key Improvements (from v4.2.0 prompt work):
- Observations now focus on deliverables shipped, not memory system operations
- Clear distinction between "what was built" vs "what the memory tool processed"
- Contrastive examples prevent pollution like "Processed tool executions"
- Smart handling of edge cases when working ON the memory system itself
Evidence:
Recent context shows progression from meta-referential garbage (10/21 10:48 PM) to excellent deliverable-focused observations (10/21 11:46 PM).
No code changes in this release - just version bump to mark the successful prompt improvements as stable.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Restored full type system: bugfix, feature, refactor, change, discovery, decision.
This enables more precise search queries like "show all bugfixes in auth" vs generic "show all changes".
Also updated README to reflect current behavior (10 summaries with three-tier verbosity).
Changes:
- prompts.ts: Expanded type field from 3 to 6 types with clear definitions
- CLAUDE.md: Fixed context hook description (3 → 10 summaries)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated SDK prompts to distinguish between deliverables (what was built/shipped) vs meta-operations (what the memory system is doing). This prevents self-referential pollution like "Process tool executions" instead of actual coding tasks like "Fix authentication bug".
Changes:
- buildInitPrompt: Added deliverable-focused framing with contrastive examples
- buildSummaryPrompt: Injected user's original prompt + explicit examples
- Added verb guidance (implemented/fixed/deployed vs analyzed/tracked/stored)
- Added "NOW DOES" present-tense capability framing
Works across all project types: dev, DevOps, docs, infrastructure, research, config.
🤖 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 `claudeSessionId` to the `ActiveSession` interface to store the real Claude Code session ID.
- Updated session initialization to fetch the real Claude Code session ID from the database.
- Modified session creation logic to ensure the real session ID is used consistently throughout the worker service.
- Adjusted message generation to utilize the real session ID instead of a placeholder.
- 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.
This plan addresses the gap where claude-mem captures tool executions but
not the user's actual requests/instructions. By storing raw prompts in a
dedicated table with FTS5 search, we can:
- See what the user actually said (not just what Claude did)
- Identify patterns where Claude didn't listen
- Search across time for repeated user requests
- Reconstruct full conversation context
Plan includes:
- Database schema (user_prompts table + FTS5)
- Code changes (SessionStore, SessionSearch, new-hook, MCP server)
- Testing strategy
- Open questions about implementation details
Ready for implementation in fresh context.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The worker was still returning 404 "Session not found" when trying to add
observations or summaries. This happened if:
- Worker restarted (sessions lost from memory)
- Race condition where observations arrive before /init
- Session continued after /exit
Changes:
- handleObservation: Auto-create session if not in memory map
- handleSummarize: Auto-create session if not in memory map
This completes the "no validation" philosophy: worker accepts any session_id
and auto-creates the session state if needed. Saves ALL data without blockage.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
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>
Version bump to 4.1.1 with critical bug fixes and API simplification.
Removed:
- Redundant advanced_search MCP tool (no unique functionality)
- advancedSearch method from SessionSearch class
Fixed:
- findByConcept, findByType, findByFile now respect limit/offset
- Parser validation prevents observation types in concepts array
- Added token limit warnings to tool descriptions
Changed:
- Simplified MCP API from 7 to 6 tools
- Enhanced SDK prompts to prevent AI data contamination
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Deleted the advanced_search tool from the search-server.ts file, which combined full-text search with structured filters for observations and sessions.
- Removed the advancedSearch method from the SessionSearch class, which handled the logic for performing advanced searches using FTS5 and structured filters.
- Filter out observation type from concepts array in parseObservations function to ensure types and concepts are treated as separate dimensions. Added logging for removed types.
- Update prompts documentation to clarify that the observation type must not be included in the concepts array.
- Modify search-server to provide clearer guidance on result limits, emphasizing starting with smaller limits to avoid exceeding token limits.
- Refactor SessionSearch methods to accept options for limit, offset, and orderBy parameters, improving flexibility in querying observations by concept and type.
- Updated the formatSearchTips function to emphasize the importance of using index format first for token efficiency.
- Revised descriptions for various search tools to include reminders about starting with index format and using full format only for specific items of interest.
- Clarified output format descriptions to recommend index format for initial searches.
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