97 lines
2.6 KiB
Markdown
97 lines
2.6 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).
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
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
|
|
|
|
```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
|