Omar Sobh
62595d5ac0
CI / test (push) Failing after 14s
- Fix version skew: clawhdf5-py (pyproject.toml 1.93.0 -> 2.1.0) and packages/clawhdf5-node (package.json 2.0.0 -> 2.1.0) were both behind the actual crate version. - Correct stale ROADMAP.md claims: the TypeScript bridge already has a complete napi-rs package (not "no package.json"); CI/CD is now wired up via .gitea/workflows/ci.yml. - Fix CLAUDE.md: clawhdf5-gpu uses wgpu with hand-written WGSL compute shaders, not CubeCL. - chunked_read.rs: drop 12 unnecessary chunk_dimensions[..rank].to_vec() allocations — all three callees already accept &[u32]. - btree_v1.rs: add an overflow-safe ensure_len(data, offset, needed) helper (checked_add) and use it at the two plain-arithmetic bounds guards, closing a usize-overflow edge case reachable from a crafted near-usize::MAX B-tree offset. Add a regression test. - Clarify that the integrity hashes in clawhdf5-agent/provenance.rs (FNV-1a) and clawhdf5-format/provenance.rs (SHA-256) are unkeyed and only detect accidental corruption, not tampering — doc-only change. - README.md: document that the mpi-io feature's read/write paths are root-read+broadcast / gather-to-rank-0, not true collective I/O.
@redclaw/clawhdf5
Node.js (TypeScript) bindings for clawhdf5 — a pure-Rust HDF5-backed agent memory system with hippocampal consolidation.
Built with napi-rs.
Installation
npm install @redclaw/clawhdf5
Pre-built binaries are published for:
| Platform | Architecture |
|---|---|
| Linux (glibc) | x64, aarch64 |
| macOS | x64, aarch64 (Apple Silicon) |
| Windows | x64 |
Quick start
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)
# 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 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