memento-mcp-server 1.6.0 → 1.7.1

package/docs/en/user-manual.md

@@ -1,595 +0,0 @@
-# User Manual
-
-## Overview
-
-This manual explains how to manage AI Agent memory using Memento MCP Server. It is designed for users of all levels, from beginners to advanced users.
-
-## Table of Contents
-
-1. [Getting Started](#getting-started)
-2. [Basic Usage](#basic-usage)
-3. [Advanced Features](#advanced-features)
-4. [Troubleshooting](#troubleshooting)
-5. [FAQ](#faq)
-
-## Getting Started
-
-### Installation
-
-#### M1 (Personal) - Local Installation
-
-```bash
-# Clone repository
-git clone https://github.com/your-org/memento.git
-cd memento
-
-# Install dependencies
-npm install
-
-# Set environment variables
-cp .env.example .env
-# Edit .env file to enter necessary settings
-
-# Initialize database
-npm run db:init
-
-# Start server (hot reload)
-npm run dev
-```
-
-#### M2 (Team) - Docker Installation
-
-```bash
-# Run with Docker Compose
-docker-compose -f docker-compose.team.yml up -d
-
-# Check server status
-curl http://localhost:8080/health
-```
-
-### MCP Client Setup
-
-#### Claude Desktop Setup
-
-1. Open Claude Desktop configuration file:
-   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-
-2. Add MCP server:
-```json
-{
-  "mcpServers": {
-    "memento": {
-      "command": "node",
-      "args": ["path/to/memento/dist/server/index.js"],
-      "env": {
-        "NODE_ENV": "production"
-      }
-    }
-  }
-}
-```
-
-3. Restart Claude Desktop
-
-#### Cursor Setup
-
-1. Add MCP server in Cursor settings
-2. Enter server URL: `ws://localhost:8080/mcp`
-3. Test connection
-
-## Basic Usage
-
-### 1. Storing Memories
-
-You can store important information from conversations with AI Agents as memories.
-
-#### Using the Actually Implemented Client
-
-```typescript
-import { createMementoClient } from './src/client/index.js';
-
-const client = createMementoClient();
-await client.connect();
-
-// Basic storage
-const memoryId = await client.callTool('remember', {
-  content: "User asked about React Hooks and I explained the difference between useState and useEffect."
-});
-
-// Store with tags
-const memoryId = await client.callTool('remember', {
-  content: "Decided to introduce TypeScript in the project.",
-  tags: ['typescript', 'decision', 'project'],
-  importance: 0.8
-});
-
-// Specify memory type
-```
-
-@memento remember "React Hook usage" --type "semantic" --tags "react,hooks,programming"
-```
-
-### 2. Searching Memories
-
-You can search stored memories to find related information. Memento provides basic search and hybrid search.
-
-#### Hybrid Search (Recommended)
-
-Using hybrid search that combines FTS5 text search and vector search provides more accurate results.
-
-```typescript
-// Basic hybrid search (vector 60%, text 40%)
-const result = await client.callTool('hybrid_search', {
-  query: "React Hook usage"
-});
-
-// Adjust weights (increase vector search ratio)
-const result = await client.callTool('hybrid_search', {
-  query: "TypeScript interface",
-  vectorWeight: 0.8,  // Vector search 80%
-  textWeight: 0.2     // Text search 20%
-});
-```
-
-#### Basic Search
-
-```
-@memento recall "React Hook"
-```
-
-#### Advanced Search
-
-```
-@memento recall "TypeScript" --type "episodic,semantic" --tags "programming" --limit 10
-```
-
-#### Time Range Search
-
-```
-@memento recall "project decision" --from "2024-01-01" --to "2024-12-31"
-```
-
-### 3. Using Embedding Features
-
-Memento uses OpenAI's `text-embedding-3-small` model to provide semantic similarity-based search. If OpenAI API is not available, it automatically uses the lightweight hybrid embedding service (TF-IDF + keyword matching).
-
-#### Embedding Feature Setup
-
-1. **Set OpenAI API Key**:
-```bash
-# Add to .env file (optional - uses lightweight embedding if not available)
-OPENAI_API_KEY=your_openai_api_key_here
-```
-
-2. **Test Embedding Service**:
-```bash
-# Test embedding functionality
-npm run test:embedding
-```
-
-#### Benefits of Embedding Features
-
-- **Semantic Search**: Search based on meaning rather than keywords
-- **Synonym Recognition**: Recognizes "car" and "vehicle" as the same meaning
-- **Related Concept Search**: Recognizes "programming" and "coding" as related concepts
-- **Automatic Embedding Generation**: Automatically generates vectors when storing memories
-
-#### Using Embedding Search
-
-```typescript
-// Embeddings are automatically generated when storing memories
-const result = await client.callTool('remember', {
-  content: "Detailed explanation and usage examples of React Hooks",
-  type: 'semantic',
-  tags: ['react', 'hooks', 'javascript']
-});
-
-// Utilize vector search in hybrid search
-const searchResult = await client.callTool('hybrid_search', {
-  query: "React state management",
-  vectorWeight: 0.7,  // Increase vector search ratio
-  textWeight: 0.3
-});
-```
-
-### 4. Managing Memories
-
-#### Pinning Memories
-
-You can pin important memories to protect them from automatic deletion.
-
-```
-@memento pin memory-123
-```
-
-#### Unpinning Memories
-
-```
-@memento unpin memory-123
-```
-
-#### Deleting Memories
-
-```
-@memento forget memory-123
-```
-
-#### Hard Delete
-
-```
-@memento forget memory-123 --hard
-```
-
-## Advanced Features
-
-### 1. Using Forgetting Policy
-
-#### What is Forgetting Policy?
-
-Forgetting policy is a system that manages memory lifespan. It mimics human memory systems by:
-
-- **Automatic Forgetting**: Automatically deleting old and unused memories
-- **Spaced Repetition**: Periodically reviewing important memories to strengthen them
-- **TTL Management**: Applying different lifespan policies by memory type
-
-#### Applying Forgetting Policy
-
-```typescript
-// Apply basic forgetting policy
-const result = await client.callTool('apply_forgetting_policy', {});
-
-console.log('Soft deleted memories:', result.softDeleted);
-console.log('Hard deleted memories:', result.hardDeleted);
-console.log('Memories scheduled for review:', result.scheduledForReview);
-```
-
-#### Custom Forgetting Policy
-
-```typescript
-// Apply forgetting policy with custom settings
-const result = await client.callTool('apply_forgetting_policy', {
-  config: {
-    forgetThreshold: 0.7,        // Forgetting threshold (0.7)
-    softDeleteThreshold: 0.7,    // Soft delete threshold (0.7)
-    hardDeleteThreshold: 0.9,    // Hard delete threshold (0.9)
-    ttlSoft: {
-      working: 3,      // Working memory 3 days
-      episodic: 45,    // Episodic memory 45 days
-      semantic: 200,   // Semantic memory 200 days
-      procedural: 120  // Procedural memory 120 days
-    }
-  }
-});
-```
-
-#### Spaced Repetition Scheduling
-
-```typescript
-// Create review schedule
-const schedule = await client.callTool('schedule_review', {
-  memory_id: 'memory-123',
-  features: {
-    importance: 0.8,        // Importance 80%
-    usage: 0.6,            // Usability 60%
-    helpful_feedback: 0.7, // Helpful feedback 70%
-    bad_feedback: 0.1      // Bad feedback 10%
-  }
-});
-
-console.log('Next review date:', schedule.next_review);
-console.log('Recall probability:', schedule.recall_probability);
-```
-
-### 2. Using HTTP Server
-
-#### What is HTTP Server?
-
-HTTP server is a real-time communication server that supports WebSocket. It is designed for communication with web clients.
-
-#### Starting HTTP Server
-
-```bash
-# Start HTTP server
-npm run dev:http
-
-# Or run directly
-node dist/server/http-server.js
-```
-
-#### WebSocket Connection
-
-```javascript
-// WebSocket connection from web client
-const ws = new WebSocket('ws://localhost:3000');
-
-ws.on('open', () => {
-  console.log('WebSocket connected');
-  
-  // Send MCP message
-  ws.send(JSON.stringify({
-    method: 'tools/call',
-    params: {
-      name: 'remember',
-      arguments: {
-        content: 'Memory stored from web',
-        type: 'episodic'
-      }
-    },
-    id: 'web-1'
-  }));
-});
-
-ws.on('message', (data) => {
-  const response = JSON.parse(data);
-  console.log('Server response:', response);
-});
-```
-
-### 3. Session Summary
-
-You can summarize conversation sessions and store them as memories.
-
-```
-@memento summarize_thread session-456 --importance 0.8
-```
-
-### 4. Creating Memory Relationships
-
-You can set relationships between memories to get better search results.
-
-```
-@memento link memory-123 memory-456 --relation "derived_from"
-```
-
-Available relationship types:
-- `cause_of`: Cause relationship
-- `derived_from`: Derived relationship
-- `duplicates`: Duplicate relationship
-- `contradicts`: Contradiction relationship
-
-### 5. Exporting Memories
-
-You can export stored memories in various formats.
-
-#### JSON Format
-
-```
-@memento export --format json --type "episodic,semantic"
-```
-
-#### CSV Format
-
-```
-@memento export --format csv --tags "programming,react"
-```
-
-#### Markdown Format
-
-```
-@memento export --format markdown --from "2024-01-01"
-```
-
-### 4. Providing Feedback
-
-You can provide feedback on memory usefulness to improve search quality.
-
-```
-@memento feedback memory-123 --helpful true --comment "Very useful information"
-```
-
-## Memory Type Usage
-
-### Working Memory
-
-Temporarily stores currently processing information.
-
-```
-@memento remember "Current bug fix work in progress" --type "working"
-```
-
-- **Features**: Automatically deleted after 48 hours
-- **Usage**: Maintain current work context
-
-### Episodic Memory
-
-Stores events and experiences.
-
-```
-@memento remember "Decisions made in today's meeting" --type "episodic" --tags "meeting,decision"
-```
-
-- **Features**: Automatically deleted after 90 days (if not pinned)
-- **Usage**: Project progress, meeting content, experiences
-
-### Semantic Memory
-
-Stores knowledge and facts.
-
-```
-@memento remember "Basic concepts and usage of React Hooks" --type "semantic" --tags "react,hooks,knowledge"
-```
-
-- **Features**: Preserved indefinitely
-- **Usage**: Technical knowledge, guidelines, rules
-
-### Procedural Memory
-
-Stores methods and procedures.
-
-```
-@memento remember "Docker container deployment procedure" --type "procedural" --tags "docker,deployment,procedure"
-```
-
-- **Features**: Preserved indefinitely
-- **Usage**: Work procedures, setup methods, problem-solving processes
-
-## Tag System
-
-### Tag Naming Rules
-
-- **Language/Technology**: `javascript`, `typescript`, `react`, `docker`
-- **Category**: `programming`, `design`, `meeting`, `decision`
-- **Status**: `todo`, `in-progress`, `completed`, `blocked`
-- **Priority**: `critical`, `important`, `nice-to-have`
-
-### Tag Usage Examples
-
-```
-@memento remember "Project architecture design" --tags "architecture,design,typescript,important"
-```
-
-## Search Tips
-
-### 1. Writing Effective Search Queries
-
-- **Use specific keywords**: "React Hook" > "programming"
-- **Utilize synonyms**: Both "JavaScript" and "JS" are searchable
-- **Include context**: "Project setup" > "setup"
-
-### 2. Using Filters
-
-- **Type filter**: Search only specific memory types
-- **Tag filter**: Search only memories with related tags
-- **Time filter**: Search only memories from specific periods
-
-### 3. Interpreting Search Results
-
-- **Score**: Higher scores indicate higher relevance
-- **recall_reason**: Explanation of why it was retrieved
-- **Tags**: Classification information of the memory
-
-## Troubleshooting
-
-### Common Issues
-
-#### 1. Connection Error
-
-**Symptoms**: Cannot connect to MCP server
-
-**Solutions**:
-1. Check if server is running
-2. Verify port is correct (default: 8080)
-3. Check firewall settings
-
-#### 2. No Search Results
-
-**Symptoms**: No results when searching
-
-**Solutions**:
-1. Try different keywords
-2. Relax filter conditions
-3. Verify memories are actually stored
-
-#### 3. Memory Shortage
-
-**Symptoms**: Server performance degradation, response delays
-
-**Solutions**:
-1. Clean up old memories
-2. Delete unnecessary memories
-3. Check server resources
-
-### Log Checking
-
-#### M1 (Local)
-
-```bash
-# Check server logs
-npm run logs
-
-# Check database status
-npm run db:status
-```
-
-#### M2+ (Docker)
-
-```bash
-# Check container logs
-docker-compose logs memento-server
-
-# Check container status
-docker-compose ps
-```
-
-### Performance Optimization
-
-#### 1. Memory Cleanup
-
-Regularly clean up unnecessary memories:
-
-```bash
-# Clean up old working memories
-@memento forget --type "working" --older-than "2 days"
-
-# Clean up duplicate memories
-@memento cleanup --duplicates
-```
-
-#### 2. Index Optimization
-
-```bash
-# Rebuild search indexes
-@memento optimize --indexes
-```
-
-## FAQ
-
-### Q: Are memories automatically deleted?
-
-A: Yes, memories are automatically deleted based on type:
-- Working memory: After 48 hours
-- Episodic memory: After 90 days (if not pinned)
-- Semantic/Procedural memory: Not automatically deleted
-
-### Q: How to preserve memories permanently?
-
-A: Use the `pin` command to exclude memories from automatic deletion:
-
-```
-@memento pin memory-123
-```
-
-### Q: How to improve search result accuracy?
-
-A: Try these methods:
-1. Use more specific search queries
-2. Add related tags
-3. Provide feedback to improve learning
-
-### Q: How to separate memories from multiple projects?
-
-A: Use tags or project IDs:
-
-```
-@memento remember "Project A related content" --tags "project-a"
-@memento recall "project-a" --tags "project-a"
-```
-
-### Q: Can I share memories with others?
-
-A: Team sharing is available in M2+ version:
-
-```
-@memento remember "Team shared information" --privacy-scope "team"
-```
-
-### Q: How to backup?
-
-A: Use the `export` command to backup:
-
-```bash
-# Full backup
-@memento export --format json > backup.json
-
-# Backup specific period
-@memento export --format json --from "2024-01-01" > backup-2024.json
-```
-
-## Additional Resources
-
-- [API Reference Documentation](api-reference.md)
-- [Developer Guide](developer-guide.md)
-- [Troubleshooting Guide](troubleshooting.md)
-- [GitHub Repository](https://github.com/your-org/memento)
-- [Community Forum](https://github.com/your-org/memento/discussions)