gemdex-mcp

gemdex-mcp

MCP memory layer for AI coding agents — save_memory / recall / get_memory / update_memory / delete_memory (plus outcome + attachment tools) backed by Gemini embeddings + embedded LanceDB.

Part of Gemdex.

Install for Claude Code

claude mcp add gemdex -- npx -y gemdex-mcp@latest

All seven tools return setup guidance until you choose a backend. Ask Claude to help choose, then run one command on your machine:

• npx gemdex-mcp setup gemini — hidden key prompt, validated before persistence.
• npx gemdex-mcp install — Apple Silicon only: installs managed Python/MLX and pinned mlx-community/bge-m3-mlx-8bit, then sets GEMINI_API_KEY=local (exact lowercase) so local text embeddings activate. Requires macOS 14+ and native arm64 Node (not Rosetta). No preinstalled Python, uv, Homebrew, Hugging Face tooling or compiler needed.
• npx gemdex-mcp init-remote home https://memory.example.com — connect an existing server, with a hidden bearer-token prompt.

Local LLM gate: the managed local model is used only when the Gemini API key env value is exactly local (e.g. MCP "GEMINI_API_KEY": "local" or ~/.gemdex/.env after install / embedding mlx). Any other non-empty value is treated as a real Gemini API key. Empty/missing still requires setup — it does not fall through to local MLX. GEMDEX_EMBEDDING_PROVIDER=mlx alone is not enough.

Install needs network access and does not migrate existing memories. Use npx gemdex-mcp migrate-text separately to move text into a new 1024-dimensional bank, with rerunnable progress. Media/attachment rows stay on Gemini. Recall searches both banks; it reports a Gemini failure rather than silently hiding legacy/media memories. With GEMINI_API_KEY=local, new MLX-only text works offline; media and history digestion still need a real Gemini key.

Use npx gemdex-mcp embedding gemini or embedding mlx to switch future text writes (mlx writes GEMINI_API_KEY=local; gemini needs a real key), and npx gemdex-mcp status to inspect configuration. Settings are saved under ~/.gemdex and shared with the Swift app's Storage & Gemini controls. Remove conflicting launch environment overrides before switching. Retry the tool after setup; reconnect via Claude Code /mcp if needed. History digestion and media still need Gemini; BYOI continues to embed server-side unchanged.

No Docker, no daemon. Memories live at ~/.gemdex/lance by default.

To use a self-hosted Gemdex Server instead, configure remote mode. The client does not need GEMINI_API_KEY; embedding runs on the server:

claude mcp add gemdex \
  -e GEMDEX_MODE=remote \
  -e GEMDEX_REMOTE_URL=https://memory.example.com \
  -e GEMDEX_REMOTE_TOKEN=your-server-token \
  -- npx -y gemdex-mcp@latest

Configure remotes with the CLI

The easiest path is init-remote — it adds the remote, prompts for the token (without echoing it), verifies the server is reachable, authenticated, and version-compatible, switches to remote mode, and prints the agent command:

npx gemdex init-remote production https://memory.example.com

# Also copy this machine's local memories into the server in the same step:
npx gemdex init-remote production https://memory.example.com --import-local

Or run the individual steps:

# Prompts for the bearer token without echoing it.
npx gemdex remote add production https://memory.example.com

npx gemdex remote list
npx gemdex mode remote production
npx gemdex status

# Return to the embedded local backend.
npx gemdex mode local

# Copy the local store to a named remote, preserving memory ids.
npx gemdex import-local-to-remote production

Named remotes live in ~/.gemdex/config.json. Bearer tokens are stored separately in ~/.gemdex/.env with user-only file permissions and are never printed. For automation, use --token-stdin; to manage the secret externally, use --token-env MY_TOKEN_VAR.

Local and remote at the same time

Mode is per process via GEMDEX_MODE, so you can register two MCP servers — one local, one remote — as two independent memory pools that never merge:

claude mcp add gemdex-local \
  -e GEMDEX_MODE=local -e GEMINI_API_KEY=your-key \
  -- npx -y gemdex-mcp@latest

claude mcp add gemdex-remote \
  -e GEMDEX_MODE=remote \
  -e GEMDEX_REMOTE_URL=https://memory.example.com \
  -e GEMDEX_REMOTE_TOKEN=your-server-token \
  -- npx -y gemdex-mcp@latest

Pass GEMDEX_MODE per server (not gemdex mode …, which sets one shared mode).

Install for any MCP client

{
  "mcpServers": {
    "gemdex": {
      "command": "npx",
      "args": ["-y", "gemdex-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-key"
      }
    }
  }
}

See the BYOI operations guide for server deployment, TLS, storage, backup/restore, upgrades, and troubleshooting.

Tools

• save_memory(content, title?) — persist a new memory; returns its id.
• recall(query, limit?) — retrieve full memories by natural language (hybrid semantic + BM25), ranked by relevance. Never returns fragments.
• update_memory(id, content?, edits?, title?) — revise an existing memory in place. edits is a targeted find-and-replace ({ oldText, newText, replaceAll? }) so you can change part of a large memory without resending it; content is a full rewrite. The two are mutually exclusive.

Deletion is intentionally not an agent tool — it's a human action in the Gemdex desktop app.

Chat-history ingestion

npx gemdex ingest-history --source claude --dry-run
npx gemdex ingest-history --source claude

Ingestion processes only sessions that have never been successfully ingested. Previously ingested sessions are reported as skipped and are never re-digested, even if the transcript later changes. This invariant is enforced by the core engine; there is no CLI or sidecar override. Digestion always needs a local GEMINI_API_KEY, including when memory storage is remote.

Syncing history to a self-hosted host

sync-history is the same pipeline pointed at a remote Gemdex host, so every machine you code on feeds one searchable pool:

npx gemdex sync-history --url https://gemdex.example.com/mcp --dry-run
npx gemdex sync-history --url https://gemdex.example.com/mcp

The first run opens a browser once to sign in as the host's allowlisted Google account; after that the stored refresh token is redeemed silently. Set GEMDEX_SYNC_URL to skip --url, and use --logout to forget a host's credentials (kept in ~/.gemdex/sync-auth.json, 0600).

Notes:

• Digests are built on your machine (your GEMINI_API_KEY) — only the digest and the transcript are uploaded, never your whole session history unprocessed.
• Session ids are deterministic, so syncing the same history twice updates in place instead of creating duplicates. Safe to re-run, and safe to run from several machines.
• https is required for anything but a loopback host: the request carries an access token.
• This is a write-only capability. It can add or update chat digests on the host and nothing else.

Desktop sidecar

The same binary also runs the localhost HTTP manager API used by the desktop app:

npx gemdex serve --port 0   # 127.0.0.1 only; --port 0 = OS picks a free port

Environment

Variable	Description
GEMDEX_MODE	local (default) or remote
GEMINI_API_KEY	Real Google AI Studio key, or exact local for managed MLX text
LANCEDB_PATH	(optional) Custom directory for the embedded store (default ~/.gemdex/lance)
GEMDEX_REMOTE_URL	Required in remote mode; Gemdex Server root URL
GEMDEX_REMOTE_TOKEN	Required in remote mode by default; server bearer token
GEMDEX_REMOTE_TOKEN_ENV_VAR	Optional alternate env var containing the remote token
GEMDEX_SYNC_URL	(optional) Default host /mcp endpoint for sync-history
GEMDEX_REMOTE_NAME	Optional human-readable remote name

See the main repo for all environment variables and configuration options.

MCP Registry

mcp-name: io.github.nikships/gemdex

License

MIT