145 lines
4.7 KiB
Markdown
145 lines
4.7 KiB
Markdown
# 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
|
||
|
||
```json
|
||
{
|
||
"memory": {
|
||
"backend": "clawhdf5",
|
||
"clawhdf5": {
|
||
"path": "./agent.brain",
|
||
"embeddingDim": 768
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Full schema
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```typescript
|
||
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"`) |
|