goodmem:mcp

GoodMem MCP Tools — Workflow Guide

The GoodMem MCP server exposes tools across multiple API namespaces plus local utilities. Most tools map to a GoodMem REST API endpoint; the utilities (goodmem_configure, goodmem_lookup_model, goodmem_client_info) run locally without contacting the server. Use tools/list to discover exact parameter schemas — this document covers workflow and patterns only.

Setup: The MCP server needs GOODMEM_BASE_URL and GOODMEM_API_KEY. These can be set as environment variables before launch, or configured from chat via goodmem_configure.

TLS: If the server uses self-signed or private CA certificates, set NODE_EXTRA_CA_CERTS=/path/to/rootCA.pem or NODE_TLS_REJECT_UNAUTHORIZED=0 (local dev only) as an environment variable before launch.

---

Typical workflow

1. Configure — call goodmem_configure if credentials weren't set via env vars.
2. Register providers — create embedder, LLM, and optionally reranker. Use goodmem_lookup_model to check the model registry before creating — it auto-infers provider, endpoint, and dimensionality for known models.
3. Create a space — a space binds an embedder and chunking config. Memories ingested into a space are automatically chunked and embedded.
4. Ingest memories — use goodmem_memories_create (single) or goodmem_memories_batch_create (bulk). Supports text, base64-encoded files, or URL references.
5. Wait for processing — after ingestion, memories are processed asynchronously. Poll with goodmem_memories_get until processingStatus is COMPLETED.
6. Retrieve — goodmem_memories_retrieve performs semantic search. Returns NDJSON with ranked results.

---

Namespaces

Embedders (goodmem_embedders_*)

Register and manage embedding models. The four SaaS provider types (OpenAI, Cohere, Voyage, Jina) require credentials. OpenAI-compatible endpoints (Anthropic, Google, Mistral) also require credentials when used under the OPENAI provider type. Omitting credentials for a known SaaS endpoint throws an error before the request is sent.

CRUD: create, list, get, update, delete.

LLMs (goodmem_llms_*)

Register and manage LLM configurations. Same credential pattern as embedders.

CRUD: create, list, get, update, delete.

Rerankers (goodmem_rerankers_*)

Register and manage reranker models for result re-ranking.

CRUD: create, list, get, update, delete.

Spaces (goodmem_spaces_*)

Memory spaces — containers that bind an embedder and chunking config.

CRUD: create, list, get, update, delete.

Memories (goodmem_memories_*)

Store, retrieve, and manage memories within spaces.

• create / batch_create — ingest content (text, base64, or URL reference)
• retrieve — semantic search across one or more spaces (returns NDJSON)
• get / batch_get — fetch by ID
• list — list memories in a space
• delete / batch_delete — remove memories
• pages — list memory page images with optional filters and pagination

Not available via MCP (binary response): content, pages_image.

OCR (goodmem_ocr_*)

• document — extract text from a document using OCR

Ping (goodmem_ping_*)

Connectivity probes for embedders, LLMs, rerankers, and other GoodMem endpoints.

• once — run one probe and return a PingResult
• stream — run streaming probes and return NDJSON ping events

Users (goodmem_users_*)

• me — get the current authenticated user
• get — get a user by ID or email

API Keys (goodmem_apikeys_*)

Manage API keys for authentication.

CRUD: create, list, update, delete.

System (goodmem_system_*)

• info — server version and configuration
• init — first-time server initialization

Admin (goodmem_admin_*)

• drain — request the server to enter drain mode
• background_jobs_purge — purge completed background jobs
• license_reload — reload the server license

Utilities

• goodmem_configure — set base URL and API key from chat
• goodmem_lookup_model — look up model registry entries before creating embedders/LLMs/rerankers
• goodmem_client_info — return MCP client version and the goodmem server commit it was built against