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

feat: Update CLAUDE.md files with recent test activities and improvements

Browse Source 
- Added detailed entries for test activities across various modules including `export-types.test.ts`, `server.test.ts`, `smart-install.test.ts`, and others.
- Documented significant changes in test coverage, cleanup efforts, and regression tests.
- Enhanced the `plans` documentation with recent implementation strategies and PR follow-ups.
- Introduced a comprehensive report on Windows platform challenges and solutions, detailing issues like zombie ports, console popups, and process management.
- Established a new `ProcessManager` architecture to address Windows-specific issues and improve reliability.
- Updated integration tests to reflect recent changes and ensure comprehensive coverage.
This commit is contained in:
Alex Newman
2026-01-07 16:53:02 -05:00
parent 0da504735b
commit a3d6bfc7dd
55 changed files with 3837 additions and 1167 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/context/CLAUDE.md
+7 -1
View File
@@ -13,7 +13,6 @@
| #34425 | 2:04 PM | 🔵 | Agent SDK V2 API Documentation and Migration Patterns | ~698 |
| #34422 | 2:03 PM | ✅ | Added Agent SDK V2 Documentation Files | ~240 |
| #34419 | 2:02 PM | ✅ | Committed Agent SDK V2 upgrade preparation | ~275 |
| #34394 | 1:52 PM | 🔵 | Agent SDK V2 Documentation Shows session.close() Method for Cleanup | ~417 |
**agent-sdk-v2-example.ts**
| ID | Time | T | Title | Read |
@@ -104,4 +103,11 @@
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #35703 | 1:01 PM | ⚖️ | Try-Catch as Anti-Pattern: Root Cause Analysis and Documentation | ~363 |
### Jan 6, 2026
**windows-code-evaluation.md**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38104 | 12:14 AM | 🔵 | Windows Compatibility Issues Documented Across 56 Memory Entries | ~509 |
</claude-mem-context>
docs/public/CLAUDE.md
+150 -61
View File
@@ -93,76 +93,165 @@ npx mintlify dev
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
### Nov 18, 2025
### Dec 28, 2025
**platform-integration.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #11206 | 3:01 PM | 🔵 | mem-search skill architecture and migration details retrieved in full format | ~538 |
### Nov 21, 2025
| #33540 | 10:55 PM | 🔵 | Grep search found mem-search references in internationalized documentation | ~577 |
| #33522 | 10:46 PM | 🔵 | Platform integration documentation describes Worker API architecture | ~351 |
**docs.json**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #13221 | 2:01 AM | 🔴 | Fixed broken markdown link to Viewer UI documentation | ~316 |
| #13220 | 2:00 AM | 🔴 | Escaped HTML less-than symbol in universal architecture timeout documentation | ~316 |
| #13216 | 1:54 AM | ✅ | Universal Architecture Added to Navigation | ~330 |
| #13215 | " | 🟣 | Universal AI Memory Architecture Documentation Created | ~732 |
| #13213 | 1:50 AM | 🔵 | Introduction Page Content and Recent v6.0.0 Release | ~495 |
| #13212 | " | 🔵 | Architecture Evolution Documentation Structure | ~408 |
| #13211 | " | 🔵 | Mintlify Documentation Site Configuration | ~430 |
| #13209 | 1:48 AM | 🔵 | Public Documentation Structure and Guidelines | ~383 |
### Nov 25, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #14994 | 2:22 PM | ✅ | Version Channel Section Added to Configuration Documentation | ~301 |
| #14993 | " | ✅ | Beta Features Added to Documentation Navigation | ~188 |
| #14992 | 2:21 PM | 🟣 | Beta Features Documentation Page Created | ~488 |
| #14991 | " | 🔵 | Mintlify Navigation Structure and Documentation Groups | ~394 |
| #14989 | " | 🔵 | Installation Documentation with Quick Start and Verification Steps | ~383 |
| #14988 | " | 🔵 | Configuration Documentation Structure and Environment Variables | ~338 |
### Nov 26, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #16190 | 10:22 PM | 🔵 | RAGTIME Search Retrieved Five Observations About Claude-Mem vs RAG Architecture | ~637 |
### Dec 3, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #19884 | 9:42 PM | 🔵 | Configuration system and environment variables | ~701 |
| #19878 | 9:40 PM | 🔵 | Installation process and system architecture | ~486 |
### Dec 8, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #22335 | 10:26 PM | 🔵 | Mintlify documentation configuration analyzed | ~534 |
| #22311 | 9:47 PM | 🔵 | Comprehensive Hooks Architecture Documentation Review | ~263 |
| #22297 | 9:43 PM | 🔵 | Mintlify Documentation Framework Configuration | ~446 |
| #22294 | " | 🔵 | Documentation Site Structure Located | ~359 |
### Dec 9, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #23179 | 10:44 PM | ✅ | Removed explanatory reasons from tool exclusion documentation | ~297 |
### Dec 15, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #27038 | 6:02 PM | 🔵 | 95% token reduction claims found only in private experimental documents, not in main public docs | ~513 |
| #27037 | " | 🔵 | Branch switching functionality exists in SettingsRoutes with UI switcher removal intent | ~463 |
| #26986 | 5:24 PM | ✅ | Updated Endless Mode latency warning in beta features documentation | ~299 |
| #33312 | 3:09 PM | ✅ | OpenRouter Provider Documentation | ~497 |
### Dec 29, 2025
**docs.json**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33938 | 6:27 PM | 🔵 | Relevant CLAUDE.md Context Identified for PR #492 | ~435 |
| #33750 | 12:25 AM | ✅ | Documentation Update: Removed Version Number from Architecture Evolution | ~281 |
| #34321 | 11:03 PM | 🔵 | Mintlify Navigation Configuration Defines Expected File Paths | ~330 |
| #34215 | 10:08 PM | 🔵 | Retrieved Detailed Cursor Integration Implementation History | ~676 |
| #34148 | 9:28 PM | 🟣 | Cursor IDE Integration with Cross-Platform Hooks and Documentation | ~514 |
| #34112 | 9:07 PM | 🟣 | Committed Cursor Public Documentation to Repository | ~427 |
| #34108 | 9:06 PM | 🟣 | Added Cursor Integration Section to Documentation Navigation | ~441 |
| #34101 | 9:04 PM | 🔵 | Documentation Navigation Configuration Using Mintlify | ~445 |
**public**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34318 | 11:03 PM | 🔵 | Mintlify Documentation Files and Configuration Located | ~294 |
**installation.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34102 | 9:04 PM | 🔵 | Current Installation Documentation Targets Claude Code Plugin Users | ~485 |
**progressive-disclosure.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33773 | 12:38 AM | ✅ | Replaced two-tier with three-layer workflow documentation | ~431 |
| #33772 | " | ✅ | Updated progressive disclosure docs with 3-layer MCP workflow | ~399 |
| #33771 | 12:37 AM | 🔵 | Progressive disclosure design rationale documented | ~508 |
| #33770 | " | 🔵 | Progressive disclosure documentation reviewed | ~479 |
| #33715 | 12:18 AM | ✅ | Future enhancements section updated for current API structure | ~308 |
| #33712 | " | ✅ | Progressive disclosure docs updated to reflect 3-layer workflow | ~363 |
| #33702 | 12:09 AM | ⚖️ | Documentation Update Strategy Finalized for MCP Architecture Transition | ~845 |
| #33696 | 12:07 AM | 🔵 | Progressive Disclosure Philosophy Requires Tool Name Updates | ~687 |
| #33685 | 12:04 AM | 🔵 | Progressive Disclosure Philosophy Document References Deprecated Tools | ~543 |
**architecture-evolution.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33763 | 12:27 AM | ✅ | Pull request #480 created for MCP architecture documentation updates | ~423 |
| #33760 | 12:26 AM | ✅ | Major documentation overhaul across 6 files with 908 additions | ~367 |
| #33749 | 12:25 AM | ✅ | Documentation Version Reference Removed | ~282 |
| #33747 | " | ✅ | Removed specific version reference from MCP architecture section | ~279 |
| #33745 | " | ✅ | Documentation Version Reference Simplified | ~224 |
| #33744 | " | ✅ | Removed fabricated version number from architecture documentation | ~319 |
| #33726 | 12:20 AM | 🟣 | v6.5.0 architecture evolution documentation added | ~599 |
| #33700 | 12:08 AM | 🔵 | Architecture Evolution Document Contains Historical MCP Tool References | ~625 |
**troubleshooting.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33722 | 12:19 AM | ✅ | Token limit troubleshooting completely rewritten for 3-layer workflow | ~426 |
| #33720 | " | ✅ | Troubleshooting search query examples updated to current API | ~329 |
| #33717 | " | 🔵 | Troubleshooting docs contain outdated search_observations references | ~333 |
| #33693 | 12:06 AM | 🔵 | Troubleshooting Documentation Contains Deprecated Search Tool Syntax | ~576 |
**introduction.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33687 | 12:05 AM | 🔵 | Introduction Documentation References mem-search Skill | ~426 |
### Dec 31, 2025
**troubleshooting.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34688 | 3:40 PM | 🔵 | Worker Logs Command Usage Across Codebase | ~320 |
### Jan 1, 2026
**context-engineering.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #35459 | 8:57 PM | 🔵 | Existing Coding Standards and Anti-Pattern References in Codebase | ~600 |
### Jan 2, 2026
**architecture-evolution.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #36096 | 10:23 PM | 🔵 | Observation API Function Names Located | ~227 |
### Jan 3, 2026
**architecture-evolution.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #36353 | 8:42 PM | 🔵 | Multiple observation table definitions found across codebase | ~280 |
### Jan 4, 2026
**hooks-architecture.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #36941 | 2:43 AM | 🔵 | Context Injection Header Format | ~220 |
### Jan 5, 2026
**CLAUDE.md**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38082 | 10:13 PM | ✅ | Merge Conflict Resolution - Kept Feature Branch Versions | ~431 |
**progressive-disclosure.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38069 | 9:51 PM | 🔵 | Progressive Disclosure Philosophy Documentation | ~546 |
**docs.json**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38066 | 9:50 PM | ✅ | v9.0 Documentation Audit Completed with 14 Files Updated | ~547 |
| #38064 | " | ⚖️ | 9.0 Release Documentation Audit Complete - Major Gaps Identified | ~997 |
| #38035 | 9:42 PM | 🔵 | Documentation Navigation Structure for 9.0 Release | ~422 |
**modes.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38060 | 9:49 PM | 🔵 | Modes System Documentation for Workflow and Language Configuration | ~514 |
**configuration.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38054 | 9:47 PM | 🔵 | Configuration Documentation Review - Missing Live Context Settings | ~530 |
**platform-integration.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38052 | 9:46 PM | 🔵 | Platform Integration Documentation Review | ~525 |
**hooks-architecture.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38045 | 9:45 PM | 🔵 | Hooks Architecture Documentation Review | ~520 |
**introduction.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38044 | 9:44 PM | 🔵 | Introduction Documentation Review for 9.0 Release | ~462 |
**context-engineering.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38043 | 9:44 PM | 🔵 | Context Engineering Documentation Review | ~455 |
**troubleshooting.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #37548 | 4:48 PM | ✅ | Issue #543 Analysis Report Created for Slash Command Availability | ~540 |
</claude-mem-context>
docs/public/architecture/CLAUDE.md
+130 -11
View File
@@ -3,28 +3,147 @@
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
### Nov 18, 2025
### Dec 16, 2025
**worker-service.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #11206 | 3:01 PM | 🔵 | mem-search skill architecture and migration details retrieved in full format | ~538 |
### Nov 21, 2025
| #28299 | 9:57 PM | ✅ | Documentation Updated for Renamed MCP Tools | ~305 |
| #28293 | 9:56 PM | 🔵 | get_batch_observations Usage Across Codebase | ~226 |
| #28292 | " | 🔵 | get_batch_observations Referenced in 4 Files | ~246 |
| #28242 | 9:38 PM | 🔵 | Progressive Description and Batch Observations Usage Sites | ~241 |
**search-architecture.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #13218 | 1:58 AM | 🔴 | Escaped HTML special character in MDX documentation | ~261 |
### Dec 3, 2025
| #28074 | 8:09 PM | 🔵 | Progressive Disclosure Pattern and Search Implementation | ~558 |
| #28067 | " | 🔵 | Progressive Disclosure and Security Architecture | ~528 |
| #28066 | 8:08 PM | 🔵 | Search Architecture Evolution from MCP to Skill-Based | ~530 |
| #28058 | " | 🔵 | Search Architecture Evolution from MCP Tools to Skill-Based HTTP API | ~528 |
**pm2-to-bun-migration.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #19891 | 9:43 PM | 🔵 | Seven hook scripts across five lifecycle events | ~713 |
| #27716 | 5:41 PM | ✅ | Better-sqlite3 References Removed from Codebase | ~319 |
| #27715 | " | 🔵 | Git Branch Already Created | ~208 |
| #27712 | 5:40 PM | 🟣 | Merged PR #332: API-Based Import/Export Architecture | ~372 |
| #27699 | 5:37 PM | 🔵 | Comprehensive PM2 to Bun migration documentation exists | ~360 |
| #27696 | 5:36 PM | 🔵 | Documentation already reflects better-sqlite3 to bun:sqlite migration | ~390 |
| #27695 | " | 🔵 | Better-sqlite3 references found in documentation | ~201 |
| #27687 | 5:32 PM | 🔴 | Corrected Migration Date in PM2 to Bun Documentation | ~270 |
| #27656 | 5:24 PM | ⚖️ | PM2 to Bun Documentation Migration Plan Created | ~551 |
| #27655 | " | 🟣 | PM2 to Bun Documentation Migration Plan Created | ~455 |
| #27654 | 5:22 PM | 🔵 | Complete PM2 Documentation Audit | ~458 |
### Dec 15, 2025
### Dec 17, 2025
**pm2-to-bun-migration.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #27040 | 6:03 PM | 🔵 | Comprehensive search confirms no 95% claims exist in main branch public documentation | ~508 |
| #27037 | 6:02 PM | 🔵 | Branch switching functionality exists in SettingsRoutes with UI switcher removal intent | ~463 |
| #28930 | 7:30 PM | 🔵 | Worker CLI Distribution and Build System | ~275 |
**worker-service.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #28929 | 7:30 PM | 🔵 | ProcessManager Usage Across Codebase | ~319 |
### Dec 18, 2025
**database.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #29815 | 7:33 PM | 🔵 | Database contains multiple session table schemas | ~311 |
### Dec 20, 2025
**worker-service.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #30675 | 5:08 PM | 🔵 | Platform Documentation Across 18 Files | ~335 |
**overview.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #30253 | 3:17 PM | 🔵 | Agent SDK Integration Throughout Codebase | ~402 |
### Dec 24, 2025
**hooks.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #32193 | 7:42 PM | 🔵 | Session completion endpoint usage across codebase | ~278 |
### Dec 25, 2025
**worker-service.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #32654 | 8:51 PM | 🔵 | Identified multiple files related to queue recovery | ~375 |
| #32456 | 5:41 PM | ✅ | Completed merge of main branch into feature/titans-phase1-3 | ~354 |
| #32432 | 3:41 PM | 🟣 | Manual Queue Recovery System with CLI and API | ~531 |
| #32425 | 3:26 PM | ✅ | API Documentation for Manual Recovery Endpoints Added | ~563 |
### Dec 27, 2025
**hooks.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33101 | 7:11 PM | 🔵 | Context Injection API Endpoint Usage Across Hooks | ~358 |
### Dec 28, 2025
**search-architecture.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33540 | 10:55 PM | 🔵 | Grep search found mem-search references in internationalized documentation | ~577 |
### Dec 29, 2025
**search-architecture.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33769 | 12:37 AM | ✅ | Documentation updated for MCP-based search architecture | ~528 |
| #33767 | 12:34 AM | ✅ | Committed MDX Syntax Fix to updates/docs Branch | ~301 |
| #33766 | " | 🔴 | Fixed MDX Syntax Error in Performance Section | ~293 |
| #33765 | 12:33 AM | 🔵 | Search Architecture Documentation Structure Analysis | ~524 |
| #33763 | 12:27 AM | ✅ | Pull request #480 created for MCP architecture documentation updates | ~423 |
| #33762 | " | ✅ | Architecture shift from skill-based to MCP-based search with 3-layer workflow | ~418 |
| #33760 | 12:26 AM | ✅ | Major documentation overhaul across 6 files with 908 additions | ~367 |
| #33756 | 12:25 AM | ✅ | Documentation Version Reference Removed from Search Architecture | ~257 |
| #33754 | " | ✅ | Removed fabricated version range from skill-based approach comparison | ~318 |
| #33753 | " | ✅ | Documentation Version Number Removed from Architecture Evolution Section | ~233 |
| #33751 | " | 🔵 | Architecture Evolution Documentation Records v6.5.0 Migration | ~227 |
| #33702 | 12:09 AM | ⚖️ | Documentation Update Strategy Finalized for MCP Architecture Transition | ~845 |
| #33698 | 12:07 AM | 🔵 | Search Architecture Documentation Comprehensively Describes Deleted Skill System | ~663 |
| #33680 | 12:03 AM | 🔵 | Search Architecture Documentation Describes Deleted Skill System | ~576 |
### Dec 31, 2025
**pm2-to-bun-migration.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34688 | 3:40 PM | 🔵 | Worker Logs Command Usage Across Codebase | ~320 |
### Jan 2, 2026
**database.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #36096 | 10:23 PM | 🔵 | Observation API Function Names Located | ~227 |
### Jan 3, 2026
**database.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #36353 | 8:42 PM | 🔵 | Multiple observation table definitions found across codebase | ~280 |
### Jan 5, 2026
**overview.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38066 | 9:50 PM | ✅ | v9.0 Documentation Audit Completed with 14 Files Updated | ~547 |
| #38064 | " | ⚖️ | 9.0 Release Documentation Audit Complete - Major Gaps Identified | ~997 |
| #38059 | 9:49 PM | 🔵 | Architecture Overview Documentation Review | ~554 |
</claude-mem-context>
docs/public/usage/CLAUDE.md
+116 -32
View File
@@ -3,45 +3,129 @@
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
### Nov 18, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #11206 | 3:01 PM | 🔵 | mem-search skill architecture and migration details retrieved in full format | ~538 |
### Dec 3, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #19892 | 9:43 PM | 🔵 | Automatic operation workflow and progressive disclosure strategy | ~780 |
### Dec 10, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #23677 | 8:37 PM | ✅ | Update Export Documentation to Reflect Hybrid Search and Project Filter | ~314 |
| #23675 | " | 🔵 | Export/Import Memory Scripts Documentation | ~399 |
| #23590 | 5:51 PM | 🔵 | Import/Export Feature Status Review | ~490 |
| #23584 | 5:50 PM | 🔵 | Export/Import Documentation | ~405 |
### Dec 14, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #26335 | 9:02 PM | 🔵 | Citation URI Scheme Documentation | ~255 |
### Dec 25, 2025
**gemini-provider.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #32536 | 7:28 PM | ✅ | Updated Gemini provider warning about free tier rate limits | ~185 |
| #32535 | " | ✅ | Updated Gemini provider tip to recommend enabling billing | ~179 |
| #32534 | 7:27 PM | ✅ | Updated Gemini provider warning about rate limits | ~174 |
| #32533 | " | ✅ | Updated Gemini provider documentation with rate limit information | ~216 |
| #32789 | 9:49 PM | 🟣 | Gemini AI Provider Integration Merged to Main | ~409 |
**manual-recovery.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #32654 | 8:51 PM | 🔵 | Identified multiple files related to queue recovery | ~375 |
### Dec 26, 2025
**openrouter-provider.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #32925 | 10:26 PM | 🔵 | OpenRouter Provider Integration Proposed in PR 448 | ~543 |
| #32924 | 10:21 PM | 🟣 | OpenRouter Provider Documentation | ~501 |
### Dec 28, 2025
**claude-desktop.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33651 | 11:44 PM | 🔴 | Migration 17 Wrapped in Transaction with Documentation Updates | ~331 |
| #33650 | 11:43 PM | 🔵 | Code Changes Ready for Token Optimizations PR | ~292 |
| #33648 | " | ✅ | Documentation Installation Steps Renumbered | ~283 |
| #33647 | 11:42 PM | ✅ | Removed Skill Installation Steps from Claude Desktop Documentation | ~347 |
| #33646 | " | ✅ | Updated Documentation to Reflect Streamlined 3-Tool MCP Architecture | ~391 |
| #33643 | 11:41 PM | 🔵 | Documentation Uses Inconsistent Naming for MCP Server | ~403 |
| #33639 | " | 🔵 | Pull Request Review Identified Critical Migration Risk | ~457 |
| #33638 | 11:40 PM | 🔵 | Pull Request Review Identified Critical Migration Risk and Token Optimization Success | ~415 |
| #33636 | 11:35 PM | ✅ | Major Documentation and Code Cleanup Removed 4,929 Lines | ~381 |
| #33598 | 11:15 PM | 🔵 | Filtered MCP search query successfully returning rename history with type constraints | ~386 |
| #33597 | 11:14 PM | 🔵 | MCP search tool successfully retrieving mem-search to mcp-search rename history | ~361 |
| #33539 | 10:54 PM | ✅ | Updated configuration examples to use mcp-search as MCP server key | ~449 |
| #33538 | " | ✅ | Updated Step 3 installation instructions to reference mcp-search MCP server | ~250 |
| #33537 | " | ✅ | Updated prerequisites documentation to reference mcp-search MCP server | ~266 |
| #33536 | 10:53 PM | 🔵 | Identified documentation file requiring MCP server name update | ~451 |
| #33526 | 10:47 PM | 🔵 | Claude Desktop skill installation guide references mem-search server and skill | ~388 |
**search-tools.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33540 | 10:55 PM | 🔵 | Grep search found mem-search references in internationalized documentation | ~577 |
**openrouter-provider.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33312 | 3:09 PM | ✅ | OpenRouter Provider Documentation | ~497 |
### Dec 29, 2025
**gemini-provider.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34335 | 11:06 PM | 🟣 | Mintlify Documentation Linting Successfully Completed | ~409 |
| #34333 | 11:05 PM | 🔴 | Fixed Broken Links in usage/gemini-provider.mdx | ~285 |
| #34328 | 11:04 PM | 🔵 | Broken Link in Usage Gemini Provider Documentation | ~330 |
| #34320 | 11:03 PM | 🔵 | Mintlify Broken Links Detected in Documentation | ~292 |
| #34103 | 9:05 PM | 🔵 | Gemini Provider Documentation Covers Free Tier and Configuration | ~480 |
**openrouter-provider.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34334 | 11:05 PM | 🔴 | Fixed All Broken Links in usage/openrouter-provider.mdx | ~339 |
| #34327 | 11:04 PM | 🔵 | Broken Links in Usage OpenRouter Provider Documentation | ~337 |
**usage**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34323 | 11:03 PM | 🔵 | Usage Directory Files Confirmed to Exist | ~280 |
**search-tools.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33763 | 12:27 AM | ✅ | Pull request #480 created for MCP architecture documentation updates | ~423 |
| #33760 | 12:26 AM | ✅ | Major documentation overhaul across 6 files with 908 additions | ~367 |
| #33702 | 12:09 AM | ⚖️ | Documentation Update Strategy Finalized for MCP Architecture Transition | ~845 |
| #33694 | 12:06 AM | 🔵 | Search Tools Documentation Describes Deleted Skill Architecture | ~615 |
| #33679 | 12:03 AM | 🔵 | Search Tools Documentation Structure and Skill-Based Architecture | ~473 |
**claude-desktop.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33703 | 12:10 AM | 🔵 | Final Documentation Review Confirms Update Requirements | ~756 |
| #33699 | 12:08 AM | ✅ | Claude Desktop Documentation Successfully Updated for MCP Tools | ~583 |
| #33689 | 12:05 AM | 🔴 | Migration 17 Transaction Safety and Documentation Updates | ~436 |
| #33681 | 12:03 AM | ✅ | Claude Desktop Documentation Updated for MCP Tools Workflow | ~491 |
| #33675 | 12:02 AM | 🔄 | Major Documentation and Code Cleanup in MCP Clarity Branch | ~491 |
### Jan 4, 2026
**gemini-provider.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #36751 | 12:32 AM | 🔵 | Gemini-Related Files Located Across Project | ~242 |
### Jan 5, 2026
**folder-context.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #37508 | 3:21 PM | 🔵 | Private Tags Documentation Defines User Privacy Control Mechanisms | ~748 |
| #38086 | 10:42 PM | ✅ | Merged PR with comprehensive CLAUDE.md documentation system | ~478 |
| #38066 | 9:50 PM | ✅ | v9.0 Documentation Audit Completed with 14 Files Updated | ~547 |
| #38064 | " | ⚖️ | 9.0 Release Documentation Audit Complete - Major Gaps Identified | ~997 |
| #38053 | 9:47 PM | 🔵 | Folder Context Documentation Exists But Marked As Disabled By Default | ~616 |
**getting-started.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38042 | 9:44 PM | 🔵 | Getting Started Documentation Review for Live Context Gap | ~411 |
**claude-desktop.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #37617 | 5:32 PM | ⚖️ | PR #558 Review Requirements Categorized by Priority | ~637 |
| #37561 | 4:50 PM | 🔵 | Claude Desktop mem-search Skill Documentation Confirms Platform-Specific Feature | ~393 |
**private-tags.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #37512 | 3:22 PM | 🔵 | Privacy Tag System Release History and Documentation Evolution | ~749 |
| #37505 | 3:21 PM | 🔵 | Comprehensive Dual-Tag Privacy System Architecture and Implementation Details | ~915 |
</claude-mem-context>
docs/reports/2026-01-06--windows-woes-comprehensive-report.md
+296
View File
@@ -0,0 +1,296 @@
# Windows Woes: Comprehensive Report
**Date:** 2026-01-06
**Coverage:** October 2025 - January 2026
**Memory Sources:** 100+ observations from claude-mem
## Executive Summary
The claude-mem project has faced significant Windows platform challenges, requiring extensive architectural changes and ongoing maintenance. The issues fall into four major categories:
1. **Zombie Port Problem** - Bun's socket cleanup bug on Windows
2. **Console Window Popups** - PowerShell/cmd windows appearing during hook execution
3. **Process Management** - Orphaned processes, cleanup failures, multi-session conflicts
4. **Path & Shell Compatibility** - PowerShell escaping, Git Bash conflicts, PATH detection
## Timeline of Major Issues & Fixes
### Phase 1: Initial Windows Support (Oct-Nov 2025)
| Date | Issue | Fix |
|------|-------|-----|
| Oct 27 | Hardcoded Unix paths | Cross-platform path refactoring |
| Nov 5 | Windows installation failures | Smart caching installer created |
| Nov 6 | PM2 ENOENT bug | Released v5.1.1 with fix |
| Nov 11 | Worker crashes on Windows | Investigation started |
### Phase 2: Worker Reliability Crisis (Dec 2025)
| Date | Issue | Fix | PR/Version |
|------|-------|-----|------------|
| Dec 4 | Console windows appearing | Added `windowsHide` parameter | - |
| Dec 9 | Multiple Windows bugs | Released v7.0.4 | @kat-bell |
| Dec 13 | libuv crash from process.type hack | Removed workaround | v7.1.7 |
| Dec 15 | Console popups on Windows 11 | Investigation (Issues #304, #330) | - |
| Dec 16 | Zombie processes persist | Considered Bun self-executable | - |
| Dec 17 | **Comprehensive stabilization** | PR #378 merged | v7.3.7 |
### Phase 3: Ongoing Challenges (Dec 2025 - Jan 2026)
| Date | Issue | Status |
|------|-------|--------|
| Dec 27 | Multi-session hangs with libuv assertion failures | Investigated |
| Dec 28 | Lock acquisition ENOENT errors | PR #470 fixes |
| Dec 29 | Windows stability refactoring | PR #492 |
| Jan 4 | PowerShell `$_` escaping in Git Bash (Issue #517) | **NOT FIXED** |
| Jan 5 | Windows hooks IPC issues (Issue #555) | **OPEN** |
---
## Issue Category 1: Zombie Port Problem
### The Problem
Bun runtime has a known bug on Windows where socket handles aren't properly released when the worker process exits. This causes "zombie ports" that remain bound even after all processes terminate, requiring system reboot to clear.
### The Solution: Worker Wrapper Architecture
**Implemented:** December 17, 2025 (PR #372 by @ToxMox)
A two-tier process architecture was introduced:
```
ProcessManager
└── worker-wrapper.cjs (no sockets, manages lifecycle)
└── worker-service.cjs (HTTP server on port 37777)
├── MCP server
└── ChromaSync
```
**How it works:**
1. `worker-wrapper.cjs` spawns as outer process with no socket bindings
2. Actual worker runs as child process with IPC communication
3. On restart/shutdown, wrapper uses `taskkill /T /F` to kill entire process tree
4. Wrapper exits itself - since it holds no sockets, port is properly released
**Files modified (14 files, +665/-249 lines):**
- `src/services/worker-wrapper.ts` (152 lines, new)
- `src/services/process/ProcessManager.ts`
- `src/services/worker-service.ts`
- All hook scripts
- Build system
### Known Limitation
**Issue:** The hooks don't set `CLAUDE_MEM_MANAGED=true` environment variable, so the managed restart code path (lines 314-330 of worker-service.ts) is never activated. Every session runs the "standalone Windows" code path which lacks proper serialization.
---
## Issue Category 2: Console Window Popups
### The Problem
Windows users on Windows 11 reported multiple PowerShell/cmd popup windows appearing during Claude Code usage, disrupting user input. Issue #367 specifically noted these popups were stealing keyboard focus.
### The Solution: Standardized windowsHide
**Implemented:** December 17, 2025 (PR #378)
- All `child_process.spawn()` calls now include `windowsHide: true`
- PowerShell spawning uses `Start-Process -WindowStyle Hidden`
- ChromaSync MCP transport includes windowsHide option
**Affected components:**
- ProcessManager subprocess spawning
- ChromaSync Python subprocess
- All hook executions
### Worker Logs Revealed Additional Issue
Worker logs showed failed orphaned process cleanup using Unix commands (`ps`, `grep`) that don't exist on Windows. This required implementing Windows-specific process enumeration using PowerShell's `Get-CimInstance`.
---
## Issue Category 3: Process Management
### 3.1 Orphaned Process Cleanup
**The Problem:** Child processes (chroma-mcp Python processes) accumulate over time, holding socket descriptors and preventing worker restart.
**The Solution (PR #378):**
```typescript
// Windows: Recursive process tree enumeration
const cmd = `powershell -Command "Get-CimInstance Win32_Process | Where-Object { $_.Name -like '*python*' -and $_.CommandLine -like '*chroma-mcp*' } | Select-Object -ExpandProperty ProcessId"`;
```
**Security:** Triple PID validation at lines 287, 306, 327 to prevent command injection.
### 3.2 Multi-Session Conflicts
**The Problem (Dec 27):** Running multiple concurrent Claude sessions causes the second session to hang indefinitely with:
- libuv assertion failure: `!(handle->flags & UV_HANDLE_CLOSING)`
- SessionStart hook error: "Worker failed to restart"
**Root Cause Analysis:**
1. SessionStart hook calls restart without locking mechanism
2. Two sessions simultaneously trigger `httpShutdown()`, `waitForPortFree()`, `spawn()`
3. `waitForPortFree()` polls for only 10 seconds (Windows TCP TIME_WAIT: 30-60s)
4. Child processes inherit socket descriptors, blocking port 37777
5. `cleanupOrphanedProcesses()` runs AFTER worker starts instead of during shutdown
**Proposed Fix:** File-based mutex to prevent concurrent restart operations.
### 3.3 Lock Acquisition ENOENT Errors
**The Problem (Dec 28):** On Windows, the `.claude-mem` directory can be in flux during filesystem operations, causing `worker.lock` file access to fail with ENOENT.
**The Solution (PR #470):**
```typescript
// Retry up to 3 times, creating DATA_DIR between attempts
for (let i = 0; i < 3; i++) {
try {
return await acquireLock();
} catch (e) {
if (e.code === 'ENOENT') {
await mkdir(DATA_DIR, { recursive: true });
}
}
}
```
---
## Issue Category 4: Path & Shell Compatibility
### 4.1 PowerShell `$_` Variable Escaping (Issue #517)
**Status:** NOT FIXED as of v8.5.7
**The Problem:** When running in Git Bash or WSL, Bash interprets `$_` before PowerShell receives it. This affects:
- `cleanupOrphanedProcesses()` (lines 170-172)
- `getChildProcesses()` (lines 91-92)
**Current Code (problematic):**
```typescript
const cmd = `powershell -Command "Get-CimInstance Win32_Process | Where-Object { $_.Name -like '*python*' ..."`;
```
**Recommended Fix:** Use WMIC instead:
```typescript
const cmd = `wmic process where "name like '%python%' and commandline like '%chroma-mcp%'" get processid /format:list`;
```
### 4.2 Bun PATH Detection
**The Problem:** Windows users with non-standard Bun installations get unhelpful error messages.
**The Solution (Dec 17):**
Enhanced `getBunPathOrThrow()` with Windows-specific troubleshooting:
- Verification command: `bun --version`
- PATH check for `%USERPROFILE%\.bun\bin`
- Reference to GitHub issue #371
- Link to troubleshooting docs
### 4.3 PowerShell String Escaping
**The Solution:** `escapePowerShellString()` function doubles single quotes for safety when constructing PowerShell commands.
---
## Timeout Adjustments
Windows requires longer timeouts due to slower filesystem and process operations:
| Setting | Unix | Windows | Multiplier |
|---------|------|---------|------------|
| Worker startup | 15s | 30s | 2.0x |
| Hook execution | 5s | 10s | 2.0x |
| Port free check | 5s | 10s | 2.0x |
| Process cleanup | 30s | 60s | 2.0x |
---
## CI/CD for Windows
**Implemented:** December 17, 2025
`.github/workflows/windows-ci.yml` tests:
- Worker process lifecycle (startup/shutdown)
- Rapid restart scenarios
- Bun PATH detection
- Port cleanup verification
- Zombie process detection
**Note:** Windows CI was later removed due to testing challenges.
---
## Currently Open Windows Issues
| Issue | Title | Severity |
|-------|-------|----------|
| #517 | PowerShell `$_` escaping in Git Bash | Medium |
| #555 | Windows hooks IPC false | High |
| #324 | Windows 11 64-bit system issues | Unknown |
---
## Key Contributors
- **@ToxMox** - Worker wrapper architecture (PR #372), zombie port fix
- **@kat-bell** - Windows plugin installation fixes (v7.0.4)
- **Claude Opus 4.5** - Co-authored many Windows stabilization commits
---
## Architectural Decisions
### Why Worker Wrapper?
The two-process architecture was chosen over alternatives like:
- Bun self-executable packaging (considered but not implemented)
- PM2 process management (replaced due to Windows issues)
- Native Node.js (abandoned due to windowsHide limitations with detached processes)
### Why PowerShell over cmd.exe?
PowerShell provides:
- `Get-CimInstance` for WMI process enumeration
- `-WindowStyle Hidden` for truly hidden windows
- Better handling of complex command strings
### Why Keep Windows Code?
December 20, 2025 decision documented:
- Active Windows users evidenced by bug reports
- 20+ Windows-specific commits with recent fixes
- Critical functionality that can't be removed
- Comprehensive documentation ensures maintainability
---
## Recommendations
1. **Implement file-based mutex** for worker restart serialization
2. **Fix Issue #517** by switching to WMIC or proper escaping
3. **Increase waitForPortFree timeout** to 60s for Windows TIME_WAIT
4. **Run cleanup BEFORE worker startup** instead of after
5. **Set CLAUDE_MEM_MANAGED=true** in hooks.json to activate managed mode
6. **Consider Windows ARM64** - currently uses x64 emulation
---
## References
### Key PRs
- PR #372: Worker wrapper architecture
- PR #377/#378: Comprehensive Windows stabilization
- PR #470: Lock acquisition retry
- PR #492: Worker service refactoring
### Key Versions
- v5.1.1: PM2 ENOENT fix
- v7.0.4: Windows installation fixes
- v7.1.7: libuv crash fix
- v7.3.7: Platform stabilization
### Documentation
- https://docs.claude-mem.ai/troubleshooting/windows-issues
- `docs/context/windows-code-evaluation.md`
- `docs/PM2-TO-BUN-MIGRATION.md`
docs/reports/CLAUDE.md
+7
View File
@@ -157,4 +157,11 @@
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #37547 | 4:47 PM | ✅ | Issue #557 Analysis Report Created for Plugin Startup Failure | ~491 |
### Jan 6, 2026
**2026-01-06--windows-woes-comprehensive-report.md**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #38109 | 12:16 AM | ✅ | Comprehensive Windows Woes Report Generated from Memory Search | ~826 |
</claude-mem-context>