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

Recommended setup

Start in the LLMnesia browser extension so you do not miss the browser permission, Node.js requirement, OS-specific command, restart, or the extra Claude Desktop step on Windows:

1. Install LLMnesia and import the chat history you want available.
2. Open Full settings → Connect desktop AI.
3. Run the exact connector command shown there.
4. Fully quit and reopen the browser.
5. Return to Connect desktop AI and enable automatic sync.

Installing the npm package is not setup. Running npm install @llmnesia/mcp only downloads package files; it does not register the native browser connector or configure desktop AI apps. Use the exact npx -y @llmnesia/mcp@latest install command below (or npx.cmd on Windows), including the final install argument.

The commands below are the connector-install step from that guided flow. They are also provided as a reference for technical users; the browser restart and permission step are still required afterward.

Connector command

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, Codex/ChatGPT, and ZCode), 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.

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.

Local storage and compaction

Conversation files are stored as losslessly compressed JSON. Search uses a contentless FTS5 token index: the canonical text is not duplicated inside the database, and result snippets are loaded from the canonical conversation only after SQLite has ranked the matches. No conversation or searchable token is dropped to save space.

Current builds discard a clean browser-to-corpus transport payload after both the canonical conversation and active index have accepted it. Malformed input is kept under inbox/quarantine/ for inspection. Older releases archived every successful payload and may also have left versioned indexes behind.

Valid blank-text turns are retained with their message metadata. If an older importer quarantined a backup containing those turns, close connected MCP clients and run llmnesia-mcp retry-quarantine. The command validates each entire file before retrying, updates the active index, and moves successfully recovered originals into inbox/recovered/ without deleting their contents. Files with unresolved malformed records remain quarantined. The warning clears on the next MCP read once no pending or quarantined files remain. This does not require rebuilding local history.

For legacy backup parts split between a conversation header and its messages, llmnesia-mcp repair-split-backups validates the parts together and checks only the saved chats named in those parts. It preserves newer transcripts, refuses conflicting or incomplete fragments, and retains successfully recovered originals. It requires an existing current index and never starts a full rebuild.

No maintenance command is required. After an upgrade, the MCP service waits through a three-day compatibility window, then reclaims the historical files automatically while the service is ready and idle. Work is single-process, resumable, yields between small batches, and retries later without interrupting search if any verification or filesystem step fails. Quarantine is never removed. Set LLMNESIA_NO_AUTO_MAINTENANCE=1 only if you need to opt out.

For support or an immediate attended cleanup, preview the exact recoverable space without writing anything:

npx -y @llmnesia/mcp@latest compact --dry-run

To apply it immediately, fully quit connected desktop AI/MCP clients, then run compact without --dry-run. It asks for confirmation, verifies every compressed conversation by reading it back before removing the legacy JSON, builds the current index before deleting older derived versions, and never removes quarantined input.

Tools

Once registered, your MCP client gains eight 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_image | Read a retained local raster image using the message and image index returned by get_conversation. No private provider URL fetching or OCR. | | get_conversation | Fetch the full transcript of one conversation by its id (the id field from search results). The response carries contentFingerprint, the current fingerprint of the returned transcript (see below). | | 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. | | conversation_inventory | Paginated, read-only inventory of every conversation as compact metadata: id, platform, title, and a versioned content fingerprint. Built for services that periodically process the corpus; see below. | | 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. | | save_memory | Record a durable fact (a decision, preference, or correction) worth carrying into later chats. Stored turned off until the user reviews and enables it. |

Conversation inventory

conversation_inventory exists for programs that periodically process the whole corpus, not for interactive questions. Each item is compact metadata: the stable id, platform, title, and a versioned content fingerprint. It never returns transcripts.

Call it with no arguments to start a scan, then pass each page's nextCursor back as cursor until a page comes back without one. Pages hold up to 100 items (limit can go lower):

{
  "count": 100,
  "total": 250,
  "scanStartedAt": 1769000000000,
  "items": [
    { "id": "claude:rust-borrow", "platform": "claude",
      "title": "Debugging a Rust borrow checker error",
      "fingerprint": "fp2:9af3c0d7…" }
  ],
  "nextCursor": "inv1.eyJzIjoi…"
}

Every page of a scan reads the same snapshot, captured (sorted by id) when the scan started. Conversations that arrive or change while you are paging never appear in, disappear from, or change values within an in-flight scan; start a new scan (omit cursor) to see them. Snapshots are bounded: at most eight are held at once (the oldest is evicted) and each expires after about 15 minutes. Cursors are opaque, they do not survive an MCP server restart, and an expired or unknown cursor returns a clear error telling the caller to begin a new scan.

Images are included in the fp2 fingerprint. MCP 0.2.13 automatically rebuilds the derived index as format v8 on first use, recomputing every inventory fingerprint from the same canonical records used by retrieval. This repairs mixed fp1/fp2 inventories left by earlier versions. The canonical transcripts are unchanged, and later opens reuse the rebuilt index. Stop all MCP clients before updating and restart them afterward; the first read can take longer while rebuilding. Clients starting together wait for the index to become ready. An interrupted initial rebuild is retried on the next open. No extension history rebuild or backup reimport is needed.

Consumer migration: begin a new complete inventory scan without an old cursor. Replace the saved fp1 baseline with the new fp2 values and reverify those records. Different scheme prefixes are not comparable content revisions. Existing fp2 digests retain their definition and values for unchanged content. Future incompatible fingerprint changes require a new scheme prefix, an index migration and a documented consumer migration before release.

Local raster copies are bounded to 2 MiB per image and 8 MiB per captured conversation. Vault sync retains URL metadata only. Protected or expired images without a retained copy need recapture or a supported bundled export.

The fingerprint is fp2: followed by a SHA-256 hex digest. It covers exactly:

• the conversation title, and the user's local alias (localTitle) when set;
• every message in msgIndex order: its index, role, stored text, and formattedText when present;
• image references, metadata and retained local bytes. Image-only changes are visible to an inventory client even when transcript text is unchanged.

It deliberately excludes every timestamp, including the provider's updatedAt: historical imports can retain old source dates, and a genuinely edited conversation can arrive with its source dates unchanged. URLs, pin state, account and model identifiers, summaries, and other derived fields are excluded too. An identical re-ingest therefore never changes the fingerprint, while an edited message or a rename always does, even when nothing else about the record moved. The fingerprint is stored in the derived search index (index format v8; opening an older index triggers a rebuild that computes fp2 fingerprints for the existing corpus), so a scan never decompresses a single transcript.

A periodic-processing loop:

1. Scan all pages of conversation_inventory, collecting each id and fingerprint.
2. Compare with the previous run: an id not seen before is new; a changed fingerprint means that conversation's content changed. Everything else can be skipped.
3. Call get_conversation only for the new or changed ids. Its response carries contentFingerprint, the fingerprint of the transcript it returns. Within the same scheme, a different digest means the conversation changed after your snapshot was taken and the fetched transcript is current. A different scheme prefix requires the baseline migration described above.

Read-only mode (LLMNESIA_READ_ONLY)

The Claude Desktop extension (.mcpb) ships with LLMNESIA_READ_ONLY=1, which disables the two write tools (save_conversation and save_memory) so that ordinary history searches run without a per-call approval prompt. The general npm install exposes all eight tools.

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. | | ZCode | Edits the user-scope ~/.zcode/cli/config.json, adding the server under ZCode's nested mcp.servers key with a backup first, and prepares that file in advance if ZCode is installed later. ZCode validates this file strictly and connects servers from it automatically at session start. | | 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 retry-quarantine # repair eligible files; retain original backups
llmnesia-mcp watch         # ingest new inbox deltas live (Ctrl+C to stop)
llmnesia-mcp stats         # corpus summary
llmnesia-mcp compact --dry-run # exact read-only storage/savings report
llmnesia-mcp compact       # confirmed lossless migration + redundant cleanup
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.