@llmnesia/mcp

@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:

• sets up the native host that bridges the browser extension to your local corpus,
• copies the server into ~/.llmnesia/bin so it has a permanent home,
• sets up the supported desktop AI apps (Claude Code, Claude Desktop, Cursor, and Codex/ChatGPT), and
• 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.

On Windows, Claude Desktop uses its supported packaged-extension flow instead of the legacy JSON config. If Claude is installed, its normal LLMnesia install window opens during setup; click Install once. Claude can run that extension with its built-in Node.js, while the system Node installation continues to run the browser helper and other desktop AI integrations. If Claude is installed later, run the same LLMnesia setup command once more.

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:

• Install the extension and run a one-time backfill to import existing history.
• After that, the extension captures new conversations as you chat.
• 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.
• 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	Windows opens Claude's regular packaged-extension installer and removes obsolete LLMnesia JSON entries. macOS keeps the working local JSON registration.
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: [e-mail].

License

MIT — see LICENSE.