@lilith/mcp-task-persistence

MCP server for persisting user prompts across Claude Code sessions, enabling task recovery after crashes or reboots.

Features

• Session Recovery: Recover from crashes, reboots, or lost sessions
• Automatic Task Tracking: Save prompts at session start
• Directory-Based Lookup: Find tasks by working directory
• Conversation History: Append summaries and updates to tasks
• Depth-First Naming: Intuitive file naming for easy identification

Installation

pnpm add @lilith/mcp-task-persistence

Claude Code Configuration

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "task-persistence": {
      "command": "npx",
      "args": ["@lilith/mcp-task-persistence"]
    }
  }
}

Or with a local installation:

{
  "mcpServers": {
    "task-persistence": {
      "command": "node",
      "args": ["/path/to/mcp-task-persistence/dist/index.js"]
    }
  }
}

How It Works

Tasks are stored as text files in ~/.local/claude/tasks/ with depth-first path naming:

~/.local/claude/tasks/
├── 1704067200000_project-Code-lilith-home-var.txt
├── 1704153600000_api-services-myapp-Code-lilith-home-var.txt
└── 1704240000000_frontend-apps-myapp-Code-lilith-home-var.txt

The filename format is: {timestamp}_{reversed-path-components}.txt

This makes it easy to:

• Sort by creation time (timestamp prefix)
• Find tasks by directory (path suffix)
• Identify the most specific directory first (depth-first)

Available Tools

save_task

Save the current prompt at the start of a new task.

{
  prompt: string;           // The user prompt to save
  working_directory: string; // Current working directory
}

Example: Called automatically when starting work on a new task.

resume_task

Resume the most recent task for a working directory. Use after reboot/crash.

{
  working_directory: string; // Current working directory to find task for
}

Trigger phrases: "continue", "resume", "what was I working on"

load_task

Load a specific task by its timestamp ID.

{
  task_id: string; // Task ID (timestamp) to load
}

Trigger phrases: "load task 1704067200000"

complete_task

Mark a task as complete and delete it.

{
  task_id?: string;          // Task ID to complete (optional)
  working_directory?: string; // Directory to find task (optional)
}

Trigger phrases: "task complete", "finished", "done with this"

list_tasks

List all saved tasks with metadata.

// No parameters required

Returns: Task ID, path info, created date, modified date for each task.

append_to_task

Append conversation context to an existing task for better recovery.

{
  content: string;           // The summary or update to append
  type: 'user' | 'summary';  // Content type
  task_id?: string;          // Task ID (optional)
  working_directory?: string; // Directory to find task (optional)
}

Use case: Called periodically to save progress for long-running tasks.

Usage Patterns

Starting a New Task

When the user begins a new task, save it immediately:

User: "Help me implement authentication for the API"
Claude: [Calls save_task with the prompt]

Recovering After Crash

When resuming after a crash or reboot:

User: "continue" or "resume"
Claude: [Calls resume_task with working_directory]
Claude: "Resuming work on authentication implementation..."

Tracking Progress

For long-running tasks, append summaries periodically:

Claude: [After completing a significant step]
Claude: [Calls append_to_task with summary of completed work]

Completing a Task

When the user confirms the task is done:

User: "task complete"
Claude: [Calls complete_task]
Claude: "Task completed and removed."

Task File Format

Task files contain the original prompt plus appended context:

Help me implement authentication for the API

--- SUMMARY --- [2024-01-01T12:00:00.000Z]
Completed JWT token generation and validation.
Added middleware for protected routes.

--- USER --- [2024-01-01T13:00:00.000Z]
Also add refresh token support

--- SUMMARY --- [2024-01-01T14:00:00.000Z]
Added refresh token rotation with 7-day expiry.

Recovery Message Format

When resuming a task, the server provides a structured recovery message:

The session that was working on the following task was lost (likely due to host reboot/crash). Figure out how to continue it.

<task_context>
[Full task content including appended summaries]
</task_context>

API Reference

Types

interface TaskInfo {
  taskId: string;
  pathInfo: string;
  created: Date;
  modified: Date;
}

interface SaveResult {
  taskId: string;
  filename: string;
}

interface LoadResult {
  prompt: string;
  recoveryMessage: string;
}

interface ResumeResult {
  taskId: string;
  content: string;
  recoveryMessage: string;
}

Storage Location

Tasks are stored in:

~/.local/claude/tasks/

This directory is created automatically on first use.

License

MIT