quantumclaw/clawhdf5

Fork 0

Files

T

osobhandClaude Opus 5.5 0c65a27b00

CI / test-arm64 (pull_request) Successful in 1m3s

Details

CI / test (pull_request) Successful in 5m48s

Details

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

2026-09-25 10:27:54 -05:00

2.9 KiB

Raw Blame History

@redclaw/clawhdf5

Node.js (TypeScript) bindings for clawhdf5 — a pure-Rust HDF5-backed agent memory system with hippocampal consolidation.

Built with 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 and docs/openclaw.md before using it.

Installation

Not published. Building from source needs @napi-rs/cli:

npm install && npm run build

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

2.9 KiB Raw Blame History