OpenClaw × clawhdf5 Configuration Reference

This document describes the full configuration schema for integrating clawhdf5 as the memory backend in an OpenClaw agent gateway.

Minimal example

{
  "memory": {
    "backend": "clawhdf5",
    "clawhdf5": {
      "path": "./agent.brain",
      "embeddingDim": 768
    }
  }
}

Full schema

{
  "memory": {
    "backend": "clawhdf5",
    "clawhdf5": {
      "path": "./agent.brain",
      "embeddingDim": 768,
      "walEnabled": true,
      "walMaxEntries": 500,
      "consolidation": {
        "workingCapacity": 100,
        "episodicCapacity": 10000,
        "episodicHalfLifeDays": 7,
        "semanticHalfLifeDays": 30,
        "promotionThreshold": 0.6,
        "semanticAccessThreshold": 10
      },
      "compaction": {
        "autoCompactThreshold": 0.3,
        "tickOnSessionEnd": true,
        "consolidateOnCompaction": true
      }
    }
  }
}

Field reference

Top level

Field	Type	Default	Description
`memory.backend`	`string`	`"clawhdf5"`	Must be `"clawhdf5"` to activate this backend

`clawhdf5`

Field	Type	Default	Description
`path`	`string`	`"./agent.brain"`	Filesystem path for the `.brain` (HDF5) file. Relative to the OpenClaw working directory.
`embeddingDim`	`number`	`768`	Dimension of the embedding vectors. Must match the embedder model. Common values: `384` (MiniLM), `768` (nomic-embed-text, BGE-base), `1536` (OpenAI text-embedding-3-small).
`walEnabled`	`boolean`	`true`	Enable the Write-Ahead Log for crash recovery. Disable only on read-only stores or when crash safety is not required.
`walMaxEntries`	`number`	`500`	Number of WAL entries to accumulate before an automatic merge to the .h5 file. Lower values = more frequent flushes (safer, slightly slower).

`clawhdf5.consolidation`

Controls the hippocampal three-tier memory engine (Working → Episodic → Semantic).

Field	Type	Default	Description
`workingCapacity`	`number`	`100`	Maximum records in the Working tier before lowest-decay entries are evicted.
`episodicCapacity`	`number`	`10000`	Maximum records in the Episodic tier.
`episodicHalfLifeDays`	`number`	`7`	Half-life (in days) for exponential decay of Episodic records. Records not accessed within roughly one half-life drop in importance.
`semanticHalfLifeDays`	`number`	`30`	Half-life for Semantic records. Longer than Episodic — semantic knowledge decays slowly.
`promotionThreshold`	`number`	`0.6`	Importance score (0–1) above which a Working record is promoted to the Episodic tier. Higher = more selective.
`semanticAccessThreshold`	`number`	`10`	Minimum access count for an Episodic record to be promoted to Semantic.

`clawhdf5.compaction`

Field	Type	Default	Description
`autoCompactThreshold`	`number`	`0.3`	Fraction of tombstoned records (0–1) that triggers automatic compaction. `0.3` = compact when 30% of records are deleted. Set to `0` to disable auto-compact.
`tickOnSessionEnd`	`boolean`	`true`	Run `tickSession()` (Hebbian decay) automatically when the agent session closes.
`consolidateOnCompaction`	`boolean`	`true`	Run the hippocampal consolidation engine after each compaction cycle.

Embedder compatibility

The embeddingDim must remain constant for the lifetime of a .brain file. Mixing embedding models in the same file is not supported.

Embedder	`embeddingDim`
`all-MiniLM-L6-v2`	`384`
`nomic-embed-text`	`768`
`BGE-base-en-v1.5`	`768`
`OpenAI text-embedding-3-small`	`1536`
`OpenAI text-embedding-3-large`	`3072`

OpenClaw integration code

import { ClawhdfMemory } from '@redclaw/clawhdf5';

// Load config from your OpenClaw config file
const cfg = loadConfig(); // your config loading logic

const mem = ClawhdfMemory.openOrCreate(
  cfg.memory.clawhdf5.path,
  cfg.memory.clawhdf5.embeddingDim ?? 768,
);

// On session end
if (cfg.memory.clawhdf5.compaction?.tickOnSessionEnd) {
  mem.tickSession();
}
if (cfg.memory.clawhdf5.compaction?.consolidateOnCompaction) {
  const stats = mem.runConsolidation(Date.now() / 1000);
  console.log('[clawhdf5] consolidation:', stats);
}

Environment variables

The following environment variables override config file values when set:

Variable	Overrides
`CLAWHDF5_PATH`	`clawhdf5.path`
`CLAWHDF5_EMBEDDING_DIM`	`clawhdf5.embeddingDim`
`CLAWHDF5_WAL_ENABLED`	`clawhdf5.walEnabled` (`"true"` / `"false"`)

4.7 KiB Raw Permalink Blame History Unescape Escape