@pairsystems/goodmem-mcp

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

Store and retrieve memories, configure embedding and inference models, and manage GoodMem resources and access policies. The tool reference lists the complete API surface.

This package runs locally over stdio. For a remote connection focused on retrieval, see GoodMem's separate hosted MCP endpoint.

Prerequisites

• A running GoodMem server, its URL, and a GoodMem API key
• Node.js 20 or newer with npm. Use a currently supported LTS release.

Connect Claude Code

Set GOODMEM_API_KEY in your environment, then replace the server URL and run:

claude mcp add goodmem \
  --env GOODMEM_BASE_URL="https://your-server.example.com" \
  --env GOODMEM_API_KEY="$GOODMEM_API_KEY" \
  -- npx -y @pairsystems/goodmem-mcp

This saves the connection for the current project in your private ~/.claude.json. Open Claude Code and run /mcp to check the connection. Add --scope user before -- to make it available across projects. Reading the key from the environment keeps its value out of the command saved in shell history.

Connect other MCP clients

For clients that use an mcpServers configuration, add:

{
  "mcpServers": {
    "goodmem": {
      "command": "npx",
      "args": ["-y", "@pairsystems/goodmem-mcp"],
      "env": {
        "GOODMEM_BASE_URL": "https://your-server.example.com",
        "GOODMEM_API_KEY": "gm_..."
      }
    }
  }
}

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: .mcp.json at the project root for shared configuration; use the CLI above for private configuration. See Claude Code's MCP documentation.
• VS Code / Cursor: see your client's MCP server configuration docs

Run from a terminal

With GOODMEM_API_KEY already set in your environment:

export GOODMEM_BASE_URL="https://your-server.example.com"
npx -y @pairsystems/goodmem-mcp

The process communicates over stdio and waits for an MCP client. You can also install the command globally:

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

First requests

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.

Custom certificates

If your server uses a private or self-signed CA, add NODE_EXTRA_CA_CERTS to the MCP server's environment, with the absolute path to its PEM certificate file. For Claude Code, add another --env NODE_EXTRA_CA_CERTS="/path/to/rootCA.pem" before --; in JSON, add it to the env object. Restart the MCP connection after changing this setting. An expired or invalid server certificate must be fixed on the server.

Available tools

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

| Tool | Description | |------|-------------| | goodmem_configure | Set base_url / api_key for the current session; overrides env vars. Use after launching npx -y @pairsystems/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_transfer_ownership | Transfer ownership of a space | | 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_content | Download memory content | | 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_pages_image | Download memory page image content | | 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_create | Create a human user | | goodmem_users_create_enrollment | Create a human-user enrollment | | goodmem_users_delete | Delete a human user | | goodmem_users_get | Get a user by ID | | goodmem_users_get_by_username | Get user by username | | goodmem_users_get_enrollment | Get a human-user enrollment | | goodmem_users_list | List human users | | goodmem_users_list_enrollments | List a human user's enrollments | | goodmem_users_me | Get current user profile | | goodmem_users_revoke_enrollment | Revoke a human-user enrollment | | goodmem_users_update | Update a human user |

API Keys

| Tool | Description | |------|-------------| | goodmem_apikeys_create | Create a new API key | | goodmem_apikeys_delete | Delete an API key | | goodmem_apikeys_get | Get 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 | | goodmem_admin_transfer_instance_ownership | Transfer GoodMem instance ownership |

Ping

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

Access_policy

| Tool | Description | |------|-------------| | goodmem_access_policy_check | Check effective authorization | | goodmem_access_policy_grants_create | Create an authorization grant | | goodmem_access_policy_grants_delete | Revoke an authorization grant | | goodmem_access_policy_grants_get | Get an authorization grant | | goodmem_access_policy_grants_list | List authorization grants | | goodmem_access_policy_role_assignments_create | Assign a scoped role | | goodmem_access_policy_role_assignments_delete | Revoke a scoped role assignment | | goodmem_access_policy_role_assignments_get | Get a scoped role assignment | | goodmem_access_policy_role_assignments_list | List scoped role assignments |

Instance

| Tool | Description | |------|-------------| | goodmem_instance_get | Get the GoodMem instance |

Service_identities

| Tool | Description | |------|-------------| | goodmem_service_identities_create | Create a service identity | | goodmem_service_identities_delete | Delete a service identity | | goodmem_service_identities_get | Get a service identity | | goodmem_service_identities_list | List service identities | | goodmem_service_identities_transfer_ownership | Transfer service-identity ownership | | goodmem_service_identities_update | Update a service identity |

User_enrollments

| Tool | Description | |------|-------------| | goodmem_user_enrollments_complete | Complete human-user enrollment |

Binary content delivery

Two memory tools return raw binary payloads:

• goodmem_memories_content — original ingested bytes (text, image, PDF, …)
• goodmem_memories_pages_image — one rendered page image as bytes

The MCP server wraps the response in the appropriate MCP content block based on the response MIME type:

| Server Content-Type | MCP block | What the agent gets | |---|---|---| | image/* | image block | base64 data + mimeType; Claude reads as vision input. | | text/*, application/json | embedded resource with text | MIME-signaled text — preserves text/markdown, text/x-python, etc. | | anything else (PDF, octet-stream, …) | embedded resource with blob | base64 blob + mimeType. Forward-compatible; current Claude models cannot natively render PDF bytes from an MCP block. |

Size cap

Both tools accept an optional max_inline_bytes parameter (units: bytes) so the agent can self-limit per call:

| Knob | Value | Notes | |---|---|---| | Hard server ceiling | 64 MB (67,108,864 bytes) | Baked into the MCP server source. Above this, the tool always errors regardless of max_inline_bytes. | | Default cap | 8 MB (8,388,608 bytes) | Used when the agent doesn't pass max_inline_bytes. | | Per-call override | max_inline_bytes argument | The agent can raise it up to the hard ceiling, or lower it for tighter context-budget control. |

When the payload exceeds the effective cap, the tool throws an error naming both the actual size and the ceiling — the agent can read the error, retry with a larger max_inline_bytes, and succeed. Above the hard ceiling, the only path is to fetch the content via REST directly (GET /v1/memories/{id}/content or /pages/{idx}/image) rather than through MCP.

These constants are not currently configurable via environment variables. If you need to tune them per deployment, edit _clients_gen/mcp/emitter.py (ABSOLUTE_MAX_INLINE_BYTES, DEFAULT_MAX_INLINE_BYTES) and regenerate.

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 model registry. 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 Community and Support
• Python SDK on PyPI
• Claude Code Plugin

License

Licensed under the Apache License 2.0. A copy is included in the package.