claude-remind-mcp

claude-remind-mcp

一个用于搜索本地 Claude Code对话历史的 Model Context Protocol (MCP) 服务。它使用 BM25 为 ~/.claude/projects/ 下的所有历史会话建立索引、对机密信息进行脱敏，并让正在运行的 Claude Agent 回忆并继续使用你已经解决过的问题方案，无需从头重新解释问题。

如果你曾发现自己在一个月内重复解决同一个 Docker、部署或身份验证问题，那么这个工具适合你。此软件包仅在本地运行（不进行网络调用），使用纯 JavaScript（不包含原生模块），并以单个可通过 npx 安装的二进制文件发布。

状态：实验性（v0.1.x）。工具接口稳定；内部实现可能会变更。

---

安装

通过 Shell 安装：

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

通过任何可手动配置的 mcp.json 安装（Cursor、Windsurf 等）：

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

无需下载模型、无需守护进程，也无需数据库。首次查询会从 ~/.claude/projects/ 建立索引（典型历史记录需几秒钟），并将其保存到 ~/.claude-remind/。后续查询会复用该索引，只重新解析 mtime 已变更的文件。

如果 npx 解析到了错误的软件包，请强制指定解析目标：

npm install -g claude-remind-mcp

---

使用场景

以下是搜索 Claude Code 历史对话能派上用场的几种场景：

• 反复出现的基础设施错误。 “上个月在暂存环境部署时遇到了 ExpiredTokenException——当时是怎么解决的？” 一次 remind_search 就会返回对应会话、解决方案片段和恢复会话的命令。
• 跨项目共享知识。 “我在另一个 Coolify 项目中是如何配置 BuildKit 缓存的？” 索引涵盖 ~/.claude/projects/ 下的所有项目，因此你在项目 B 中工作时，也能找到项目 A 的解决方案。
• 回顾自己过去的工作。 几周后重新回到某个代码仓库？搜索“Cognito”“RunPod”“tailwind config”，并阅读最新的会话摘要，无需在代码中反复 grep。
• 避免重复深入排查。 在 Claude 花费 10k 个 token 从头诊断问题之前，它可以先调用 remind_search，看看你是否已经解决过。默认响应约为 1.5 KB。
• 从上次停下的地方继续。 每条搜索结果都包含可直接粘贴的 claude --resume <id> 命令，以及原始的 cwd 和 gitBranch，只需粘贴一次，即可回到未完成的对话。

工具

四个可组合使用的工具：搜索 → 阅读 → 恢复。

remind_search

使用 BM25 搜索历史消息。返回排序后的命中结果，其中包含片段、solvedHint、messageUuid，以及可直接粘贴的 claude --resume 命令。

{
  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-..."
  }
]

查询提示：尽量使用具体词语，例如精确的错误字符串、工具／库名称、文件路径。单独使用 auth 或 docker 这样的通用词会降低相关性。

remind_message

获取一条消息的全文，以及可选的前后对话轮次。可在 remind_search 返回你想完整阅读的 messageUuid 后使用。

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

在返回的对话窗口中，匹配到的消息会标记为 isFocus: true。

remind_session

会话结构化摘要：标题、消息数量、使用过的工具名称、涉及的文件、错误数量、时间范围、解决方案提示、最后一条用户消息。

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

remind_resume

根据会话 ID（完整 ID 或 8 个字符的前缀）解析出可直接运行的 claude --resume <id> 命令，以及会话的 cwd 和 Git 分支。remind_search 已在每条命中结果中返回这些信息，因此优先使用它；此工具适用于你手头只有 ID 的情况。

---

工作原理

1. 逐行读取 ~/.claude/projects/ 下的所有 JSONL 文件，每行上限为 1 MB，每个文件上限为 50 000 条消息，以控制索引器的资源占用。
2. 跳过 Claude Code 的附属条目（permission-mode、file-history-snapshot、attachment、system-reminder 等），仅为实际的 user 和 assistant 对话轮次建立索引。
3. 在内容进入索引前，清除常见的秘密信息模式（API 密钥、JWT、私钥块、环境变量格式的赋值）。
4. 使用 minisearch 根据消息文本、工具名称和项目路径构建 BM25 索引，并以原子方式将其持久化到 ~/.claude-remind/。
5. 启动时仅重新解析 mtime 已更改的文件。
6. 为每个会话推导出 hasError、endedCleanly、最后一条用户消息和保守的 solvedHint（仅在明确表达积极情绪，或会话干净结束且没有错误时设为 likely；仅在明确表达消极情绪时设为 unlikely；其他情况均为 unknown）。

磁盘上的索引是一个 JSON 文件，可以安全删除；下次查询时会重新构建。

---

配置

环境变量	默认值	用途
CLAUDE_CONFIG_DIR	~/.claude	Claude Code 存储日志的位置。
CLAUDE_REMIND_DIR	~/.claude-remind	持久化索引的位置。

若设置，这两个路径都必须是绝对路径；否则将使用默认值。

---

隐私

~/.claude-remind/index.json 中的索引文件以 0600 权限写入，包含对话中的索引文本。在内容进入索引前，内置的正则表达式处理会清除常见的秘密信息格式（OpenAI / Anthropic / GitHub / AWS / Stripe / Google / Slack 密钥、JWT、私钥块、常见的 KEY=value 环境变量赋值）。这只能尽力而为；如果你在过去的对话中粘贴了自定义凭据格式，可能无法检测到。删除 ~/.claude-remind/ 即可清除索引。

该服务完全在本地通过 stdio 运行，不会发起网络请求。

---

开发

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

脚本：

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

要让 Claude Code 实例指向本地检出目录：

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

在 shell 中对 MCP 握手进行冒烟测试：

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 会通过 Husky 运行 lint-staged（对暂存文件运行 ESLint + Prettier）。

---

要求

• Node.js ≥ 20
• 安装了 Claude Code，且会将文件写入 ~/.claude/projects/

该软件包有两个运行时依赖项：@modelcontextprotocol/sdk 和 minisearch。不包含原生模块。

---

许可证

MIT