# clawhdf5-napi

> **Status: does not work end to end.** The TypeScript package built on
> this crate (`packages/clawhdf5-node`) has never run successfully, is
> unpublished, and is not built or tested in CI. See "The Node.js package
> does not work" in [`docs/known-issues.md`](../../docs/known-issues.md).
> Fix it and add CI, or remove it, before depending on it.

A Node.js native addon ([napi-rs](https://napi.rs), N-API 9) exposing
[`clawhdf5-agent`](../clawhdf5-agent/README.md) as a `ClawhdfMemory`
class. It wraps `clawhdf5_agent::openclaw::ClawhdfBackend` (the agent's
`search` with re-ranking and confidence on) and the consolidation engine.
It was written for an OpenClaw integration that is not being pursued
([`docs/openclaw.md`](../../docs/openclaw.md)).

## What the addon exposes

`ClawhdfMemory.create(path, dim)`, `.open(path)`, `.openOrCreate(path,
dim)`, and on an instance: `search`, `get`, `write`, `ingestMarkdown`,
`exportMarkdown`, `save`, `saveBatch`, `stats`, `compact`, `tickSession`,
`flushWal`, `walPendingCount`, `runConsolidation`, and the ephemeral tier
(`enableEphemeral`, `ephemeralSet`/`Get`/`Delete`, `ephemeralStats`,
`promoteEphemeral`). napi-rs converts names and `#[napi(object)]` fields to
camelCase.

## Build

```bash
cargo build --release -p clawhdf5-napi     # the Rust cdylib
# the .node package: npm install -g @napi-rs/cli; cd packages/clawhdf5-node; napi build --platform --release
```

It links against Node's N-API through `napi-sys` (a `-sys` crate), so it is
exempt from CI's "no C in the default build" check.

## License

MIT