@llmnesia/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keiran Flynn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @llmnesia/mcp
+
+Search your own AI chat history from Claude Desktop, Claude Code, Cursor,
+Codex, and other MCP clients. Covers every conversation the
+[LLMnesia browser extension](https://llmnesia.com) 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](https://modelcontextprotocol.io)
+over stdio.
+
+Requires **Node.js ≥ 22.13.0** (for the built-in `node:sqlite` module).
+
+## Install
+
+```bash
+npx @llmnesia/mcp install
+```
+
+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. detects which MCP clients you have (Claude Code, Claude Desktop, Cursor,
+   Codex, and others), and
+4. registers that copy with each of them — after a confirm prompt and a backup
+   of any config file it edits.
+
+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
+
+```bash
+npx @llmnesia/mcp@latest install
+```
+
+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](https://llmnesia.com), free on
+the [Chrome Web Store](https://chromewebstore.google.com/detail/llmnesia/leekfgbdojiaabifbjbbgiiclannjdkf):
+
+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. It writes them to the local corpus at `~/.llmnesia/corpus/`. `@llmnesia/mcp`
+   reads from the same folder — there is nothing to configure.
+
+If you have not run the extension yet, the corpus will be empty and every
+search will come back empty too.
+
+## Tools
+
+Once registered, your MCP client gains five 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_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` with the absolute Node and installed runtime paths (detects `claude` on PATH). |
+| Claude Desktop | Edits `claude_desktop_config.json` at the standard OS-specific path. |
+| Cursor | Edits `~/.cursor/mcp.json`. |
+| Codex | Prints a TOML block for `~/.codex/config.toml` (auto-edit is too fragile). |
+| 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
+
+```bash
+npx @llmnesia/mcp doctor
+```
+
+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
+
+```bash
+npx @llmnesia/mcp uninstall
+```
+
+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: [llmnesia.com/mcp](https://llmnesia.com/mcp) or
+hello@llmnesia.com.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,205 @@
+@llmnesia/mcp includes portions of the following third-party software.
+
+-------------------------------------------------------------------------------
+@modelcontextprotocol/sdk
+
+MIT License
+
+Copyright (c) 2024 Anthropic, PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+zod
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+ajv and ajv-formats
+
+The MIT License (MIT)
+
+Copyright (c) 2015-2021 Evgeny Poberezkin (ajv)
+Copyright (c) 2020 Evgeny Poberezkin (ajv-formats)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+fast-uri
+
+Copyright (c) 2011-2021, Gary Court until
+https://github.com/garycourt/uri-js/commit/a1acf730b4bba3f1097c9f52e7d9d3aba8cdcaae
+Copyright (c) 2021-present The Fastify team
+<https://github.com/fastify/fastify#team>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * The names of any contributors may not be used to endorse or promote
+      products derived from this software without specific prior written
+      permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The complete list of contributors can be found at:
+https://github.com/garycourt/uri-js/graphs/contributors
+
+-------------------------------------------------------------------------------
+chokidar
+
+The MIT License (MIT)
+
+Copyright (c) 2012 Paul Miller (https://paulmillr.com), Elan Shanker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+-------------------------------------------------------------------------------
+readdirp
+
+MIT License
+
+Copyright (c) 2012-2019 Thorsten Lorenz, Paul Miller (https://paulmillr.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+fast-deep-equal and json-schema-traverse
+
+MIT License
+
+Copyright (c) 2017 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+zod-to-json-schema
+
+ISC License
+
+Copyright (c) 2020, Stefan Terdell
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
+USE OR PERFORMANCE OF THIS SOFTWARE.