openclaw-never-forget-tasks

Multi-agent task tracking and progress reporting — TypeScript + Node, providing both MCP Server and OpenClaw Plugin, designed for a CEO Agent managing multiple specialized agents.

Features

• Track "who needs to do what": CEO assigns tasks with assignee, title, description, due date, etc.
• Task dependencies: predecessor_ids / successor_ids for expressing dependencies and pipelines
• Periodic checks: CEO can pull "incomplete", "overdue", "blocked", "ready to execute" views
• Progress reports: progressReport() and formatReportForAgent() generate readable summaries for reporting and decision-making

Tech Stack

• TypeScript + Node.js (≥20)
• SQLite (better-sqlite3)
• MCP (@modelcontextprotocol/sdk): exposes Tools via stdio for OpenClaw, Cursor, Claude, etc.

Installation

git clone https://github.com/miguoliang/openclaw-never-forget-tasks.git
cd openclaw-never-forget-tasks
npm install

Running as MCP Server (stdio)

# Development
npm run mcp
# Or build first
npm run build && node dist/mcp-server.js

Set the OPENCLAW_TASKS_DB environment variable to specify the SQLite file path (defaults to ~/.openclaw/openclaw_tasks.db).

Add this server to OpenClaw's MCP configuration:

{
  "mcp": {
    "servers": {
      "never-forget-tasks": {
        "command": "node",
        "args": ["/path/to/openclaw-never-forget-tasks/dist/mcp-server.js"]
      }
    }
  }
}

For Cursor and other MCP clients, point to the same command + args.

As OpenClaw Plugin (recommended for OpenClaw users)

No need to run a separate MCP process — install the plugin directly within OpenClaw:

# From the repo root
npm install && npm run build
cd plugin-openclaw && npm install

# Install and enable the plugin (--link for local development)
openclaw plugins install --link /path/to/openclaw-never-forget-tasks/plugin-openclaw
openclaw plugins enable never-forget-tasks

Add never-forget-tasks or specific tool names to your agent's tools.allow. Optionally set dbPath in the OpenClaw plugin config to share the same SQLite DB with MCP; if not set, uses OPENCLAW_TASKS_DB env var or defaults to ~/.openclaw/openclaw_tasks.db.

Quick Start Guide

Prerequisites: OpenClaw installed and openclaw command available; Node.js ≥ 20.

1. Build and install plugin dependencies

cd /path/to/openclaw-never-forget-tasks
npm install && npm run build
cd plugin-openclaw && npm install

2. Install plugin via link (no copy, code changes take effect immediately)

openclaw plugins install --link /path/to/openclaw-never-forget-tasks/plugin-openclaw
openclaw plugins enable never-forget-tasks

3. Verify plugin is loaded

openclaw plugins list
openclaw plugins doctor

You should see never-forget-tasks in the list with no errors.

4. Allow task tools for your agent

In your OpenClaw config (e.g., openclaw.json), add the tool allowlist for the agent that needs task capabilities:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "allow": ["never-forget-tasks"]
        }
      }
    ]
  }
}

Or allow specific tools: ["task_assign", "task_get_progress_report", "task_list_by_assignee", "task_update_status", "task_get", "task_list_overdue", "task_list_blocked"].

5. Start OpenClaw and test

Start OpenClaw and ask the agent: "Assign a task to agent_research with the title 'Test task'." Then: "Show me the current task progress report." If configured correctly, the agent will call task_assign and task_get_progress_report.

6. (Optional) Specify database path

To fix the database location, set dbPath in the plugin config. OpenClaw only recognizes plugins.entries.<id>.enabled and plugins.entries.<id>.config — do not use unsupported keys like sourcePath or installPath:

{
  "plugins": {
    "entries": {
      "never-forget-tasks": {
        "config": { "dbPath": "/your/path/openclaw_tasks.db" }
      }
    }
  }
}

For local plugin paths, use CLI installation (openclaw plugins install --link <path>) or add directories via plugins.load.paths. Without configuration, defaults to OPENCLAW_TASKS_DB env var or ~/.openclaw/openclaw_tasks.db.

Without OpenClaw: Run the MCP Server (npm run mcp) and configure MCP in Cursor/Claude; or run the example script: npx tsx examples/ceo-workflow.ts.

Exposed MCP / Plugin Tools

Tool	Description
task_assign	Assign a task to an agent
task_update_status	Update task status (only assignee can update via requested_by; status_note required for blocked/failed)
task_list_by_assignee	List tasks by assignee
task_get_progress_report	Get progress report summary (for CEO periodic review)
task_list_overdue	List overdue incomplete tasks
task_list_blocked	List tasks blocked by predecessors
task_get	Get task details by ID

As a Library (Node/TS)

Use the store and report logic directly in your own Node/TS code (without MCP):

import { TaskStore } from "./src/store.js";
import { progressReport, formatReportForAgent } from "./src/report.js";

const store = new TaskStore("tasks.db");

// Assign
const t = store.assign({
  assignee: "agent_research",
  title: "Complete market research report",
  description: "Q1 competitive analysis and user needs",
  assigned_by: "ceo_agent",
});

// Update status
store.updateStatus(t.id, "completed");

// Progress report
const report = progressReport(store, {});
const text = formatReportForAgent(store, { language: "en" });
console.log(text);

Example

npx tsx examples/ceo-workflow.ts

Demo: CEO assigns three dependent tasks → simulates research/design completion → views progress report twice (blocked/unblocked changes).

Testing

npm test

Method	Command/Steps	What it verifies
1. Example script (fastest)	npm run build && npm run example	Store + report logic: assign, update, progress, blocked/unblocked
2. MCP Server	npm run mcp, configure MCP in Cursor/Claude, ask AI to call task_assign, task_get_progress_report, etc.	MCP-exposed tools
3. OpenClaw Plugin	Follow the Quick Start Guide above	Plugin-registered Agent Tools
4. Unit tests	npm test	30 tests covering models, store, report

For full-auto multi-agent collaboration roadmap (claimable tasks, reassignment/retry, priority, roles, output passing), see the project website.

Project Structure

openclaw-never-forget-tasks/
├── README.md
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── website/
│   └── index.html         # Project website (GitHub Pages)
├── src/
│   ├── models.ts          # Task types and serialization
│   ├── store.ts           # TaskStore (SQLite)
│   ├── report.ts          # progressReport, formatReportForAgent
│   ├── mcp-server.ts      # MCP Server (stdio)
│   └── __tests__/         # Unit tests
├── plugin-openclaw/       # OpenClaw plugin (in-process Agent Tools)
│   ├── openclaw.plugin.json
│   ├── package.json
│   ├── index.ts           # Registers task_* tools
│   └── tsconfig.json
└── examples/
    └── ceo-workflow.ts    # CEO workflow example

Data Model

Field	Description
id	Unique task ID
assignee	Responsible agent
title / description	Title and description
status	pending / in_progress / completed / blocked / failed / cancelled
status_note	Reason for blocked/failed status, for CEO follow-up
predecessor_ids	Predecessor task IDs
successor_ids	Successor task IDs
due_at	Due date (ISO string)
assigned_by	Assigner (e.g., CEO)

Persistence uses a single SQLite file, suitable for multi-process/multi-agent sharing. The optional status_note field is required when setting status to blocked or failed, and is displayed in progress reports for CEO follow-up.

Troubleshooting

SqliteError: unable to open database file after plugin loads

Default db path is ~/.openclaw/openclaw_tasks.db. If ~/.openclaw/ doesn't exist, SQLite can't create the file. Ensure the directory exists:

mkdir -p ~/.openclaw

Or specify a path in an existing directory via plugin config:

{
  "plugins": {
    "entries": {
      "never-forget-tasks": {
        "config": { "dbPath": "/your/path/openclaw_tasks.db" }
      }
    }
  }
}

tools.allow reports unknown entries (never-forget-tasks)

The plugin didn't load successfully. Check:

1. openclaw plugins list shows never-forget-tasks
2. openclaw plugins doctor has no errors
3. Gateway logs (/tmp/openclaw/openclaw-*.log) — search for never-forget for specific errors

Sharing db between MCP Server and Plugin

Set the OPENCLAW_TASKS_DB environment variable or configure the same dbPath in both to share data.

License

MIT