GoodMem

Getting Started

Getting started with GoodMem configuration and testing

By now you should have installed GoodMem, either manually or through the devcontainer. If you have not completed this step, please begin with the installation.

Prefer a visual interface? The GoodMem server includes a built-in web console at /console/. It walks you through the same setup steps below — creating an embedder, space, and LLM — without needing the command line. See the Console documentation for details.

Note: OCR (Optical Character Recognition) is provided by the GoodMem OCR add-on service/image and is not included in the base install. If you plan to use OCR, enable the add-on and configure GOODMEM_OCR_BASE_URL.

Devcontainer Setup (Skip if you installed GoodMem manually)

  1. Click below to open a Codespace using the GoodMem template repository:

    Open Codespace

  2. To view your GoodMem API Key, use this command: grep api_key ~/.goodmem/config.toml

Configuration Steps

  1. When installation completes, you should see output similar to the following:

    ✓ Installation completed successfully!

ℹ GoodMem is ready to use.
ℹ Web console: https://localhost:8080/console

ℹ Active profile: default
ℹ   Server URL:   https://localhost:9090
ℹ   API Key:      gm_xxxxxxxxxxxxxxxxxxxxxxxx
ℹ   Install type: local-docker

The default install uses a self-signed certificate. TLS is enabled out of the box, but clients (browsers, SDKs, curl) cannot verify the ephemeral certificate. For local development we recommend mkcert — it creates locally-trusted certificates in minutes and eliminates TLS errors in every language. If you already installed with the default self-signed setup, the same guide includes a step-by-step migration for switching that install to mkcert later. See TLS Configuration for the full set of options.

  1. The installer saves your root API key to the active CLI profile automatically, so CLI commands work immediately. If you plan to use the SDKs or REST API directly, note the key from the output above — it is only shown once. You can also use the command below to grab the GoodMem api key:
grep api_key ~/.goodmem/config.toml

  1. Obtain your OpenAI API Key from the OpenAI dashboard and keep it ready for the next step.

  2. Create an embedder (must be created before a space):

    goodmem embedder create \
  --display-name "OpenAI Small Embedder" \
  --provider-type OPENAI \
  --endpoint-url "https://api.openai.com/v1" \
  --model-identifier "text-embedding-3-small" \
  --dimensionality 1536 \
  --cred-api-key YOUR_OPENAI_API_KEY_FROM_STEP_3

    The command should output:

    Embedder created successfully!

ID:               xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Display Name:     OpenAI Small Embedder
Owner:            xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Provider Type:    OPENAI
Distribution:     DENSE
Endpoint URL:     https://api.openai.com/v1
API Path:         /embeddings
Model:            text-embedding-3-small
Dimensionality:   1536
Created by:       xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Created at:       2026-08-20T21:09:00Z

    SAVE THE ID

Need help choosing endpoint_url or api_path for a provider? See the Endpoint registration guide.

  1. Create a space linked to that embedder:

    goodmem space create \
  --name "My OpenAI Small Space" \
  --embedder-id YOUR_EMBEDDER_ID_FROM_STEP_4

    The command should output:

    Space created successfully!

ID:         xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Name:       My OpenAI Small Space
Owner:      xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Created by: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Created at: 2026-08-20T21:08:20Z
Public:     false
Embedder:   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (weight: 1.0)

    SAVE THE ID

  2. Create an LLM:

    goodmem llm create \
  --display-name "My GPT-4" \
  --provider-type OPENAI \
  --endpoint-url "https://api.openai.com/v1" \
  --model-identifier "gpt-4o"

    The command should output:

    LLM created successfully!

ID:               xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Display Name:     My GPT-4
Owner:            xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Provider Type:    OPENAI
Endpoint URL:     https://api.openai.com/v1
API Path:         /chat/completions
Model:            gpt-4o
Modalities:       TEXT
Capabilities:     Chat, Completion, Functions, System Messages, Streaming, Sampling Parameters
Created by:       xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Created at:       2026-03-17T23:06:04Z

Capability Inference:
✓ Chat Support: true (detected from model family 'gpt-4o')
✓ Completion Support: true (detected from model family 'gpt-4o')
✓ Function Calling: true (detected from model family 'gpt-4o')
✓ System Messages: true (detected from model family 'gpt-4o')
✓ Streaming: true (detected from model family 'gpt-4o')
✓ Sampling Parameters: true (detected from model family 'gpt-4o')

    SAVE THE ID

Testing the Queries

The next major step is to upload content into memory so it can be queried. To do this, we will first upload a PDF and store it in memory. After that, we will run some queries. Follow the directions below:

  1. Begin by creating a memory. This guide uses the following sample PDF for testing:

    An Excellent Study of Social Media and Its Positive and Negative Effects on Human Being’s Mental Health

    Then run this command:

    goodmem memory create \
  --content-type "application/pdf" \
  --file "PATH_TO_WHERE_YOU_DOWNLOADED_THE_PDF" \
  --space-id YOUR_SPACE_ID_FROM_STEP_5

    It should output:

    Memory created successfully!

ID:            xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Space ID:      xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content Type:  application/pdf
Page images:   enabled
Status:        PENDING
Created by:    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Created at:    2026-03-17T23:18:33Z
Metadata:
filename: social_media_study.pdf

    SAVE THE ID (not the space ID since you already have that)

  2. To run a query, you have two options: non-interactive mode and interactive mode.

    Non-interactive mode:

    goodmem memory retrieve \
   "what are the top three negative effects of social media?" \
   --space-id YOUR_SPACE_ID_FROM_STEP_5

    Interactive mode (easier to retrieve results):

    goodmem memory retrieve \
  --post-processor-interactive "what are the top three negative effects of social media?" \
  --space-id YOUR_SPACE_ID_FROM_STEP_5

Optional Features

To enable optional features (Jupyter Notebook, SDK playground, etc.):

source .devcontainer/optional-feature-installer.sh

Optional Features Supported Languages & Tools:

  • Python 3.10 - includes the GoodMem SDK and OpenAI integration
  • Java 17
  • .NET 9
  • Go 1.22
  • Node.js 20 with pnpm
  • Visual Studio Code Extensions — language servers, formatters, linters, and productivity tools for all supported languages

Optimize Document Ingestion for Better Search

Learn chunking strategies and configuration techniques to improve search performance for your documents

On this page

Devcontainer Setup (Skip if you installed GoodMem manually)Configuration StepsTesting the QueriesOptional Features