oGMemory Configuration Guide

This guide describes how to generate configuration files, where to generate them, and what the core content is, based on the installation mode.

For details about the complete fields, see config/ogmem.reference.yaml and OGMEMORY_ENV.md.

1. Configuration Entry

The interactive wizard is the most recommended configuration mode.

ogmem onboard

The wizard sequentially asks you about the model, embedding, database, and deployment mode, and then generate the corresponding files based on your selection.

Installation Mode	Application Scenario	Interactive File Generation
Headless Local Service	Only the oGMemory HTTP service is started for the SDK, scripts, or existing systems to invoke.	config/ogmem.yaml
Agent Plugin	Accessing the existing OpenClaw or Claude Code on the local host	config/ogmem.yaml, and openclaw.plugin.json or .claude/settings.json
Docker Integrated Deployment	Deploying OpenClaw Gateway, oGMemory, and optionally openGauss at a time	deploy/deploy.env, deploy/ogmemory.yaml

By default, ogmem.yaml is generated in the config/ogmem.yaml directory in the root directory of the project. If you need to save the file to another path, you can use OGMEM_CONFIG=/path/to/ogmem.yaml to specify the path.

2. Headless Local Service

After you select Headless (CE server only), the wizard generates the following:

config/ogmem.yaml

The typical content is as follows:

# Generated by ogmem onboard
paths:
  data_root: .ogmem_data       # Local data directory, which is used to store runtime data and local indexes.

llm:
  provider: openai             # LLM provider: openai / volcengine / dashscope / zhipu / mock
  api_key: "sk-xxx"            # LLM API key. You can also use OGMEM_API_KEY to overwrite it.
  base_url: "https://api.openai.com/v1" # OpenAI compatible API address. For models in China, replace it with the corresponding Base URL.
  model: "gpt-4o-mini"         # LLM model used for tasks such as semantic extraction and classification.
  temperature: 0.1             # Randomness of generation. It is recommended that the value be small for memory extraction.

embedding:
  provider: openai             # Embedding provider. Generally, the value is the same as that of llm.provider.
  model: "text-embedding-ada-002" # Vectorization model, which must match vector_db.dimension.

storage:
  backend: sql                 # Memory storage backend: sql / agfs. The SQL backend is recommended.
  connection_string: "host=127.0.0.1 port=5432 dbname=ogmemory user=postgres password=postgres"           # PostgreSQL DSN
  pool_size: 5                 # Size of the database connection pool.

vector_db:
  type: chroma                 # Vector index backend. Chroma is available by default on the local host.
  dimension: 1536              # Embedding vector dimension, which must be the same as the model output.
  chroma_persist_dir: .ogmem_data/chroma # Local persistent directory of Chroma

service:
  http_port: 8090              # HTTP service port of oGMemory
  workers: 2                   # Number of workers for the HTTP service

identity:
  account_id: "acct-demo"      # Default account ID, used for multi-tenant isolation
  user_id: "u-alice"           # Default user ID
  agent_id: "main"             # Default agent ID

Start:

ogmem start headless

You need to check the following three types of configurations: whether the LLM can be accessed, whether the embedding dimension and model are matched, and whether the storage.connection_string can connect to PostgreSQL.

3. Agent Plugin

After you select Agent Plugin (OpenClaw / Claude Code), the wizard generates the oGMemory configuration.

config/ogmem.yaml

Compared with the headless mode, the plugin section is added:

llm:
  provider: openai             # LLM provider
  api_key: "sk-xxx"            # LLM API Key
  base_url: "https://api.openai.com/v1" # OpenAI compatible API address
  model: "gpt-4o-mini"         # LLM model name
  temperature: 0.1             # A lower temperature is recommended for memory extraction.

embedding:
  provider: openai             # Embedding provider
  model: "text-embedding-ada-002" # Embedding model name

storage:
  backend: sql                 # Memory storage backend: sql / agfs.
  connection_string: "host=127.0.0.1 port=5432 dbname=ogmemory user=postgres password=postgres"           # PostgreSQL DSN
  pool_size: 5                 # Size of the database connection pool

vector_db:
  type: chroma                 # Vector index backend
  dimension: 1536              # Vector dimension, which must be the same as that of the embedding model
  chroma_persist_dir: .ogmem_data/chroma # Local index directory of Chroma

service:
  http_port: 8090              # HTTP service port of oGMemory
  workers: 2                   # Number of workers for the HTTP service

identity:
  account_id: "acct-demo"      # Default account ID
  user_id: "u-alice"           # Default user ID
  agent_id: "main"             # Default agent ID

plugin:
  type: "openclaw"             # Agent access type: openclaw or claude_hooks
  openclaw_config: "D:/path/to/project/openclaw.plugin.json" # OpenClaw Gateway configuration file path

If you select OpenClaw, the following files are generated:

openclaw.plugin.json

The main function is to connect the model configuration of the OpenClaw Gateway to the oGMemory address. The actual file contains the complete schema required by OpenClaw. You can check the following fields:

{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-xxx",
  "ogmem_url": "http://127.0.0.1:8090",
  "gateway_port": "18789"
}

If you select Claude Code, the wizard writes hooks to:

.claude/settings.json

Start:

ogmem start plugin

Note: The plugin mode does not install OpenClaw or Claude Code itself. It only generates the oGMemory configuration and agent access configuration. OpenClaw/Claude Code must be available on your local machine.

4. Docker-based Integrated Deployment

After you select Docker (containerized), the wizard generates two types of files:

deploy/deploy.env
deploy/ogmemory.yaml

deploy/deploy.env is responsible for container deployment and sharing environment variables. The typical content is as follows:

# Generated by ogmem onboard
LLM_PROVIDER="openai"
LLM_API_KEY="sk-xxx"
LLM_BASE_URL="https://api.openai.com/v1"
LLM_MODEL="gpt-4o-mini"

ENABLE_OPENGAUSS="true"
OG_HOST_PORT="15432"
OPENGAUSS_HOST_IP="127.0.0.1"

deploy/ogmemory.yaml is the configuration used by oGMemory in the container, which references deploy.env.

# Generated by ogmem onboard (Docker mode)
llm:
  provider: "${LLM_PROVIDER}"  # Read the LLM provider from deploy.env.
  api_key: "${LLM_API_KEY}"    # Read the LLM API key from deploy.env.
  base_url: "${LLM_BASE_URL}"  # Read the base URL of the model service from deploy.env.
  model: "${LLM_MODEL}"        # The LLM model name is read from deploy.env.
  temperature: 0.1             # A lower temperature is recommended for memory extraction.

embedding:
  provider: openai             # Embedding provider
  model: "text-embedding-ada-002" # Embedding model name
  base_url: "${LLM_BASE_URL}"  # By default, the LLM Base URL is reused.
  api_key: "${LLM_API_KEY}"    # By default, the LLM API Key is reused.

vector_db:
  type: opengauss              # In the Docker scenario, openGauss or pgvector is commonly used.
  connection_string: "host=127.0.0.1 port=8799 dbname=postgres user=gaussdb password=CHANGE_ME"          # Vector database connection string
  dimension: 1536              # Vector dimension, which must be the same as that of the embedding model.
  table_name: vector_index     # Name of the vector index table
  pool_size: 5                 # Size of the vector database connection pool

storage:
  backend: sql                 # Backend for storing structured memory data: sql or agfs

agfs:
  base_url: "http://127.0.0.1:1833" # AGFS service address
  mount_prefix: /local/plugin  # AGFS mount prefix

index:
  interval: 15                 # Polling interval of the background indexing task, in seconds.
  workers: 1                   # Number of background indexing workers

service:
  http_port: 8090              # HTTP service port of oGMemory in the container
  workers: 2                   # Number of HTTP service workers

identity:
  account_id: "acct-demo"      # Default account ID.
  user_id: "u-alice"           # Default user ID
  agent_id: "main"             # Default agent ID

The interactive ogmem onboard --mode docker asks whether to start the container immediately. If you select yes, deploy/deploy.sh is called. If only the configuration is generated, you can manually start the container later.

bash deploy/deploy.sh -password "OpenGauss@2024"

5. Storage and Vector Index

The installation mode determines how the service is started, and the storage backend determines how the memory is flushed to disks. STORAGE_BACKEND / storage.backend supports two values:

Value	Description	When to Use
sql	Uses PostgreSQL to directly connect to the storage memory data.	This is the recommended default option, which is suitable for local development, service deployment, and troubleshooting.
agfs	Uses the AGFS file system link to store memory data.	This is used when the AGFS capability is required or the old link is compatible.

Currently, the default SQL is recommended:

storage:
  backend: sql                 # Recommended memory storage backend. The options are sql and agfs.
  connection_string: "host=127.0.0.1 port=5432 dbname=ogmemory user=postgres password=postgres" # PostgreSQL DSN

You can select the local Chroma for vector indexes.

vector_db:
  type: chroma                 # Local Chroma vector index
  dimension: 1536              # Vector dimension, which must be the same as that of the embedding model.
  chroma_persist_dir: .ogmem_data/chroma # Local index persistence directory.

You can also select openGauss or pgvector.

vector_db:
  type: opengauss              # Uses openGauss or pgvector as the vector index.
  connection_string: "host=127.0.0.1 port=5432 dbname=postgres user=gaussdb password=CHANGE_ME"          # openGauss connection string
  dimension: 1024              # Vector dimension, which must be the same as that of the embedding model.

dimension must be the same as the output dimension of the embedding model.

6. Main Environment Variables

Generally, the YAML file is preferred. Environment variables are suitable for temporary overwriting, container deployment, or CI. For details, see OGMEMORY_ENV.md.

Variable	Default Value	Description
OGMEM_API_KEY	None	LLM API key, which can be directly used by OpenAI-compatible APIs.
OGMEM_BASE_URL	None	Customized base URL of the LLM API.
OGMEM_LLM_MODEL	gpt-4o-mini	LLM model used for semantic processing such as extraction and classification.
OGMEM_EMBEDDING_MODEL	text-embedding-ada-002	Embedding model used for vector indexing.
OGMEM_EMBEDDING_API_KEY	Rolling back to OGMEM_API_KEY	Embedding independent API key
VECTOR_DB_TYPE	chroma	Vector backend: chroma / memory / opengauss
STORAGE_BACKEND	sql	Storage backend: sql / agfs (sql is recommended.)
SQL_CONNECTION_STRING	None	PostgreSQL DSN, for example, host=127.0.0.1 port=5432 dbname=ogmemory user=postgres password=postgres.
OGMEM_HTTP_PORT	8090	HTTP service listening port.
OGMEM_CONFIG	config/ogmem.yaml	Path of the YAML configuration file.

Configuration priority:

Command line input > YAML configuration > Environment variable > Default value in code

7. Self-check

View the current configuration:

ogmem config show

Check dependencies and services:

ogmem check
curl http://127.0.0.1:8090/api/v1/health

References

Document	Description
config/ogmem.reference.yaml	Complete YAML template.
OGMEMORY_ENV.md	Description of complete environment variables
deploy/README.md	Docker integrated deployment
openclaw_context_engine_plugin/ENV.md	OpenClaw plugin variables