Gemdex README

Persistent memory for AI coding agents

Save a useful memory once and recall it across repos and sessions. Gemdex indexes small chunks for precise hybrid semantic + BM25 matching, then resolves matches to whole parent memories. MCP agents scan a cheap title index and open only the memories they need.

Two ways to run it

These are separate pools. The npx package and desktop sidecar are local-only; connect directly to HTTP MCP for a self-hosted pool.

Local quickstart

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

The explicit install downloads managed Python/MLX and pinned mlx-community/bge-m3-mlx-8bit weights, about 600 MB. No Python, uv, Homebrew, HF CLI, or compiler setup is needed. Embeddings run offline after installation. There is no API key, sentinel value, or provider switch. Rosetta Node is unsupported. See MLX model and runtime requirements.

All seven tools remain discoverable before installation and return setup guidance. Retry a tool after installation, or reconnect your MCP client.

For another MCP client:

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

Upgrade from Gemini-based releases

Run npx gemdex-mcp migrate after installation. It re-embeds legacy memories from memories into memories_mlx_bge_m3_8bit, preserving text, titles, timestamps and attachment bytes. Installation alone does not migrate.

Recall and hygiene refuse to run while legacy rows remain. List/get/update/ delete/export remain available after installation. Migration reports progress and is rerunnable. Legacy media blobs remain readable but are not media-searchable; back up your store before migrating.

Save and recall

Ask your agent to save something durable:

Save how we set up the review workflow to memory.

Then, in another session or repo using that pool:

Check memory for our review workflow and use it here.

Tell your agent when to use memory in its instructions:

## Memory

Use Gemdex recall to find relevant memories before starting work.
Recall returns titles and ids; use get_memory only for useful hits.
Save reusable findings and update existing memories when correcting them.
Report worked/failed/stale outcomes after acting on a fetched memory.
Use read_attachment for transcript bytes.
Delete only when a memory should be permanently removed and the connected
surface provides delete_memory.

MCP tools

get_memory, not title-index recall, increments recall counts. Stats live in a separate ledger (~/.gemdex/stats.json by default). GEMDEX_TRUST_RANKING=true enables outcome-weighted title ranking; otherwise ranking is relevance-only.

Local saves include an advisory when existing memories are similar, using already-computed vectors and centroid similarity (default threshold 0.90). The advisory does not block the save. Configure it with GEMDEX_SIMILAR_ON_SAVE and GEMDEX_SIMILAR_THRESHOLD.

Attachments

Local attachments are text files only: .txt, .json, .jsonl/.ndjson. Use a local path or inline base64 data + mimeType. Supported MIME types are text/plain, application/json, application/jsonl, application/x-ndjson, text/x-jsonl, up to four files per memory, 20 MiB each. Bytes are non-embedded blobs, readable through read_attachment. New images, audio, video, PDF and media recall queries are unsupported locally.

The self-hosted server supports Gemini multimodal embedding and media recall through /v1. HTTP MCP attachment inputs are inline base64 only, never client filesystem paths. See the /v1 contract.

Chat history and memory hygiene

Local digestion and hygiene use your existing Claude Code login. Install Claude Code and run claude auth login, then:

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

Sources include Claude Code, Factory CLI, Codex, Antigravity, or a folder path. Only never-before-ingested sessions are processed. Each produces a digest memory and a cleaned transcript attachment. backfill-transcripts attaches files referenced by older digest footers, with --dry-run and --force options; missing files are skipped with a message.

Inference runs as isolated claude -p --model haiku structured-JSON calls: no tools, settings, skills, MCP servers, hooks, CLAUDE.md, or session persistence, and a temporary working directory. Concurrency is four, with at most three total attempts and a five-minute timeout per call.

Cost estimates are Haiku API list-price equivalents ($1 input / $5 output per million tokens). With a Claude subscription, usage counts against plan limits, not a per-token bill. Local embeddings stay on-device, but ingestion transcripts and hygiene candidates go through Claude Code inference.

Hygiene first clusters local vectors, then judges candidates with Claude Code. Deleting findings requires human approval. Self-hosted uploads instead use the server's Gemini digestion. See chat-history paths.

The desktop app (maintenance-only)

The native macOS app manages the local pool through gemdex serve, which binds only 127.0.0.1 and uses a per-launch token. Its contract exposes explicit MLX install/migration jobs and Claude Code readiness. Memory routes return 503 {needsInstall:true} until installation; ingestion/hygiene start requires Claude Code readiness. See the sidecar contract.

The web manager is the primary human surface for self-hosted deployments. The desktop app is not a client for that pool.

Self-host the whole stack (one command)

curl -fsSL https://raw.githubusercontent.com/nikships/gemdex/main/scripts/install.sh | bash

The installer starts Postgres, gemdex-server, HTTP MCP and the web manager, generates secrets, waits for migrations, verifies a real save and recall, and prints Streamable HTTP client configuration. It asks for a Google AI Studio key, or reads GEMINI_API_KEY. This key belongs to the server, not the agent client.

The default is loopback-only. --lan exposes MCP and web to your trusted LAN with static MCP auth and login-free web access. For public access, use HTTPS, Google OAuth, and the deployment guide. Never publish Postgres or /v1.

{
  "mcpServers": {
    "gemdex": {
      "type": "http",
      "url": "https://gemdex.example.com/mcp"
    }
  }
}

This example targets a Google OAuth deployment; the client handles login.

Packages and library use

To use the engine directly, see the core library example. Local environment settings are in the MCP README; self-hosted settings are in the server README.

Privacy & safety

Memory text and attachment bytes are plaintext unless you add your own storage controls. Gemdex provides no secret redaction or hosted custody service. Local embeddings run on-device; local ingestion and hygiene send selected content through Claude Code using your account. The self-hosted server sends embedding payloads and uploaded-session digestion to Gemini using its key. See custody and self-host security.

Build from source

From a clone with Node ≥24 and pnpm ≥10:

pnpm install
pnpm build

The local MCP entry point is packages/mcp/dist/index.js. See CONTRIBUTING.md for checks and development guidance.

License

MIT. See LICENSE.

MCP Registry

mcp-name: io.github.nikships/gemdex