mindpm

mindpm

Persistent project memory for LLMs. Never re-explain your project again.

mindpm is an MCP (Model Context Protocol) server that gives LLMs a SQLite-backed brain for your projects. It tracks tasks, decisions, architecture notes, and session context — so every new conversation picks up exactly where you left off.

The Problem

Every new LLM chat starts from zero:

• "Let me remind you about my project..."
• "Last time we decided to use Redis for..."
• "Where did we leave off?"

The Solution

mindpm persists your project state in a local SQLite database. The LLM reads and writes to it via MCP tools. No chat history needed. No memory features needed.

You: "What should I work on next?"
LLM: [queries mindpm] "Last session you finished the auth refactor.
      You have 3 high-priority tasks: rate limiting, API docs, and
      the webhook retry bug. Rate limiting is unblocked — start there."

What It Tracks

• Tasks — status, priority, blockers, sub-tasks
• Decisions — what was decided, why, what alternatives were rejected
• Notes — architecture, bugs, ideas, research
• Context — key-value pairs (tech stack, conventions, config)
• Sessions — what was done, what's next

Kanban Board

mindpm includes a built-in Kanban UI. When the MCP server starts, it serves a web interface at http://localhost:3131.

Every start_session call returns a direct link to your project's board:

Kanban board: http://localhost:3131?project=<project-id>

The port is configurable via the MINDPM_PORT environment variable.

Session Brief

get_project_status tells you what you were doing. The session brief tells you what changed while you were away — commits landed, the branch moved, the working tree got dirty, tasks changed status, blockers appeared, a decision was logged.

Every start_session call embeds a brief automatically (pass brief: false to skip it), and you can also fetch one without opening a session via get_session_brief. It's fully deterministic — no LLM calls happen inside mindpm — and it never touches the network: everything comes from local git subprocess calls and the local SQLite database.

To get git activity in the brief, tell mindpm where your repo lives:

set_project_repo_path(project: "my-app", repo_path: "/Users/you/code/my-app")

(or pass repo_path directly to create_project). Without a configured repo, the brief still reports the task/blocker/decision delta — it just skips the git section.

Example output:

{
  "project": "my-app",
  "degraded": false,
  "degraded_reasons": [],
  "gap": {
    "last_session_ended_at": "2026-08-08T22:14:03.000Z",
    "hours_elapsed": 11.3,
    "label": "overnight"
  },
  "handoff": {
    "last_session_summary": "Finished the auth refactor",
    "next_steps": "Wire up rate limiting, then tackle the webhook retry bug"
  },
  "git": {
    "available": true,
    "anchor": "sha",
    "branch_then": "feat/phase-3",
    "branch_now": "feat/phase-3",
    "branch_changed": false,
    "commits": [
      { "sha": "a1b2c3d", "author": "umit", "date": "2026-08-09T09:02:11+00:00", "subject": "Add rate limit middleware" }
    ],
    "commit_count": 4,
    "commits_truncated": false,
    "files_changed": [
      { "path": "src/middleware/rate-limit.ts", "added": 82, "deleted": 11 }
    ],
    "files_changed_truncated": false,
    "working_tree_dirty": true,
    "untracked_count": 2,
    "stash_count": 0
  },
  "tasks": {
    "changed": [
      { "id": "a1b2c3d4", "title": "Add rate limiting", "from_status": "in_progress", "to_status": "done", "at": "2026-08-09T09:05:00.000Z" }
    ],
    "in_progress_now": [{ "id": "e5f6a7b8", "title": "Webhook retry bug" }],
    "next_suggested": [{ "id": "c9d0e1f2", "title": "Write API docs", "priority": "high" }]
  },
  "blockers": [],
  "decisions_since": [
    { "id": "9f8e7d6c", "title": "Use token bucket for rate limiting", "at": "2026-08-09T09:00:00.000Z" }
  ],
  "notes_since_count": 3
}

gap.label is same-day (<6h), overnight (6-20h), multi-day (20h-14d), or stale (>14d) — a stale gap adds a gap.hint telling the agent to re-verify context rather than trust next_steps at face value.

The git delta is anchored on the exact commit sha recorded when the prior session ended (via end_session), not on a timestamp — sha-based anchoring survives rebases and amends that would break a clock-based diff. If that sha becomes unreachable (force-push, rebase, or the repo was pruned), the brief transparently falls back to a timestamp anchor and reports it in degraded_reasons. A broken or missing repo never fails the brief — it just comes back with git.available: false and degraded: true, while the task/blocker/decision delta is unaffected.

Setup

Install

npm install -g mindpm

Or run from source:

git clone https://github.com/umitkavala/mindpm.git
cd mindpm
npm install
npm run build

Configure your MCP client

All clients use the same JSON format — just different config file locations. They all share the same ~/.mindpm/memory.db, so you can switch tools mid-project without losing context.

Claude Code — ~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "mindpm": {
      "command": "mindpm",
      "env": {
        "MINDPM_DB_PATH": "~/.mindpm/memory.db",
        "MINDPM_PORT": "3131"
      }
    }
  }
}

Or use the one-liner:

claude mcp add mindpm -e MINDPM_DB_PATH=~/.mindpm/memory.db -- npx -y mindpm

Cursor — .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally)

{
  "mcpServers": {
    "mindpm": {
      "command": "npx",
      "args": ["-y", "mindpm"],
      "env": {
        "MINDPM_DB_PATH": "~/.mindpm/memory.db"
      }
    }
  }
}

VS Code + Copilot — .vscode/mcp.json in your project root

{
  "servers": {
    "mindpm": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mindpm"],
      "env": {
        "MINDPM_DB_PATH": "~/.mindpm/memory.db"
      }
    }
  }
}

Cline — Add via VS Code settings → Cline → MCP Servers, or edit cline_mcp_settings.json:

{
  "mcpServers": {
    "mindpm": {
      "command": "npx",
      "args": ["-y", "mindpm"],
      "env": {
        "MINDPM_DB_PATH": "~/.mindpm/memory.db"
      }
    }
  }
}

Windsurf — Settings → Cascade → MCP, using the same JSON structure as Cline above.

Using mindpm with any LLM

On first run, mindpm writes ~/.mindpm/AGENT.md — a ready-to-paste system prompt that tells your LLM how to use mindpm proactively. Paste its contents into your client's custom instructions or system prompt box.

You can also call the get_agent_instructions tool at any time to retrieve the instructions.

Start Using

That's it. The LLM now has access to mindpm tools. Just start talking about your projects.

MCP Tools

Projects

Tool	Description
create_project	Create a new project
list_projects	List all projects
get_project_status	Full project overview
set_project_repo_path	Set/update the project's local git repo path (enables the session brief's git delta)

Tasks

Tool	Description
create_task	Add a task
update_task	Update status, priority, etc.
list_tasks	List with filters
get_task	Full task detail with sub-tasks and notes
get_next_tasks	Smart: highest priority, unblocked

Decisions

Tool	Description
log_decision	Record a decision with reasoning
list_decisions	Browse decision history

Notes & Context

Tool	Description
add_note	Add a note (architecture, bug, idea, etc.)
search_notes	Full-text search
set_context	Store key-value context
get_context	Retrieve context

Sessions

Tool	Description
start_session	Get full project context + last session's next steps + session brief
end_session	Record summary + what to do next time
get_session_brief	Read-only: what changed since the last session ended, without opening a session

Query

Tool	Description
query	Read-only SQL against the database
get_project_summary	Tasks by status, blockers, recent activity
get_blockers	All blocked tasks with what's blocking them
search	Full-text search across everything

How It Works

┌─────────────┐     MCP      ┌─────────┐     SQLite     ┌──────────┐
│  Claude Code │ ◄──────────► │ mindpm  │ ◄────────────► │ memory.db│
│  / Desktop   │   tools      │ server  │   read/write   │          │
└─────────────┘               └─────────┘                └──────────┘

1. You start a conversation and mention your project
2. The LLM calls start_session → gets full context
3. During the conversation, it creates tasks, logs decisions, adds notes
4. When you're done, it calls end_session → saves what's next
5. Next conversation: instant context, zero re-explanation

Storage

Default: ~/.mindpm/memory.db

Override with MINDPM_DB_PATH or PROJECT_MEMORY_DB_PATH environment variable.

Database and tables are created automatically on first run.

Development

npm install
npm run build       # Build with tsup
npm run typecheck   # Type-check without emitting
npm run dev         # Build in watch mode

License

MIT