FloorMemory Python SDK

This page describes how to use the FloorMemory Python SDK in real backend applications, services, automation pipelines, and AI agents.

Use this SDK to:

Query memory-aware, multi-turn conversations

Add content and knowledge to Floors

Retrieve recent activity and conversations

Fetch floor metadata and structure

Manage floor settings (owner-only actions)

The SDK is designed for server-side usage and mirrors the FloorMemory APIs closely.

⚠️ Important
Functionality is accessed through capability-specific API classes such as QueryApi, EventApi, GetRecentEventsApi, etc.

Source Code

Official Python SDK Repository
👉 https://github.com/xFloorllm/floor-memory-sdk-client/tree/main/python

Production-ready usage examples
👉 https://github.com/xFloorllm/floor-memory-sdk-examples/tree/main/python

The examples repository contains:

Clean backend integration samples

Multi-turn conversation patterns

Structured ingestion flows

Production-safe usage templates

If you're building a real backend service, start there.

Installation

Authentication & Setup (Required)

All authenticated APIs use Bearer Token authentication.

You must also provide an app_id when invoking APIs that require application context.

Environment Variables (Recommended)

Client Configuration

Key Points

Authentication header:
Authorization: Bearer <BEARER_TOKEN>

Create one ApiClient per service

Reuse API instances (do not recreate per request)

app_id is passed per API call

app_id is never embedded inside payload JSON

Adding Content to a Floor (Create Event)

Use this API to store knowledge that future conversations can reference.

API class: EventApi

Endpoint: POST /api/memory/events

Ingestion model: Asynchronous
200 OK means accepted and queued, not immediately searchable

Method Parameters

Field	Type	Required	Description
`app_id`	str	✅	Calling application context

`input_info` (JSON string)

Field	Type	Required	Description
`floor_id`	str	✅	Floor where content is stored
`block_id`	str	Optional	Block container inside the floor
`block_type`	str	Optional	Content category (`post`, `forum`)
`user_id`	str	✅	Author / owner of the content
`title`	str	Optional	Optional title
`description`	str	✅	Main textual content

Correct Example

Important Notes

app_id is NOT part of input_info

200 OK means queued

Indexing is asynchronous

Poll Recent Events API if you need ingestion confirmation

Do not assume immediate search visibility

Querying Memory (Multi-Turn Conversations)

Use this API to retrieve memory-aware answers across one or more Floors.

API class: QueryApi

Designed for conversational continuity

Supports summarization and metadata control

Example

Key Query Controls

Parameter	Purpose
`summary_needed="1"`	Returns summarized answer
`include_metadata="1"`	Includes source metadata
`floor_ids=[]`	Restrict search to specific floors
`user_id`	Enables conversation continuity

Production-Safe Agent Pattern

This pattern ensures:

One shared client

Clean API separation

Deterministic parameter handling

Safe integration with FastAPI / Celery / workers

Why This Structure Matters (Subtle but Critical)

Keeps SDK aligned with OpenAPI contract

Avoids silent validation failures

Prevents future SDK updates from breaking payloads

Makes distributed workers deterministic

Ensures multi-turn memory continuity works correctly

When to Use the Examples Repository

If you are:

Building a real backend service

Integrating with FastAPI

Running Celery workers

Designing an AI agent

Creating automation pipelines

Use the official examples:

👉 https://github.com/xFloorllm/floor-memory-sdk-examples/tree/main/python

That repository reflects best-practice integration patterns, not just raw SDK calls.

Python SDK

FloorMemory Python SDK#

Source Code#

Installation#

Authentication & Setup (Required)#

Environment Variables (Recommended)#

Client Configuration#

Key Points#

Adding Content to a Floor (Create Event)#

Method Parameters#

input_info (JSON string)#

Correct Example#

Important Notes#

Querying Memory (Multi-Turn Conversations)#

Example#

Key Query Controls#

Production-Safe Agent Pattern#

Why This Structure Matters (Subtle but Critical)#

When to Use the Examples Repository#