config/ — oGMemory Configuration Directory

This directory holds all configuration files, templates, and environment variables for oGMemory.

Runtime Files (gitignored)

File	Purpose
ogmem.yaml	Runtime config (generated by ogmem onboard or ogmem config init)
.env	Runtime environment variables (API keys, etc.)

Templates

File	Purpose
ogmem.reference.yaml	Master config template for all modes (local/docker/plugin)
env.example	Environment variable template
deploy.env.reference	Docker deployment environment variables template
agfs/config.reference.yaml	AGFS server configuration reference
openclaw/ogmem.template.json	OpenClaw Gateway template (placeholder-based)

The OpenClaw template, plugin schema, and server configuration default semanticTurnMode to user_message, matching the verified OpenClaw 2026.6.10 lifecycle. This is currently the only supported semantic Turn mode; the option is retained as an explicit extension point for future host lifecycles.

Large tool-result externalization is opt-in. When enabled, first_view_enabled defaults to true, allowing a trusted post-tool/pre-model middleware to replace an individual result at or above single_result_chars with a multiresolution Artifact stub before its first model request.

Usage

Quick start (recommended)

ogmem onboard   # Interactive wizard generates config/ogmem.yaml

Local development (manual)

cp config/ogmem.reference.yaml config/ogmem.yaml
cp config/env.example config/.env
# Edit config/ogmem.yaml and config/.env with your settings

Docker deployment

cp config/deploy.env.reference deploy/deploy.env
# Edit deploy/deploy.env, then run bash deploy/deploy.sh

Config search order

1. OGMEM_CONFIG environment variable
2. config/ogmem.yaml (this directory)
3. /etc/ogmem/config.yaml (Docker/production)

Priority per field: YAML value > environment variable > code default

Mode annotations in ogmem.reference.yaml

• [all] — applies to all deployment modes
• [local] — local development only
• [docker] — Docker deployment (uses ${ENV_VAR} from deploy.env)

Re-running local onboarding

Local onboarding requires the managed HTTP service to be stopped first:

ogmem stop local
ogmem onboard --mode local

When a local service is running, the wizard exits without changing configuration or installing dependencies. ogmem start local also refuses a second launch, even if the saved port or model has changed. Stop the managed process first.

With an existing configuration, interactive onboarding offers Use existing configuration, Modify configuration, or Exit. Use existing starts with the saved file after confirmation. Modify uses existing settings as defaults and preserves fields outside the wizard, including memory.after_turn_threshold, identity, LLM tuning, and custom sections. Non-interactive onboarding updates the configuration only when the local service is stopped.

Changed YAML is backed up to config/ogmem.yaml.bak-<timestamp> before atomic replacement; unchanged YAML is not rewritten. Invalid YAML is rejected. Formatting/comments may change; the backup preserves the original text. Backups may contain credentials and are written with owner-only permissions.

Local lifecycle commands record only PID, process start identity, and port in .ogmem_data/local-runtime.json. They do not save configuration snapshots or launch environments, or automatically restart/roll back services. Startup failure terminates the failed child and reports failure. Stop verifies the recorded process, even when saved YAML has changed or is invalid, and does not kill an unrelated listener based on the newly configured HTTP port.

Configuration path and separate databases

Local onboarding and startup resolve the configuration path consistently: explicit start --config > OGMEM_CONFIG in the process environment > OGMEM_CONFIG in the project's config/.env > project config/ogmem.yaml > existing /etc/ogmem/config.yaml. Relative selected paths are resolved against the caller's working directory; ~ and paths containing spaces are supported. Onboarding may create a new selected file, and backups are placed beside that file. It does not update the project's default YAML when another file has been selected.

OGMEM_CONFIG=/path/to/custom.yaml ogmem onboard --mode local
OGMEM_CONFIG=/path/to/custom.yaml ogmem start local --daemon

Existing storage.connection_string and vector_db.connection_string are preserved separately. Interactive modification offers masked connection input (Enter keeps the existing value), plus a choice to use the SQL connection for the vector database. Non-interactive callers can set --db-connection and --vector-db-connection independently. On first setup, an omitted vector connection defaults to the SQL connection; a previously configured vector connection is retained. Each distinct required database is checked before saving.

Local service status

ogmem status checks the managed Local service at its recorded HTTP port. SQL storage does not require AGFS. When the live health response identifies AGFS storage, status also checks the reported AGFS endpoint. Healthy required services return exit code 0; stopped or unhealthy services return 1. A project's local process record takes precedence over unrelated Docker containers.

Embedding provider

embedding.provider selects an implementation/protocol, not necessarily the service vendor. For OpenAI-compatible APIs, use openai. Local onboarding maps zhipu and dashscope to openai, preserving their endpoint, model, key and dimension. Other supported adapters are openai-cached, volcengine, st, and mock; unsupported names are rejected before configuration is saved.

In non-interactive onboarding, a different Embedding vendor uses its own default endpoint and requires --embedding-api-key (except local st/mock adapters). Specify --embedding-base-url for a custom endpoint. The LLM key is reused only when the selected providers are the same.