Java SDK

The Java SDK is the ai.smritea:smritea-sdk package. It gives you a thread-safe, synchronous SmriteaClient with four calls: add, search, get and delete. It needs Java 11 or later. Every error is an unchecked exception.

InstallCopy Anchor Link

Add the dependency to your Maven pom.xml. Replace LATEST with the current release number from Maven Central.

<dependency>
  <groupId>ai.smritea</groupId>
  <artifactId>smritea-sdk</artifactId>
  <version>LATEST</version>
</dependency>

For Gradle, add this line:

implementation 'ai.smritea:smritea-sdk:LATEST'

Import the client and the model types:

import ai.smritea.sdk.SmriteaClient;
import ai.smritea.sdk.model.*;
import ai.smritea.sdk.errors.*;

Create a clientCopy Anchor Link

SmriteaClient takes your API key and your app ID. You must pass both, and a null value throws NullPointerException. Create them in the dashboard; see Create an app and API key.

The constructors accept the first two, four, five or six arguments, in the order shown. Pass null for baseUrl to use the default. The client has no timeout argument. Set a timeout on the HttpClient you pass in.

MethodsCopy Anchor Link

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

Pass null for no options. The getAll method exists but throws UnsupportedOperationException. Use search to find memories.

Add optionsCopy Anchor Link

Build options with the fluent methods on new AddOptions().

Build a RelativeStanding with new RelativeStanding(). Chain withImportance(Float), withDecayFactor(Float) and withDecayFunction(String). Import it from ai.smritea.sdk.model. The importance ranges from 0 to 1. The decay factor is 0 or higher. The decay function 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

Build options with the fluent methods on new SearchOptions().

You cannot combine withValidAt with withFromTime or withToTime.

Memory scopeCopy Anchor Link

Build a scope with MemoryScope.builder(). Every field is optional. See Memory scope for the rules.

ResultsCopy Anchor Link

search returns a List<SearchResult>. It never returns null.

add returns a MemoryCreationResult.

get returns a Memory. It has getId, getAppId, getContent, getScope, getMetadata, getActiveFrom, getActiveTo, getCreatedAt and getUpdatedAt. Read the actor and conversation through getScope().

ExceptionsCopy Anchor Link

Every error extends SmriteaError, which extends RuntimeException. The SDK picks the class from the HTTP status.

Each exception has getHttpStatus(), getCode(), isRetryable(), getBody() and getRequestId(). SmriteaTooManyRequestsError also has getRetryAfter(), 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 program stores a memory, searches for it and handles the failures.

import ai.smritea.sdk.SmriteaClient;
import ai.smritea.sdk.errors.SmriteaError;
import ai.smritea.sdk.errors.SmriteaPaymentRequiredError;
import ai.smritea.sdk.errors.SmriteaTooManyRequestsError;
import ai.smritea.sdk.model.AddOptions;
import ai.smritea.sdk.model.MemoryScope;
import ai.smritea.sdk.model.SearchOptions;
import ai.smritea.sdk.model.SearchResult;
import java.util.List;

public class Example {
    public static void main(String[] args) {
        SmriteaClient client = new SmriteaClient(
            System.getenv("SMRITEA_API_KEY"),
            System.getenv("SMRITEA_APP_ID"));
        MemoryScope alice = MemoryScope.builder()
            .actorId("alice")
            .actorType("user")
            .build();

        try {
            client.add("Alice is vegetarian and loves hiking",
                new AddOptions().withScope(alice));
            List<SearchResult> results = client.search(
                "What does Alice eat?",
                new SearchOptions().withScope(alice));
            for (SearchResult r : results) {
                System.out.printf("%.2f  %s%n", r.getScore(), r.getContent());
            }
        } catch (SmriteaPaymentRequiredError e) {
            System.out.println("Plan quota used up (402)");
        } catch (SmriteaTooManyRequestsError e) {
            System.out.println("Rate limited. Retry in " + e.getRetryAfter());
        } catch (SmriteaError e) {
            System.out.println(
                e.getHttpStatus() + " " + e.getCode() + " " + e.getRequestId());
        }
    }
}

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.