claude-memory-search-mcp
This MCP server lets Claude Code search, retrieve, filter, and link across its local memory files instead of loading everything into context.
Search memories by keyword with optional result limit, ranking hits by relevance and matched terms.
Fetch a single memory's full body by file name (without
.md).List all memories, optionally filtered by type:
user,feedback,project, orreference.Find related memories via
[[wikilinks]], showing memories linked from or to a given memory.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@claude-memory-search-mcp search memories for 'database migration'"
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-memory-search-mcp
MCP server that searches and links across Claude Code memory files.
Why
Claude Code's auto-memory directory grows large quickly (100+ files in my setup). Loading every memory into context defeats the point of having them — and the auto-loaded MEMORY.md only carries a 150-char hook per entry. This server lets Claude:
search by keyword across every memory body, not just titles,
filter by type (
user/feedback/project/reference),fetch a single memory in full only when needed,
traverse
[[wikilinks]]to pull related context on demand.
In short: stop trying to hold the whole memory in the window. Index it, then pull what you need.
Requires Node.js 18 or newer.
Related MCP server: Central Brain
Tools
Tool | Args | Description |
|
| Ranked keyword search across all memory bodies. Bonuses for title and description hits. |
|
| Fetch the full body of one memory by file name (no |
|
| List every memory, optionally filtered by type. |
|
| Return memories linked from or to a given memory via |
Where it reads from
Claude Code stores memories under ~/.claude/projects/<project-id>/memory/,
where <project-id> is the working directory with / replaced by -. A
session started in your home directory writes to -Users-jane; one started in
a project writes somewhere else.
The server resolves the directory in this order:
CLAUDE_MEMORY_DIR, if set.The directory derived from
$HOME— right when you run Claude Code from your home directory, which is where most personal memories accumulate.If that does not exist and there is exactly one
memorydirectory under~/.claude/projects/, that one.
If several exist and none is the home-derived one, the server says so and lists
them rather than guessing. Point CLAUDE_MEMORY_DIR at the one you want:
CLAUDE_MEMORY_DIR=~/.claude/projects/-Users-jane-work/memoryThis server exposes every memory in that directory to whichever MCP client connects. It only ever reads local files and sends nothing anywhere, but the contents do enter the model's context — worth knowing if your memories hold anything you would not paste into a chat.
Install
From source (recommended for Claude Code MCP config)
git clone https://github.com/yangchoi/claude-memory-search-mcp.git
cd claude-memory-search-mcp
npm install
npm run buildRun directly via npx (no local clone)
npx -y github:yangchoi/claude-memory-search-mcpSlower on first invocation (npx fetches and builds), then cached.
Configure in Claude Code
Add to your Claude Code MCP config (~/.claude/settings.json or project .mcp.json):
{
"mcpServers": {
"memory-search": {
"command": "node",
"args": ["/absolute/path/to/claude-memory-search-mcp/dist/index.js"],
"env": {
"CLAUDE_MEMORY_DIR": "/Users/you/.claude/projects/<your-project-id>/memory"
}
}
}
}CLAUDE_MEMORY_DIR is optional — by default the server derives the path from $HOME (e.g. /Users/jane → ~/.claude/projects/-Users-jane/memory on macOS, /home/jane → ~/.claude/projects/-home-jane/memory on Linux). Set it explicitly if your memory lives elsewhere.
Restart Claude Code. The four tools above will appear under mcp__memory-search__*.
Example
> search_memory query="database migration"
[42] backend-project-notes (project)
matches: database, migration
Postgres migration patterns and rollback strategy
[18] team-conventions (reference)
matches: migration
...Tests
npm testThe suite runs against the built server over its real stdio transport, using throwaway memory directories rather than your own. It covers the four tools, the ranking rules, and every branch of the directory resolution above.
License
MIT
Available Tools
4 toolsget_memoryA
Fetch the full body of a memory file by its name (without .md).
Inputs: name (required).
list_memoriesA
List all memory files. Optionally filter by type (user/feedback/project/reference).
Inputs: type.
search_memoryA
Search across memory files by keyword. Returns ranked hits with file name, score, matched terms, type, and description.
Inputs: query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: find_related for wikilink navigation, get_memory for full content retrieval, list_memories for enumeration with filtering, and search_memory for keyword search. No overlap in functionality.
All tool names follow the consistent snake_case verb_noun pattern (find_related, get_memory, list_memories, search_memory). No deviations or mixed conventions.
4 tools is well-scoped for a memory search server. Each tool serves a distinct need (listing, retrieval, search, link navigation) without unnecessary redundancy or gaps.
The set covers core read/search operations for a memory system. However, it lacks write operations (create, update, delete), which may be intentional given the 'search' focus, but slightly limits completeness for full lifecycle management.
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Shared, scoped, reviewable team memory for AI coding agents.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables searching and retrieving Claude Code conversation history via hybrid semantic and keyword search, allowing the agent to access its own past interactions.142 PyPI5MIT
- AlicenseNot gradedqualityDmaintenanceProvides persistent memory for Claude Code, automatically extracting and surfacing relevant context from past sessions to avoid re-explaining issues and decisions.MIT
- AlicenseNot gradedqualityDmaintenanceProvides local-first, cross-session memory for Claude Code, enabling semantic search across past sessions to retrieve procedures, decisions, or answers without exposing secrets.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides persistent long-term memory for Claude Code by enabling semantic save, search, and context retrieval across sessions.1MIT