{
  "markdown": "# mindpm\n\n**Persistent project memory for LLMs.** Never re-explain your project again.\n\nmindpm 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.\n\n## The Problem\n\nEvery new LLM chat starts from zero:\n\n- *\"Let me remind you about my project...\"*\n- *\"Last time we decided to use Redis for...\"*\n- *\"Where did we leave off?\"*\n\n## The Solution\n\nmindpm 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.\n\n```\nYou: \"What should I work on next?\"\nLLM: [queries mindpm] \"Last session you finished the auth refactor.\n      You have 3 high-priority tasks: rate limiting, API docs, and\n      the webhook retry bug. Rate limiting is unblocked — start there.\"\n```\n\n## What It Tracks\n\n- **Tasks** — status, priority, blockers, sub-tasks\n- **Decisions** — what was decided, why, what alternatives were rejected\n- **Notes** — architecture, bugs, ideas, research\n- **Context** — key-value pairs (tech stack, conventions, config)\n- **Sessions** — what was done, what's next\n\n## Kanban Board\n\nmindpm includes a built-in Kanban UI. When the MCP server starts, it serves a web interface at `http://localhost:3131`.\n\nEvery `start_session` call returns a direct link to your project's board:\n\n```\nKanban board: http://localhost:3131?project=<project-id>\n```\n\nThe port is configurable via the `MINDPM_PORT` environment variable.\n\n## Session Brief\n\n`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.\n\nEvery `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.\n\nTo get git activity in the brief, tell mindpm where your repo lives:\n\n```\nset_project_repo_path(project: \"my-app\", repo_path: \"/Users/you/code/my-app\")\n```\n\n(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.\n\nExample output:\n\n```jsonc\n{\n  \"project\": \"my-app\",\n  \"degraded\": false,\n  \"degraded_reasons\": [],\n  \"gap\": {\n    \"last_session_ended_at\": \"2026-08-08T22:14:03.000Z\",\n    \"hours_elapsed\": 11.3,\n    \"label\": \"overnight\"\n  },\n  \"handoff\": {\n    \"last_session_summary\": \"Finished the auth refactor\",\n    \"next_steps\": \"Wire up rate limiting, then tackle the webhook retry bug\"\n  },\n  \"git\": {\n    \"available\": true,\n    \"anchor\": \"sha\",\n    \"branch_then\": \"feat/phase-3\",\n    \"branch_now\": \"feat/phase-3\",\n    \"branch_changed\": false,\n    \"commits\": [\n      { \"sha\": \"a1b2c3d\", \"author\": \"umit\", \"date\": \"2026-08-09T09:02:11+00:00\", \"subject\": \"Add rate limit middleware\" }\n    ],\n    \"commit_count\": 4,\n    \"commits_truncated\": false,\n    \"files_changed\": [\n      { \"path\": \"src/middleware/rate-limit.ts\", \"added\": 82, \"deleted\": 11 }\n    ],\n    \"files_changed_truncated\": false,\n    \"working_tree_dirty\": true,\n    \"untracked_count\": 2,\n    \"stash_count\": 0\n  },\n  \"tasks\": {\n    \"changed\": [\n      { \"id\": \"a1b2c3d4\", \"title\": \"Add rate limiting\", \"from_status\": \"in_progress\", \"to_status\": \"done\", \"at\": \"2026-08-09T09:05:00.000Z\" }\n    ],\n    \"in_progress_now\": [{ \"id\": \"e5f6a7b8\", \"title\": \"Webhook retry bug\" }],\n    \"next_suggested\": [{ \"id\": \"c9d0e1f2\", \"title\": \"Write API docs\", \"priority\": \"high\" }]\n  },\n  \"blockers\": [],\n  \"decisions_since\": [\n    { \"id\": \"9f8e7d6c\", \"title\": \"Use token bucket for rate limiting\", \"at\": \"2026-08-09T09:00:00.000Z\" }\n  ],\n  \"notes_since_count\": 3\n}\n```\n\n`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.\n\nThe 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.\n\n## Setup\n\n### Install\n\n```bash\nnpm install -g mindpm\n```\n\nOr run from source:\n\n```bash\ngit clone https://github.com/umitkavala/mindpm.git\ncd mindpm\nnpm install\nnpm run build\n```\n\n### Configure your MCP client\n\nAll 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.\n\n**Claude Code** — `~/.claude/claude_desktop_config.json`\n```json\n{\n  \"mcpServers\": {\n    \"mindpm\": {\n      \"command\": \"mindpm\",\n      \"env\": {\n        \"MINDPM_DB_PATH\": \"~/.mindpm/memory.db\",\n        \"MINDPM_PORT\": \"3131\"\n      }\n    }\n  }\n}\n```\n\nOr use the one-liner:\n```bash\nclaude mcp add mindpm -e MINDPM_DB_PATH=~/.mindpm/memory.db -- npx -y mindpm\n```\n\n**Cursor** — `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` globally)\n```json\n{\n  \"mcpServers\": {\n    \"mindpm\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mindpm\"],\n      \"env\": {\n        \"MINDPM_DB_PATH\": \"~/.mindpm/memory.db\"\n      }\n    }\n  }\n}\n```\n\n**VS Code + Copilot** — `.vscode/mcp.json` in your project root\n```json\n{\n  \"servers\": {\n    \"mindpm\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mindpm\"],\n      \"env\": {\n        \"MINDPM_DB_PATH\": \"~/.mindpm/memory.db\"\n      }\n    }\n  }\n}\n```\n\n**Cline** — Add via VS Code settings → Cline → MCP Servers, or edit `cline_mcp_settings.json`:\n```json\n{\n  \"mcpServers\": {\n    \"mindpm\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mindpm\"],\n      \"env\": {\n        \"MINDPM_DB_PATH\": \"~/.mindpm/memory.db\"\n      }\n    }\n  }\n}\n```\n\n**Windsurf** — Settings → Cascade → MCP, using the same JSON structure as Cline above.\n\n### Using mindpm with any LLM\n\nOn 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.\n\nYou can also call the `get_agent_instructions` tool at any time to retrieve the instructions.\n\n### Start Using\n\nThat's it. The LLM now has access to mindpm tools. Just start talking about your projects.\n\n## MCP Tools\n\n### Projects\n| Tool | Description |\n|------|-------------|\n| `create_project` | Create a new project |\n| `list_projects` | List all projects |\n| `get_project_status` | Full project overview |\n| `set_project_repo_path` | Set/update the project's local git repo path (enables the session brief's git delta) |\n\n### Tasks\n| Tool | Description |\n|------|-------------|\n| `create_task` | Add a task |\n| `update_task` | Update status, priority, etc. |\n| `list_tasks` | List with filters |\n| `get_task` | Full task detail with sub-tasks and notes |\n| `get_next_tasks` | Smart: highest priority, unblocked |\n\n### Decisions\n| Tool | Description |\n|------|-------------|\n| `log_decision` | Record a decision with reasoning |\n| `list_decisions` | Browse decision history |\n\n### Notes & Context\n| Tool | Description |\n|------|-------------|\n| `add_note` | Add a note (architecture, bug, idea, etc.) |\n| `search_notes` | Full-text search |\n| `set_context` | Store key-value context |\n| `get_context` | Retrieve context |\n\n### Sessions\n| Tool | Description |\n|------|-------------|\n| `start_session` | Get full project context + last session's next steps + session brief |\n| `end_session` | Record summary + what to do next time |\n| `get_session_brief` | Read-only: what changed since the last session ended, without opening a session |\n\n### Query\n| Tool | Description |\n|------|-------------|\n| `query` | Read-only SQL against the database |\n| `get_project_summary` | Tasks by status, blockers, recent activity |\n| `get_blockers` | All blocked tasks with what's blocking them |\n| `search` | Full-text search across everything |\n\n## How It Works\n\n```\n┌─────────────┐     MCP      ┌─────────┐     SQLite     ┌──────────┐\n│  Claude Code │ ◄──────────► │ mindpm  │ ◄────────────► │ memory.db│\n│  / Desktop   │   tools      │ server  │   read/write   │          │\n└─────────────┘               └─────────┘                └──────────┘\n```\n\n1. You start a conversation and mention your project\n2. The LLM calls `start_session` → gets full context\n3. During the conversation, it creates tasks, logs decisions, adds notes\n4. When you're done, it calls `end_session` → saves what's next\n5. Next conversation: instant context, zero re-explanation\n\n## Storage\n\nDefault: `~/.mindpm/memory.db`\n\nOverride with `MINDPM_DB_PATH` or `PROJECT_MEMORY_DB_PATH` environment variable.\n\nDatabase and tables are created automatically on first run.\n\n## Development\n\n```bash\nnpm install\nnpm run build       # Build with tsup\nnpm run typecheck   # Type-check without emitting\nnpm run dev         # Build in watch mode\n```\n\n## License\n\nMIT\n",
  "bytes": 9529,
  "sha": "944d334a0a226391bf0af57f5294765dd51d6da5766a71aa1a6b6e6b59940cc6",
  "repo_slug": "umitkavala/mindpm",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_umitkavala_mindpm_9118e28f/readme"
}