@cartisien/engram-client

Typed HTTP client for Engram Cloud — persistent semantic memory for AI agents.

Install

npm install @cartisien/engram-client

Quick start

import { createClient } from '@cartisien/engram-client';

const engram = createClient({ apiKey: process.env.ENGRAM_API_KEY! });

await engram.remember('session-123', 'The user prefers TypeScript', { role: 'user' });

const hits = await engram.recall('session-123', 'programming preferences', { limit: 5 });
for (const entry of hits) {
  console.log(entry.content, entry.similarity);
}

Options

createClient({
  apiKey: 'ek_live_...',
  baseUrl: 'https://api.cartisien.com', // default
  timeoutMs: 30_000,                    // per-attempt timeout
  maxRetries: 3,                        // retries on 429 / 5xx with exponential backoff + Retry-After
  fetch,                                // inject for tests / non-global-fetch runtimes
});

API

| Method | HTTP | | --- | --- | | remember(sessionId, content, opts?) | POST /v1/memory | | recall(sessionId, query?, opts?) | GET /v1/memory/recall | | forget(sessionId, opts?) | DELETE /v1/memory | | stats(sessionId) | GET /v1/memory/stats | | exportEntries(sessionId) | GET /v1/memory/export — async iterable of NDJSON rows |

Errors

All errors extend EngramApiError with a stable code:

• EngramAuthError — 401 / 403 (never retried)
• EngramRateLimitError — 429 after retries exhausted (retryAfterSeconds when server sets Retry-After)
• EngramNetworkError — transport failures
• EngramTimeoutError — request exceeded timeoutMs

import { EngramAuthError, EngramRateLimitError } from '@cartisien/engram-client';

try {
  await engram.recall('s1', 'hello');
} catch (err) {
  if (err instanceof EngramRateLimitError) {
    console.log('retry after', err.retryAfterSeconds);
  } else if (err instanceof EngramAuthError) {
    throw err; // don't retry; rotate the key
  } else {
    throw err;
  }
}

Types

Re-exported from @cartisien/engram so local (new Engram()) and cloud code share shapes: MemoryEntry, MemoryRole, MemoryTier, SessionStats, RecallOptions.

License

MIT