# Web Dashboard Guide ## Current dashboard changes (v12.5-v12.6) Updated 2026-11-05: - The default theme follows the system color scheme; an explicit light or dark choice takes precedence. - The interface has ten language catalogs, including Russian, Hindi, Indonesian and Brazilian Portuguese. Search counts, dialogs, analytics, credentials and graph controls now follow the selected language. - Delta-sync status shows peers, cursors, cycle results and errors. SSE updates refresh the dashboard, with a 30-second fallback. - Memory Growth is a line chart of the running total over the selected period. The screenshots and version-labelled walkthrough below describe earlier releases. See the [release notes](https://github.com/doobidoo/mcp-memory-service/releases/tag/v12.6.0) for current behavior. **Version:** 9.3.0 **Status:** Production-ready since v7.2.2 **URL:** http://127.0.0.1:8000/ (HTTP) or https://localhost:8000/ (HTTPS) > **📸 Dashboard Tour GIF:** See the dashboard in action with our [animated tour](images/dashboard/mcp-memory-dashboard-v9.3.0-tour.gif) --- ## 📋 Overview The MCP Memory Service Web Dashboard is a production-ready, interactive web interface providing complete memory management capabilities with excellent performance. Built with FastAPI backend and vanilla JavaScript frontend, it offers real-time updates, semantic search, and comprehensive CRUD operations. ### ✨ Key Features - **Complete CRUD Operations** - Create, read, update, delete memories with intuitive UI - **Advanced Search** - Semantic search, tag-based filtering, and time-based queries - **Real-time Updates** - Server-Sent Events (SSE) with 30-second heartbeat - **Document Ingestion** - Upload PDF, DOCX, PPTX, TXT, MD files with automatic chunking - **Bulk Operations** - Delete by tag, cleanup duplicates, date-based deletion - **Analytics Dashboard** - Memory growth charts, tag usage, and activity reports - **Mobile Responsive** - CSS breakpoints for mobile (768px) and tablet (1024px) - **Security** - XSS protection via `escapeHtml()` throughout frontend - **Themes** - Light/dark mode toggle with persistent preferences - **Quality Analytics** - AI-powered memory quality scoring and visualization (NEW in v9.0) - **Multi-language Support** - English, German, Spanish, French, Japanese, Korean, Chinese ### 📊 Performance Benchmarks (Validated v7.2.2) | Component | Target | Actual | Status | |-----------|--------|--------|--------| | Page Load | <2s | 25ms | ✅ EXCELLENT | | Memory Operations | <1s | 26ms | ✅ EXCELLENT | | Tag Search | <500ms | <100ms | ✅ EXCELLENT | | Large Dataset | 1000+ | 994+ tested | ✅ EXCELLENT | --- ## 🚀 Quick Start ### Prerequisites - MCP Memory Service installed (see [Installation Guide](./01-Installation-Guide)) - HTTP server enabled in configuration ### Starting the Dashboard **Option 1: Command Line** ```bash # Start with HTTP server enabled uv run memory server --http # Access dashboard open http://127.0.0.1:8000/ ``` **Option 2: Environment Variable** ```bash # Add to .env file export MCP_HTTP_ENABLED=true export MCP_HTTP_PORT=8000 # Start server uv run memory server ``` **Option 3: Background Service (Linux)** ```bash # Start systemd service systemctl --user start mcp-memory-http.service # Check status systemctl --user status mcp-memory-http.service # View logs journalctl --user -u mcp-memory-http.service -f ``` ### First-Time Setup 1. **Access Dashboard** - Navigate to http://127.0.0.1:8000/ 2. **Verify Connection** - Check "Connected" indicator in footer 3. **Check Stats** - Dashboard shows total memories, weekly count, and tags 4. **Test Search** - Use quick search bar to find existing memories 5. **Explore Tabs** - Navigate through all 8 dashboard sections (Dashboard, Search, Browse, Documents, Manage, Analytics, Quality, API Docs) --- ## 🎯 Dashboard Features ### 1. Dashboard Tab **Purpose:** Overview and quick access to recent memories ![Dashboard Tab](images/dashboard/01-dashboard.gif) **Layout:** - **Header Section** - Version badge (v9.3.0) - Quick search bar - Add Memory button - Theme toggle (light/dark mode) - Settings button - **Stats Cards** - Total Memories - Overall count - This Week - Memories created in last 7 days - Tags - Total unique tags across all memories - **Sync Status** (Hybrid Backend only) - ✅ Synced indicator - Last sync timestamp - ⚡ Sync Now button for manual sync - **Recent Memories List** - Shows last 10-20 memories - Date, content preview, tags - Memory type indicators (note, release, milestone, etc.) - Click any memory for detailed view - **Quick Actions** - Advanced Search - Navigate to Search tab - Add Memory - Open creation modal - Browse Tags - Navigate to Browse tab - Export Data - Download all memories (JSON format) **Usage:** ```javascript // Dashboard auto-loads on page load // Real-time updates via SSE keep memory list fresh // Click any memory card to view/edit/delete ``` --- ### 2. Search Tab **Purpose:** Advanced search with multiple query types ![Search Tab](images/dashboard/02-search.gif) **Search Capabilities:** **a) Semantic Search** (Default) ```bash # Natural language queries "database configuration from last week" "bug fixes related to authentication" "deployment instructions for production" ``` - Uses vector similarity (embedding-based) - Finds conceptually similar memories - Results ranked by relevance score **b) Tag-Based Search** ```bash # Filter by specific tags "v8.9.0 release milestone" "troubleshooting cloudflare" "configuration hybrid-backend" ``` - Exact tag matching - Supports multiple tags (AND logic) - Shows tag counts **c) Time-Based Search** ```bash # Natural language time expressions "yesterday" "last week" "this month" "2 days ago" "October 2025" ``` - Natural time parsing - Combines with semantic search - Date range filtering **Search Interface:** - **Search Input** - Type query, live suggestions - **Search Type Selector** - Semantic / Tag / Time - **Results Limit** - Configurable (default: 10) - **Sort Options** - Relevance / Date / Alphabetical - **Filter Panel** - Refine by tags, dates, memory types **Search Results Display:** - Relevance score (0-100%) - Memory content with highlighting - Tags (clickable for filtering) - Created/modified timestamps - Quick actions (view, edit, delete, share) **Keyboard Shortcuts:** - `Ctrl/Cmd + K` - Focus search - `Enter` - Execute search - `Esc` - Clear search - `↑/↓` - Navigate results --- ### 3. Browse Tab **Purpose:** Visual tag exploration and filtering ![Browse Tab](images/dashboard/03-browse.gif) **Features:** **Tag Cloud** - **Visual Representation** - Tag size = usage frequency - **Interactive** - Click any tag to filter memories - **Color Coding** - Categories by memory type - **Hover Info** - Shows exact count **Tag Statistics:** ``` important (245 memories) configuration (183 memories) troubleshooting (156 memories) release (89 memories) documentation (67 memories) ``` **Tag Management:** - **Search Tags** - Filter tag cloud - **Sort Options** - Alphabetical / Usage / Recent - **Tag Actions** - Click to filter, right-click for options **Filtered View:** - Shows all memories with selected tag - Supports multi-tag selection (AND/OR logic) - Clear filters button - Breadcrumb navigation **Use Cases:** - Explore what you've stored - Discover related topics - Find memories by category - Understand your knowledge graph --- ### 4. Documents Tab **Purpose:** Upload and ingest documents into memory ![Documents Tab](images/dashboard/04-documents.gif) **Supported Formats:** | Format | Parser | Quality | Features | |--------|--------|---------|----------| | **PDF** | LlamaParse/PyPDF2 | Excellent | OCR, tables, images | | **DOCX** | LlamaParse | Excellent | Formatting, styles | | **PPTX** | LlamaParse | Excellent | Slides, notes | | **TXT** | Built-in | Perfect | Plain text | | **MD** | Built-in | Perfect | Markdown | **Upload Interface:** **Drag-and-Drop Zone** ``` ┌─────────────────────────────────────┐ │ 📁 Drag files here or click browse │ │ │ │ Supports: PDF, DOCX, PPTX, TXT, MD│ │ Max size: 50MB per file │ └─────────────────────────────────────┘ ``` **Upload Options:** - **Processing Mode** - Batch (default) - Upload all at once - Individual - Process one by one (500ms delay) - **Chunk Settings** - Chunk Size: 1000 characters (configurable) - Overlap: 200 characters (maintains context) - **Tagging** - Auto-tags: `document`, file extension, filename - Custom tags: Add your own (comma-separated) - **Metadata** - Preserve file info, page numbers - Extraction method (LlamaParse/native) - Upload timestamp **Upload Process:** 1. Select files (drag-and-drop or browse) 2. Review file list with previews 3. Configure processing options 4. Click "Upload & Process" 5. Monitor progress bar and status 6. View upload history **Upload History:** ``` document.pdf (1.2 MB) - Oct 27, 2025 15:30 ├─ Status: ✅ Completed ├─ Chunks: 45 memories created ├─ Tags: document, pdf, technical-spec └─ Duration: 8.3 seconds presentation.pptx (3.4 MB) - Oct 27, 2025 14:15 ├─ Status: ✅ Completed ├─ Chunks: 23 memories created ├─ Tags: document, pptx, quarterly-review └─ Duration: 12.1 seconds ``` **Document Chunking Strategy:** - Respects paragraph/sentence boundaries - Maintains semantic coherence - Overlaps for context continuity - Preserves formatting where possible **Semtools Integration:** If [semtools](https://github.com/run-llama/semtools) is installed: ```bash # Install for enhanced quality npm i -g @llamaindex/semtools # Optional: LlamaParse API key for best results export LLAMAPARSE_API_KEY="llx-..." ``` **Benefits:** - Superior OCR quality for scanned PDFs - Better table extraction - DOCX/PPTX support - Graceful fallback to native parsers if unavailable --- ### 5. Manage Tab **Purpose:** Bulk operations and database maintenance ![Manage Tab](images/dashboard/05-manage.gif) **Bulk Delete Operations:** **a) Delete by Tag** ```bash # Select tag from dropdown Tag: [test ▼] # Shows impact Will delete: 127 memories # Confirm and execute [Delete Memories with Tag] ``` **b) Cleanup Duplicates** ```bash # Detects exact duplicates (content hash) Found: 43 duplicate memories # Removes duplicates, keeps oldest [Remove Duplicates] ``` **c) Delete by Date** ```bash # Date picker Delete before: [2025-01-01] # Shows impact Will delete: 892 memories older than Jan 1, 2025 # Confirm and execute [Delete Old Memories] ``` **d) Delete by Date Range** ```bash # Date range picker From: [2024-01-01] To: [2024-12-31] # Optional tag filter Tag: [archive ▼] (optional) # Confirm and execute [Delete Range] ``` **Tag Management:** **Rename Tag** ```bash # Old tag → New tag [bug-fix] → [bugfix] # Updates all memories with this tag Updates: 156 memories [Rename Tag] ``` **Merge Tags** ```bash # Merge multiple tags into one Tags to merge: [documentation, docs, wiki] Target tag: [documentation] # Combines all into target Affects: 234 memories [Merge Tags] ``` **Database Operations:** **Optimize Database** ```bash # Vacuum, reindex, analyze Current size: 7.77 MB Estimated savings: ~0.8 MB [Optimize Now] ``` **Rebuild Index** ```bash # Rebuild vector embeddings Total memories: 1717 Estimated time: ~5 minutes [Rebuild Index] ``` **Safety Features:** - Confirmation dialog for all bulk operations - Shows impact before execution - Transaction rollback on error - Operation logging for audit trail --- ### 6. Analytics Tab **Purpose:** Insights and visualizations ![Analytics Tab](images/dashboard/06-analytics.gif) **✨ Complete Analytics Implementation (v8.10.0):** All analytics features are now fully implemented! See the complete dashboard below: ![Complete Analytics Dashboard](images/dashboard/06-analytics.gif) **Overview Metrics:** ``` ┌─────────────┬────────────┬─────────────┬────────────┐ │ Total │ This Week │ Unique Tags │ DB Size │ │ 1717 │ 75 │ 2588 │ 7.77 MB │ └─────────────┴────────────┴─────────────┴────────────┘ ``` **Charts & Visualizations:** **a) Memory Growth Chart** ``` Line chart showing memory creation over time Y-axis: Number of memories X-axis: Date (last 30/90/365 days) Features: - Trend line - Daily/weekly/monthly aggregation - Zoom and pan - Hover for details ``` **b) Tag Usage Distribution** ``` Bar chart showing most-used tags Top 10 Tags: ┌─────────────────┬──────┐ │ configuration │ ████████████████ 183 │ troubleshooting │ ██████████████ 156 │ release │ ████████ 89 │ documentation │ ██████ 67 │ milestone │ █████ 54 └─────────────────┴──────┘ ``` **c) Memory Types Breakdown** ``` Pie chart showing memory type distribution Types: ├─ note: 45% (773) ├─ reference: 22% (378) ├─ release: 12% (206) ├─ troubleshooting: 10% (172) ├─ milestone: 6% (103) └─ other: 5% (85) ``` **d) Activity Heatmap** ``` Calendar heatmap showing daily activity Mon Tue Wed Thu Fri Sat Sun ■■■ ■■■ ■■■ ■■■ ■■■ □ □ ■■■ ■■ ■■■ ■■ ■ □ □ ■■ ■■■ ■■■ ■■■ ■■■ ■ □ Darker = More activity ``` **Reports:** **Top Tags Report** - Most frequently used tags (last 30 days) - Tag co-occurrence patterns - Trending tags (increasing usage) - Unused tags (candidates for cleanup) **Recent Activity Report** - Hourly/daily activity breakdown - Peak usage times - Active days vs quiet days - Streak tracking (consecutive days with activity) **Storage Report** - Total database size - Average memory size - Largest memories - Storage growth trend **Export Options:** - CSV export for all data - Chart images (PNG/SVG) - JSON data dump --- ### 7. Quality Tab (NEW in v9.0) **Purpose:** AI-powered memory quality analytics and scoring ![Quality Tab](images/dashboard/13-quality.gif) **Overview:** The Quality Tab provides comprehensive analytics for memory quality assessment using AI-powered scoring. This helps identify high-value memories and those that might need improvement. **Key Metrics:** ``` ┌─────────────┬────────────┬─────────────┬────────────┬────────────┐ │ Total │ High │ Medium │ Low │ Average │ │ 5,784 │ 950 (≥0.7) │ 4,263 │ 571 (<0.5) │ 0.53 │ └─────────────┴────────────┴─────────────┴────────────┴────────────┘ ``` **Quality Score Distribution Chart:** - Visual histogram showing the distribution of quality scores - Color-coded bars: Green (High ≥0.7), Yellow (Medium 0.5-0.7), Red (Low <0.5) - Helps identify the overall health of your memory database **Quality Scoring Factors:** - **Content Specificity** - How detailed and actionable is the memory? - **Recency** - More recent memories may be more relevant - **Context Relevance** - How well does the memory fit its tags/type? - **Retrieval Frequency** - Frequently accessed memories score higher - **User Ratings** - Manual quality ratings override AI scores **Usage:** ```javascript // Quality scores are calculated automatically on memory creation // Scores range from 0.0 (lowest) to 1.0 (highest) // Use the Quality tab to identify memories that need improvement ``` **Filtering by Quality:** - Click on any quality tier to filter memories - Export low-quality memories for review - Bulk update tags for unreviewed memories --- ### 8. API Docs Tab **Purpose:** REST API reference and testing ![API Docs Tab](images/dashboard/07-api-docs.gif) **API Endpoints Documentation:** **Health Check** ```http GET /api/health Response: { "status": "ok", "version": "8.9.0", "storage": "hybrid", "uptime": 86400 } ``` **Memory CRUD** ```http # Create memory POST /api/memories Body: { "content": "Memory content", "tags": ["tag1", "tag2"] } # Get memory GET /api/memories/{hash} # Update memory PUT /api/memories/{hash} Body: { "content": "Updated content", "tags": ["new-tag"] } # Delete memory DELETE /api/memories/{hash} ``` **Search Endpoints** ```http # Semantic search POST /api/search Body: { "query": "search query", "limit": 10 } # Tag search POST /api/search/by-tag Body: { "tags": ["tag1", "tag2"], "limit": 10 } # Time search POST /api/search/by-time Body: { "query": "last week", "n_results": 10 } ``` **Document Upload** ```http POST /api/documents/upload Content-Type: multipart/form-data Body: file=@document.pdf, tags=doc,pdf ``` **Tag Management** ```http # Get all tags GET /api/tags Response: { "tags": [ {"tag": "important", "count": 245}, {"tag": "reference", "count": 183} ] } ``` **Analytics** ```http GET /api/analytics/overview GET /api/analytics/growth GET /api/analytics/tag-usage GET /api/analytics/memory-types GET /api/analytics/activity-heatmap?days=365 GET /api/analytics/top-tags?period=30d&limit=20 GET /api/analytics/activity-breakdown?granularity=daily GET /api/analytics/storage-stats ``` **Interactive Testing:** - Built-in request builder - Try API calls directly from dashboard - View raw request/response - Copy cURL commands **Authentication:** ```http # If OAuth enabled Authorization: Bearer # If API key enabled X-API-Key: ``` --- ## ⚙️ Advanced Features ### Real-Time Updates (SSE) The dashboard uses Server-Sent Events for live updates: ```javascript // Automatically connects on page load EventSource → /api/events // 30-second heartbeat keeps connection alive ping → pong // Event types: memory_created → Update memory list memory_updated → Refresh specific memory memory_deleted → Remove from display sync_complete → Update sync status (hybrid backend) ``` **Benefits:** - No page refresh needed - Instant updates from other clients - Low overhead (server push) - Automatic reconnection ### Add Memory Modal **Purpose:** Quick memory creation interface ![Add Memory Modal](images/dashboard/08-add-memory-modal.png) **Fields:** - **Content** - Main memory text (required, multiline) - **Tags** - Comma-separated tags for organization - **Memory Type** - note, reference, milestone, etc. - **Metadata** - Additional JSON metadata (optional) **Features:** - Auto-save draft to localStorage - Tag suggestions from existing tags - Character count indicator - Keyboard shortcut: `Ctrl/Cmd + N` - Immediate SSE notification on save ### Settings Modal **Purpose:** System configuration and preferences ![Settings Modal](images/dashboard/09-settings-modal.png) **System Information:** ``` Version: 8.9.0 Backend: hybrid (sqlite-vec + cloudflare) Primary Backend: sqlite-vec Embedding Model: sentence-transformers/all-MiniLM-L6-v2 Embedding Dimension: 384 Database Size: 7.77 MB Total Memories: 1717 Uptime: 1 day, 3 hours ``` **Preferences:** ``` Theme: [Light ▼] [Dark] View Density: [Comfortable ▼] [Compact] [Spacious] Preview Lines: [3 ▼] lines per memory Live Search: [✓] Enable Results per page: [10 ▼] [25] [50] ``` **Keyboard Shortcuts:** ``` Ctrl/Cmd + K - Focus search Ctrl/Cmd + N - New memory Ctrl/Cmd + / - Show shortcuts Esc - Close modals ↑/↓ - Navigate lists Enter - Select/Open ``` ### Dark Mode **Activation:** - Click theme toggle button (sun/moon icon) - Keyboard: `Ctrl/Cmd + D` - Automatically detects system preference **Dashboard in Dark Mode:** ![Dark Mode - Dashboard](images/dashboard/10-dark-mode-dashboard.png) **Search Tab in Dark Mode:** ![Dark Mode - Search](images/dashboard/11-dark-mode-search.png) **Features:** - Smooth transition animation - Persistent preference (localStorage) - All UI elements styled appropriately - Reduced eye strain for night usage --- ### Mobile Responsive Design **Breakpoints:** ```css /* Mobile */ @media (max-width: 768px) { - Single column layout - Hamburger menu - Touch-optimized buttons - Simplified navigation } /* Tablet */ @media (max-width: 1024px) { - Two column layout - Condensed sidebar - Optimized card sizes } /* Desktop */ @media (min-width: 1025px) { - Full multi-column layout - Expanded navigation - Maximum information density } ``` **Touch Gestures:** - Swipe left/right - Navigate tabs - Pull down - Refresh memory list - Pinch to zoom - Charts and images - Long press - Context menu --- ## 🔧 Configuration ### Environment Variables ```bash # HTTP Server export MCP_HTTP_ENABLED=true export MCP_HTTP_PORT=8000 # Default: 8000 export MCP_HTTPS_ENABLED=true # Enable HTTPS export MCP_HTTPS_PORT=8443 # HTTPS port # API Security export MCP_API_KEY="your-secure-key" # API key authentication # CORS (for external clients) export MCP_CORS_ORIGINS="https://example.com,https://app.example.com" # SSE Configuration export MCP_SSE_HEARTBEAT=30 # Heartbeat interval (seconds) export MCP_SSE_RETRY=5000 # Reconnection delay (ms) # Upload Limits export MCP_MAX_UPLOAD_SIZE=52428800 # 50MB default export MCP_MAX_CHUNK_SIZE=1000 # Characters per chunk export MCP_CHUNK_OVERLAP=200 # Overlap for context ``` ### OAuth 2.1 Setup (Optional) ```bash # Enable OAuth export MCP_OAUTH_ENABLED=true export MCP_OAUTH_CLIENT_ID="your-client-id" export MCP_OAUTH_CLIENT_SECRET="your-secret" export MCP_OAUTH_ISSUER="https://auth.example.com" ``` ### Port Configuration **Default Ports:** - HTTP Server: `8000` (API + Dashboard) - HTTPS Server: `8443` (Production) - MCP Server: stdio (no port) **Important:** The dashboard port (8000/8443) is separate from the MCP memory hooks endpoint. If using Claude Code hooks, ensure hooks config uses the correct port. ### SSL/TLS Certificates For HTTPS, provide certificates: ```bash # Certificate paths export MCP_SSL_CERT="/path/to/cert.pem" export MCP_SSL_KEY="/path/to/key.pem" # Or use Let's Encrypt certbot certonly --standalone -d memory.example.com export MCP_SSL_CERT="/etc/letsencrypt/live/memory.example.com/fullchain.pem" export MCP_SSL_KEY="/etc/letsencrypt/live/memory.example.com/privkey.pem" ``` --- ## 🚨 Troubleshooting ### Dashboard Won't Load **Symptom:** Blank page or connection error **Solutions:** ```bash # 1. Check if HTTP server is running curl http://127.0.0.1:8000/api/health # 2. Check server logs journalctl --user -u mcp-memory-http.service -f # 3. Verify port not in use lsof -i :8000 # 4. Restart HTTP server systemctl --user restart mcp-memory-http.service # 5. Check firewall rules sudo ufw status ``` ### Real-Time Updates Not Working **Symptom:** Memory list doesn't update automatically **Solutions:** ```bash # 1. Check SSE connection curl -N http://127.0.0.1:8000/api/events # 2. Check browser console for errors # Open DevTools (F12) → Console tab # 3. Verify SSE not blocked by proxy/firewall # SSE requires persistent connections # 4. Check heartbeat in console # Should see "ping" every 30 seconds ``` ### Upload Fails **Symptom:** Document upload shows error **Solutions:** ```bash # 1. Check file size # Default limit: 50MB export MCP_MAX_UPLOAD_SIZE=104857600 # 100MB # 2. Verify file format supported # Supported: PDF, DOCX, PPTX, TXT, MD # 3. Check semtools installation (for DOCX/PPTX) npm list -g @llamaindex/semtools # 4. Check server logs for parsing errors tail -f ~/.mcp_memory_service/logs/mcp-memory-service.log ``` ### Search Returns No Results **Symptom:** Search query finds nothing **Solutions:** ```bash # 1. Verify memories exist curl http://127.0.0.1:8000/api/health | jq .storage.total_memories # 2. Check search type (semantic vs tag vs time) # Semantic search may need exact terminology # 3. Try broader query # Instead of: "fix bug in auth module" # Try: "authentication" # 4. Rebuild embeddings index # From Manage tab → Rebuild Index ``` ### Performance Issues **Symptom:** Dashboard slow or unresponsive **Solutions:** ```bash # 1. Check database size # Large databases (>10,000 memories) may need optimization curl http://127.0.0.1:8000/api/health | jq .storage.database_size_mb # 2. Optimize database # From Manage tab → Optimize Database # 3. Clear browser cache # DevTools (F12) → Application → Clear Storage # 4. Check system resources top | grep python # 5. Consider hybrid backend for better performance export MCP_MEMORY_STORAGE_BACKEND=hybrid ``` ### OAuth Authentication Fails **Symptom:** 401 Unauthorized errors **Solutions:** ```bash # 1. Verify OAuth configuration curl http://127.0.0.1:8000/api/health | jq .oauth # 2. Check token expiration # Tokens typically expire after 1 hour # 3. Re-authenticate # Dashboard → Settings → Logout → Login # 4. Verify OAuth issuer reachable curl https://auth.example.com/.well-known/openid-configuration ``` --- ## 📚 Use Cases & Examples ### Use Case 1: Project Documentation Repository **Scenario:** Store all project docs for easy AI access **Workflow:** 1. **Upload Documents** → Documents tab - Upload design docs, API specs, meeting notes - Auto-tagged with `documentation`, filenames 2. **Organize with Tags** → Browse tab - Add project-specific tags: `api-design`, `architecture` 3. **Search When Needed** → Search tab - "What was the decision about database schema?" - AI can find relevant context quickly ### Use Case 2: Bug Tracking & Solutions **Scenario:** Remember how you fixed similar bugs **Workflow:** 1. **Document Bug Fix** → Add Memory ``` Content: Fixed authentication timeout issue by increasing JWT expiration from 1h to 24h Tags: bugfix, authentication, jwt, production ``` 2. **Search Similar Issues** → Search tab ``` Query: "authentication timeout" → Finds all related fixes ``` 3. **Build Knowledge Base** → Analytics tab - See most common bug categories - Identify patterns in fixes ### Use Case 3: Development Journal **Scenario:** Track daily development decisions **Workflow:** 1. **Daily Entries** → Add Memory ``` Content: Decided to use Redis for session storage instead of in-memory Reason: Need persistence across restarts Tags: decision, architecture, redis, sessions ``` 2. **Review Weekly** → Search by time ``` Query: "this week" → See all decisions made this week ``` 3. **Analytics** → Analytics tab - Track productivity (memories per day) - Identify busy periods ### Use Case 4: Team Knowledge Sharing **Scenario:** Share knowledge across team members **Workflow:** 1. **Store Best Practices** → Add Memory ``` Content: Always use prepared statements for SQL queries Tags: best-practice, security, sql ``` 2. **Export for Sharing** → Dashboard - Export Data → JSON - Share file with team 3. **Import in Team Members' Instances** - Import memories - Everyone has same knowledge base --- ## 🔗 API Integration Examples ### Python Client ```python import requests BASE_URL = "http://127.0.0.1:8000/api" # Create memory def create_memory(content, tags): response = requests.post( f"{BASE_URL}/memories", json={"content": content, "tags": tags} ) return response.json() # Search memories def search_memories(query, limit=10): response = requests.post( f"{BASE_URL}/search", json={"query": query, "limit": limit} ) return response.json() # Example usage memory = create_memory( "Fixed bug in authentication module", ["bugfix", "authentication"] ) print(f"Created memory: {memory['content_hash']}") results = search_memories("authentication bug") print(f"Found {len(results)} results") ``` ### JavaScript/Node.js Client ```javascript const BASE_URL = "http://127.0.0.1:8000/api"; // Create memory async function createMemory(content, tags) { const response = await fetch(`${BASE_URL}/memories`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({content, tags}) }); return await response.json(); } // Search memories async function searchMemories(query, limit = 10) { const response = await fetch(`${BASE_URL}/search`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({query, limit}) }); return await response.json(); } // Example usage const memory = await createMemory( "Updated API documentation", ["documentation", "api"] ); console.log(`Created memory: ${memory.content_hash}`); const results = await searchMemories("api docs"); console.log(`Found ${results.length} results`); ``` ### cURL Examples ```bash # Health check curl http://127.0.0.1:8000/api/health | jq # Create memory curl -X POST http://127.0.0.1:8000/api/memories \ -H "Content-Type: application/json" \ -d '{ "content": "Memory content here", "tags": ["tag1", "tag2"] }' | jq # Search memories curl -X POST http://127.0.0.1:8000/api/search \ -H "Content-Type: application/json" \ -d '{ "query": "search query", "limit": 10 }' | jq # Get tags curl http://127.0.0.1:8000/api/tags | jq # Upload document curl -X POST http://127.0.0.1:8000/api/documents/upload \ -F "file=@document.pdf" \ -F "tags=document,pdf" | jq ``` --- ## 🎓 Best Practices ### Memory Organization 1. **Use Consistent Tags** ``` Good: ["bugfix", "authentication", "production"] Bad: ["bug", "auth fix", "prod issue"] ``` 2. **Descriptive Content** ``` Good: "Fixed authentication timeout by increasing JWT expiration from 1h to 24h" Bad: "Fixed auth issue" ``` 3. **Tag Hierarchies** ``` General → Specific - project → project-alpha → project-alpha-api - documentation → documentation-api → documentation-api-v2 ``` ### Search Strategies 1. **Start Broad, Then Narrow** - First: "authentication" - Then: "authentication timeout" - Finally: "authentication timeout JWT" 2. **Use Time Filters for Recent** - "last week" for current work - "this month" for recent decisions 3. **Combine Search Types** - Semantic search first (natural language) - Tag filter to narrow down - Time filter for recency ### Document Ingestion 1. **Batch Similar Documents** - Upload related docs together - Use consistent tags for the batch 2. **Optimize Chunk Size** - Technical docs: 1000-1500 characters - Meeting notes: 500-800 characters - Code documentation: 1500-2000 characters 3. **Review Upload History** - Check for failed uploads - Verify chunk counts are reasonable ### Maintenance 1. **Regular Cleanup** - Monthly: Remove duplicates - Quarterly: Delete old test data - Yearly: Archive old projects 2. **Tag Management** - Merge similar tags quarterly - Rename inconsistent tags - Remove unused tags (0 memories) 3. **Database Optimization** - Run optimization monthly - Rebuild index after bulk operations - Monitor database size growth --- ## 📖 Related Documentation - **[Installation Guide](./01-Installation-Guide)** - Setup and configuration - **[Integration Guide](./03-Integration-Guide)** - Connect with AI tools - **[Troubleshooting Guide](./07-TROUBLESHOOTING)** - Common issues and solutions - **[Examples](./09-Examples)** - Practical usage examples - **[API Reference](https://github.com/doobidoo/mcp-memory-service#-api-reference)** - Complete API documentation --- ## 🆘 Getting Help - **GitHub Issues** - [Report bugs or request features](https://github.com/doobidoo/mcp-memory-service/issues) - **Discussions** - [Ask questions and share ideas](https://github.com/doobidoo/mcp-memory-service/discussions) - **Wiki** - [Complete documentation](https://github.com/doobidoo/mcp-memory-service/wiki) --- *This guide documents the Web Dashboard as of v8.9.0. For the latest updates, see the [CHANGELOG](https://github.com/doobidoo/mcp-memory-service/blob/main/CHANGELOG.md).* --- **[MCP Memory Service](https://github.com/doobidoo/mcp-memory-service)** • [🏠 Home](./Home) • [📚 Docs](./01-Installation-Guide) • [🔧 Troubleshooting](./07-TROUBLESHOOTING) • [💬 Discussions](https://github.com/doobidoo/mcp-memory-service/discussions) • [⭐ Star](https://github.com/doobidoo/mcp-memory-service)