@hebbs/sdk — TypeScript SDK for HEBBS

Async gRPC client for the HEBBS cognitive memory engine. Node.js 18+ only.

Install

npm install @hebbs/sdk

Quick Start

import { HebbsClient } from '@hebbs/sdk';

const client = new HebbsClient('localhost:6380', {
  apiKey: process.env.HEBBS_API_KEY,
});
await client.connect();

// Store a memory
const memory = await client.remember({
  content: 'User prefers dark mode',
  importance: 0.8,
  entityId: 'user-123',
});

// Recall by similarity
const { results } = await client.recall({
  cue: 'user preferences',
  strategies: ['similarity'],
});

// Prime a session
const primeOut = await client.prime({ entityId: 'user-123' });

// Real-time subscribe
const sub = await client.subscribe({ entityId: 'user-123' });
await sub.feed('Tell me about user preferences');
for await (const push of sub) {
  console.log('Surfaced:', push.memory.content);
}
await sub.close();

await client.close();

API

HebbsClient

| Method | Description | |--------|------------| | connect() | Open gRPC channel | | close() | Close connection | | remember(params) | Store a memory | | get(memoryId) | Retrieve by ID | | recall(params) | Multi-strategy recall | | prime(params) | Session warm-up | | revise(memoryId, params) | Update a memory | | forget(params) | GDPR-compliant erasure | | setPolicy(params) | Configure tenant policy | | subscribe(params) | Real-time streaming | | reflect(params) | Generate insights | | insights(params) | Retrieve insights | | health() | Server health check | | count() | Total memory count |

Recall Strategies

• similarity — semantic vector search
• temporal — time-ordered retrieval
• causal — cause-and-effect graph traversal
• analogical — cross-domain pattern matching

Error Handling

All SDK errors extend HebbsError. Specific subclasses map to gRPC status codes:

| Error | gRPC Status | |-------|-------------| | HebbsConnectionError | Channel failure | | HebbsUnavailableError | UNAVAILABLE | | HebbsTimeoutError | DEADLINE_EXCEEDED | | HebbsNotFoundError | NOT_FOUND | | HebbsInvalidArgumentError | INVALID_ARGUMENT | | HebbsAuthenticationError | UNAUTHENTICATED | | HebbsPermissionDeniedError | PERMISSION_DENIED | | HebbsInternalError | INTERNAL | | HebbsRateLimitError | RESOURCE_EXHAUSTED |

Testing

# Unit tests (no server needed)
npm test

# Integration tests (requires live server)
HEBBS_TEST_SERVER=localhost:6380 HEBBS_API_KEY=hb_... npm run test:integration

# E2E validation (requires live server + OpenAI for reflect)
HEBBS_API_KEY=hb_... OPENAI_API_KEY=sk-... npm run test:e2e

Demo App

cd demo && npm install

# Interactive mode (mock LLM, no API keys)
npx tsx src/index.ts interactive --mock-llm

# Interactive mode (real OpenAI)
OPENAI_API_KEY=sk-... npx tsx src/index.ts interactive

# Run scripted scenarios
npx tsx src/index.ts scenarios --all --mock-llm

License

Apache-2.0