{
  "markdown": "# claude-remind-mcp\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that searches your local [Claude Code](https://docs.anthropic.com/en/docs/claude-code) **conversation history**. It indexes every past session under `~/.claude/projects/` with BM25, redacts secrets, and lets the running Claude agent recall and resume solutions you've already worked out — without re-explaining the problem from scratch.\n\nIf you've ever caught yourself solving the same Docker, deployment, or auth bug twice in a month, this is for you. The package is local-only (no network calls), pure-JS (no native modules), and ships as a single `npx`-installable binary.\n\n[![npm version](https://img.shields.io/npm/v/claude-remind-mcp.svg)](https://www.npmjs.com/package/claude-remind-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)\n\n![demo](assets/demo.gif)\n\n> Status: experimental (`v0.1.x`). Tool surface is stable; internals may change.\n\n---\n\n## install\n\n**From shell:**\n\n```bash\nclaude mcp add claude-remind -- npx -y claude-remind-mcp\n```\n\n**From any manually configurable `mcp.json`** (Cursor, Windsurf, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-remind\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"claude-remind-mcp\"]\n    }\n  }\n}\n```\n\nNo model downloads, no daemons, no database. The first query builds an index from `~/.claude/projects/` (a few seconds for a typical history) and persists it to `~/.claude-remind/`. Subsequent queries reuse the index and only re-parse files whose mtime changed.\n\nIf `npx` resolves the wrong package, force resolution:\n\n```bash\nnpm install -g claude-remind-mcp\n```\n\n---\n\n## use cases\n\nA few patterns where searching past Claude Code conversation history pays off:\n\n- **Recurring infrastructure errors.** _\"We hit `ExpiredTokenException` on the staging deploy last month — what was the fix?\"_ One `remind_search` returns the exact session, the resolved snippet, and the resume command.\n- **Cross-project knowledge.** _\"How did I configure BuildKit cache on the other Coolify project?\"_ The index spans every project under `~/.claude/projects/`, so solutions from project A surface when you're working in project B.\n- **Onboarding into your own past work.** Coming back to a repo after weeks? Search for \"Cognito\", \"RunPod\", \"tailwind config\" and read the latest session summary instead of grepping through code.\n- **Avoiding redundant deep-dives.** Before Claude burns 10k tokens diagnosing a problem from scratch, it can call `remind_search` first and see if you already solved it. The default response is ~1.5 KB.\n- **Resuming where you left off.** Every search result includes a ready-to-paste `claude --resume <id>` command, plus the original `cwd` and `gitBranch`, so jumping back into a half-finished thread is one paste away.\n\n## tools\n\nFour tools, designed to compose: search → read → resume.\n\n### `remind_search`\n\nBM25 search over past messages. Returns ranked hits with a snippet, a `solvedHint`, a `messageUuid`, and a ready-to-paste `claude --resume` command.\n\n```ts\n{\n  query: string;\n  project?: string;       // substring of cwd, e.g. \"my-app\"\n  limit?: number;         // 1–50, default 5\n  sinceDays?: number;     // age filter\n  format?: \"compact\" | \"detailed\" | \"full\";  // 400 / 1000 / 2000-char snippet\n}\n```\n\n```json\n[\n  {\n    \"sessionId\": \"abc12345-...\",\n    \"messageUuid\": \"msg-9f8e-...\",\n    \"score\": 432.8,\n    \"ts\": \"2026-04-10T11:30:26Z\",\n    \"role\": \"assistant\",\n    \"project\": \"/Users/you/Code/my-app\",\n    \"gitBranch\": \"deploy\",\n    \"hasError\": false,\n    \"solvedHint\": \"likely\",\n    \"aiTitle\": \"RunPod serverless deploy walkthrough\",\n    \"snippet\": \"Step-by-step: 1) Push the image to NGC 2) Configure the Network Volume…\",\n    \"resumeCommand\": \"claude --resume abc12345-...\"\n  }\n]\n```\n\nQuery tips: prefer concrete terms — exact error strings, tool/library names, file paths. Generic words like `auth` or `docker` on their own dilute relevance.\n\n### `remind_message`\n\nFetch the full text of one message plus optional surrounding turns. Use after `remind_search` returns a `messageUuid` you want to read in full.\n\n```ts\n{\n  sessionId: string;       // full or 8-char prefix\n  messageUuid?: string;    // omit to read whole session (capped at 50 messages)\n  contextBefore?: number;  // 0–20, default 1\n  contextAfter?: number;   // 0–20, default 1\n}\n```\n\nThe matched message is flagged with `isFocus: true` inside the returned window.\n\n### `remind_session`\n\nStructured summary of a session: title, message count, tool names used, files touched, error count, time span, solved hint, last user message.\n\n```ts\n{\n  sessionId: string; // full or 8-char prefix\n}\n```\n\n### `remind_resume`\n\nResolves a session id (full or 8-char prefix) to a ready-to-run `claude --resume <id>` command, plus the session's cwd and git branch. `remind_search` already returns this on every hit, so prefer that; this tool exists for the case where you only have an id.\n\n---\n\n## how it works\n\n1. Streams every JSONL under `~/.claude/projects/` line-by-line, with a 1 MB per-line cap and a 50 000 message-per-file cap to keep the indexer bounded.\n2. Skips Claude Code's sidecar entries (`permission-mode`, `file-history-snapshot`, `attachment`, `system-reminder`, etc.) so only real `user` and `assistant` turns are indexed.\n3. Redacts well-known secret patterns (API keys, JWTs, private key blocks, env-style assignments) before content enters the index.\n4. Builds a [minisearch](https://github.com/lucaong/minisearch) BM25 index over the message text plus tool names and project path, and persists it atomically to `~/.claude-remind/`.\n5. On startup only files whose `mtime` changed are re-parsed.\n6. For each session derives `hasError`, `endedCleanly`, last user message, and a conservative `solvedHint` (`likely` only on explicit positive sentiment or a clean end with no errors; `unlikely` only on explicit negative sentiment; `unknown` otherwise).\n\nThe on-disk index is a single JSON file. It is safe to delete; the next query rebuilds it.\n\n---\n\n## configuration\n\n| Environment variable | Default            | Purpose                            |\n| -------------------- | ------------------ | ---------------------------------- |\n| `CLAUDE_CONFIG_DIR`  | `~/.claude`        | Where Claude Code stores its logs. |\n| `CLAUDE_REMIND_DIR`  | `~/.claude-remind` | Where the index is persisted.      |\n\nBoth must be absolute paths if set; otherwise the default is used.\n\n---\n\n## privacy\n\nThe index file at `~/.claude-remind/index.json` is written with mode `0600` and contains the indexed text from your conversations. A built-in regex pass redacts well-known secret formats (OpenAI / Anthropic / GitHub / AWS / Stripe / Google / Slack keys, JWTs, private key blocks, common `KEY=value` env assignments) before content enters the index. This is best-effort; if you've pasted a custom credential format into a past conversation it may not be caught. Delete `~/.claude-remind/` to wipe the index.\n\nThe server runs entirely locally over stdio. It makes no network calls.\n\n---\n\n## development\n\n```bash\ngit clone https://github.com/emretheus/claude-remind-mcp && cd claude-remind-mcp\nnpm install\nnpm run build\nnpm test\n```\n\nScripts:\n\n```bash\nnpm run build         # TypeScript build with executable permissions on dist/index.js\nnpm run dev           # tsc --watch\nnpm run start         # Run the MCP server (stdio)\nnpm run lint          # ESLint\nnpm run lint:fix      # ESLint --fix\nnpm run format        # Prettier write\nnpm run format:check  # Prettier check\nnpm run typecheck     # tsc --noEmit\nnpm test              # Vitest run\n```\n\nTo point a Claude Code instance at a local checkout:\n\n```bash\nclaude mcp add claude-remind -- node /absolute/path/to/dist/index.js\n```\n\nSmoke-test the MCP handshake from the shell:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"t\",\"version\":\"1\"}}}' \\\n  | node dist/index.js\n```\n\nPre-commit runs `lint-staged` (ESLint + Prettier on staged files) via Husky.\n\n---\n\n## requirements\n\n- Node.js ≥ 20\n- A Claude Code installation that writes to `~/.claude/projects/`\n\nThe package has two runtime dependencies: `@modelcontextprotocol/sdk` and `minisearch`. No native modules.\n\n---\n\n## license\n\n[MIT](LICENSE)\n",
  "bytes": 8565,
  "sha": "ba1eaedce80f574cf9b5b7bfd3876e6dacbaba9d0bca63d17075d43ab2a5b876",
  "repo_slug": "emretheus/claude-remind-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_emretheus_claude_remind_mcp_17d090ce/readme"
}