From 87d64588e5aff829bd2b4c5862d4c1b989ac422f Mon Sep 17 00:00:00 2001 From: osobh Date: Fri, 25 Sep 2026 11:08:41 -0500 Subject: [PATCH 1/2] docs: withdraw the ZeroClaw integration claims CLAUDE.md said ZeroClaw "imports this as a Cargo feature (clawhdf5 feature flag)" and uses clawhdf5 as its memory backend; the agent crate called itself the "ZeroClaw agent memory HDF5 backend"; the migrator claimed to read "the ZeroClaw layout". Checked on 2026-09-25 against ZeroClaw v0.8.5 (its latest release), the osobh/zeroclaw fork (on v0.8.5) and both histories back to February 2026: - no `clawhdf5` feature, dependency or memory backend has ever existed in ZeroClaw; its backends are sqlite, lucid, postgres, qdrant, markdown and none, behind its own `Memory` trait; - ZeroClaw's SQLite schema is a single `memories` table (id, key, content, category, embedding, created_at, updated_at); the migrator's memory_chunks/sessions/entities/relations layout never existed in ZeroClaw, so it cannot read a ZeroClaw database. Decision: withdraw the claims (as with OpenClaw); clawhdf5 is a standalone library with no framework integration. The migrator's default layout is documented as its own. ZEROCLAW_VERSION keeps its name and value (it is the persisted `edgehdf5_version` writer tag) with a doc comment saying it is unrelated to ZeroClaw. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 8 ++++++++ CLAUDE.md | 15 ++++++++++++--- README.md | 4 +++- crates/clawhdf5-agent/src/lib.rs | 2 +- crates/clawhdf5-agent/src/schema.rs | 3 +++ crates/clawhdf5-migrate/README.md | 7 +++++-- crates/clawhdf5-migrate/src/main.rs | 5 +++-- crates/clawhdf5-migrate/src/sqlite_reader.rs | 8 +++++--- docs/openclaw.md | 7 ++++--- 9 files changed, 44 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1176614..a1ece78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,14 @@ ## Unreleased ### Upgrade Notes +- **ZeroClaw does not use clawhdf5.** The project described itself as + ZeroClaw's memory backend ("imported as a `clawhdf5` Cargo feature"). Checked + against ZeroClaw v0.8.5 (the latest release), the `osobh/zeroclaw` fork and + their full history: no such feature or backend has ever existed. And + `clawhdf5-migrate`'s "ZeroClaw layout" (`memory_chunks`, `sessions`, + `entities`, `relations`) is not ZeroClaw's schema — ZeroClaw uses a single + `memories` table — so the migrator cannot read a ZeroClaw database. The + claims are withdrawn; the migrator's layout is documented as its own. - **OpenClaw is not supported, and never was.** The docs described a "drop-in" OpenClaw memory backend enabled with `memory.backend = "clawhdf5"`. That config was never valid in any OpenClaw release (v2026.2–v2026.7 diff --git a/CLAUDE.md b/CLAUDE.md index 60319a6..89870c8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # clawhdf5 ## Purpose -Pure-Rust HDF5 format implementation with HNSW vector search, WAL-backed persistence, agent memory storage, and GPU-accelerated I/O. Used by ZeroClaw as its persistent memory and knowledge graph backend. +Pure-Rust HDF5 format implementation with HNSW vector search, WAL-backed persistence, agent memory storage, and GPU-accelerated I/O. A standalone library: no agent framework currently integrates it (OpenClaw and ZeroClaw claims were withdrawn on 2026-09-25 — neither was ever true). ## Architecture @@ -109,7 +109,15 @@ Cargo workspace with 16 crates under `crates/` (plus `libaec-sys`, an internal F - **OpenClaw is not supported** (decided 2026-09-25): clawhdf5 is not an OpenClaw memory plugin and never was — the old `memory.backend = "clawhdf5"` config was never valid. Don't reintroduce OpenClaw claims; `docs/openclaw.md` - records what a real plugin would need. ZeroClaw is the integration target. Measure changes with + records what a real plugin would need. +- **ZeroClaw does not use clawhdf5** (checked 2026-09-25 against upstream + v0.8.5 and the `osobh/zeroclaw` fork, and their full history): no + `clawhdf5` feature or backend exists; ZeroClaw's memory backends are + sqlite/lucid/postgres/qdrant/markdown/none behind its own `Memory` trait. + `clawhdf5-migrate`'s default SQLite layout (`memory_chunks`, `sessions`, + `entities`, `relations`) is not ZeroClaw's schema either (ZeroClaw's is a + `memories` table). Don't reintroduce integration claims without an + integration and a test against the real consumer. Measure changes with `search_harness --options-study`. - `MemoryConfig::compression` is off by default; when on, embeddings are deflate-compressed, or Zstd with the agent's `zstd` feature (links libzstd). @@ -188,4 +196,5 @@ python -c "import clawhdf5; print(clawhdf5.__version__)" ``` ## Integration -ZeroClaw imports this as a Cargo feature (`clawhdf5` feature flag) to persist agent memory with HNSW vector search for context retrieval. +None today. OpenClaw and ZeroClaw were both described as consumers; neither +integrates clawhdf5 (see Key Features and `docs/openclaw.md`). diff --git a/README.md b/README.md index 71f6e37..d21462c 100644 --- a/README.md +++ b/README.md @@ -818,7 +818,9 @@ clawhdf5-migrate --sqlite old.db --hdf5 memory.h5 --agent-id my-agent --embedder The output is an ordinary `clawhdf5-agent` store, written through the agent's own API: open it with `HDF5Memory::open` (or `clawhdf5-cli --path memory.h5 …`) -and search it straight away. What carries over from the ZeroClaw tables: +and search it straight away. The source must use the `memory_chunks` / `sessions` / `entities` / `relations` layout (names are +configurable with `--*-table`); note that this is not ZeroClaw's schema, and +ZeroClaw does not use clawhdf5. What carries over: | SQLite | Agent store | |--------|-------------| diff --git a/crates/clawhdf5-agent/src/lib.rs b/crates/clawhdf5-agent/src/lib.rs index 8bb7811..431cd45 100644 --- a/crates/clawhdf5-agent/src/lib.rs +++ b/crates/clawhdf5-agent/src/lib.rs @@ -1,4 +1,4 @@ -//! ZeroClaw agent memory HDF5 backend. +//! Agent memory stored in a single HDF5 file. //! //! Provides persistent memory storage for AI agents using HDF5 files. //! All data is cached in-memory for fast access and flushed to disk diff --git a/crates/clawhdf5-agent/src/schema.rs b/crates/clawhdf5-agent/src/schema.rs index 679a0b5..432b2d8 100644 --- a/crates/clawhdf5-agent/src/schema.rs +++ b/crates/clawhdf5-agent/src/schema.rs @@ -15,6 +15,9 @@ use crate::session::SessionCache; use crate::wal::WalMark; pub const SCHEMA_VERSION: &str = "1.0"; +/// Writer-version tag stored in `/meta` as `edgehdf5_version`. Kept for file +/// compatibility; despite the name it has nothing to do with ZeroClaw, which +/// does not use clawhdf5. pub const ZEROCLAW_VERSION: &str = "0.8.0"; /// `/meta` attributes holding the [`WalMark`] of the WAL prefix already folded diff --git a/crates/clawhdf5-migrate/README.md b/crates/clawhdf5-migrate/README.md index 54b74a6..092bc94 100644 --- a/crates/clawhdf5-migrate/README.md +++ b/crates/clawhdf5-migrate/README.md @@ -3,8 +3,11 @@ [![crates.io](https://img.shields.io/crates/v/clawhdf5-migrate.svg)](https://crates.io/crates/clawhdf5-migrate) [![docs.rs](https://img.shields.io/docsrs/clawhdf5-migrate)](https://docs.rs/clawhdf5-migrate) -CLI tool to migrate SQLite agent memory databases (the ZeroClaw layout) to a -[clawhdf5-agent](https://crates.io/crates/clawhdf5-agent) store. +CLI tool to migrate a SQLite agent-memory database in the `memory_chunks` / `sessions` / `entities` / `relations` layout (table and +column names are configurable) to a +[clawhdf5-agent](https://crates.io/crates/clawhdf5-agent) store. This is **not** +ZeroClaw's schema — ZeroClaw keeps memories in a single `memories` table and +does not use clawhdf5. The output is written through `clawhdf5-agent`'s own API, so it opens with `HDF5Memory::open` and is searchable immediately: memory records, sessions and diff --git a/crates/clawhdf5-migrate/src/main.rs b/crates/clawhdf5-migrate/src/main.rs index 4a0f58b..3536780 100644 --- a/crates/clawhdf5-migrate/src/main.rs +++ b/crates/clawhdf5-migrate/src/main.rs @@ -12,7 +12,8 @@ use validate::ValidationSummary; type BoxErr = Box; -/// Migrate ZeroClaw agent memory from SQLite to a clawhdf5-agent store. +/// Migrate agent memory from SQLite (memory_chunks / sessions / entities / +/// relations tables) to a clawhdf5-agent store. /// /// The output is an ordinary agent store: open it with /// `HDF5Memory::open` (or `clawhdf5-cli --path ...`). @@ -270,7 +271,7 @@ mod tests { use std::path::PathBuf; use tempfile::TempDir; - /// Create a test SQLite database with the ZeroClaw schema. + /// Create a test SQLite database with the default migration layout. fn create_test_db(dir: &TempDir) -> String { let db_path = dir.path().join("test.db"); let path_str = db_path.to_str().unwrap().to_string(); diff --git a/crates/clawhdf5-migrate/src/sqlite_reader.rs b/crates/clawhdf5-migrate/src/sqlite_reader.rs index 1a20dbe..d997b21 100644 --- a/crates/clawhdf5-migrate/src/sqlite_reader.rs +++ b/crates/clawhdf5-migrate/src/sqlite_reader.rs @@ -43,7 +43,7 @@ pub struct Relation { pub timestamp: f64, } -/// All data read from a ZeroClaw SQLite database. +/// All data read from a source SQLite database. #[derive(Debug)] pub struct SqliteData { pub chunks: Vec, @@ -63,7 +63,9 @@ pub struct TableSchema { /// Configurable mapping from a SQLite layout to the migration's data model. /// -/// Defaults to the ZeroClaw schema; the CLI can override the table names so the +/// Defaults to the `memory_chunks` / `sessions` / `entities` / `relations` +/// layout (not ZeroClaw's schema, despite what earlier docs said); the CLI can +/// override the table names so the /// tool can migrate databases whose tables are named differently. Column names /// (and order) are part of the config too, so a library caller can remap them. #[derive(Debug, Clone)] @@ -190,7 +192,7 @@ fn blob_to_f32(blob: &[u8]) -> Vec { .collect() } -/// Read all data from a ZeroClaw SQLite database. +/// Read all data from a source SQLite database. /// /// If `skip_deleted` is true, rows with `deleted=1` are excluded from chunks. /// If `embedding_dim` is `None`, auto-detect from the first row (0 when there diff --git a/docs/openclaw.md b/docs/openclaw.md index 0e49dd2..6e76a08 100644 --- a/docs/openclaw.md +++ b/docs/openclaw.md @@ -9,9 +9,10 @@ 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. +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) From dd5b3f6633c04702e098bc6cb89d85e5793d7b8b Mon Sep 17 00:00:00 2001 From: osobh Date: Fri, 25 Sep 2026 11:18:14 -0500 Subject: [PATCH 2/2] docs: ClawBrainHub is the one verified consumer The previous commit said clawhdf5 has no integration at all. ClawBrainHub (clawverse/clawbrainhub) does use it: cbh-core reads and writes .brain files through the facade, cbh-scanner uses the facade, and cbh-cli uses clawhdf5_agent::bm25::BM25Index, all via path dependencies on this repo. Checked on 2026-09-25 against main: it builds on its pinned toolchain and its 204 tests pass. CLAUDE.md now records that, and that path dependencies mean API changes here reach it directly. Co-Authored-By: Claude Opus 5.5 (1M context) --- CLAUDE.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 89870c8..1fa4581 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # clawhdf5 ## Purpose -Pure-Rust HDF5 format implementation with HNSW vector search, WAL-backed persistence, agent memory storage, and GPU-accelerated I/O. A standalone library: no agent framework currently integrates it (OpenClaw and ZeroClaw claims were withdrawn on 2026-09-25 — neither was ever true). +Pure-Rust HDF5 format implementation with HNSW vector search, WAL-backed persistence, agent memory storage, and GPU-accelerated I/O. A standalone library. Its one verified consumer is ClawBrainHub (`.brain` files); no agent framework integrates it (OpenClaw and ZeroClaw claims were withdrawn on 2026-09-25 — neither was ever true). ## Architecture @@ -196,5 +196,12 @@ python -c "import clawhdf5; print(clawhdf5.__version__)" ``` ## Integration -None today. OpenClaw and ZeroClaw were both described as consumers; neither -integrates clawhdf5 (see Key Features and `docs/openclaw.md`). +- **ClawBrainHub** (`clawverse/clawbrainhub` on git.redclaw.dev) is the one + verified consumer: `cbh-core` reads and writes `.brain` files through the + facade (`File`, `FileBuilder`, `AttrValue`, `Selection`), `cbh-scanner` + uses the facade, and `cbh-cli` uses `clawhdf5_agent::bm25::BM25Index`. It + depends on this repo by path (`../clawhdf5`), so it builds against whatever + is checked out — changes to those APIs reach it directly. Verified + 2026-09-25 against main: builds, and its 204 tests pass. +- OpenClaw and ZeroClaw were both described as consumers; neither integrates + clawhdf5 (see Key Features and `docs/openclaw.md`).