@llmnesia/mcp

Search your own AI chat history from Claude Desktop, Claude Code, Cursor, Codex, and other MCP clients. It is designed to cover every conversation the LLMnesia browser extension has captured across ChatGPT, Claude, Gemini, Character.AI, Grok, DeepSeek, and the rest of the supported platforms.

Everything is local. No network calls, no cloud. The corpus lives on your machine and the MCP server speaks Model Context Protocol over stdio.

Requires Node.js ≥ 22.13.0 (for the built-in node:sqlite module). The installer checks this before changing anything and prints the exact recovery steps when the installed version is too old. If that happens in an interactive terminal, it offers the official Node.js installer through an OS-specific LLMnesia download link for you.

Install

On macOS or Linux:

npx -y @llmnesia/mcp@latest install

On Windows PowerShell:

npx.cmd -y @llmnesia/mcp@latest install

Windows uses npx.cmd because PowerShell commonly blocks npm's npx.ps1 wrapper even when Node.js installed correctly. It requires Node.js 22.13 or newer; there is no global package install and no client config to edit by hand in the normal path.

If your installed Node.js is too old, LLMnesia offers to open the right official installer; install it, reopen Terminal/PowerShell, and run the command again. If npx is not recognised at all, Node.js is not installed yet, so the command cannot start far enough to show that prompt. In that case, install the current LTS release from Mac installer on macOS, or the Windows installer on Windows.

The installer:

1. sets up the native host that bridges the browser extension to your local corpus,
2. copies the server into ~/.llmnesia/bin so it has a permanent home,
3. sets up the supported desktop AI apps (Claude Code, Cursor, and Codex/ChatGPT), and
4. registers that copy using the client's own CLI where available, or with an automatic backup before editing its documented user config. It prepares all of those standard config paths, so an app installed later does not require running setup again.

Claude Desktop on Windows does not provide a supported API for third-party installers to add a local desktop extension. LLMnesia therefore leaves any existing Claude configuration untouched rather than claiming that Claude has been connected.

Claude Desktop on Windows (current one-time manual step)

Until LLMnesia is available in Claude's extension directory, Claude Desktop on Windows has one extra, manual step. First run install above so the local browser bridge and corpus exist. Then download the official LLMnesia llmnesia.mcpb desktop-extension file from LLMnesia and use Claude Desktop's Settings → Extensions → Install extension flow to install it. Fully quit and reopen Claude Desktop afterwards.

This is deliberately separate from the npm command: Claude does not provide a supported Windows API for another installer to silently add an .mcpb extension. The command therefore never edits Claude's internal extension state or reports a false success. The packaged extension itself is read-only: it can search, list, and read the local corpus but cannot modify it.

The future Claude Directory listing is a convenience distribution route, not a dependency for the general LLMnesia release. It will replace this one manual Claude step with Claude's own in-app install button if Anthropic selects the extension. See docs/CLAUDE_DESKTOP_RELEASE_PLAN.md for the release and directory-submission plan.

The install command is the approval to perform those setup steps. It does not interrupt setup with a separate prompt for every detected app, and it never prints existing client configurations or their credentials.

Then fully quit and reopen your MCP client. Clients read their config once at startup, so reloading a window is not enough.

Why it installs a copy

Registered clients get an absolute path — your node binary plus ~/.llmnesia/bin/cli.js — rather than a bare llmnesia-mcp command:

• npx unpacks packages into a temporary cache that is not on PATH and is cleared by npm cache clean, so a command name registered from an npx run stops resolving the moment it finishes.
• Desktop clients launched from the Dock or Start menu inherit a minimal PATH that usually excludes nvm, Homebrew, and Volta — so even a global install can be invisible to them.

The copy is self-contained (no node_modules beside it) and re-running install replaces it, which is also how you upgrade.

Updating

Run the same OS-specific install command above again.

Your corpus is untouched; only the server copy is replaced.

The corpus comes from the extension

@llmnesia/mcp does not collect conversations on its own. The corpus is populated by the LLMnesia browser extension, free on the Chrome Web Store:

1. Install the extension and run a one-time backfill to import existing history.
2. After that, the extension captures new conversations as you chat.
3. Run the installer above, fully restart the browser, then open LLMnesia Settings and click Enable automatic sync once. Chrome requires this one-time permission confirmation.
4. The extension immediately backfills its indexed history to the local corpus at ~/.llmnesia/corpus/, then syncs new and changed chats automatically. @llmnesia/mcp reads from the same folder — there is nothing to configure.

If nothing has written to the corpus yet, search results will be empty.

Tools

Once registered, your MCP client gains six tools over the corpus:

| Tool | Purpose | | --- | --- | | search_conversations | Full-text search across every past conversation. Returns ranked matches with highlighted snippets. Supports platform, title, date_from/date_to filters and a match_mode (any / all / phrase) for when a wrong hit matters. | | get_conversation | Fetch the full transcript of one conversation by its id (the id field from search results). | | list_conversations | List conversations by chronology, including oldest-first for questions about the user's earliest chat. | | list_recent | List the most recently updated conversations with title, summary, and platform. | | corpus_status | Report when the corpus last received data and how many conversations it holds. Use this when an expected conversation cannot be found, to tell a genuinely missing chat apart from a corpus that has stopped receiving updates. | | save_conversation | Add or update a conversation in the corpus, so MCP is also an ingestion route. |

Search and list results carry a corpus block saying when the corpus last received data — check it before concluding a chat does not exist.

Supported clients

| Client | How install wires it | | --- | --- | | Claude Code | Runs claude mcp add --scope user with the absolute Node and installed runtime paths when available. Otherwise it writes the documented user-scope ~/.claude.json entry, so Windows users do not need the claude command on PATH. | | Claude Desktop | macOS uses the working local JSON registration. On Windows, run install for browser sync, then install the official llmnesia.mcpb once in Claude Desktop; Claude exposes no supported external installation API for custom desktop extensions. | | Cursor | Edits ~/.cursor/mcp.json, preparing it in advance if Cursor is installed later. | | Codex / ChatGPT desktop | Runs codex mcp add with the absolute runtime paths when available. If the bundled CLI is unavailable, the installer safely edits ~/.codex/config.toml itself and backs up existing settings first, including preparing it for a later installation. Read-only LLMnesia tools are configured to run without repeated approval prompts; writes still ask. | | Others (Windsurf, Zed, LM Studio, …) | Prints the generic stdio block for you to paste. |

Cloud-only clients cannot reach a local stdio server (web ChatGPT, Lovable, and similar). That is architectural, not a packaging gap — a future relay may close it.

Diagnose an install

Use npx -y @llmnesia/mcp@latest doctor on macOS/Linux, or npx.cmd -y @llmnesia/mcp@latest doctor in Windows PowerShell.

Checks whether the native host is installed, the server runtime is present, the corpus is receiving data, and each detected client is correctly wired — including whether the command each client is registered with can actually be executed, which is the usual cause of a server that silently never starts.

Exit code 0 means no check is failing; some checks are warnings that are correct on a healthy machine (a client you don't use, the un-checkable restart reminder).

Uninstall

Use npx -y @llmnesia/mcp@latest uninstall on macOS/Linux, or npx.cmd -y @llmnesia/mcp@latest uninstall in Windows PowerShell.

Removes native-host manifests and registry keys, the copied server in ~/.llmnesia/bin, and client registrations. The shared config file and your conversation corpus are not deleted — uninstall prints the corpus path and the rm -rf command if you want to remove the data yourself.

CLI reference

The bin exposes the subcommands above plus power-user verbs for working directly with the corpus:

llmnesia-mcp install       # native host + client registration
llmnesia-mcp serve         # the MCP stdio server clients spawn
llmnesia-mcp doctor        # diagnose the install
llmnesia-mcp uninstall     # remove manifests, config, client entries
llmnesia-mcp init          # create an empty corpus
llmnesia-mcp ingest <…>    # ingest an NDJSON backup file
llmnesia-mcp drain         # ingest everything in <corpus>/inbox
llmnesia-mcp watch         # ingest new inbox deltas live (Ctrl+C to stop)
llmnesia-mcp stats         # corpus summary
llmnesia-mcp reindex       # drop + rebuild the search index from the corpus
llmnesia-mcp search <q>    # one-shot search from the terminal
llmnesia-mcp --version     # print the installed version

Support

Questions and bug reports: [email protected].

Privacy Policy

The MCP server reads and writes only the LLMnesia corpus stored on the user's own computer. It does not upload conversation content, titles, URLs, prompts, responses, or search queries to LLMnesia or to any third party, and it makes no analytics or advertising requests of its own.

The browser extension separately sends limited, non-content product analytics to PostHog. Conversation data and MCP searches are excluded. The complete policy explains collection, local storage, third-party processing, retention, deletion, and contact details: LLMnesia Privacy Policy.

The local MCP corpus remains on the device until the user deletes it. Running uninstall deliberately leaves that corpus intact so uninstalling the helper cannot accidentally destroy the user's history.

License

MIT — see LICENSE.