# Gemdex

A memory layer for AI coding agents: store a note once, then pull it back in another session or repo.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6
- Author: nikships
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/nikships/gemdex
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/gemdex

## What it 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`.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `GEMINI_API_KEY`, `GEMDEX_MODE`, `LANCEDB_PATH`, `EMBEDDING_MODEL`, `GEMDEX_REMOTE_URL`, `GEMDEX_REMOTE_TOKEN`, `GEMDEX_REMOTE_NAME`, `GEMDEX_TRUST_RANKING` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 3 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 3 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 3 more environment variables are in the server README

## When to use it
- 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
- Look in memory for our review workflow and apply it here.
- Is there anything in memory about this screenshot?

## Similar
- [memory-lancedb-pro](https://affpapa.org/en/nevibecode/skills/memory-lancedb-pro.md) — skill · 643 installs
- [memory-lancedb-pro-openclaw](https://affpapa.org/en/nevibecode/skills/memory-lancedb-pro-openclaw.md) — skill · 1300 installs
- [elite-longterm-memory](https://affpapa.org/en/nevibecode/skills/elite-longterm-memory.md) — skill · 2400 installs
- [memory-hygiene](https://affpapa.org/en/nevibecode/skills/aaaaqwq-memory-hygiene.md) — skill · 374 installs
- [memory-bridge](https://affpapa.org/en/nevibecode/skills/ruvnet-memory-bridge.md) — skill · 744 installs
- [shodh-memory](https://affpapa.org/en/nevibecode/mcp/shodh-memory.md) — MCP server · ★ 316

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md