@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

2.6 KiB Raw Permalink Blame History