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.

Tools

| Tool | Args | Description | |---|---|---| | search_memory | query, limit? | Ranked keyword search across all memory bodies. Bonuses for title and description hits. | | get_memory | name | Fetch the full body of one memory by file name (no .md). | | list_memories | type? | List every memory, optionally filtered by type. | | find_related | name | Return memories linked from or to a given memory via [[wikilinks]]. |

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:

1. CLAUDE_MEMORY_DIR, if set.
2. The directory derived from $HOME — right when you run Claude Code from your home directory, which is where most personal memories accumulate.
3. If that does not exist and there is exactly one memory directory 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/memory

This 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 build

Run directly via npx (no local clone)

npx -y github:yangchoi/claude-memory-search-mcp

Slower 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 test

The 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