How do I use claude-remind-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-remind-mcp search for the staging deploy ExpiredTokenException fix" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

claude-remind-mcp

by emretheus

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Local

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.

npm version License: MIT TypeScript Node.js

demo

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

Related MCP server: mcp-sessions

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

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

Available Tools

4 tools

remind_messageA

Fetch the full text of a specific past message, plus optional surrounding turns. Returns up to ~10 KB; the matched message is flagged with isFocus: true inside the returned window.

When to use: only after remind_search returns a messageUuid whose snippet looks promising but is truncated. Don't call this for every search hit — pick the one or two most relevant first. If you want a structural overview of the whole session (tools, files, errors), call remind_session instead.

To read the entire session, omit messageUuid (capped at 50 messages).

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	Full or prefix of the session UUID.
`messageUuid`	No	Optional. If provided, returns this message plus context window. If omitted, returns all indexed messages of the session (capped at 50).
`contextBefore`	No	Messages before the focus message.
`contextAfter`	No	Messages after the focus message.

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses return size limit (~10 KB), the isFocus flag, and behavior when messageUuid is omitted (capped at 50 messages). No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured into three concise paragraphs: what it does, when to use (with siblings), and alternative usage. Every sentence adds value and is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description effectively covers return content and behavior for both modes (specific message and entire session). It addresses sibling tools and provides sufficient context for an AI agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description adds extra context beyond schema, such as the 10 KB limit and the 50-message cap when omitting messageUuid. This adds meaningful value beyond the schema's parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches the full text of a specific past message with optional surrounding turns. It distinguishes from siblings like remind_search and remind_session by specifying when each should be used.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when-to-use guidance: only after remind_search returns a promising but truncated uuid, and notes not to call for every hit. Also clearly states when to use remind_session instead, providing an alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remind_resumeA

Resolve a (full or 8-char prefix) session id into a ready-to-run claude --resume <id> command, plus the session's cwd and git branch.

When to use: only when you already have a sessionId in hand and need just the resume command. remind_search already returns resumeCommand on every hit, so prefer that. This tool exists for cases where the user pastes a bare sessionId or a previous tool flow stored only the id.

ParametersJSON Schema

Name	Required	Description	Default
`sessionId`	Yes	Full or prefix of the Claude session UUID.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses what the tool does (resolve and output command, cwd, git branch) but does not explicitly state that the operation is non-destructive or read-only. Despite this minor omission, the behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two clear sentences for the main action, followed by a short usage paragraph. No redundant information, front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is complete. It explains the tool's output (command, cwd, git branch) and its relationship to siblings, fulfilling all informational needs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description adds only the detail '8-char prefix' which is already implied in the schema description. Baseline of 3 is appropriate as the description does not significantly add beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool resolves a session ID into a command and additional context (cwd, git branch). It distinguishes itself from siblings by noting that remind_search already returns resumeCommand, so this tool is for cases with only the sessionId.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'When to use' section: only when you have a sessionId and need the resume command; prefer remind_search otherwise. Also gives concrete examples like user pasting bare sessionId or tool flow storing only the id.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remind_searchA

Search past Claude Code sessions for solutions to recurring problems. Returns BM25-ranked hits with a snippet, a solvedHint, a messageUuid, and a ready-to-paste claude --resume <id> command.

When to use: at the start of a task to check for prior work on the same codebase; or when the user mentions an error, tool, or feature they may have already solved. One call is usually enough — only re-call with a different query if the first returned no useful hits.

Query tips: use specific concrete terms — exact error strings (ExpiredTokenException, LoginRefreshRequired), tool/lib names (BuildKit, Cognito, Tailwind), or real file paths (tailwind.config, shared_auth/jwt.py). Avoid generic words that flood the corpus (e.g. AWS, auth, docker on their own). Good: ExpiredTokenException SendSSHPublicKey. Bad: AWS auth issue.

Cost: ~1–2 KB per call at default (5 hits, 1000-char snippets). Use format: "compact" (400 chars) for cheap scans, format: "full" (2000 chars) when you need to read in place. After finding a relevant hit, call remind_message with its messageUuid to read the full content.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Free-text search query.
`project`	No	Optional. Substring match against the session's cwd (e.g. 'my-app').
`limit`	No
`sinceDays`	No	Optional. Only include sessions updated within the last N days.
`format`	No	Snippet length: compact=400, detailed=1000, full=2000 chars.	detailed

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses the search algorithm (BM25), return fields (snippet, solvedHint, messageUuid, resume command), cost per call, and format options. Does not mention rate limits or token budgets, but for a search tool this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Information is front-loaded with the core purpose, then usage guidelines, query tips, and cost details. Every sentence adds value; no redundancy or filler. Well-structured into clear sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, the description thoroughly explains return values and actionable follow-up (call remind_message). It covers all aspects an agent needs: when to use, query formulation, format options, and cost awareness. Complete for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, and the description adds significant value beyond schema: explains query tips (specific terms to use/avoid), defines enum values for format (compact=400 chars, etc.), and suggests project substring matching usage. The description compensates well for the remaining undocumented parameter aspects.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches past Claude Code sessions for solutions, with a specific verb and resource. It effectively distinguishes itself from siblings like remind_message (for reading full content) and remind_resume (likely resuming sessions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to use: at task start or when user mentions a problem. Advises one call is sufficient, and provides query tips with good/bad examples. Clearly tells the agent when not to re-call unnecessarily.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remind_sessionA

Get a structured summary of one past session: title, message count, tool names used, files touched, error count, time span, solved hint, and the last user message. Cheap (~1 KB).

When to use: when a remind_search hit looks relevant and you need the bigger picture (was this session productive? which tools/files were involved?) before drilling into specific messages. Requires a sessionId — the 8-char prefix from a search hit is enough. To read message bodies, use remind_message instead.

ParametersJSON Schema

Name	Required	Description	Default
`sessionId`	Yes	Full or prefix of the Claude session UUID.

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Mentions the operation is cheap (~1 KB) and provides summary content. No annotations provided, so description carries burden; it could explicitly state read-only/no side effects, but the nature is implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise paragraphs: first states purpose and content, second provides when-to-use. No waste, front-loaded with essential info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 1-param tool without output schema, the description covers purpose, usage context, and parameter details completely. Sibling references are included.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers sessionId with description; description adds practical guidance that prefix is enough, which adds value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool retrieves a structured summary of a past session with specific content (title, message count, tool names, etc.). Differentiates from sibling `remind_message` for message bodies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises using after a `remind_search` hit to get the bigger picture, and directs to `remind_message` for message bodies. Also clarifies that an 8-char prefix sessionId is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

4 tool updatesv0.1.1Jun 14, 2026
- First observedremind_message
- First observedremind_resume
- First observedremind_search
- First observedremind_session

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0

Scored 2026-06-14 21:35 across 4 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: searching sessions, fetching full messages, summarizing session metadata, and providing resume commands. No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent 'remind_<verb>' pattern with snake_case, making the action and target clear (e.g., remind_search, remind_message).

Tool Count5/5

Four tools cover the core workflow (search, read, summarize, resume) without unnecessary extras. The count is perfectly scoped for the domain.

Completeness5/5

The set covers the full lifecycle of retrieving past session information: searching, viewing details, getting summaries, and obtaining resume commands. There are no obvious missing operations.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

HeyClaude — Claude & AI workflow directory A
io.github.JSONbored
Search the HeyClaude directory of Claude Code agents, MCP servers, skills, and tools.
Search AI & Machine Learning
282257
suma-memory A
io.github.sumanaddanki
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Knowledge & Memory Developer Tools Autonomous Agents
2
SirroOAuth
io.github.Jonathanmberg
Shared memory for AI coding agents. Save once, reuse from Cursor, Claude Code, Codex.
Knowledge & Memory Developer Tools
1
TeamShared C
io.github.xhad
Shared memory for coding agents. Stop re-explaining your codebase every session.
Knowledge & Memory Developer Tools
1271

Related MCP Servers

claude-kb
RAG Systems Search Vector Databases
tenequm
A
license
Not graded
quality
C
maintenance
Enables searching and retrieving Claude Code conversation history via hybrid semantic and keyword search, allowing the agent to access its own past interactions.
Updated 4 months ago (2026-05-07 19:15 UTC)
4
MIT
mcp-sessions
Search Developer Tools
Yurich-ru
A
license
Not graded
quality
C
maintenance
Search and browse Claude Code conversation history across all your projects.
Updated 6 months ago (2026-03-12 05:17 UTC)
1
MIT
Claude Code History MCP
Search Knowledge & Memory Developer Tools
tim0120
A
license
Not graded
quality
D
maintenance
Search and reference your Claude Code conversation history directly from Claude, with full-text search, conversation viewing, and project browsing.
Updated 8 months ago (2026-01-08 02:09 UTC)
13
MIT
MCP Claude Code Conversation
Knowledge & Memory Search
Stefan-Nitu
A
license
A
quality
D
maintenance
Enables Claude Code to search, browse, and read its own past conversation history across all projects using BM25 keyword search.
Updated 5 months ago (2026-03-27 17:09 UTC)
1
16
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/emretheus/claude-remind-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server