memento-mcp-server 1.7.4 → 1.7.5

package/INSTALL.md

@@ -379,7 +379,35 @@ Remove-Item data\memory.db* -Force
 npm run db:init
 ```
 
-#### 5. Docker 오류
+#### 5. Node.js 버전으로 인한 SQLite 모듈 오류
+
+**증상**: "SQLite를 사용할 수 없습니다" 또는 "Module not found: better-sqlite3" 오류
+
+**원인**: Node.js 버전이 높거나 낮아서 네이티브 모듈이 빌드되지 않음
+
+**해결 방법**:
+
+```bash
+# 방법 1: 네이티브 모듈 재빌드 (권장)
+npm rebuild better-sqlite3 sqlite-vec
+
+# 방법 2: 소스에서 빌드
+npm install better-sqlite3 sqlite-vec --build-from-source
+
+# 방법 3: Node.js 버전 확인 및 변경 (20.x 권장)
+node --version  # 20.x 이상이어야 함
+
+# 방법 4: 완전 재설치
+rm -rf node_modules package-lock.json
+npm cache clean --force
+npm install --build-from-source
+```
+
+**상세 가이드**: 
+- [Node.js 버전 호환성 문제 해결 가이드](docs/troubleshooting-node-version.md)
+- [npx 사용자 문제 해결 가이드](docs/npx-troubleshooting.md)
+
+#### 6. Docker 오류
 ```bash
 # Docker 컨테이너 완전 정리
 docker-compose down -v

package/README.md

@@ -110,6 +110,7 @@ npm run quick-start
 ### 📚 **상세 설치 가이드**
 - [INSTALL.md](INSTALL.md) - 전체 설치 가이드
 - [Cursor MCP 설정 가이드](docs/cursor-mcp-setup.ko.md) - Cursor에서 MCP 서버 사용하기
+- [npx 사용자 문제 해결](docs/npx-troubleshooting.md) - npx 실행 시 문제 해결
 
 ## 💡 사용 예시
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mcp-server",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "description": "AI Agent 기억 보조 MCP 서버 - 사람의 기억 구조를 모사한 스토리지+검색+요약+망각 메커니즘",
   "main": "dist/server/index.js",
   "type": "module",
@@ -49,6 +49,7 @@
     "test:docker": "node test-docker.js",
     "setup": "node scripts/auto-setup.js",
     "postinstall": "node scripts/auto-setup.js",
+    "rebuild-native": "npm rebuild better-sqlite3 sqlite-vec",
     "prepublishOnly": "npm run build && npm run verify-bin",
     "verify-bin": "node scripts/verify-bin.js",
     "quick-start": "npm install && npm run setup && npm run dev",

package/scripts/auto-setup.js

@@ -113,6 +113,70 @@ async function initializeDatabase() {
   }
 }
 
+async function rebuildNativeModules() {
+  try {
+    logStep('네이티브 모듈', 'better-sqlite3 및 sqlite-vec 재빌드 시도 중...');
+    
+    const nodeModulesPath = path.join(projectRoot, 'node_modules');
+    if (!fs.existsSync(nodeModulesPath)) {
+      logWarning('node_modules가 없습니다. 먼저 npm install이 실행됩니다.');
+      return;
+    }
+    
+    // 네이티브 모듈이 제대로 작동하는지 확인 (동적 import 사용)
+    try {
+      const betterSqlite3Path = path.join(nodeModulesPath, 'better-sqlite3');
+      if (fs.existsSync(betterSqlite3Path)) {
+        // 모듈 존재 확인만 (실제 로드는 나중에)
+        logSuccess('better-sqlite3 모듈 확인됨');
+      } else {
+        throw new Error('better-sqlite3 not found');
+      }
+    } catch (error) {
+      logWarning('better-sqlite3 모듈을 찾을 수 없거나 빌드가 필요합니다.');
+      logStep('재빌드', 'better-sqlite3 재빌드 중...');
+      
+      try {
+        execSync('npm rebuild better-sqlite3', {
+          cwd: projectRoot,
+          stdio: 'inherit'
+        });
+        logSuccess('better-sqlite3 재빌드 완료');
+      } catch (rebuildError) {
+        logWarning(`better-sqlite3 재빌드 실패: ${rebuildError.message}`);
+        logWarning('수동으로 실행하세요: npm rebuild better-sqlite3');
+      }
+    }
+    
+    // sqlite-vec도 확인 (선택적)
+    try {
+      const sqliteVecPath = path.join(nodeModulesPath, 'sqlite-vec');
+      if (fs.existsSync(sqliteVecPath)) {
+        logSuccess('sqlite-vec 모듈 확인됨');
+      } else {
+        throw new Error('sqlite-vec not found');
+      }
+    } catch (error) {
+      logWarning('sqlite-vec 모듈을 찾을 수 없거나 빌드가 필요합니다.');
+      logStep('재빌드', 'sqlite-vec 재빌드 시도 중...');
+      
+      try {
+        execSync('npm rebuild sqlite-vec', {
+          cwd: projectRoot,
+          stdio: 'inherit'
+        });
+        logSuccess('sqlite-vec 재빌드 완료');
+      } catch (rebuildError) {
+        logWarning(`sqlite-vec 재빌드 실패: ${rebuildError.message}`);
+        logWarning('sqlite-vec는 선택적 의존성입니다. 벡터 검색 기능이 제한될 수 있습니다.');
+      }
+    }
+  } catch (error) {
+    logWarning(`네이티브 모듈 재빌드 중 오류: ${error.message}`);
+    logWarning('수동으로 실행하세요: npm rebuild better-sqlite3 sqlite-vec');
+  }
+}
+
 async function checkDependencies() {
   const packageJsonPath = path.join(projectRoot, 'package.json');
   const nodeModulesPath = path.join(projectRoot, 'node_modules');
@@ -210,6 +274,15 @@ async function main() {
   try {
     log('🚀 Memento MCP Server 자동 설정을 시작합니다...', 'bright');
     
+    // npx를 통해 실행되는 경우 네이티브 모듈 재빌드 먼저 시도
+    const isNpx = process.env.npm_config_user_config === undefined || 
+                   process.env.npm_execpath?.includes('npx') ||
+                   process.env.npm_lifecycle_event === 'postinstall';
+    
+    if (isNpx) {
+      await rebuildNativeModules();
+    }
+    
     await checkNodeVersion();
     await checkDependencies();
     await createDataDirectory();