FloorMemory SDKs — Installation & Setup Guide

This guide explains how to install, configure, and initialize the official FloorMemory SDKs.

All SDKs share:

the same API contract

the same authentication model

the same conceptual workflow

Language-specific usage examples are covered in their respective SDK pages.

⚠️ Important
FloorMemory SDKs do not expose a single high-level client (such as MemoryClient).
Instead, each SDK provides capability-based API classes (Query, Events, Floors, Auth, etc.), generated directly from the FloorMemory OpenAPI specification.

1. Choose Your SDK

FloorMemory provides official SDKs for:

Python

JavaScript

TypeScript

Java

All SDKs are:

generated from the same OpenAPI specification

functionally equivalent

kept intentionally close to the underlying REST APIs

Differences between SDKs are language ergonomics only, not behavior.

2. Installation

Python

JavaScript

TypeScript

Type definitions are included by default.

Java

Maven

<dependency>
  <groupId>ai.xfloor.memory</groupId>
  <artifactId>floor-memory-sdk</artifactId>
  <version>YOUR_VERSION</version>
</dependency>

Build from source (optional)

3. Authentication Model (Common to All SDKs)

All FloorMemory APIs use Bearer Token authentication.

Key concepts

Tokens are generated per App

Tokens authorize access to FloorMemory APIs

Tokens are not user credentials

User context is passed separately using user_id

Environment variable (recommended)

🔐 Security note
Tokens must be kept server-side.
Do not embed tokens directly in frontend JavaScript unless you are intentionally building a client-side integration.

4. Base URL Configuration

By default, SDKs point to the FloorMemory production API.

If you are using a custom domain or environment, configure the base URL explicitly.

Example:

https://appfloor.in

5. SDK Initialization (Correct Pattern)

All SDKs follow the same one-time initialization pattern:

create a shared client/configuration once

reuse it across API calls

pass app_id explicitly per request

Python

API usage is then done via capability-based classes:

JavaScript

Then use specific APIs:

TypeScript

import { Configuration, QueryApi } from "@xfloor/floor-memory-sdk-ts";

const config = new Configuration({
  accessToken: process.env.XFLOOR_API_KEY,
  basePath: "https://appfloor.in",
});

const queryApi = new QueryApi(config);

Java

API classes are then instantiated as needed:

6. `app_id` vs Authentication (Very Important)

All SDKs share this rule:

Authentication → handled globally via Bearer token

Application context (app_id) → passed explicitly per API call

This allows:

one token to serve multiple apps

pod-based and multi-tenant workflows

explicit control over application scope

7. Thread Safety & Reuse

Across all SDKs:

SDK clients/configurations are safe to reuse

Create one instance per service or application

Do not create a new client per request

This applies to:

Python ApiClient

JS shared ApiClient.instance

TS Configuration

Java ApiClient

8. Error Handling (High-Level)

SDKs surface API errors using:

HTTP status codes

structured error payloads

Best practices:

do not rely on string matching

always inspect:

HTTP status code

error code (if provided)

response body

Language-specific error handling examples are documented in each SDK page.

9. Where to Go Next

Once installation and setup are complete:

👉 Python SDK (/python-sdk-1930592m0)

👉 JavaScript SDK (/javascript-sdk-1930593m0)

👉 TypeScript SDK (/typescript-sdk-1930595m0)

👉 Java SDK (/java-sdk-1930594m0)

Or jump directly to core APIs:

Query API — conversational retrieval (most common)

Create Event API — store memory

Recent Events API — feeds and confirmation

Floor APIs — metadata and permissions

Summary

All FloorMemory SDKs are OpenAPI-generated

SDKs simplify integration but do not change API behavior

Authentication is app-scoped, not user-scoped

app_id is passed explicitly per API call

SDKs are initialized once and reused

The conceptual model is identical across languages

SDK Installation & Setup

FloorMemory SDKs — Installation & Setup Guide#

1. Choose Your SDK#

2. Installation#

Python#

JavaScript#

TypeScript#

Java#

Maven#

Build from source (optional)#

3. Authentication Model (Common to All SDKs)#

Key concepts#

Environment variable (recommended)#

4. Base URL Configuration#

5. SDK Initialization (Correct Pattern)#

Python#

JavaScript#

TypeScript#

Java#

6. app_id vs Authentication (Very Important)#

7. Thread Safety & Reuse#

8. Error Handling (High-Level)#

9. Where to Go Next#

Summary#

FloorMemory SDKs — Installation & Setup Guide

1. Choose Your SDK

2. Installation

Python

JavaScript

TypeScript

Java

Maven

Build from source (optional)

3. Authentication Model (Common to All SDKs)

Key concepts

Environment variable (recommended)

4. Base URL Configuration

5. SDK Initialization (Correct Pattern)

Python

JavaScript

TypeScript

Java

6. `app_id` vs Authentication (Very Important)

7. Thread Safety & Reuse

8. Error Handling (High-Level)

9. Where to Go Next

Summary