@ever_cheng/memory-task-mcp/README.md

Memory and task management MCP Server

# MCP Memory & Task Management Server

## Overview

This is a complete implementation of a Model Context Protocol (MCP) server, providing memory management, as well as task and progress tracking functionalities. The server adopts a modular design and emphasizes a local-first data storage strategy.

## Features

### Memory & Context Management Module
- **Persistent Memory**: Local JSON file storage to ensure data privacy
- **Semantic Search**: Similarity calculation based on token overlap
- **Tagging System**: Supports memory categorization and filtering

### Task & Progress Tracking Module
- **Task CRUD**: Full lifecycle management for tasks
- **Status Tracking**: todo, in progress, completed, cancelled
- **Priority Management**: Three levels—low, medium, high
- **Progress Notes**: Timestamped progress update records
- **Task Dependencies**: Support for task dependency relationships with `depends_on` field
- **Dependency Validation**: Prevents circular dependencies and validates executable tasks
- **Semantic Linking**: Mechanism to associate tasks with memories

## Installation & Setup

### Quick Start
```bash
# Install globally
npm install -g @ever_cheng/memory-task-mcp

# Or use npx (no installation required)
npx @ever_cheng/memory-task-mcp
```

### Development Setup
```bash
# Clone and install dependencies
git clone <repository-url>
cd MemTask
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

## Test Server (MCP Inspector)

```bash
npx @modelcontextprotocol/inspector npx @ever_cheng/memory-task-mcp
```

## Run Server

```bash
# Development mode
npm run dev

# Production mode
npm run build
npm start

# npx execution (after publishing to npm)
npx @ever_cheng/memory-task-mcp

# local development
npm run build
npm link
memory-task-mcp
```

## Add Memory & Task Management Server to MCP Client

### Using npx (Recommended)
```json
{
  "mcpServers": {
    "memory-task": {
      "command": "npx",
      "args": ["@ever_cheng/memory-task-mcp"],
      "env": {
        "DATA_DIR": "./mcp_data",
        "USER_ID": "default",
        "LOG_PATH": "./logs/mem_task.log",
        "CHROMADB_URL": "http://localhost:8000"
      }
    }
  }
}
```

### Using local installation
```bash
node ./node_modules/@ever_cheng/memory-task-mcp/dist/src/index.js
```

### Environment Variables
- `DATA_DIR`: Directory for storing data files (default: `./mcp_data`)
- `USER_ID`: User identifier for multi-tenant support (default: `default`)
- `LOG_PATH`: Log file path (default: `./logs/mem_task.log`)
- `CHROMADB_URL`: ChromaDB server URL for vector storage (default: `http://localhost:8000`)
- `EMBEDDING_MODELS_PATH`: Path to embedding models (optional, uses smart search if not set)
- `LOG_LEVEL`: Logging level (default: `info`)

## Web Viewer Dashboard

The server includes a web-based monitoring dashboard that provides real-time insights into the system's operations. To access the dashboard:

1. Start the server in development mode: `node web-viewer/server.js --data-dir ./mcp_data`
2. Open your browser to `http://localhost:8080`

The dashboard provides three distinct views:

### List View (Default)
- **System Overview**: Real-time statistics and metrics
- **Task Management**: Complete task listing with expandable details
- **Memory Management**: Browse and search through stored memories

### Kanban Board View
- **Visual Task Flow**: Drag-and-drop style task management
- **Status Columns**: Todo, In Progress, and Completed sections
- **Progress Tracking**: Real-time completion rate visualization
- **Task Cards**: Compact view with priority indicators

### Dependencies View
- **Dependency Visualization**: Clear view of task relationships
- **Status Badges**: Color-coded task IDs showing current status
  - 🔴 Todo: Red badges for pending tasks
  - 🟡 In Progress: Orange badges for active tasks
  - 🟢 Completed: Green badges for finished tasks
  - ⚪ Cancelled: Grey badges for cancelled tasks
- **Blocking Relationships**: Shows which tasks are blocked by dependencies
- **Interactive Details**: Expandable rows with complete task information

![Monitoring Dashboard](image/dashboard.png)  
*Example monitoring interface*

### Kanban Board
![Kanban Board](image/Kanban_Board.png) 

### Dependencies
![Dependencies](image/Dependencies.png) 

### Key Features
- **Real-time Updates**: WebSocket-powered live data synchronization
- **Multi-View Interface**: List, Kanban, and Dependencies views
- **Visual Status Indicators**: Color-coded badges and progress bars
- **Task Relationship Management**: Dependency tracking and validation
- **Interactive UI**: Expandable details and hover effects
- **Responsive Design**: Mobile-friendly interface

> Note: The monitoring page requires the web-viewer component to be running. See the "Run Server" section for startup instructions.

### Project Structure
```
├── src/
│   ├── config.ts             # Configuration management
│   ├── logger.ts             # Logging utilities
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP Server implementation
│   ├── memory.ts             # Memory service + storage
│   ├── task.ts               # Task service + storage
│   ├── utils.ts              # Utility functions
│   └── types.ts              # Type definitions
├── web-viewer/
│   ├── server.js             # Web dashboard server
│   └── public/
│       ├── index.html        # Dashboard HTML
│       ├── app.js            # Frontend JavaScript
│       └── style.css         # Dashboard styles
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # Documentation
```

## MCP Usage Guide

### Memory Management

#### Unified Memory Tool
```json
{
  "tool": "memory_tool",
  "arguments": {
    "operation": "create",
    "content": "Meeting notes: Discussed new product feature planning",
    "summary": "Product feature meeting notes",
    "tags": ["meeting", "product"],
  }
}

{
  "tool": "memory_tool",
  "arguments": {
    "operation": "search",
    "query": "product feature",
    "limit": 5
  }
}

{
  "tool": "memory_tool",
  "arguments": {
    "operation": "list",
    "tags": ["meeting"]
  }
}

{
  "tool": "memory_tool",
  "arguments": {
    "operation": "delete",
    "id": "memory-id"
  }
}
```

### Task Management

#### Unified Task Tool
```json
{
  "tool": "task_tool",
  "arguments": {
    "operation": "create",
    "title": "Complete product prototype",
    "description": "Build the product prototype based on meeting discussions",
    "priority": "high",
    "due_date": "2024-12-31T23:59:59Z",
    "linked_memories": ["memory-id-1", "memory-id-2"],
    "depends_on": ["task-id-1", "task-id-2"]
  }
}

{
  "tool": "task_tool",
  "arguments": {
    "operation": "update",
    "id": "task-id",
    "status": "in_progress",
    "progress_note": "Initial design completed"
  }
}

{
  "tool": "task_tool",
  "arguments": {
    "operation": "read",
    "id": "task-id"
  }
}

{
  "tool": "task_tool",
  "arguments": {
    "operation": "list",
    "status": "in_progress",
    "priority": "high"
  }
}
```


### System Overview

#### Get System Overview
```json
{
  "tool": "overview",
  "arguments": {}
}
```

## Data Formats

### Memory Format
```json
{
  "id": "uuid-string",
  "content": "Memory content",
  "summary": "Memory summary",
  "embedding": [],
  "metadata": {
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "tags": ["tag1", "tag2"],
  }
}
```

### Task Format
```json
{
  "id": "uuid-string",
  "title": "Task title",
  "description": "Task description",
  "status": "todo|in_progress|completed|cancelled",
  "priority": "low|medium|high",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "due_date": "2024-12-31T23:59:59Z",
  "linked_memories": ["memory-id-1", "memory-id-2"],
  "depends_on": ["prerequisite-task-id-1", "prerequisite-task-id-2"],
  "progress_notes": [
    "2024-01-01T00:00:00Z: Progress note 1",
    "2024-01-02T00:00:00Z: Progress note 2"
  ]
}
```

## Integration Recommendations

### Integrating with MCP Client
1. Add this server to the MCP client configuration
2. Use the stdio protocol for communication
3. Manage memories and tasks via tool invocation MCP

### Extension Features
1. **Scheduling**: Add scheduled task reminders
2. **Collaboration**: Multi-user memory and task sharing
3. **Backup & Sync**: Cloud backup and ...

## Performance Optimizations

### Implemented Optimizations
1. **LRU Cache**: Memory cache with size limits and expiration policies
2. **Batch Operations**: Efficient batch processing to reduce database access
3. **Async I/O**: All file operations use asynchronous patterns for better performance
4. **Error Handling**: Unified error handling strategy with detailed error logging

### Future Optimizations
1. **Database** Migration: Option to use SQLite or other databases for larger datasets
2. **Pagination**: Add pagination support for large result sets
3. **Compression**: Implement data compression for memory storage
4. **Worker Threads**: Use worker threads for CPU-intensive operations

### Task Management Interface
![Task Management Interface](image/tasks.png)   
*Example task management interface*

### Memory Management Interface
![Memory Management Interface](image/memories.png)   
*Example memory management interface*


## Development Guidelines

### Code Structure
- Follow the three-layer architecture: Storage Layer, Service Layer, and MCP Layer
- Each class should have a single responsibility
- Use dependency injection for better testability

### TypeScript Best Practices
- Use strict typing and avoid `any` where possible
- Define interfaces for all MCP parameters and return values
- Use generics for reusable components

### Testing
- Unit tests for all services and utilities
- Integration tests for MCP endpoints
- Run tests with `npm test`