Skip to content

Web Dashboard Guide

Jump to bottom
doobidoo edited this page Nov 9, 2025 · 5 revisions

Web Dashboard Guide

Version: 8.9.0 Status: Production-ready since v7.2.2 URL: http://127.0.0.1:8000/ (HTTP) or https://localhost:8443/ (HTTPS)

📋 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

📊 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)
  • HTTP server enabled in configuration

Starting the Dashboard

Option 1: Command Line

# Start with HTTP server enabled
uv run memory server --http

# Access dashboard
open http://127.0.0.1:8000/

Option 2: Environment Variable

# 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)

# 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 7 dashboard sections

🎯 Dashboard Features

1. Dashboard Tab

Purpose: Overview and quick access to recent memories

Dashboard Tab

Layout:

  • Header Section

    • Version badge (v8.9.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:

// 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

Search Capabilities:

a) Semantic Search (Default)

# 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

# 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

# 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

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

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 is installed:

# 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

Bulk Delete Operations:

a) Delete by Tag

# Select tag from dropdown
Tag: [test ▼]

# Shows impact
Will delete: 127 memories

# Confirm and execute
[Delete Memories with Tag]

b) Cleanup Duplicates

# Detects exact duplicates (content hash)
Found: 43 duplicate memories

# Removes duplicates, keeps oldest
[Remove Duplicates]

c) Delete by Date

# 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

# 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

# Old tag → New tag
[bug-fix] → [bugfix]

# Updates all memories with this tag
Updates: 156 memories

[Rename Tag]

Merge Tags

# 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

# Vacuum, reindex, analyze
Current size: 7.77 MB
Estimated savings: ~0.8 MB

[Optimize Now]

Rebuild Index

# 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

✨ Complete Analytics Implementation (v8.10.0):

All analytics features are now fully implemented! See the complete dashboard below:

Complete Analytics Dashboard

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. API Docs Tab

Purpose: REST API reference and testing

API Docs Tab

API Endpoints Documentation:

Health Check

GET /api/health
Response: {
  "status": "ok",
  "version": "8.9.0",
  "storage": "hybrid",
  "uptime": 86400
}

Memory CRUD

# 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

# 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

POST /api/documents/upload
Content-Type: multipart/form-data
Body: [email protected], tags=doc,pdf

Tag Management

# Get all tags
GET /api/tags
Response: {
  "tags": [
    {"tag": "important", "count": 245},
    {"tag": "reference", "count": 183}
  ]
}

Analytics

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:

# If OAuth enabled
Authorization: Bearer <token>

# If API key enabled
X-API-Key: <your-key>

⚙️ Advanced Features

Real-Time Updates (SSE)

The dashboard uses Server-Sent Events for live updates:

// 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

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

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

Search Tab in Dark Mode:

Dark Mode - Search

Features:

  • Smooth transition animation
  • Persistent preference (localStorage)
  • All UI elements styled appropriately
  • Reduced eye strain for night usage

Mobile Responsive Design

Breakpoints:

/* 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

# 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)

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

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

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

# 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 "[email protected]" \
  -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

🆘 Getting Help

This guide documents the Web Dashboard as of v8.9.0. For the latest updates, see the CHANGELOG.

MCP Memory Service • 🏠 Home • 📚 Docs • 🔧 Troubleshooting • 💬 Discussions • ⭐ Star

Clone this wiki locally