memento-mcp-server 0.1.0

package/INSTALL.md

@@ -0,0 +1,303 @@
+# 🚀 Memento MCP Server 설치 가이드
+
+<div align="center">
+  [🇰🇷 한국어](INSTALL.md) | [🇺🇸 English](INSTALL.en.md)
+</div>
+
+AI Agent 기억 보조 MCP 서버의 다양한 설치 방법을 제공합니다.
+
+## 📋 설치 방법 선택
+
+### 🥇 **1순위: 원클릭 설치 (권장)**
+```bash
+# 자동 설치 스크립트 실행
+curl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash
+```
+
+### 🥈 **2순위: npx 방식 (개발자용)**
+```bash
+# 즉시 실행 (설치 없이)
+npx memento-mcp-server@latest dev
+
+# 자동 설정 후 실행
+npx memento-mcp-server@latest setup
+npx memento-mcp-server@latest start
+```
+
+### 🥉 **3순위: Docker 방식 (프로덕션용)**
+```bash
+# 개발 환경
+docker-compose -f docker-compose.dev.yml up -d
+
+# 프로덕션 환경
+docker-compose -f docker-compose.prod.yml up -d
+```
+
+### 🛠️ **4순위: 소스코드 방식 (개발자용)**
+```bash
+# 저장소 클론
+git clone https://github.com/jee1/memento.git
+cd memento
+
+# 원클릭 설치 및 실행
+npm run quick-start
+```
+
+## 🎯 사용자별 권장 설치 방법
+
+### 👨‍💻 **개발자/연구자**
+- **npx 방식** 또는 **소스코드 방식** 권장
+- 빠른 프로토타이핑과 디버깅에 최적화
+
+### 👤 **일반 사용자**
+- **원클릭 설치** 또는 **Docker 방식** 권장
+- 간단한 설치와 안정적인 실행
+
+### 🏢 **팀/조직**
+- **Docker 방식** 필수
+- 표준화된 배포와 확장성
+
+## 📚 상세 설치 방법
+
+### 1. 원클릭 설치
+
+#### 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 방식
+
+#### 기본 사용법
+```bash
+# 개발 모드 (핫 리로드)
+npx memento-mcp-server@latest dev
+
+# 프로덕션 모드
+npx memento-mcp-server@latest start
+
+# HTTP/WebSocket 서버
+npx memento-mcp-server@latest dev-http
+
+# 자동 설정
+npx memento-mcp-server@latest setup
+```
+
+#### 전역 설치
+```bash
+# 전역 설치
+npm install -g memento-mcp-server
+
+# 사용법
+memento-mcp dev
+memento-mcp start
+memento-mcp setup
+```
+
+### 3. Docker 방식
+
+#### 개발 환경
+```bash
+# 개발용 Docker Compose 실행
+docker-compose -f docker-compose.dev.yml up -d
+
+# 로그 확인
+docker-compose -f docker-compose.dev.yml logs -f
+
+# 중지
+docker-compose -f docker-compose.dev.yml down
+```
+
+#### 프로덕션 환경
+```bash
+# 프로덕션용 Docker Compose 실행
+docker-compose -f docker-compose.prod.yml up -d
+
+# 로그 확인
+docker-compose -f docker-compose.prod.yml logs -f
+
+# 중지
+docker-compose -f docker-compose.prod.yml down
+```
+
+#### 기본 Docker Compose
+```bash
+# 기본 실행 (프로덕션 모드)
+docker-compose up -d
+
+# 로그 확인
+docker-compose logs -f
+
+# 중지
+docker-compose down
+```
+
+### 4. 소스코드 방식
+
+#### 기본 설치
+```bash
+# 저장소 클론
+git clone https://github.com/jee1/memento.git
+cd memento
+
+# 의존성 설치
+npm install
+
+# 자동 설정
+npm run setup
+
+# 개발 서버 시작
+npm run dev
+```
+
+#### 원클릭 설치
+```bash
+# 모든 과정을 한 번에
+npm run quick-start
+```
+
+## ⚙️ 환경 설정
+
+### 환경 변수 설정
+```bash
+# .env 파일 생성
+cp env.example .env
+
+# API 키 설정 (선택사항)
+# OPENAI_API_KEY=your_openai_api_key_here
+# GEMINI_API_KEY=your_gemini_api_key_here
+```
+
+### 데이터베이스 초기화
+```bash
+# SQLite 데이터베이스 초기화
+npm run db:init
+
+# 마이그레이션 실행
+npm run db:migrate
+```
+
+## 🔧 사용 가능한 명령어
+
+### 개발 명령어
+```bash
+npm run dev              # MCP 서버 개발 모드
+npm run dev:http         # HTTP/WebSocket 서버 개발 모드
+npm run dev:http-v2      # HTTP 서버 v2 개발 모드
+```
+
+### 프로덕션 명령어
+```bash
+npm run build            # TypeScript 컴파일
+npm run start            # MCP 서버 프로덕션 실행
+npm run start:http       # HTTP/WebSocket 서버 프로덕션 실행
+```
+
+### 테스트 명령어
+```bash
+npm run test             # 모든 테스트 실행
+npm run test:client      # 클라이언트 테스트
+npm run test:search      # 검색 기능 테스트
+npm run test:forgetting  # 망각 정책 테스트
+npm run test:performance # 성능 벤치마크
+```
+
+### Docker 명령어
+```bash
+npm run docker:dev       # 개발용 Docker 실행
+npm run docker:prod      # 프로덕션용 Docker 실행
+npm run docker:build     # Docker 이미지 빌드
+npm run docker:logs      # Docker 로그 확인
+```
+
+### 유틸리티 명령어
+```bash
+npm run setup            # 자동 설정 실행
+npm run quick-start      # 원클릭 설치 및 실행
+npm run backup:embeddings # 임베딩 백업
+npm run regenerate:embeddings # 임베딩 재생성
+```
+
+## 🌐 접속 정보
+
+설치 완료 후 다음 주소로 접속할 수 있습니다:
+
+- **MCP 서버**: `stdio` 또는 `ws://localhost:8080/mcp`
+- **HTTP API**: `http://localhost:8080`
+- **WebSocket**: `ws://localhost:8080`
+- **관리 대시보드**: `http://localhost:8080/admin`
+
+## 🚨 문제 해결
+
+### 일반적인 문제들
+
+#### 1. Node.js 버전 오류
+```bash
+# Node.js 20 이상 필요
+node --version
+
+# nvm으로 Node.js 설치 (Linux/macOS)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 20
+nvm use 20
+```
+
+#### 2. 포트 충돌
+```bash
+# 포트 8080이 사용 중인 경우
+# .env 파일에서 PORT 변경
+PORT=8081
+```
+
+#### 3. 데이터베이스 오류
+```bash
+# 데이터베이스 재초기화
+rm -rf data/memory.db*
+npm run db:init
+```
+
+#### 4. Docker 오류
+```bash
+# Docker 컨테이너 완전 정리
+docker-compose down -v
+docker system prune -a
+docker-compose up -d
+```
+
+### 로그 확인
+```bash
+# 애플리케이션 로그
+tail -f logs/memento-server.log
+
+# Docker 로그
+docker-compose logs -f
+
+# 시스템 로그 (Linux)
+journalctl -u memento-mcp-server -f
+```
+
+## 📞 지원
+
+- **이슈 리포트**: [GitHub Issues](https://github.com/jee1/memento/issues)
+- **문서**: [Wiki](https://github.com/jee1/memento/wiki)
+- **개발자 가이드**: [docs/developer-guide.md](docs/developer-guide.md)
+- **API 참조**: [docs/api-reference.md](docs/api-reference.md)
+
+## 🎉 설치 완료!
+
+설치가 완료되면 다음 단계를 진행하세요:
+
+1. **서버 상태 확인**: `http://localhost:8080/health`
+2. **MCP 클라이언트 연결**: [클라이언트 가이드](packages/mcp-client/README.md)
+3. **API 테스트**: [API 문서](docs/api-reference.md)
+4. **사용법 학습**: [사용자 매뉴얼](docs/user-manual.md)
+
+---
+
+**💡 팁**: 처음 사용하시는 경우 `npm run quick-start` 명령어로 모든 설정을 자동으로 완료할 수 있습니다!

package/README.en.md

@@ -0,0 +1,330 @@
+# Memento MCP Server
+
+<div align="center">
+  <img src="static/logo.png" alt="Memento Logo" width="200" height="200">
+  
+  [🇰🇷 한국어](README.md) | [🇺🇸 English](README.en.md)
+</div>
+
+AI Agent Memory Assistant MCP Server - Storage+Search+Summary+Forgetting mechanisms modeled after human memory structure
+
+## 🎯 Project Overview
+
+Memento MCP Server is a Model Context Protocol (MCP) server that helps AI Agents store and manage long-term memory. It simulates human memory structure (working memory, episodic memory, semantic memory, procedural memory) to provide an efficient memory management system.
+
+## ✨ Key Features
+
+### 🧠 Core Memory Management (MCP Client)
+- **Memory Storage**: Store 4 types of memories (working, episodic, semantic, procedural)
+- **Memory Search**: Hybrid search (text + vector)
+- **Memory Pinning**: Pin/unpin important memories
+- **Memory Deletion**: Soft/hard deletion
+
+### 🔍 Advanced Search
+- **FTS5 Text Search**: SQLite's Full-Text Search
+- **Vector Search**: OpenAI embedding-based semantic search
+- **Hybrid Search**: Combination of text and vector search
+- **Lightweight Embedding**: TF-IDF + keyword matching based fallback solution
+- **Tag-based Filtering**: Metadata-based search
+
+### 🧹 Forgetting Policy
+- **Forgetting Algorithm**: Forgetting score calculation based on recency, usage, duplication ratio
+- **Spaced Repetition**: Review scheduling based on importance and usage
+- **TTL Management**: Type-specific lifespan management
+- **Auto Cleanup**: Automated soft/hard deletion
+
+### 📊 Performance Monitoring (HTTP Management API)
+- **Real-time Metrics**: Database, search, memory performance monitoring
+- **Real-time Alerts**: Automatic performance checks every 30 seconds with threshold-based alerts
+- **Error Logging**: Structured error logging and statistics collection
+- **Database Optimization**: Automatic index recommendation and creation
+- **Cache System**: LRU + TTL based caching
+- **Async Processing**: Worker pool based parallel processing
+
+## 🚀 Quick Start
+
+### 🥇 **One-click Installation (Recommended)**
+```bash
+# Run automatic installation script
+curl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash
+```
+
+### 🥈 **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
+```
+
+### 🥉 **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
+```
+
+### 🛠️ **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
+```
+
+### 📚 **Detailed Installation Guide**
+For detailed installation methods, see [INSTALL.en.md](INSTALL.en.md).
+
+## 🛠️ Usage
+
+### MCP Client Connection
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+
+const client = new Client({
+  name: "memento-client",
+  version: "0.1.0"
+}, {
+  capabilities: {
+    tools: {},
+    resources: {},
+    prompts: {}
+  }
+});
+
+// stdio connection
+await client.connect({
+  command: "node",
+  args: ["dist/server/index.js"]
+});
+
+// WebSocket connection
+await client.connect({
+  transport: {
+    type: "websocket",
+    url: "ws://localhost:8080/mcp"
+  }
+});
+```
+
+### Memory Storage
+
+```typescript
+// Store memory
+const result = await client.callTool({
+  name: "remember",
+  arguments: {
+    content: "I learned about React Hooks. useState manages state and useEffect handles side effects.",
+    type: "episodic",
+    tags: ["react", "hooks", "javascript"],
+    importance: 0.8
+  }
+});
+```
+
+### Memory Search
+
+```typescript
+// Search memory
+const results = await client.callTool({
+  name: "recall",
+  arguments: {
+    query: "React Hook",
+    filters: {
+      type: ["episodic", "semantic"],
+      tags: ["react"]
+    },
+    limit: 10
+  }
+});
+```
+
+## 📋 API Documentation
+
+### MCP Tools (Core 5 Only)
+
+> **Important**: MCP client only exposes 5 core memory management functions.  
+> Management functions are separated into HTTP API endpoints.
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `remember` | Store memory | content, type, tags, importance, source, privacy_scope |
+| `recall` | Search memory | query, filters, limit |
+| `pin` | Pin memory | memory_id |
+| `unpin` | Unpin memory | memory_id |
+| `forget` | Delete memory | memory_id, hard |
+
+### HTTP Management API
+
+| Endpoint | Description | Method |
+|----------|-------------|--------|
+| `/admin/memory/cleanup` | Memory cleanup | POST |
+| `/admin/stats/forgetting` | Forgetting statistics | GET |
+| `/admin/stats/performance` | Performance statistics | GET |
+| `/admin/stats/errors` | Error statistics | GET |
+| `/admin/errors/resolve` | Resolve errors | POST |
+| `/admin/alerts/performance` | Performance alerts | GET |
+| `/admin/database/optimize` | Database optimization | POST |
+
+### Resources
+
+| Resource | Description |
+|----------|-------------|
+| `memory/{id}` | Single memory detail |
+| `memory/search?query=...` | Search result cache |
+
+## 🔧 Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NODE_ENV` | development | Runtime environment |
+| `PORT` | 8080 | Server port |
+| `DB_PATH` | ./data/memory.db | Database path |
+| `LOG_LEVEL` | info | Log level |
+| `OPENAI_API_KEY` | - | OpenAI API key (optional) |
+
+### Forgetting Policy Configuration
+
+```bash
+# Forgetting thresholds
+FORGET_THRESHOLD=0.6
+SOFT_DELETE_THRESHOLD=0.6
+HARD_DELETE_THRESHOLD=0.8
+
+# TTL settings (in days)
+TTL_SOFT_WORKING=2
+TTL_SOFT_EPISODIC=30
+TTL_SOFT_SEMANTIC=180
+TTL_SOFT_PROCEDURAL=90
+```
+
+## 🧪 Testing
+
+```bash
+# Run all tests (Vitest)
+npm run test
+
+# Run individual tests
+npm run test:client                    # Client tests
+npm run test:search                    # Search functionality tests
+npm run test:embedding                 # Embedding functionality tests
+npm run test:lightweight-embedding     # Lightweight embedding tests
+npm run test:forgetting                # Forgetting policy tests
+npm run test:performance               # Performance benchmarks
+npm run test:monitoring                # Performance monitoring tests
+npm run test:error-logging             # Error logging tests
+npm run test:performance-alerts        # Performance alert tests
+
+# Test watch mode
+npm run test -- --watch
+
+# Tests with coverage
+npm run test -- --coverage
+```
+
+## 📚 Developer Guidelines
+
+### Repository Guidelines (`AGENTS.md`)
+- **Project Structure**: Module organization under `src/`
+- **Build/Test Commands**: `npm run dev`, `npm run build`, `npm run test`, etc.
+- **Coding Style**: Node.js ≥ 20, TypeScript ES modules, 2-space indentation
+- **Testing Guidelines**: Vitest based, `src/test/` or `*.spec.ts` files
+- **Commit/PR Guidelines**: Conventional Commits, Korean context included
+- **Environment/Database**: `.env` configuration, `data/` folder management
+
+## 📊 Performance Metrics
+
+### Basic Performance
+- **Database Performance**: Average query time 0.16-0.22ms
+- **Search Performance**: 0.78-4.24ms (improved with cache effects)
+- **Memory Usage**: 11-15MB heap usage
+- **Concurrent Connections**: Supports up to 1000 connections
+
+### Advanced Performance Optimization
+- **Cache Hit Rate**: 80%+ (search result caching)
+- **Embedding Caching**: 24-hour TTL for cost savings
+- **Async Processing**: Worker pool based parallel processing
+- **Database Optimization**: Automatic index recommendation and creation
+- **Real-time Monitoring**: Automatic performance checks every 30 seconds
+- **Error Logging**: Structured error tracking and statistics
+- **Performance Alerts**: Threshold-based automatic alert system
+
+### Lightweight Embedding Performance
+- **TF-IDF Vectorization**: Fixed 512-dimensional vector generation
+- **Multilingual Support**: Korean/English stopword removal
+- **Local Processing**: Works without OpenAI API
+- **Cosine Similarity**: Fast vector search
+
+## 🏗️ Architecture
+
+### M1: Personal Use (Current Implementation)
+- **Storage**: better-sqlite3 embedded
+- **Index**: FTS5 + sqlite-vss
+- **Authentication**: None (local only)
+- **Operation**: Local execution
+- **MCP Client**: Only exposes 5 core tools
+- **Management Functions**: Separated into HTTP API
+- **Additional Features**: Lightweight embedding, performance monitoring, cache system
+
+### M2: Team Collaboration (Planned)
+- **Storage**: SQLite server mode
+- **Authentication**: API Key
+- **Operation**: Docker single container
+
+### M3: Organization Entry (Planned)
+- **Storage**: PostgreSQL + pgvector
+- **Authentication**: JWT
+- **Operation**: Docker Compose
+
+## 🤝 Contributing
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'feat: add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+### Development Environment Setup
+```bash
+# Fork and clone repository
+git clone https://github.com/your-username/memento.git
+cd memento
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Run tests
+npm run test
+```
+
+## 📄 License
+
+This project is distributed under the MIT License. See the `LICENSE` file for details.
+
+## 📞 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)
+
+## 🙏 Acknowledgments
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP Protocol
+- [OpenAI](https://openai.com/) - Embedding Service
+- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) - High-performance SQLite driver
+- [Express](https://expressjs.com/) - Web framework
+- [Vitest](https://vitest.dev/) - Testing framework
+- [TypeScript](https://www.typescriptlang.org/) - Development language