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

---

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

Environment variable	Default	Purpose
CLAUDE_CONFIG_DIR	~/.claude	Where Claude Code stores its logs.
CLAUDE_REMIND_DIR	~/.claude-remind	Where the index is persisted.

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