# Claude Remind Mcp

> MCP server for searching past Claude Code conversation history. Local BM25 search over JSONL logs with persistent index, secret redaction, solved-hint, and instant claude --resume.

- **Type:** MCP server
- **Install:** `agentstack add mcp-emretheus-claude-remind-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [emretheus](https://agentstack.voostack.com/s/emretheus)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [emretheus](https://github.com/emretheus)
- **Source:** https://github.com/emretheus/claude-remind-mcp
- **Website:** https://www.npmjs.com/package/claude-remind-mcp

## Install

```sh
agentstack add mcp-emretheus-claude-remind-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# claude-remind-mcp

A [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.

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.

[](https://www.npmjs.com/package/claude-remind-mcp)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)

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

---

## install

**From shell:**

```bash
claude mcp add claude-remind -- npx -y claude-remind-mcp
```

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

```json
{
  "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:

```bash
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.

```ts
{
  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
}
```

```json
[
  {
    "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.

```ts
{
  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.

```ts
{
  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](https://github.com/lucaong/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

```bash
git clone https://github.com/emretheus/claude-remind-mcp && cd claude-remind-mcp
npm install
npm run build
npm test
```

Scripts:

```bash
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:

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

Smoke-test the MCP handshake from the shell:

```bash
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](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [emretheus](https://github.com/emretheus)
- **Source:** [emretheus/claude-remind-mcp](https://github.com/emretheus/claude-remind-mcp)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/claude-remind-mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-emretheus-claude-remind-mcp
- Seller: https://agentstack.voostack.com/s/emretheus
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.