memento-mcp-server 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,165 @@
+# 기여하기 (Contributing)
+
+Memento MCP Server 프로젝트에 기여해주셔서 감사합니다! 이 문서는 프로젝트에 기여하는 방법을 안내합니다.
+
+## 🚀 빠른 시작
+
+### 1. 저장소 포크
+1. GitHub에서 [memento 저장소](https://github.com/jee1/memento)를 포크합니다.
+2. 포크한 저장소를 로컬에 클론합니다:
+   ```bash
+   git clone https://github.com/your-username/memento.git
+   cd memento
+   ```
+
+### 2. 개발 환경 설정
+```bash
+# 의존성 설치
+npm install
+
+# 개발 서버 시작
+npm run dev
+
+# 테스트 실행
+npm run test
+```
+
+## 📋 기여 방법
+
+### 버그 리포트
+버그를 발견하셨나요? 다음 정보를 포함하여 이슈를 생성해주세요:
+- **버그 설명**: 무엇이 잘못되었는지 명확한 설명
+- **재현 단계**: 버그를 재현하는 단계별 방법
+- **예상 동작**: 어떻게 동작해야 하는지
+- **실제 동작**: 실제로 어떻게 동작하는지
+- **환경 정보**: OS, Node.js 버전, 브라우저 등
+
+### 기능 제안
+새로운 기능을 제안하고 싶으신가요? 다음을 포함해주세요:
+- **기능 설명**: 어떤 기능을 원하는지
+- **사용 사례**: 왜 이 기능이 필요한지
+- **구현 아이디어**: 어떻게 구현할 수 있을지 (선택사항)
+
+### 코드 기여
+코드로 기여하고 싶으신가요? 다음 단계를 따라주세요:
+
+1. **이슈 생성**: 먼저 작업할 내용에 대해 이슈를 생성하세요.
+2. **브랜치 생성**: `feature/기능명` 또는 `fix/버그명` 형식으로 브랜치를 생성하세요.
+3. **코드 작성**: 변경사항을 구현하세요.
+4. **테스트**: 테스트를 작성하고 실행하세요.
+5. **커밋**: [Conventional Commits](https://www.conventionalcommits.org/) 형식을 따라 커밋하세요.
+6. **PR 생성**: Pull Request를 생성하세요.
+
+## 🛠️ 개발 가이드라인
+
+### 코딩 스타일
+- **언어**: TypeScript (Node.js ≥ 20)
+- **들여쓰기**: 2칸 공백
+- **따옴표**: 단일 따옴표 (`'`)
+- **세미콜론**: 사용
+- **ESLint**: 프로젝트의 ESLint 설정을 따릅니다.
+
+### 커밋 메시지
+[Conventional Commits](https://www.conventionalcommits.org/) 형식을 사용합니다:
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**타입 예시:**
+- `feat`: 새로운 기능
+- `fix`: 버그 수정
+- `docs`: 문서 변경
+- `style`: 코드 스타일 변경 (포맷팅, 세미콜론 등)
+- `refactor`: 코드 리팩토링
+- `test`: 테스트 추가/수정
+- `chore`: 빌드 프로세스, 도구 변경
+
+**예시:**
+```
+feat(search): 하이브리드 검색 엔진 추가
+fix(memory): 메모리 누수 문제 해결
+docs(readme): 설치 가이드 업데이트
+```
+
+### 테스트
+- **테스트 프레임워크**: Vitest
+- **단위 테스트**: `*.spec.ts` 파일로 작성
+- **E2E 테스트**: `src/test/` 디렉토리에 작성
+- **테스트 실행**: `npm run test`
+
+### 브랜치 전략
+- `main`: 안정적인 릴리스 브랜치
+- `feature/*`: 새로운 기능 개발
+- `fix/*`: 버그 수정
+- `docs/*`: 문서 업데이트
+- `chore/*`: 유지보수 작업
+
+## 📁 프로젝트 구조
+
+```
+src/
+├── algorithms/     # 검색 및 망각 알고리즘
+├── client/         # MCP 클라이언트
+├── config/         # 설정 관리
+├── database/       # 데이터베이스 스키마 및 마이그레이션
+├── server/         # MCP 서버 엔트리포인트
+├── services/       # 비즈니스 로직 서비스
+├── test/           # E2E 테스트
+├── tools/          # MCP 도구 구현
+├── types/          # 공유 타입 정의
+└── utils/          # 유틸리티 함수
+```
+
+## 🔍 코드 리뷰 프로세스
+
+1. **자동 검사**: CI/CD 파이프라인이 자동으로 실행됩니다.
+2. **리뷰 요청**: 최소 1명의 리뷰어가 승인해야 합니다.
+3. **피드백 반영**: 리뷰어의 피드백을 반영하여 수정합니다.
+4. **병합**: 승인 후 `main` 브랜치에 병합됩니다.
+
+## 🐛 버그 수정
+
+버그를 수정할 때:
+1. **재현 테스트**: 버그를 재현하는 테스트를 작성합니다.
+2. **수정**: 버그를 수정합니다.
+3. **테스트 통과**: 모든 테스트가 통과하는지 확인합니다.
+4. **문서 업데이트**: 필요시 관련 문서를 업데이트합니다.
+
+## ✨ 기능 추가
+
+새로운 기능을 추가할 때:
+1. **설계 검토**: 기능 설계에 대해 이슈에서 논의합니다.
+2. **테스트 작성**: 기능에 대한 테스트를 작성합니다.
+3. **구현**: 기능을 구현합니다.
+4. **문서 작성**: API 문서와 사용법을 작성합니다.
+
+## 📚 문서화
+
+문서를 업데이트할 때:
+- **한국어 우선**: 한국어 문서를 우선으로 작성합니다.
+- **영어 번역**: 필요시 영어 문서도 업데이트합니다.
+- **예시 포함**: 코드 예시와 사용 사례를 포함합니다.
+- **최신 상태 유지**: 코드 변경사항과 동기화합니다.
+
+## 🤝 커뮤니티
+
+- **이슈**: [GitHub Issues](https://github.com/jee1/memento/issues)
+- **토론**: [GitHub Discussions](https://github.com/jee1/memento/discussions)
+- **문서**: [Wiki](https://github.com/jee1/memento/wiki)
+
+## 📄 라이선스
+
+이 프로젝트는 MIT 라이선스 하에 배포됩니다. 기여하시는 코드는 동일한 라이선스 하에 배포됩니다.
+
+## 🙏 감사
+
+모든 기여자분들께 감사드립니다! 여러분의 기여가 Memento를 더 나은 프로젝트로 만들어줍니다.
+
+---
+
+**질문이 있으시면 언제든지 이슈를 생성하거나 토론에 참여해주세요!**

package/DOCKER_SETUP_GUIDE.md

@@ -0,0 +1,84 @@
+# 🐳 Memento Docker 설정 가이드
+
+## 📋 현재 상태
+- ✅ 도커 설정 완료 (MCP 서버용)
+- ✅ MCP 클라이언트 분리 완료
+- ✅ 데이터 백업 완료 (473개 기억)
+- ✅ mcp.json 설정 업데이트 완료
+
+## 🚀 Docker Desktop 시작 후 실행할 명령어
+
+### 1단계: Docker Desktop 시작
+- Windows 시작 메뉴에서 "Docker Desktop" 검색 후 실행
+- Docker Desktop이 완전히 시작될 때까지 대기
+
+### 2단계: 자동 설정 실행
+```bash
+# 방법 1: 배치 파일 실행 (권장)
+start-docker-setup.bat
+
+# 방법 2: 수동 실행
+docker-compose build
+docker-compose up -d
+```
+
+**📁 데이터 마운트 방식:**
+- 호스트 `./data` 폴더가 컨테이너 `/app/data`에 직접 마운트됩니다
+- 파일 복사 없이 실시간 동기화됩니다
+- 컨테이너 재시작해도 데이터가 유지됩니다
+
+### 3단계: 설정 확인
+```bash
+# 컨테이너 상태 확인
+docker-compose ps
+
+# 로그 확인
+docker-compose logs memento-mcp-server
+
+# 데이터베이스 확인
+docker exec memento-mcp-server sqlite3 /app/data/memory.db "SELECT COUNT(*) FROM memory_item;"
+
+# 서버 접속 테스트
+curl http://localhost:9001/health
+```
+
+## 🔧 문제 해결
+
+### Docker Desktop이 시작되지 않는 경우
+1. Windows 재시작
+2. Docker Desktop 재설치
+3. WSL2 업데이트
+
+### 컨테이너가 시작되지 않는 경우
+```bash
+# 로그 확인
+docker-compose logs memento-mcp-server
+
+# 컨테이너 재시작
+docker-compose restart memento-mcp-server
+```
+
+### 데이터가 보이지 않는 경우
+```bash
+# 마운트 확인
+docker inspect memento-mcp-server | grep -A 5 "Mounts"
+
+# 데이터 디렉토리 확인
+docker exec memento-mcp-server ls -la /app/data
+
+# 호스트 데이터 확인
+dir ".\data"
+```
+
+## 📊 현재 데이터 상태
+- **총 기억 수**: 473개
+- **일화기억**: 357개
+- **의미기억**: 105개
+- **절차기억**: 7개
+- **작업기억**: 4개
+
+## 🎯 완료 후 확인사항
+1. Cursor에서 Memento MCP 서버 연결 확인
+2. 기억 검색 기능 테스트
+3. 새 기억 저장 테스트
+4. 도커 재시작 후 데이터 유지 확인

package/Dockerfile

@@ -0,0 +1,90 @@
+# Multi-stage build for Memento MCP Server
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY tsconfig*.json ./
+
+# Install all dependencies (including dev dependencies for build) without running scripts
+RUN npm ci --ignore-scripts
+
+# Copy source code
+COPY src/ ./src/
+COPY scripts/ ./scripts/
+
+# Run postinstall scripts now that source code is available
+RUN npm run postinstall
+
+# Build application
+RUN npm run build
+
+# Production stage
+FROM node:20-slim AS production
+
+# Install SQLite and development tools (FTS5 is included in SQLite)
+# Install dependencies for sqlite-vec compilation
+RUN apt-get update && apt-get install -y \
+    python3 \
+    make \
+    g++ \
+    sqlite3 \
+    libsqlite3-dev \
+    git \
+    cmake \
+    build-essential \
+    wget \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files and scripts, then install dependencies
+COPY package*.json ./
+COPY scripts/ ./scripts/
+RUN npm cache clean --force && npm install --omit=dev
+
+# Install sqlite-vec npm package and copy .so files to /usr/lib/ without .so extension
+RUN npm install sqlite-vec --build-from-source && \
+    find /app/node_modules -name "*.so" -type f && \
+    cp /app/node_modules/sqlite-vec-linux-x64/vec0.so /usr/lib/vec0 && \
+    chmod +x /usr/lib/vec0 && \
+    ls -la /usr/lib/vec0
+
+# Copy built application
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package*.json ./
+
+# Install only production dependencies (skip scripts since they were already run in builder stage)
+# Rebuild better-sqlite3 for Debian Linux and install sqlite-vec
+RUN npm ci --only=production --ignore-scripts && \
+    npm rebuild better-sqlite3 --build-from-source && \
+    npm install sqlite-vec --build-from-source && \
+    npm install --platform=linux --arch=x64 sharp && \
+    npm cache clean --force
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Create non-root user
+RUN groupadd -g 1001 nodejs
+RUN useradd -r -u 1001 -g nodejs memento
+
+# Change ownership (data directory will be mounted, so we'll set permissions at runtime)
+RUN chown -R memento:nodejs /app
+USER memento
+
+# Expose port
+EXPOSE 9001
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node -e "console.log('Health check passed')" || exit 1
+
+# Copy startup script
+COPY --chmod=755 scripts/start-container.sh /app/start-container.sh
+
+# Start application
+CMD ["/app/start-container.sh"]

package/INSTALL.en.md

@@ -0,0 +1,303 @@
+# 🚀 Memento MCP Server Installation Guide
+
+<div align="center">
+  [🇰🇷 한국어](INSTALL.md) | [🇺🇸 English](INSTALL.en.md)
+</div>
+
+Provides various installation methods for the AI Agent Memory Assistant MCP Server.
+
+## 📋 Installation Method Selection
+
+### 🥇 **1st Priority: One-click Installation (Recommended)**
+```bash
+# Run automatic installation script
+curl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash
+```
+
+### 🥈 **2nd Priority: npx Method (For Developers)**
+```bash
+# Run immediately (without installation)
+npx memento-mcp-server@latest dev
+
+# Auto setup then run
+npx memento-mcp-server@latest setup
+npx memento-mcp-server@latest start
+```
+
+### 🥉 **3rd Priority: Docker Method (For Production)**
+```bash
+# Development environment
+docker-compose -f docker-compose.dev.yml up -d
+
+# Production environment
+docker-compose -f docker-compose.prod.yml up -d
+```
+
+### 🛠️ **4th Priority: Source Code Method (For Developers)**
+```bash
+# Clone repository
+git clone https://github.com/jee1/memento.git
+cd memento
+
+# One-click installation and run
+npm run quick-start
+```
+
+## 🎯 Recommended Installation Method by User Type
+
+### 👨‍💻 **Developers/Researchers**
+- **npx method** or **source code method** recommended
+- Optimized for rapid prototyping and debugging
+
+### 👤 **General Users**
+- **One-click installation** or **Docker method** recommended
+- Simple installation and stable execution
+
+### 🏢 **Teams/Organizations**
+- **Docker method** required
+- Standardized deployment and scalability
+
+## 📚 Detailed Installation Methods
+
+### 1. One-click Installation
+
+#### Linux/macOS
+```bash
+curl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash
+```
+
+#### Windows (PowerShell)
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/jee1/memento/main/install.sh" -OutFile "install.sh"
+bash install.sh
+```
+
+### 2. npx Method
+
+#### Basic Usage
+```bash
+# Development mode (hot reload)
+npx memento-mcp-server@latest dev
+
+# Production mode
+npx memento-mcp-server@latest start
+
+# HTTP/WebSocket server
+npx memento-mcp-server@latest dev-http
+
+# Auto setup
+npx memento-mcp-server@latest setup
+```
+
+#### Global Installation
+```bash
+# Global installation
+npm install -g memento-mcp-server
+
+# Usage
+memento-mcp dev
+memento-mcp start
+memento-mcp setup
+```
+
+### 3. Docker Method
+
+#### Development Environment
+```bash
+# Run development Docker Compose
+docker-compose -f docker-compose.dev.yml up -d
+
+# Check logs
+docker-compose -f docker-compose.dev.yml logs -f
+
+# Stop
+docker-compose -f docker-compose.dev.yml down
+```
+
+#### Production Environment
+```bash
+# Run production Docker Compose
+docker-compose -f docker-compose.prod.yml up -d
+
+# Check logs
+docker-compose -f docker-compose.prod.yml logs -f
+
+# Stop
+docker-compose -f docker-compose.prod.yml down
+```
+
+#### Basic Docker Compose
+```bash
+# Basic run (production mode)
+docker-compose up -d
+
+# Check logs
+docker-compose logs -f
+
+# Stop
+docker-compose down
+```
+
+### 4. Source Code Method
+
+#### Basic Installation
+```bash
+# Clone repository
+git clone https://github.com/jee1/memento.git
+cd memento
+
+# Install dependencies
+npm install
+
+# Auto setup
+npm run setup
+
+# Start development server
+npm run dev
+```
+
+#### One-click Installation
+```bash
+# All processes in one command
+npm run quick-start
+```
+
+## ⚙️ Environment Configuration
+
+### Environment Variable Setup
+```bash
+# Create .env file
+cp env.example .env
+
+# Set API keys (optional)
+# OPENAI_API_KEY=your_openai_api_key_here
+# GEMINI_API_KEY=your_gemini_api_key_here
+```
+
+### Database Initialization
+```bash
+# Initialize SQLite database
+npm run db:init
+
+# Run migrations
+npm run db:migrate
+```
+
+## 🔧 Available Commands
+
+### Development Commands
+```bash
+npm run dev              # MCP server development mode
+npm run dev:http         # HTTP/WebSocket server development mode
+npm run dev:http-v2      # HTTP server v2 development mode
+```
+
+### Production Commands
+```bash
+npm run build            # TypeScript compilation
+npm run start            # MCP server production run
+npm run start:http       # HTTP/WebSocket server production run
+```
+
+### Test Commands
+```bash
+npm run test             # Run all tests
+npm run test:client      # Client tests
+npm run test:search      # Search functionality tests
+npm run test:forgetting  # Forgetting policy tests
+npm run test:performance # Performance benchmarks
+```
+
+### Docker Commands
+```bash
+npm run docker:dev       # Run development Docker
+npm run docker:prod      # Run production Docker
+npm run docker:build     # Build Docker image
+npm run docker:logs      # Check Docker logs
+```
+
+### Utility Commands
+```bash
+npm run setup            # Run auto setup
+npm run quick-start      # One-click installation and run
+npm run backup:embeddings # Backup embeddings
+npm run regenerate:embeddings # Regenerate embeddings
+```
+
+## 🌐 Access Information
+
+After installation, you can access the following addresses:
+
+- **MCP Server**: `stdio` or `ws://localhost:8080/mcp`
+- **HTTP API**: `http://localhost:8080`
+- **WebSocket**: `ws://localhost:8080`
+- **Admin Dashboard**: `http://localhost:8080/admin`
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+#### 1. Node.js Version Error
+```bash
+# Node.js 20+ required
+node --version
+
+# Install Node.js with nvm (Linux/macOS)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 20
+nvm use 20
+```
+
+#### 2. Port Conflict
+```bash
+# If port 8080 is in use
+# Change PORT in .env file
+PORT=8081
+```
+
+#### 3. Database Error
+```bash
+# Reinitialize database
+rm -rf data/memory.db*
+npm run db:init
+```
+
+#### 4. Docker Error
+```bash
+# Complete Docker container cleanup
+docker-compose down -v
+docker system prune -a
+docker-compose up -d
+```
+
+### Log Checking
+```bash
+# Application logs
+tail -f logs/memento-server.log
+
+# Docker logs
+docker-compose logs -f
+
+# System logs (Linux)
+journalctl -u memento-mcp-server -f
+```
+
+## 📞 Support
+
+- **Issue Reports**: [GitHub Issues](https://github.com/jee1/memento/issues)
+- **Documentation**: [Wiki](https://github.com/jee1/memento/wiki)
+- **Developer Guide**: [docs/en/developer-guide.md](docs/en/developer-guide.md)
+- **API Reference**: [docs/en/api-reference.md](docs/en/api-reference.md)
+
+## 🎉 Installation Complete!
+
+After installation, proceed with the following steps:
+
+1. **Check Server Status**: `http://localhost:8080/health`
+2. **Connect MCP Client**: [Client Guide](packages/mcp-client/README.md)
+3. **Test API**: [API Documentation](docs/en/api-reference.md)
+4. **Learn Usage**: [User Manual](docs/en/user-manual.md)
+
+---
+
+**💡 Tip**: For first-time users, you can complete all setup automatically with the `npm run quick-start` command!