type: Overview title: smritea SDK — TypeScript / Node.js status: stable tags:

• readme stale_after: 2026-12-31 generated: by: Tushar Dwivedi at: 2026-08-25T00:00:00Z

smritea SDK — TypeScript / Node.js

| Section | What it covers | |---------|----------------| | Installation | Requires Node.js 18+. Ships as ESM + CJS with bundled type declarations. | | Get your API key | Sign up at smritea.ai — free account, no credit card required | | Quickstart | Quickstart | | Constructor | Constructor | | Methods | All methods are async and return Promises. | | Error handling | Error handling | | Memory type reference | All fields use camelCase. |

TypeScript SDK for the smritea AI memory system.

Get a free API key →

Installation

npm install smritea-sdk

Requires Node.js 18+. Ships as ESM + CJS with bundled type declarations.

Get your API key

1. Sign up at smritea.ai — free account, no credit card required
2. Create an app in the dashboard and copy your API key (sk-...) and App ID (app_...)
3. Export them as environment variables:

export SMRITEA_API_KEY="sk-..."
export SMRITEA_APP_ID="app_..."

Quickstart

import { SmriteaClient } from 'smritea-sdk';

const client = new SmriteaClient({
  apiKey: process.env.SMRITEA_API_KEY!,
  appId: process.env.SMRITEA_APP_ID!,
});

// Store something about a user
await client.add('Alice is a vegetarian and loves hiking', { actorId: 'alice', actorType: 'user' });

// Retrieve it later in a different session
const results = await client.search("What are Alice's food preferences?", { actorId: 'alice', actorType: 'user' });
for (const r of results) {
  console.log(r.score?.toFixed(2), r.content);
}

Constructor

import { SmriteaClient } from 'smritea-sdk';

const client = new SmriteaClient({
  apiKey: 'sk-...',                       // required
  appId: 'app_...',                       // required
  baseUrl: 'https://api-us.smritea.ai',      // optional, default shown
  maxRetries: 2,                          // optional, default 2; 0 disables retry
  traceId: 'checkout-flow-2026',          // optional, see below
});

traceId is sent as the X-Trace-ID header on every request, so your own logs and the smritea request logs can be correlated. It must be 8-100 characters, limited to A-Z, a-z, 0-9, ., _, : and -. An invalid value throws a TypeError from the constructor, before any network call is made.

Methods

All methods are async and return Promises.

add — Store a memory

const memory = await client.add('User prefers concise replies', {
  actorId: 'alice',
  actorType: 'user',
  metadata: { source: 'chat' },
  conversationId: 'conv_123',
});
console.log(memory.id); // mem_...

| Option | Default | Description | |---|---|---| | actorId | undefined | Actor ID | | actorType | undefined | "user" | "agent" | "system" | | actorName | undefined | Display name | | metadata | undefined | Arbitrary key-value object | | conversationId | undefined | Conversation context |

search — Semantic search

const results = await client.search('dietary restrictions', {
  actorId: 'alice',
  actorType: 'user',
  limit: 5,
  method: 'deep_search',  // "quick_search" | "deep_search" | "context_aware_search"
});
results.forEach(r => console.log(r.score, r.content));

Results are ordered by relevance (descending). Each result exposes score (0.0–1.0) and all Memory fields directly.

| Search method | When to use | |---|---| | quick_search | Low-latency, keyword + vector hybrid | | deep_search | Higher recall, traverses the memory graph | | context_aware_search | Reranks results using conversation context |

| Option | Default | Description | |---|---|---| | actorId | undefined | Filter by actor ID | | actorType | undefined | Filter by actor type | | limit | app default | Max results to return | | method | app default | Search strategy | | graphDepth | undefined | Graph traversal depth override | | conversationId | undefined | Conversation context |

get — Retrieve a memory by ID

const memory = await client.get('mem_abc123');
console.log(memory.content, memory.createdAt);
// Throws SmriteaNotFoundError if the ID does not exist

delete — Delete a memory by ID

await client.delete('mem_abc123');
// Throws SmriteaNotFoundError if the ID does not exist

getAll — List all memories

Not yet implemented. getAll() throws an Error when called. Use search() with a broad query as a workaround:

const results = await client.search('', { actorId: 'alice', actorType: 'user', limit: 20 });

limit must not exceed the server's top_n_max (default 20); a larger value returns a 400 error. Omit it to use the app's top_n.

Error handling

import {
  SmriteaBadRequestError,
  SmriteaUnauthorizedError,
  SmriteaPaymentRequiredError,
  SmriteaForbiddenError,
  SmriteaNotFoundError,
  SmriteaConflictError,
  SmriteaUnprocessableError,
  SmriteaTooManyRequestsError,
  SmriteaError,
} from 'smritea-sdk';

try {
  await client.delete('mem_unknown');
} catch (e) {
  if (e instanceof SmriteaNotFoundError) console.log('Memory not found');
  if (e instanceof SmriteaTooManyRequestsError) console.log(`Retry after ${e.retryAfter}s`);
  if (e instanceof SmriteaUnauthorizedError) console.log('Invalid API key');
  if (e instanceof SmriteaPaymentRequiredError) console.log('Plan quota exceeded');
}

Every SmriteaError and its subclasses expose requestId, the server's request ID for the failed call. It is taken from the response body's request_id field when that is a non-empty string, otherwise from the X-Request-ID response header. It is undefined when neither is present:

try {
  await client.add('Alice prefers morning meetings', { actorId: 'alice', actorType: 'user' });
} catch (e) {
  if (e instanceof SmriteaError) console.log(e.requestId);
}

| Exception | HTTP | When | |---|---|---| | SmriteaBadRequestError | 400 | Invalid request parameters | | SmriteaUnauthorizedError | 401 | Invalid or missing API key | | SmriteaPaymentRequiredError | 402 | Organisation quota exceeded | | SmriteaForbiddenError | 403 | Access denied | | SmriteaNotFoundError | 404 | Memory ID does not exist | | SmriteaConflictError | 409 | Resource conflict | | SmriteaUnprocessableError | 422 | Unprocessable entity | | SmriteaTooManyRequestsError | 429 | Rate limit hit — check .retryAfter | | SmriteaError | other | Unexpected server error |

Memory type reference

All fields use camelCase.

| Field | Type | Description | |---|---|---| | id | string | Memory ID (mem_...) | | appId | string | App this memory belongs to | | content | string | Memory text | | actorId | string | Actor who owns this memory | | actorType | string | "user" | "agent" | "system" | | actorName | string? | Display name | | metadata | object? | Arbitrary key-value pairs | | conversationId | string? | Conversation context | | activeFrom | string | ISO 8601 — when memory becomes valid | | activeTo | string? | ISO 8601 — when memory expires | | createdAt | string | ISO 8601 creation timestamp | | updatedAt | string | ISO 8601 last update timestamp |