zme-mcp

Zeug Memory Engine as an MCP server. Hybrid retrieval (vector + lexical, RRF-fused) and a bitemporal knowledge graph over Zeug's collected knowledge — 15k+ chunks of research, notes, articles and transcripts — exposed to any MCP client: Claude, Cursor, Codex, Hermes, and ChatGPT (deep research + company knowledge compatible).

Measured on the Zeug corpus: hybrid R@5 0.800 · MRR 0.562 · source-recall@10 0.900 — +18.1% MRR over vector-only.

Tools

Related MCP server: engram

Authentication — the zeuglab → ClawPanel auth model (alpha)

This server is the alpha ring of the ecosystem auth design:

OAuth 2.1, self-contained (no external IdP): DCR, PKCE, authorization codes, refresh tokens, revocation — the full flow ChatGPT performs. /authorize shows a zeuglab login form; profiles are configured server-side:

ZME_AUTH=oauth
ZME_BASE_URL=https://zme-mcp.fly.dev
ZME_OAUTH_PROFILES='{"alex":{"secret":"…","level":"owner"},
                     "guest":{"secret":"…","level":"viewer"}}'

Profile levels → scopes: owner/operator get zme:read + zme:write; viewer gets zme:read. The server forces scopes from the profile — client requests are never trusted. A viewer's tools/list doesn't even contain remember. In beta the in-memory stores become tables and passphrases become Supabase sessions; the scope contract stays identical, so alpha clients keep working.

Legacy token mode (ZME_AUTH=token + ZME_MCP_TOKEN) still works in the alpha ring for stdio-style clients that can't do OAuth; it is a startup error from ring beta onwards.

Configuration

On macOS, keys are also auto-resolved from the NoxKey keychain (one Touch ID prompt per session) when the env vars are absent.

Install & run — local agents (stdio)

No install needed with uv (any machine with Python):

uvx --from git+https://github.com/Sidarau/zme-mcp zme-mcp

or pipx: pipx install git+https://github.com/Sidarau/zme-mcp · PyPI (uvx zme-mcp) once the package is published there.

Claude Code — claude mcp add zme -- uvx --from git+https://github.com/Sidarau/zme-mcp zme-mcp

Claude Desktop / Cursor (mcpServers JSON):

{
  "zme": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/Sidarau/zme-mcp", "zme-mcp"],
    "env": { "ZME_SUPABASE_KEY": "…", "NVIDIA_API_KEY": "…" }
  }
}

Run as a service (HTTP) — for ChatGPT

zme-mcp --http --host 0.0.0.0 --port 8000
# streamable HTTP endpoint: POST /mcp · health: GET /healthz

Connect from ChatGPT (OAuth)

1. Server is live at https://zme-mcp.fly.dev (this repo ships Dockerfile + fly.toml: flyctl deploy).

2. In ChatGPT: Settings → Security and login → Developer mode → on.

3. Go to chatgpt.com/plugins → + → enter https://zme-mcp.fly.dev/mcp.

4. ChatGPT discovers the OAuth metadata, registers itself via DCR, and opens the zeuglab login form — sign in with your profile (alex + passphrase). The token it gets back carries your level's scopes.

5. Use it in chat — and in deep research, where the search/fetch pair makes ZME a citable knowledge source.

Security model

• Read path is plain SELECT through PostgREST with whatever key you configure — use the anon key anywhere shared.

• The only write is remember, which calls zme_remember(): a SECURITY DEFINER function whose entire capability is "create one note". No UPDATE, no DELETE, no schema access.

• The HTTP layer never logs keys; the token is compared, not echoed.

Development

python3 -m venv .venv && .venv/bin/pip install -e .
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}' | .venv/bin/zme-mcp