Merge pull request 'Withdraw the ZeroClaw integration claims' (#10) from docs/withdraw-zeroclaw into main

Reviewed-on: #10

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

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. 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
 
@@ -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,12 @@ 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.
+- **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`).

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 |
 |--------|-------------|

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

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

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

crates/clawhdf5-migrate/src/main.rs

@@ -12,7 +12,8 @@ use validate::ValidationSummary;
 
 type BoxErr = Box<dyn std::error::Error>;
 
-/// 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 <store> ...`).
@@ -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();

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<MemoryChunk>,
@@ -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<f32> {
         .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

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)