Gemdex — MCP server for Claude Code: persistent agent memory
A memory layer for AI coding agents: store a note once, then pull it back in another session or repo.
claude mcp add --env GEMINI_API_KEY=<GEMINI_API_KEY> --env GEMDEX_MODE=<GEMDEX_MODE> --env LANCEDB_PATH=<LANCEDB_PATH> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --env GEMDEX_REMOTE_URL=<GEMDEX_REMOTE_URL> --transport stdio gemdex -- npx -y gemdex-mcpWhat Gemdex does
Gemdex keeps small chunks in a local store and matches them with hybrid search — semantic similarity plus BM25 — then hands the agent the full parent memory. Agents read a cheap title index first and open only what they need.
There are two ways to run it. Locally it speaks stdio through npx gemdex-mcp: EmbeddingGemma 2 runs on-device and data sits in LanceDB under ~/.gemdex. That path wants Apple Silicon, macOS 14+ and native arm64 Node ≥24. The explicit install pulls managed Python/MLX and model weights — roughly 1.45 GB to download, 1.9 GB on disk. No API key is involved and embeddings keep working offline. Rosetta Node is not supported, which is where older Macs fail first.
The self-hosted route connects over Streamable HTTP at /mcp, embeds with server-side Gemini, and stores data in Postgres/pgvector plus file or S3 blobs. It is a separate pool shared across machines. Local attachments cover images, audio up to 5 minutes and video; PDFs are out. Digesting chat history and memory hygiene need a Claude login via claude auth login.
What it helps with
- keep a good debugging write-up and reuse it in another repo
- find a screenshot or recording by what it shows or says
- update an outdated note instead of creating a duplicate
- mark whether a recalled tip actually worked
- turn past Claude sessions into digest memories
Example prompts for the agent
- Look in memory for our review workflow and apply it here.
- Is there anything in memory about this screenshot?
How to install Gemdex
Platform CLI
claude mcp add --env GEMINI_API_KEY=<GEMINI_API_KEY> --env GEMDEX_MODE=<GEMDEX_MODE> --env LANCEDB_PATH=<LANCEDB_PATH> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --env GEMDEX_REMOTE_URL=<GEMDEX_REMOTE_URL> --transport stdio gemdex -- npx -y gemdex-mcpReplace <…> with your own values. 3 more environment variables are in the server README
Platform CLI
codex mcp add gemdex --env GEMINI_API_KEY=<GEMINI_API_KEY> --env GEMDEX_MODE=<GEMDEX_MODE> --env LANCEDB_PATH=<LANCEDB_PATH> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --env GEMDEX_REMOTE_URL=<GEMDEX_REMOTE_URL> -- npx -y gemdex-mcpReplace <…> with your own values. 3 more environment variables are in the server README
Config file
{
"mcpServers": {
"gemdex": {
"command": "npx",
"args": [
"-y",
"gemdex-mcp"
],
"env": {
"GEMINI_API_KEY": "<GEMINI_API_KEY>",
"GEMDEX_MODE": "<GEMDEX_MODE>",
"LANCEDB_PATH": "<LANCEDB_PATH>",
"EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
"GEMDEX_REMOTE_URL": "<GEMDEX_REMOTE_URL>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README
Config file
{
"servers": {
"gemdex": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"gemdex-mcp"
],
"env": {
"GEMINI_API_KEY": "<GEMINI_API_KEY>",
"GEMDEX_MODE": "<GEMDEX_MODE>",
"LANCEDB_PATH": "<LANCEDB_PATH>",
"EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
"GEMDEX_REMOTE_URL": "<GEMDEX_REMOTE_URL>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README
Platform CLI
gemini mcp add -e GEMINI_API_KEY=<GEMINI_API_KEY> -e GEMDEX_MODE=<GEMDEX_MODE> -e LANCEDB_PATH=<LANCEDB_PATH> -e EMBEDDING_MODEL=<EMBEDDING_MODEL> -e GEMDEX_REMOTE_URL=<GEMDEX_REMOTE_URL> gemdex npx -y gemdex-mcpReplace <…> with your own values. 3 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Gemdex
How do I install Gemdex in Claude Code?
Run npx gemdex-mcp install, then claude mcp add gemdex -- npx -y gemdex-mcp@latest. Reconnect your MCP client afterwards.
What does Gemdex do?
It gives an agent persistent memory: saving, recalling and updating entries that survive a new session or repository.
Do I need an API key for the local mode?
No. Embeddings run on-device and work offline once installed. A Gemini key only matters for the self-hosted setup.
