@totalreclaw/client
TypeScript client library for TotalReclaw -- E2EE, LSH blind indexing, embeddings, and reranking
Website ·
npm ·
Repository
---
Build encrypted memory into any AI agent. All encryption happens client-side -- the server never sees plaintext.
This is the core cryptographic library used by [@totalreclaw/totalreclaw](https://www.npmjs.com/package/@totalreclaw/totalreclaw) (OpenClaw plugin) and [@totalreclaw/mcp-server](https://www.npmjs.com/package/@totalreclaw/mcp-server). Most users should install one of those packages instead.
**Requirements:** Node.js 18+
### Architecture
All cryptographic operations (XChaCha20-Poly1305, HKDF key derivation, LSH hashing, blind indices, content fingerprinting) are powered by [`@totalreclaw/core`](https://www.npmjs.com/package/@totalreclaw/core) -- a unified Rust/WASM module that ensures byte-for-byte consistency across all TotalReclaw clients.
## Installation
```bash
npm install @totalreclaw/client
```
## Features
- **XChaCha20-Poly1305 encryption** -- All memories encrypted client-side
- **Blind index search** -- LSH-based blind indices for searching encrypted data
- **Local embeddings** -- Harrier-OSS-v1-270M for semantic similarity (no API keys)
- **BM25 + cosine reranking** -- Reciprocal rank fusion for high-quality retrieval
- **Smart Account derivation** -- BIP-39 mnemonic to ERC-4337 Smart Account address
- **Memory decay** -- Importance-based lifecycle management
## Quick Start
```typescript
import { TotalReclaw } from '@totalreclaw/client';
const client = new TotalReclaw({ serverUrl: 'https://api.totalreclaw.xyz' });
await client.init();
const userId = await client.register('your twelve word recovery phrase');
await client.remember('I prefer coffee over tea in the morning');
const results = await client.recall('what do I like to drink?');
```
## Crypto Primitives
| Operation | Algorithm | Purpose |
|-----------|-----------|---------|
| Key derivation | Argon2id + HKDF-SHA256 | Memory-hard password hashing + auth key derivation |
| Encryption | XChaCha20-Poly1305 | Authenticated encryption of memories and embeddings |
| Blind indices | SHA-256 | Searchable encryption without exposing plaintext |
| LSH | Random hyperplane | Approximate nearest neighbor search on encrypted data |
| Embeddings | Harrier-OSS-v1-270M (640d) | Local semantic similarity (no API calls) |
| Reranking | BM25 + cosine + RRF | Multi-signal result fusion |
## Development
```bash
npm install # Install dependencies
npm test # Run tests (217 tests)
npm run build # Build
```
## Learn More
- [Architecture Spec](../docs/specs/totalreclaw/architecture.md) -- E2EE design with LSH + blind buckets
- [totalreclaw.xyz](https://totalreclaw.xyz)
- [Main Repository](https://github.com/p-diogo/totalreclaw)
## License
MIT