oGMemory Quick Installation ​

1. Installation Modes ​

If you only want to verify the command link, you can select the mock provider and do not need to use the real model API key. If real memory extraction is required, select openai, volcengine, dashscope, or zhipu.

2. Preparations ​

1. Installing Basic Dependencies ​

Recommended environment:

• Python 3.11+
• PostgreSQL, which is optional. Currently, SQL storage configuration is generated by default in ogmem onboard.
• Docker, which is optional. It is required only for integrated Docker deployment.
• OpenClaw or Claude Code, which is optional. It is required only in the Agent Plugin mode.

2. Obtaining the Project Source Code ​

git clone --branch dev https://gitcode.com/opengauss/oGMemory.git
cd oGMemory

3. Creating a Python Environment and Installing It ​

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

If you also want to run tests:

pip install -e ".[dev]"

Verify that the CLI has been installed:

ogmem --help

4. Selecting a Storage Backend ​

The installation mode and storage backend of oGMemory are two-layered. Headless, Agent Plugin, or Docker determines how the service is started. SQL or AGFS determines how memory data is flushed to disks.

By default, ogmem onboard generates the SQL storage configuration and attempts to initialize the schema when PostgreSQL is connected. You can use SQL or AGFS as required, regardless of whether you select Headless, Agent Plugin, or Docker.

3. Method A: Headless Local Service ​

This method is applicable when only the oGMemory HTTP service is started and then accessed by the SDK, script, or existing Agent.

Interactive configuration:

ogmem onboard

Select the following in Deployment Target:

Headless (CE server only)

The configuration will be written into:

config/ogmem.yaml

Start the services.

ogmem start headless

If AGFS binary not found is reported during startup, build AGFS first:

cd agfs
make build
cd ..
ogmem start headless

If the SQL storage backend is used, you generally do not need to start AGFS. Instead, you need to ensure that the storage.connection_string in config/ogmem.yaml can connect to PostgreSQL.

Background running:

ogmem start headless --daemon

Stop the service:

ogmem stop local

4. Method B: Connecting to the Local Agent ​

This method is suitable for you who have installed OpenClaw or Claude Code on your local machine and want to integrate oGMemory as a long-term memory capability.

Note: ogmem onboard --mode plugin is not responsible for installing OpenClaw or Claude Code itself. It only generates the oGMemory configuration and generates the corresponding plugin configuration or hooks based on the agent you select.

Interactive configuration:

ogmem onboard

Select the following in Deployment Target:

Agent Plugin (OpenClaw / Claude Code)

Then select:

• OpenClaw (context-engine plugin): Generates the configuration file on the OpenClaw side.
• Claude Code (hooks): Writes hooks to the project .claude/settings.json.

Common outputs:

config/ogmem.yaml
openclaw.plugin.json

Start the plugin mode:

ogmem start plugin

ogmem start plugin ensures that the oGMemory ContextEngine is available. If the OpenClaw configuration is detected and the openclaw command is available on the local host, OpenClaw will be started based on the generated configuration. You need to install OpenClaw in advance.

To stop the oGMemory local service, run the following command:

ogmem stop local

To stop the OpenClaw or Claude Code process, stop them using the corresponding tools.

For more variables of the OpenClaw local plugin, see:

• openclaw_context_engine_plugin/ENV.md
• openclaw_context_engine_plugin/README.md

5. Method C: Docker-Based Integrated Deployment ​

This method is suitable for starting the OpenClaw Gateway, oGMemory, and optional openGauss at once.

Interactive configuration:

ogmem onboard

Select the following in Deployment Target:

Docker (containerized)

The configuration will be written to:

deploy/deploy.env
deploy/ogmemory.yaml

Start the container.

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

View the status and logs:

bash deploy/deploy.sh --status
docker logs ogmem -f
docker logs openclaw_ogmem -f
docker logs opengauss -f

For details about complete deployment variables, restrictions on ARM64 images, multi-tenant deployment, and troubleshooting, see deploy/README.md.

6. Verifying the Service ​

1. Environment ​

ogmem check

You are advised to confirm the following:

• The Python package is successfully imported.
• The config/ogmem.yaml or key environment variables have been configured.
• The API key has been configured when a real model is used.
• PostgreSQL can be connected when the SQL backend is used.

2. Health Check ​

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

3. Writing a Round of Conversation ​

If you want to trigger extraction immediately for a short conversation, you are advised to set the following parameters before starting the service:

export OGMEM_AFTER_TURN_THRESHOLD=1

Write example:

curl -X POST http://localhost:8090/api/v1/after_turn \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acct-demo",
    "userId": "user-1",
    "agentId": "main",
    "sessionId": "session-1",
    "messages": [
      {"role": "user", "content": "My name is Alice, and I am a backend engineer."},
      {"role": "assistant", "content": "Nice to meet you, Alice."}
    ]
  }'

Common responses:

• status: "accumulating": The message has entered the buffer, but the extraction threshold has not been reached.
• status: "processing": Extraction, writing, and indexing have been triggered in the background.
• status: "completed": When the background thread fails to be created, the service is degraded to synchronous execution.

4. Retrieving Memories ​

curl -X POST http://localhost:8090/api/v1/compose \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acct-demo",
    "userId": "user-1",
    "agentId": "main",
    "sessionId": "session-2",
    "prompt": "What is Alice's job?",
  }'

Pay attention to the following in the returned result:

• messages: message list after the memory context is injected
• identityContext: stable identity information of the profile class
• retrievedEvidence: evidence hit by semantic retrieval
• estimatedTokens: estimated number of tokens after the assembly.