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, and clawhdf5 has no framework integration at all (ZeroClaw, also named as a consumer in older docs, does not use it either). This page records what an OpenClaw 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 (re-checked 2026-09-28: unchanged).