osobhandClaude Opus 5.5
0c65a27b00
The docs described a "drop-in" OpenClaw memory backend enabled with `memory.backend = "clawhdf5"`. Checked against OpenClaw's source and docs (v2026.2.26 through v2026.9.6): that config was never valid — v2026.2-v2026.7 accepted only "builtin"/"qmd" and rejected unknown keys, so a Gateway given it refuses to start, and v2026.8.1 (OpenClaw 2.0) removed the key. No plugin was ever built (no manifest, no registration, no tools), nothing was tested against OpenClaw, the linked github.com/redclawsystems/openclaw is a 404, and @redclaw/clawhdf5 was never published. Decision (2026-09-25): not pursuing an OpenClaw plugin for now; ZeroClaw is the integration target. - Remove openclaw-integration.md, openclaw-config.md and migration-guide.md; add docs/openclaw.md: the status, what a memory plugin needs against v2026.9.6 (plugins.slots.memory, manifest with kind "memory", registerMemoryCapability / MemorySearchManager, prebuilt native packages), and what this repo has as building blocks. - README, QUICKSTART, USE_CASES, ROADMAP (Track 7 withdrawn), CLAUDE.md and the `openclaw` module docs describe ClawhdfBackend as what it is: a Markdown-oriented library backend, not an OpenClaw plugin. The QUICKSTART example is corrected (the old one called a three-argument create that does not exist) and states its limits. - packages/clawhdf5-node: marked unpublished and broken, "private": true so it cannot be published by accident; its bugs (snake_case vs camelCase fields, wrong addon path, no way to store an embedding, wrong WAL name) are recorded in docs/known-issues.md. - Two broken rustdoc links fixed along the way. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
# OpenClaw: not supported
|
|
|
|
**clawhdf5 does not currently work as an [OpenClaw](https://docs.openclaw.ai)
|
|
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](https://docs.openclaw.ai/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](https://docs.openclaw.ai/gateway/config-extensions)).
|
|
Memory search settings are under `memory.search`
|
|
([reference/memory-config](https://docs.openclaw.ai/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](https://docs.openclaw.ai/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](https://docs.openclaw.ai/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](https://docs.openclaw.ai/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](https://docs.openclaw.ai/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`.
|