clawhdf5/docs/openclaw.md

OpenClaw: not supported

clawhdf5 does not currently work as an OpenClaw memory backend, and never has. Earlier versions of these docs described a "drop-in" backend enabled with memory.backend = "clawhdf5". That configuration was never valid: from v2026.2 through v2026.7 OpenClaw's memory.backend accepted only "builtin" or "qmd" and rejected unknown keys, and since v2026.8.1 ("OpenClaw 2.0") the key no longer exists. A Gateway given that config refuses to start. No plugin was ever built or tested against OpenClaw, and the @redclaw/clawhdf5 npm package was never published.

As of 2026-09-25 we are not pursuing an OpenClaw plugin; the maintained integration target is ZeroClaw. This page records what a plugin would need, for when that changes.

What OpenClaw expects today (v2026.9.6)

Checked against the OpenClaw source at tag v2026.9.6 and its docs on 2026-09-25. OpenClaw marks every plugin API as experimental, so re-check before building anything.

• Memory lives in Markdown files, which are the source of truth: MEMORY.md, USER.md, daily notes in memory/YYYY-MM-DD.md in the agent workspace. The memory engine is an index over them (concepts/memory).
• A memory plugin is selected with plugins.slots.memory: "<plugin-id>" (default memory-core), its settings under plugins.entries.<plugin-id>.config, validated against the plugin's own schema (gateway/config-extensions). Memory search settings are under memory.search (reference/memory-config).
• A plugin needs an openclaw.plugin.json manifest with id, configSchema, "kind": "memory" and every tool listed in contracts.tools (plugins/manifest); a package.json with openclaw.extensions, openclaw.compat.pluginApi and an openclaw peer dependency; and an entry built with definePluginEntry.
• Two ways to integrate (both exist upstream): tools only, as memory-lancedb does (api.registerTool), or a full memory engine, as memory-core does, through api.registerMemoryCapability({ runtime, ... }), whose runtime returns a MemorySearchManager implementing search, readFile (returning status: "ok" | "not_found"), status, probeEmbeddingAvailability and probeVectorAvailability. Active Memory expects memory_search and memory_get tools (plugins/sdk-overview/memory-and-context).
• Embeddings come from OpenClaw's providers (memory.search.provider), or a plugin registers one with api.registerEmbeddingProvider.
• Native code: plugin installs run with --ignore-scripts, so a napi addon has to ship as prebuilt per-platform packages (the pattern memory-lancedb uses for LanceDB), loaded lazily (plugins/dependency-resolution).
• Distribution: openclaw plugins install from npm or ClawHub; a first install from an arbitrary source needs explicit review, and community ClawHub packages go through a security audit.
• Churn to plan for: the memory SDK was reshaped in 2026 (separate registration functions merged into registerMemoryCapability; registerMemoryEmbeddingProvider removed on 2026-08-21), and further SDK surfaces become eligible for removal on 2026-10-01 (plugins/sdk-migration/removal-timeline).

What this repository has

Building blocks, usable as a library today, but not an OpenClaw plugin:

• clawhdf5_agent::openclaw::ClawhdfBackend — a Markdown-oriented backend over HDF5Memory: ingest Markdown by section, hybrid search with re-ranking and confidence rejection, read back by path, export. Gaps a plugin would have to close: write/ingest_markdown store no embeddings (search is keyword-only for that content unless records are saved with save_entry), re-ingesting appends rather than replaces, there is no delete, line_range is never set, and export rewrites every heading as ##.
• crates/clawhdf5-napi and packages/clawhdf5-node — Node bindings and a TypeScript wrapper. Not published, not built or tested in CI, and known to be broken; see docs/known-issues.md.