@pairsystems/goodmem-mcp

GoodMem MCP server — gives AI agents direct access to GoodMem memory infrastructure via the Model Context Protocol.

Tools across namespaces: embedders, LLMs, rerankers, spaces, memories, retrieval, OCR, users, API keys, and system administration.

Prerequisites

• A running GoodMem server
• Node.js 18+

Configuration

What you need to configure

GoodMem credentials (required):

• GOODMEM_BASE_URL — GoodMem server URL (e.g., https://your-server.example.com)
• GOODMEM_API_KEY — GoodMem API key (starts with gm_)

TLS / self-signed certificates (optional):

This is an advanced topic. If you do not even know what that is, skip this section.

If the GoodMem server uses self-signed CA certificates, set one and only one of the following:

• NODE_EXTRA_CA_CERTS=/path/to/rootCA.pem — adds the CA to the trusted store. More secure, but requires you to copy the certificate file from the GoodMem server to the machine where the MCP server is running.
• NODE_TLS_REJECT_UNAUTHORIZED=0 — disables certificate verification entirely. Easy and hassle-free, but not recommended for production.

How to configure

1. In English from chat (GoodMem credentials only; TLS variables cannot be set this way)

Just tell the MCP server your server details — it will call goodmem_configure automatically:

"Configure GoodMem with base URL https://my-server.com and API key gm_abc123"

Credentials persist for the session. You can reconfigure anytime to switch servers.

2. Shell export (before launching the MCP server; works for all configurations)

export GOODMEM_BASE_URL="https://your-server.example.com"
export GOODMEM_API_KEY="gm_..."
export NODE_EXTRA_CA_CERTS="/path/to/rootCA.pem"  # only if needed for self-signed certs
export NODE_TLS_REJECT_UNAUTHORIZED=0              # only if you want to skip cert verification

3. MCP client JSON config

Add an env block in your MCP client's JSON configuration:

{
  "mcpServers": {
    "goodmem": {
      "command": "npx",
      "args": ["-y", "@pairsystems/goodmem-mcp"],
      "env": {
        "GOODMEM_BASE_URL": "https://your-server.example.com",
        "GOODMEM_API_KEY": "gm_...",
        "NODE_EXTRA_CA_CERTS": "/path/to/rootCA.pem", // only if needed for self-signed certs
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"            // only if you want to skip cert verification
      }
    }
  }
}

The JSON file location depends on your MCP client:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Claude Code: .claude/mcp.json in your project
• VS Code / Cursor: see your client's MCP server configuration docs

4. App launcher CLI (only works for apps that support configuration environment variables in is launcher)

For example, in Claude Code:

claude mcp add goodmem -- \
  env GOODMEM_BASE_URL=https://your-server.example.com \
  env GOODMEM_API_KEY=gm_... \
  env NODE_EXTRA_CA_CERTS=/path/to/rootCA.pem

Global install

npm install -g @pairsystems/goodmem-mcp
goodmem-mcp

Quick start

Once connected, ask your AI assistant to:

Create a text-embedding-3-large embedder called "My Embedder" with credentials <sk-...>
Create a space called "Research" using that embedder
Store this text as a memory: "GoodMem is a memory infrastructure platform for AI agents"
Search my Research space for "memory infrastructure"

The MCP server auto-infers provider, endpoint, dimensions, and other fields from the model name — you only need display_name, model_identifier, and credentials for the embedding provider.

Available tools

goodmem_configure

Set server credentials at runtime. Call this if GOODMEM_BASE_URL / GOODMEM_API_KEY are not set as environment variables.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | base_url | string | yes | GoodMem server URL | | api_key | string | yes | GoodMem API key (gm_...) |

goodmem_lookup_model

Inspect the built-in model registry. Shows what fields will be auto-inferred for a given model identifier.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | model_identifier | string | yes | Model name to look up | | type | string | no | embedder, llm, or reranker |

Embedders

| Tool | Description | |------|-------------| | goodmem_embedders_create | Register an embedding model | | goodmem_embedders_list | List registered embedders | | goodmem_embedders_get | Get embedder by ID | | goodmem_embedders_update | Update embedder configuration | | goodmem_embedders_delete | Delete an embedder |

Create parameters: display_name (required), model_identifier (required), credentials (required for SaaS providers), provider_type, endpoint_url, dimensionality — last three auto-inferred from model_identifier for 29 known models.

LLMs

| Tool | Description | |------|-------------| | goodmem_llms_create | Register an LLM configuration | | goodmem_llms_list | List registered LLMs | | goodmem_llms_get | Get LLM by ID | | goodmem_llms_update | Update LLM configuration | | goodmem_llms_delete | Delete an LLM |

Create parameters: display_name (required), model_identifier (required), credentials (required for SaaS providers) — provider_type, endpoint_url, max_context_length auto-inferred for 34 known models.

Rerankers

| Tool | Description | |------|-------------| | goodmem_rerankers_create | Register a reranker model | | goodmem_rerankers_list | List registered rerankers | | goodmem_rerankers_get | Get reranker by ID | | goodmem_rerankers_update | Update reranker configuration | | goodmem_rerankers_delete | Delete a reranker |

Create parameters: display_name (required), model_identifier (required), credentials (required for SaaS providers) — provider_type and endpoint_url auto-inferred for 16 known models.

Spaces

Memory spaces are containers that associate a set of memories with an embedder.

| Tool | Description | |------|-------------| | goodmem_spaces_create | Create a memory space | | goodmem_spaces_list | List spaces | | goodmem_spaces_get | Get space by ID | | goodmem_spaces_update | Update space configuration | | goodmem_spaces_delete | Delete a space |

Memories

| Tool | Description | |------|-------------| | goodmem_memories_create | Store a memory (text, base64, or file reference) | | goodmem_memories_list | List memories in a space | | goodmem_memories_get | Get memory by ID | | goodmem_memories_update | Update memory metadata | | goodmem_memories_delete | Delete a memory | | goodmem_memories_retrieve | Semantic search — query memories by meaning | | goodmem_memories_batch_create | Create multiple memories in one request | | goodmem_memories_batch_get | Get multiple memories by IDs | | goodmem_memories_batch_delete | Delete multiple memories by IDs |

goodmem_memories_retrieve key parameters: space_keys (required), query (required), llm_id (optional, for RAG), reranker_id (optional), max_results, relevance_threshold.

OCR

| Tool | Description | |------|-------------| | goodmem_ocr_document | Extract text from a document |

Users

| Tool | Description | |------|-------------| | goodmem_users_me | Get current authenticated user | | goodmem_users_get | Get user by ID or email |

API Keys

| Tool | Description | |------|-------------| | goodmem_apikeys_create | Create an API key | | goodmem_apikeys_list | List API keys | | goodmem_apikeys_update | Update an API key | | goodmem_apikeys_delete | Delete an API key |

System

| Tool | Description | |------|-------------| | goodmem_system_info | Get server version and configuration | | goodmem_system_init | Initialize the server (first-time setup) |

Admin

| Tool | Description | |------|-------------| | goodmem_admin_drain | Drain the server | | goodmem_admin_background_jobs_purge | Purge completed background jobs | | goodmem_admin_license_reload | Reload the server license |

Auto-inference

When creating embedders, LLMs, or rerankers, provide model_identifier and the server fills in provider_type, endpoint_url, dimensions, and other fields automatically from the built-in registry of 79 models.

Example: calling goodmem_embedders_create with model_identifier: "text-embedding-3-large" auto-fills:

• provider_type → "OPENAI"
• endpoint_url → "https://api.openai.com/v1"
• dimensionality → 1536
• distribution_type → "DENSE"

User-provided values always override inferred defaults. Use goodmem_lookup_model to inspect what will be inferred before creating a resource.

Credential validation

SaaS providers require API credentials. If you call a create tool for a known SaaS endpoint (OpenAI, Cohere, Voyage, Jina, Anthropic via OpenAI-compatible API, Google, Mistral) without providing credentials, the server returns a clear error before the request is sent — no wasted round trips.

For self-hosted or local providers (vLLM, TEI, Ollama, custom endpoints), credentials are optional.

Links

• GoodMem Documentation
• GoodMem on GitHub
• Python SDK on PyPI
• Claude Code Plugin