# claude-memory-search-mcp

MCP server that searches and links across [Claude Code](https://claude.com/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:

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

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

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

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

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