TypeScript SDK

The TypeScript SDK is the smritea-sdk package. It gives you an async SmriteaClient with four calls: add, search, get and delete. It ships both ESM and CommonJS builds.

InstallCopy Anchor Link

npm install smritea-sdk

Import the client from smritea-sdk:

import { SmriteaClient } from 'smritea-sdk';

Create a clientCopy Anchor Link

SmriteaClient takes one config object. You must set apiKey and appId. Create them in the dashboard; see Create an app and API key.

The client has no timeout option. Pass a fetch that sets one.

MethodsCopy Anchor Link

The table lists the client methods and what each one returns.

The getAll method exists but throws an error. Use search to find memories.

Add optionsCopy Anchor Link

The table lists the options that add accepts.

Pass relativeStanding as an object literal, such as { importance: 0.9, decayFactor: 0.5, decayFunction: 'exponential' }. The package does not export a type for it, so pass the literal inline or add as const. importance ranges from 0 to 1. decayFactor is 0 or higher. decayFunction takes 'exponential', 'gaussian' or 'linear'. Decay affects quick_search, context_aware_search and deep_search with temporal or rrf_temporal; importance affects deep_search with rrf or rrf_temporal.

Search optionsCopy Anchor Link

The table lists the options that search accepts.

You cannot combine validAt with fromTime or toTime. Put actor and conversation fields inside scope. The client ignores them anywhere else.

Memory scopeCopy Anchor Link

MemoryScope decides who a memory belongs to. Every field is optional. See Memory scope for the rules.

ResultsCopy Anchor Link

search returns an array of SearchResult. Each one has a score and a memory. The memory field is optional in the type, so read it with ?..

add returns a MemoryCreationResult.

ExceptionsCopy Anchor Link

Every error derives from SmriteaError. The SDK picks the class from the HTTP status.

Each exception has httpStatus, code, retryable, body and requestId. SmriteaTooManyRequestsError also has retryAfter, in seconds.

The SDK retries a 429 up to maxRetries times. It never retries a 402. For every code, see Errors and codes.

ExampleCopy Anchor Link

This script stores a memory, searches for it and handles the failures.

import {
  SmriteaClient,
  SmriteaError,
  SmriteaPaymentRequiredError,
  SmriteaTooManyRequestsError,
} from 'smritea-sdk';

const client = new SmriteaClient({
  apiKey: process.env.SMRITEA_API_KEY!,
  appId: process.env.SMRITEA_APP_ID!,
});
const scope = { actorId: 'alice', actorType: 'user' as const };

try {
  await client.add('Alice is vegetarian and loves hiking', { scope });
  const results = await client.search('What does Alice eat?', { scope });
  for (const r of results) {
    console.log(r.score, r.memory?.content);
  }
} catch (e) {
  if (e instanceof SmriteaPaymentRequiredError) {
    console.log('Plan quota used up (402)');
  } else if (e instanceof SmriteaTooManyRequestsError) {
    console.log(`Rate limited. Retry in ${e.retryAfter}s`);
  } else if (e instanceof SmriteaError) {
    console.log(e.httpStatus, e.code, e.requestId);
  } else {
    throw e;
  }
}

Don't see your language? Request it on GitHub. Search existing requests first and add a 👍 if yours is there. That helps the Smritea team rank requests.