docs: withdraw the OpenClaw integration claims
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]>
This commit is contained in:
osobh
+19
-61
@@ -11,7 +11,7 @@ ClawhDF5 serves three audiences with different entry points:
|
||||
| You Are | You Want | Start Here |
|
||||
|---------|----------|------------|
|
||||
| **AI agent developer** | Persistent memory for your agent | [Agent Memory (Rust)](#1-agent-memory-rust-library) |
|
||||
| **OpenClaw user** | Better memory for your OpenClaw agent | [OpenClaw Integration](#2-openclaw-integration) |
|
||||
| **OpenClaw user** | clawhdf5 is not an OpenClaw memory plugin | [Status](openclaw.md) |
|
||||
| **Data scientist** | Read/write HDF5 files in Rust | [HDF5 File I/O](#3-hdf5-file-io) |
|
||||
| **CLI user** | Inspect and manage agent memories | [CLI Tool](#4-cli-tool) |
|
||||
| **Python user** | Use clawhdf5 from Python | [Python Bindings](#5-python-bindings) |
|
||||
@@ -197,80 +197,38 @@ if let Some(alert) = detector.check_rate_anomaly() {
|
||||
|
||||
---
|
||||
|
||||
## 2. OpenClaw Integration
|
||||
## 2. Markdown Memory (and OpenClaw)
|
||||
|
||||
ClawhDF5 can serve as the memory backend for [OpenClaw](https://docs.openclaw.ai) agents, replacing the default Markdown + sqlite-vec approach.
|
||||
**clawhdf5 is not an OpenClaw memory backend.** Earlier versions of this guide
|
||||
described one; it never worked — see [openclaw.md](openclaw.md) for what
|
||||
happened and what a real plugin would need.
|
||||
|
||||
### How It Works
|
||||
|
||||
```
|
||||
OpenClaw Agent
|
||||
│
|
||||
├── memory_search("user preferences")
|
||||
│ │
|
||||
│ └── ClawhdfBackend
|
||||
│ ├── Vector search (cosine)
|
||||
│ ├── BM25 keyword search
|
||||
│ ├── Reciprocal Rank Fusion
|
||||
│ ├── Multi-factor re-ranking
|
||||
│ └── Low-confidence rejection
|
||||
│
|
||||
└── agent_memory.h5 (single file, portable)
|
||||
```
|
||||
|
||||
### Migration from Markdown
|
||||
What does exist is `ClawhdfBackend`, a library API that ingests Markdown files
|
||||
by section and searches them with the full pipeline (hybrid retrieval,
|
||||
re-ranking, confidence rejection):
|
||||
|
||||
```rust
|
||||
use clawhdf5_agent::openclaw::*;
|
||||
use std::path::Path;
|
||||
|
||||
// Create a new HDF5 backend
|
||||
let mut backend = ClawhdfBackend::create("memory.h5", "my-agent", 384)?;
|
||||
let mut backend = ClawhdfBackend::create(Path::new("memory.h5"), 384)?;
|
||||
|
||||
// Import your existing MEMORY.md
|
||||
let md = std::fs::read_to_string("~/.openclaw/workspace/MEMORY.md")?;
|
||||
// Each heading becomes a record, stored under "MEMORY.md::<heading>".
|
||||
let md = std::fs::read_to_string("MEMORY.md")?;
|
||||
let count = backend.ingest_markdown("MEMORY.md", &md)?;
|
||||
println!("Imported {} sections", count);
|
||||
println!("Imported {count} sections");
|
||||
|
||||
// Import daily logs
|
||||
for entry in std::fs::read_dir("~/.openclaw/workspace/memory/")? {
|
||||
let path = entry?.path();
|
||||
if path.extension().map(|e| e == "md").unwrap_or(false) {
|
||||
let content = std::fs::read_to_string(&path)?;
|
||||
let name = path.file_name().unwrap().to_string_lossy();
|
||||
backend.ingest_markdown(&name, &content)?;
|
||||
}
|
||||
}
|
||||
|
||||
// Search using the full pipeline
|
||||
let results = backend.search("what are user preferences", &query_embedding, 5);
|
||||
for r in &results {
|
||||
println!("[{:.3}] {} (from {})", r.score, r.text, r.path);
|
||||
}
|
||||
|
||||
// Export back to Markdown (lossless roundtrip)
|
||||
let exported = backend.export_markdown("MEMORY.md")?;
|
||||
```
|
||||
|
||||
### What You Get Over sqlite-vec
|
||||
|
||||
| Feature | sqlite-vec | ClawhDF5 |
|
||||
|---------|-----------|----------|
|
||||
| Vector search | ✅ | ✅ (8× faster at 100K) |
|
||||
| Keyword search | ❌ | ✅ BM25 |
|
||||
| Hybrid fusion | ❌ | ✅ RRF |
|
||||
| Re-ranking | ❌ | ✅ Multi-factor |
|
||||
| Confidence rejection | ❌ | ✅ |
|
||||
| Knowledge graph | ❌ | ✅ |
|
||||
| Memory consolidation | ❌ | ✅ |
|
||||
| Temporal queries | ❌ | ✅ (716ns) |
|
||||
| Anomaly detection | ❌ | ✅ |
|
||||
| Provenance tracking | ❌ | ✅ |
|
||||
| Multi-modal | ❌ | ✅ |
|
||||
| Single portable file | ❌ (SQLite + MD files) | ✅ |
|
||||
|
||||
### Future: Native OpenClaw Plugin
|
||||
|
||||
The Phase 2 roadmap includes a native OpenClaw plugin (`memory.backend = "clawhdf5"`) that transparently replaces sqlite-vec. Until then, the Rust library can be wrapped via NAPI or used from the CLI.
|
||||
Limits to know: sections ingested this way carry no embedding (search over them
|
||||
is keyword-only unless you save records with vectors via `save_entry`);
|
||||
ingesting the same file again adds the sections again rather than replacing
|
||||
them; and `export_markdown` rewrites every heading as `##`, so it is not a
|
||||
lossless round trip.
|
||||
|
||||
---
|
||||
|
||||
@@ -547,7 +505,7 @@ let final_results = confidence::reject_low_confidence(
|
||||
|
||||
**Why not a vector database?** Pinecone, Qdrant, Weaviate — they're cloud services or heavy servers. Agent memory should be local, portable, and zero-dependency. An agent's memories should travel with it.
|
||||
|
||||
**Why not Markdown?** OpenClaw uses Markdown today and it works for simple cases. But it doesn't scale: no vector search, no knowledge graph, no structured retrieval. ClawhDF5 can import/export Markdown while providing everything Markdown can't.
|
||||
**Why not Markdown?** Plain Markdown files work for simple cases. But it doesn't scale: no vector search, no knowledge graph, no structured retrieval. ClawhDF5 can import/export Markdown while providing everything Markdown can't.
|
||||
|
||||
**Why HDF5 specifically?**
|
||||
- Native N-dimensional array storage (perfect for embeddings)
|
||||
|
||||
Reference in New Issue
Block a user