@engramtraining/sdk

Official TypeScript/JavaScript SDK for the Engram memory API — persistent, versioned memory for AI agents built on Shelby Protocol.

Installation

npm install @engramtraining/sdk

Quick Start

import { Engram } from '@engramtraining/sdk';

const engram = new Engram({
  apiKey: process.env.ENGRAM_API_KEY!,
});

// Store a memory
const memory = await engram.store({
  type: 'semantic',
  key: 'facts/user-name',
  content: 'User name is Alice',
  importance: 0.8,
  expiresIn: '30d',
  metadata: { tags: ['user'], visibility: 'private' },
});

// Retrieve
const result = await engram.get(memory.id);
console.log(result.content); // "User name is Alice"

// Search
const found = await engram.search({
  contentQuery: 'Alice',
  type: 'semantic',
});

// Update (creates version 2)
await engram.update(memory.id, {
  content: 'User name is Alice Smith',
});

// Delete
await engram.delete(memory.id);

Encryption

Store and retrieve encrypted memories with built-in AES-256-GCM:

// Store encrypted (auto-encrypts with your API key)
const secret = await engram.storeEncrypted({
  type: 'semantic',
  key: 'secrets/db-password',
  content: 's3cret_p@ss!',
});

// Retrieve and decrypt
const decrypted = await engram.getDecrypted(secret.id);
console.log(decrypted.content); // "s3cret_p@ss!"

File Upload & Download

import { readFileSync, writeFileSync } from 'fs';

// Upload
const file = await engram.upload({
  file: readFileSync('report.pdf'),
  filename: 'report.pdf',
  key: 'docs/quarterly-report',
  type: 'file',
  mimeType: 'application/pdf',
});

// Download
const buffer = await engram.download(file.id);
writeFileSync('downloaded.pdf', Buffer.from(buffer));

Bulk Operations

// Bulk store (up to 20)
const result = await engram.bulkStore({
  memories: [
    { type: 'semantic', key: 'facts/1', content: 'Fact one' },
    { type: 'semantic', key: 'facts/2', content: 'Fact two' },
    { type: 'semantic', key: 'facts/3', content: 'Fact three' },
  ],
});
console.log(`${result.succeeded} stored, ${result.failed} failed`);

// Bulk delete (up to 50)
await engram.bulkDelete({ ids: ['uuid-1', 'uuid-2'] });

Vector Search

const similar = await engram.vectorSearch({
  embedding: [0.85, 0.15, 0.25, 0.1, 0.75],
  type: 'semantic',
  threshold: 0.7,
  limit: 5,
});

TTL & Expiry Management

// Check what's expiring
const expiring = await engram.expiring('24h');
console.log(`${expiring.count} memories expiring within 24h`);

// Check and renew in one call
const alerts = await engram.ttlAlerts({
  within: '24h',
  renewIds: ['uuid-1', 'uuid-2'],
  renewExpiresIn: '30d',
});

Pin & Importance

// Pin a memory (free — no credit cost)
await engram.pin(memory.id, true);

// Set importance (free — no credit cost)
await engram.setImportance(memory.id, 0.95);

// List pinned memories
const pinned = await engram.list({ pinned: true });

// List high-importance memories
const important = await engram.list({
  minImportance: 0.8,
  sortBy: 'importance',
});

Media Storage

// Upload media
const photo = await engram.media.upload({
  file: readFileSync('photo.jpg'),
  filename: 'photo.jpg',
  title: 'Profile Photo',
});

// List media
const media = await engram.media.list({ category: 'photo' });

// Stream media
const stream = await engram.media.stream(photo.id);

// Delete media
await engram.media.delete(photo.id);

Billing

// Check balance
const balance = await engram.billing.balance();
console.log(`${balance.creditBalance} credits ($${balance.creditValueUsd})`);

// Get pricing
const pricing = await engram.billing.pricing();

// Confirm APT deposit
const deposit = await engram.billing.deposit({
  txHash: '0xcf515fe7...',
});

Agent Self-Registration

No API key needed — register a new autonomous agent:

import { Engram } from '@engramtraining/sdk';

const agent = await Engram.register({ name: 'my-research-agent' });
console.log(agent.apiKey);          // sk_live_...
console.log(agent.rotationSecret);  // sk_live_ROT...
console.log(agent.creditBalance);   // 100

// Now create a client with the new key
const engram = new Engram({ apiKey: agent.apiKey });

Key Rotation

const rotated = await engram.rotateKey({
  rotationSecret: 'sk_live_ROT...',
});
console.log(rotated.apiKey);          // New API key
console.log(rotated.rotationSecret);  // New rotation secret

Error Handling

import { Engram, EngramError } from '@engramtraining/sdk';

try {
  await engram.store({ type: 'semantic', key: 'test', content: 'hello' });
} catch (err) {
  if (err instanceof EngramError) {
    console.log(err.status);    // 409
    console.log(err.message);   // "Key exists"
    console.log(err.retryable); // false
    console.log(err.details);   // Validation errors (for 400s)
  }
}

Configuration

const engram = new Engram({
  apiKey: 'sk_live_...',                          // Required
  baseUrl: 'https://api.engram.training/v1',      // Default
  timeout: 30000,                                 // Default: 30s
  fetch: customFetchImplementation,               // Optional: custom fetch
});

Requirements

• Node.js 18+ (uses native fetch)
• Zero runtime dependencies

Links

• Documentation
• API Reference

License

MIT