@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

Utility tools (hand-coded, not derived from the IR)

| Tool | Description | |------|-------------| | goodmem_configure | Set base_url / api_key at runtime; overrides env vars. Call once after npx @goodmem/mcp if env isn't configured. | | goodmem_lookup_model | Inspect the built-in model registry. Shows what fields auto-infer for a given model_identifier. | | goodmem_client_info | Report MCP client package version and the goodmem server commit it was built against. No server connection required. |

API tools (auto-generated from the OpenAPI/IR)

Embedders

| Tool | Description | |------|-------------| | goodmem_embedders_create | Create a new embedder | | goodmem_embedders_delete | Delete an embedder | | goodmem_embedders_get | Get an embedder by ID | | goodmem_embedders_list | List embedders | | goodmem_embedders_update | Update an embedder |

LLMs

| Tool | Description | |------|-------------| | goodmem_llms_create | Create a new LLM | | goodmem_llms_delete | Delete an LLM | | goodmem_llms_get | Get an LLM by ID | | goodmem_llms_list | List LLMs | | goodmem_llms_update | Update an LLM |

Rerankers

| Tool | Description | |------|-------------| | goodmem_rerankers_create | Create a new reranker | | goodmem_rerankers_delete | Delete a reranker | | goodmem_rerankers_get | Get a reranker by ID | | goodmem_rerankers_list | List rerankers | | goodmem_rerankers_update | Update a reranker |

Spaces

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

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

Memories

| Tool | Description | |------|-------------| | goodmem_memories_batch_create | Create multiple memories in a batch | | goodmem_memories_batch_delete | Delete memories in batch | | goodmem_memories_batch_get | Get multiple memories by ID | | goodmem_memories_create | Create a new memory | | goodmem_memories_delete | Delete a memory | | goodmem_memories_get | Get a memory by ID | | goodmem_memories_list | List memories in a space | | goodmem_memories_pages | List memory page images | | goodmem_memories_retrieve | Advanced semantic memory retrieval with JSON |

OCR

| Tool | Description | |------|-------------| | goodmem_ocr_document | Run OCR on a document or image |

Users

| Tool | Description | |------|-------------| | goodmem_users_get | Get a user by ID | | goodmem_users_me | Get current user profile |

API Keys

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

System

| Tool | Description | |------|-------------| | goodmem_system_info | Retrieve server build metadata | | goodmem_system_init | Initialize the system |

Admin

| Tool | Description | |------|-------------| | goodmem_admin_background_jobs_purge | Purge completed background jobs | | goodmem_admin_drain | Request the server to enter drain mode | | goodmem_admin_license_reload | Reload the active license from disk | | goodmem_admin_retrieve_memory_log_policies_create | Create a RetrieveMemory log policy | | goodmem_admin_retrieve_memory_log_policies_delete | Delete a RetrieveMemory log policy | | goodmem_admin_retrieve_memory_log_policies_get | Get a RetrieveMemory log policy | | goodmem_admin_retrieve_memory_log_policies_list | List RetrieveMemory log policies |

Ping

| Tool | Description | |------|-------------| | goodmem_ping_once | Run a single ping probe | | goodmem_ping_stream | Stream ping probe results |

Auto-inference

When creating embedders, LLMs, or rerankers, provide model_identifier and the MCP server fills in provider_type, endpoint_url, dimensions, and other fields automatically from the built-in registry of 79 models. Inference happens client-side in the MCP layer before the request is sent.

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 MCP server returns a clear error locally — before the request leaves the process — so there are 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