Claude Remind MCP

claude-remind-mcp

A Model Context Protocol (MCP) server that searches your local 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.

If 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.

Status: experimental (v0.1.x). Tool surface is stable; internals may change.

install

From shell:

claude mcp add claude-remind -- npx -y claude-remind-mcp

From any manually configurable `mcp.json` (Cursor, Windsurf, etc.):

{

"mcpServers": { "claude-remind": { "command": "npx", "args": ["-y", "claude-remind-mcp"] } } }

No 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.

If npx resolves the wrong package, force resolution:

npm install -g claude-remind-mcp

use cases

A few patterns where searching past Claude Code conversation history pays off:

• 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.
• 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.
• 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.
• 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.
• Resuming where you left off. Every search result includes a ready-to-paste claude --resume command, plus the original cwd and gitBranch, so jumping back into a half-finished thread is one paste away.

tools

Four tools, designed to compose: search → read → resume.

remind_search

BM25 search over past messages. Returns ranked hits with a snippet, a solvedHint, a messageUuid, and a ready-to-paste claude --resume command.

{

query: string; project?: string; // substring of cwd, e.g. "my-app" limit?: number; // 1–50, default 5 sinceDays?: number; // age filter format?: "compact" | "detailed" | "full"; // 400 / 1000 / 2000-char snippet }

[

{ "sessionId": "abc12345-...", "messageUuid": "msg-9f8e-...", "score": 432.8, "ts": "2026-04-10T11:30:26Z", "role": "assistant", "project": "/Users/you/Code/my-app", "gitBranch": "deploy", "hasError": false, "solvedHint": "likely", "aiTitle": "RunPod serverless deploy walkthrough", "snippet": "Step-by-step: 1) Push the image to NGC 2) Configure the Network Volume…", "resumeCommand": "claude --resume abc12345-..." } ]

Query tips: prefer concrete terms — exact error strings, tool/library names, file paths. Generic words like auth or docker on their own dilute relevance.

remind_message

Fetch the full text of one message plus optional surrounding turns. Use after remind_search returns a messageUuid you want to read in full.

{

sessionId: string; // full or 8-char prefix messageUuid?: string; // omit to read whole session (capped at 50 messages) contextBefore?: number; // 0–20, default 1 contextAfter?: number; // 0–20, default 1 }

The matched message is flagged with isFocus: true inside the returned window.

remind_session

Structured summary of a session: title, message count, tool names used, files touched, error count, time span, solved hint, last user message.

{

sessionId: string; // full or 8-char prefix }

remind_resume

Resolves a session id (full or 8-char prefix) to a ready-to-run claude --resume 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.

how it works

1. 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.
2. Skips Claude Code's sidecar entries (permission-mode, file-history-snapshot, attachment, system-reminder, etc.) so only real user and assistant turns are indexed.
3. Redacts well-known secret patterns (API keys, JWTs, private key blocks, env-style assignments) before content enters the index.
4. Builds a minisearch BM25 index over the message text plus tool names and project path, and persists it atomically to ~/.claude-remind/.
5. On startup only files whose mtime changed are re-parsed.
6. 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).

The on-disk index is a single JSON file. It is safe to delete; the next query rebuilds it.

configuration

Both must be absolute paths if set; otherwise the default is used.

privacy

The 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.

The server runs entirely locally over stdio. It makes no network calls.

development

git clone https://github.com/emretheus/claude-remind-mcp && cd claude-remind-mcp

npm install npm run build npm test

Scripts:

npm run build         # TypeScript build with executable permissions on dist/index.js

npm run dev # tsc --watch npm run start # Run the MCP server (stdio) npm run lint # ESLint npm run lint:fix # ESLint --fix npm run format # Prettier write npm run format:check # Prettier check npm run typecheck # tsc --noEmit npm test # Vitest run

To point a Claude Code instance at a local checkout:

claude mcp add claude-remind -- node /absolute/path/to/dist/index.js

Smoke-test the MCP handshake from the shell:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \

| node dist/index.js

Pre-commit runs lint-staged (ESLint + Prettier on staged files) via Husky.

requirements

• Node.js ≥ 20
• A Claude Code installation that writes to ~/.claude/projects/

The package has two runtime dependencies: @modelcontextprotocol/sdk and minisearch. No native modules.

license

MIT