memento-mcp-server 1.30.1-a → 1.30.1

package/INSTALL.en.md

@@ -1,369 +1,165 @@
-# 🚀 Memento MCP Server Installation Guide
+# Memento installation guide
 
 <div align="center">
   [🇰🇷 한국어](INSTALL.md) | [🇺🇸 English](INSTALL.en.md)
 </div>
 
-Provides various installation methods for the AI Agent Memory Assistant MCP Server.
+Pick **one default path** for your role. Product overview: [README.en.md](README.en.md). Full docs: [docs/README.md](docs/README.md).
 
-How you install Memento depends on **how fast you want to try it** and **how much of the stack you want to control**. The one-click script is fastest; npx runs without cloning; Docker fits teams; source is for contributors. Pick a path below and follow it through.
+This project uses **npm** only.
 
-## 📋 Installation Method Selection
+## Default path by role
+
+### Claude Code → plugin
 
-### 🧩 **Claude Code users: install the plugin**
 ```
 /plugin marketplace add jee1/memento
 /plugin install memento@memento
 ```
-This registers the MCP server and ships a skill for the `recall` → `remember` loop. The memory database lives at `${CLAUDE_PLUGIN_DATA}/memory.db` and survives plugin updates.
 
-Four MCP tools are advertised by default: `recall`, `remember`, `memory_injection`, and `feedback`. To reach the rest — anchors, procedural versioning, introspection — add `MEMENTO_TOOLSET=full` to the `memento` server's `env` block in your user or project MCP config (edits to the plugin's own `.mcp.json` are lost on update).
+This registers the MCP server and ships a `recall` → `remember` skill. The memory DB lives at `${CLAUDE_PLUGIN_DATA}/memory.db` and survives plugin updates. Confirm the `memento` MCP server in the `/plugin` panel.
 
-### 🥇 **1st Priority: One-click Installation (Recommended)**
-```bash
-# Run automatic installation script
-curl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash
-```
+Four tools are advertised by default: `recall`, `remember`, `memory_injection`, and `feedback`. To list the rest, set `MEMENTO_TOOLSET=full` on the `memento` server `env` in your user or project MCP config. Edits inside the plugin's own `.mcp.json` are lost on update.
 
-### 🥈 **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 -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/docker-compose.dev.yml up -d
-
-# Production environment
-docker compose -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/docker-compose.prod.yml up -d
-```
+### Cursor and other MCP hosts → npx + mcp.json
 
-### 🛠️ **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 and researchers** usually prefer npx or a source clone so they can debug and patch quickly. **General users** can start with the one-click script or Docker when they mainly want a stable server. **Teams and organizations** should standardize on Docker so everyone runs the same image and the same `memory.db` mount policy.
-
-## 📚 Detailed Installation Methods
-
-### 1. One-click Installation
-
-#### Linux/macOS
-```bash
-curl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash
+npx memento-mcp-server@latest
 ```
 
-#### Windows (PowerShell)
-```powershell
-Invoke-WebRequest -Uri "https://raw.githubusercontent.com/jee1/memento/main/install.sh" -OutFile "install.sh"
-bash install.sh
+```json
+{
+  "mcpServers": {
+    "memento": {
+      "command": "npx",
+      "args": ["memento-mcp-server@latest"],
+      "env": {
+        "DB_PATH": "/absolute/path/to/data/memory.db"
+      }
+    }
+  }
+}
 ```
 
-### 2. npx Method
+Config locations:
 
-#### Basic Usage
-```bash
-# Development mode (hot reload)
-npx memento-mcp-server@latest dev
+- Cursor: `.cursor/mcp.json` or `~/.cursor/mcp.json`
+- Claude Desktop / Claude Code: see the [Cursor MCP setup guide](docs/guides/en/cursor-mcp-setup.md) (includes host paths)
 
-# Production mode
-npx memento-mcp-server@latest start
+For frequent use, prefer `npm i -g memento-mcp-server`. With `npm exec`, name the binary: `npm exec -- memento-mcp-server@latest`.
 
-# HTTP/WebSocket server
-npx memento-mcp-server@latest dev-http
+Official MCP registry name: `io.github.jee1/memento-mcp-server` (`server.json`).
 
-# Auto setup
-npx memento-mcp-server@latest setup
-```
+### Ops / self-hosting → Docker or source
 
-#### Global Installation
-```bash
-# Global installation
-npm install -g memento-mcp-server
+**Docker (teams / production)**
 
-# Usage
-memento-mcp-server dev
-memento-mcp-server start
-memento-mcp-server setup
-```
-
-### 3. Docker Method
-
-#### Development Environment
 ```bash
-# Run development Docker Compose
 docker compose -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/docker-compose.dev.yml up -d
-
-# Check logs
-docker compose -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/docker-compose.dev.yml logs -f
-
-# Stop
-docker compose -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/docker-compose.dev.yml down
-```
-
-#### Production Environment
-```bash
-# Run production Docker Compose
 docker compose -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/docker-compose.prod.yml up -d
-
-# Check logs
-docker compose -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/docker-compose.prod.yml logs -f
-
-# Stop
-docker compose -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/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
-```
+Use the same `-f` file with `logs -f` / `down`. Project name defaults to `memento`; override with `COMPOSE_PROJECT_NAME`.
 
-### 4. Source Code Method
+**Source (contributors / debugging)**
 
-#### 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 build
 npm run db:init
-
-# Run migrations
 npm run db:migrate
+npm run quick-start
 ```
 
-## 🔧 Available Commands
+Or run `npm run setup`, then `npm run dev` / `npm run start`.
 
-### Development Commands
-```bash
-npm run dev              # MCP server development mode
-npm run dev:http         # HTTP/WebSocket server development mode
-```
+**One-click script** (fast local bootstrap)
 
-### Production Commands
 ```bash
-npm run build            # TypeScript compilation
-npm run start            # MCP server production run
-npm run start:http       # HTTP/WebSocket server production run
+curl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash
 ```
 
-### Test Commands
-```bash
-npm run test             # Run all tests
-npm run test:ci:core     # Core search, embedding, and memory tests
-npm run test:ci:server   # Server and monitoring tests
-npm test -w @jee1/memento-client # Client tests
-npm run benchmark:consolidation-quality # Consolidation Score benchmark
-```
+On Windows PowerShell, download the script and run `bash install.sh`.
 
-### 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
-```
+### Multi-agent → one HTTP MCP process
+
+SQLite needs a single writer. Run **one** MCP/HTTP server and point every agent at it.
 
-### 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
+npm run build && npm run start:http
 ```
 
-## 🌐 Access Information
-
-After installation, you can access the following addresses:
-
-- **MCP Server**: `stdio` or `http://localhost:9001/mcp`
-- **HTTP API**: `http://localhost:9001`
-- **WebSocket**: `ws://localhost:9001`
-- **Admin Dashboard**: `http://localhost:9001/dashboard`
-
-## 🪟 Platform-Specific Execution
-
-### Windows
-
-#### PowerShell/CMD
-```powershell
-# npx method (recommended)
-npx memento-mcp-server@latest dev
-npx memento-mcp-server@latest setup
-
-# Using npm exec
-npm exec -- memento-mcp-server@latest dev
-
-# After global installation
-npm install -g memento-mcp-server
-memento-mcp-server dev
+```json
+{
+  "mcpServers": {
+    "memento": {
+      "type": "http",
+      "url": "http://127.0.0.1:9001/mcp"
+    }
+  }
+}
 ```
 
-#### WSL (Windows Subsystem for Linux)
-```bash
-# Same as Linux
-npx memento-mcp-server@latest dev
-```
+See **Ports** below for which number to use.
 
-### Linux/macOS
+## Environment
 
 ```bash
-# npx method (recommended)
-npx memento-mcp-server@latest dev
-npx memento-mcp-server@latest setup
-
-# Using npm exec
-npm exec -- memento-mcp-server@latest dev
-
-# After global installation
-npm install -g memento-mcp-server
-memento-mcp-server dev
+cp env.example .env
 ```
 
-### Platform Differences
+OpenAI and Gemini keys are optional. [env.example](env.example) is the source of truth for variables.
 
-| Item | Windows | Linux/macOS |
-|------|---------|-------------|
-| Path separator | `\` | `/` |
-| Execution permissions | Auto-handled | Requires `chmod +x` |
-| Shebang | Ignored (npm handles) | Used |
-| npm exec | Requires explicit command | Requires explicit command |
-| npx | Recommended | Recommended |
+## Ports
 
-## 🚨 Troubleshooting
+HTTP/MCP ports come in three flavors:
 
-### Common Issues
+- **Code default**: `3000`
+- **Local/Docker recommended profile** ([env.example](env.example)): `MCP_SERVER_PORT=9001` / `PORT=9001`
+- **Docker image default**: `9001` — the `Dockerfile` bakes `PORT=9001` so it matches `EXPOSE`/`HEALTHCHECK`. Override with an environment variable.
 
-#### 1. npm exec Error: "could not determine executable to run"
+URLs in this guide use the **recommended `9001` profile**. If you run with code defaults, read them as `3000`. On conflict, change `PORT` / `MCP_SERVER_PORT` in `.env`.
 
-**Cause**: npm exec requires you to explicitly specify the command to run.
+Recommended-profile examples:
 
-**Solution**:
-```bash
-# ❌ Incorrect usage
-npm exec memento-mcp-server@latest
+- MCP (HTTP): `http://localhost:9001/mcp`
+- HTTP API: `http://localhost:9001`
+- Dashboard: `http://localhost:9001/dashboard`
+- Health: `http://localhost:9001/health`
 
-# ✅ Correct usage
-npm exec -- memento-mcp-server@latest dev
-npm exec -- memento-mcp-server@latest setup
+stdio MCP does not use a port.
 
-# Or use npx (recommended)
-npx memento-mcp-server@latest dev
-```
-
-#### 2. Node.js Version Error
-```bash
-# Node.js 24+ required (package.json engines: >=24)
-node --version
+## Common commands
 
-# Install Node.js with nvm (Linux/macOS)
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
-nvm install 24
-nvm use 24
-```
-
-#### 2. Port Conflict
 ```bash
-# If port 9001 is in use
-# Change PORT / MCP_SERVER_PORT in .env file
-PORT=9002
-```
-
-#### 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
+npm run dev
+npm run start
+npm run dev:http
+npm run start:http
+npm run test
+npm run docker:dev
+npm run docker:prod
 ```
 
-## 📞 Support
+## Troubleshooting (short)
 
-- **Issue Reports**: [GitHub Issues](https://github.com/jee1/memento/issues)
-- **Documentation**: [Wiki](https://github.com/jee1/memento/wiki)
-- **Developer Guide**: [docs/guides/en/developer-guide.md](docs/guides/en/developer-guide.md)
-- **API Reference**: [docs/api/en/api-reference.md](docs/api/en/api-reference.md)
+- **`npm exec` errors**: pass the binary explicitly (`npm exec -- memento-mcp-server@latest …`) or use `npx`.
+- **Node.js**: **≥ 24** per `package.json` engines.
+- **SQLite / native modules**: `npm rebuild better-sqlite3 sqlite-vec`, or see [npx troubleshooting](docs/operations/en/npx-troubleshooting.md).
+- **DB reset**: `npm run db:init` (delete the DB files first if required).
 
-## 🎉 Installation Complete!
+More ops notes: [docs/operations/](docs/operations/).
 
-After installation, proceed with the following steps:
+## Next steps
 
-1. **Check Server Status**: `http://localhost:9001/health`
-2. **Connect MCP Client**: [Client Guide](packages/memento-client/README.md)
-3. **Test API**: [API Documentation](docs/api/en/api-reference.md)
-4. **Learn Usage**: [User Manual](docs/guides/en/user-manual.md)
+1. Confirm the server and MCP connection
+2. [User manual](docs/guides/en/user-manual.md)
+3. [API reference](docs/api/en/api-reference.md)
+4. External assistants: [docs/integrations/](docs/integrations/README.md)
 
----
+## Support
 
-**💡 Tip**: For first-time users, you can complete all setup automatically with the `npm run quick-start` command!
+- Issues: [GitHub Issues](https://github.com/jee1/memento/issues)
+- Docs: [docs/README.md](docs/README.md)