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]>
97 lines
2.9 KiB
Markdown
97 lines
2.9 KiB
Markdown
# @redclaw/clawhdf5
|
|
|
|
Node.js (TypeScript) bindings for [clawhdf5](../../README.md) — a pure-Rust
|
|
HDF5-backed agent memory system with hippocampal consolidation.
|
|
|
|
Built with [napi-rs](https://napi.rs).
|
|
|
|
> **Status: unpublished and known to be broken.** This package is not on npm,
|
|
> no binaries are built, nothing in CI builds or tests it, and the wrapper
|
|
> reads field names the native layer does not produce. It is not an OpenClaw
|
|
> plugin. See [known issues](../../docs/known-issues.md) and
|
|
> [docs/openclaw.md](../../docs/openclaw.md) before using it.
|
|
|
|
## Installation
|
|
|
|
Not published. Building from source needs `@napi-rs/cli`:
|
|
|
|
```bash
|
|
npm install && npm run build
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
import { ClawhdfMemory } from '@redclaw/clawhdf5';
|
|
|
|
// Open or create a memory store (embedding dim must match your embedder)
|
|
const mem = ClawhdfMemory.openOrCreate('./agent.brain', 768);
|
|
|
|
// Ingest your existing MEMORY.md files
|
|
import { readFileSync } from 'fs';
|
|
const md = readFileSync('./memory/MEMORY.md', 'utf8');
|
|
mem.ingestMarkdown('memory/MEMORY.md', md);
|
|
|
|
// Write raw content
|
|
mem.write('memory/session.md', '# Session\n\nStarted task X.');
|
|
|
|
// Search
|
|
const embedding = new Float32Array(768); // supply a real embedding here
|
|
const results = mem.search('task X progress', embedding, 5);
|
|
console.log(results[0].text);
|
|
|
|
// Run consolidation at session end
|
|
const stats = mem.runConsolidation(Date.now() / 1000);
|
|
console.log(`Episodic: ${stats.episodicCount}, Semantic: ${stats.semanticCount}`);
|
|
```
|
|
|
|
## Building from source
|
|
|
|
Requirements:
|
|
|
|
- Rust (latest stable, edition 2024)
|
|
- Node.js ≥ 16
|
|
- `@napi-rs/cli` (`npm install -g @napi-rs/cli`)
|
|
|
|
```bash
|
|
# From the repo root
|
|
cd packages/clawhdf5-node
|
|
npm install
|
|
npm run build # release build
|
|
npm run build:debug # debug build (faster, no optimisations)
|
|
```
|
|
|
|
## API reference
|
|
|
|
See [`src/index.ts`](src/index.ts) for full JSDoc-annotated types.
|
|
|
|
### `ClawhdfMemory`
|
|
|
|
**Factory methods (use instead of `new`):**
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `ClawhdfMemory.create(path, embeddingDim)` | Create a new memory store |
|
|
| `ClawhdfMemory.open(path)` | Open existing store, replay WAL |
|
|
| `ClawhdfMemory.openOrCreate(path, embeddingDim)` | Open or create |
|
|
|
|
**Instance methods:**
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `search(queryText, queryEmbedding, k)` | Hybrid BM25 + vector search |
|
|
| `get(path, fromLine?, numLines?)` | Retrieve raw content |
|
|
| `write(path, content)` | Store raw content |
|
|
| `ingestMarkdown(path, content)` | Parse Markdown and ingest sections |
|
|
| `exportMarkdown(path)` | Reconstruct Markdown from stored sections |
|
|
| `stats()` | Aggregate store statistics |
|
|
| `compact()` | Remove tombstoned entries |
|
|
| `tickSession()` | Hebbian decay tick |
|
|
| `flushWal()` | Force WAL merge to disk |
|
|
| `runConsolidation(nowSecs)` | Full hippocampal consolidation cycle |
|
|
| `walPendingCount()` | Pending WAL entry count |
|
|
|
|
## License
|
|
|
|
MIT
|