FAQ & Troubleshooting

This section covers real-world failure modes you may hit while integrating FloorMemory APIs and SDKs across Node / TypeScript / Python / Java.

If something feels stuck, it usually is — and the cause is almost always cache, identity, or versioning, not your business logic.

General FAQs (Applies to All SDKs)

❓ “My API calls succeed, but responses don’t reflect newly added content”

This is expected behavior.

FloorMemory uses indexed retrieval, not live database reads.

What’s happening

Newly ingested content may not be indexed yet

Cached metadata may still be in use

You may be querying a different floor_id than intended

What you should check

Confirm the content ingestion request completed successfully

Allow time for indexing to complete

Verify the floor_id in your request

Retry the query (do not assume instant freshness)

Reality check

FloorMemory is not a real-time database.
It’s a memory system optimized for conversations.

❓ “The AI responds, but ignores what the user said previously”

This almost always indicates an identity continuity issue.

Common causes

user_id is generated dynamically or per request

Different IDs are used across calls

user_id and xfloor_user_id are mixed inconsistently

What to do

Use one stable user ID per human

Generate and store it server-side

Reuse it across all requests and sessions

No stable user ID → no conversational memory
This is non-negotiable.

❓ “Sometimes the AI answers without using floor content”

This is intentional.

FloorMemory does not force retrieval when the query does not require it.

Examples

“Hi”
“Explain recursion”

What this means

Retrieval is context-aware, not mandatory

Floor content is used only when relevant

This behavior is by design

❓ “Is FloorMemory just RAG?”

No.

RAG is one component, not the product.

FloorMemory also handles:

Conversation continuity

User-level memory

Floor-level isolation

Context assembly across turns

Think memory infrastructure, not just retrieval.

Node.js / JavaScript SDK Issues

❓ “Running `npm install` doesn’t give me the latest SDK”

This is a registry behavior, not a coding error.

What to verify first

If this shows an older version, the newer SDK is not yet available

Local reinstalls will not change that

To rule out local cache issues

If the installed version still matches what npm view shows:

Your environment is behaving correctly.
You are waiting on a platform release.

Important

npm will never update a package unless a new version exists in the registry.

❓ “It works locally but fails in production”

This is usually an environment mismatch.

Check

Also verify:

Environment variables exist in prod

The deployed build actually includes recent changes

The runtime Node version matches local

TypeScript SDK Issues

❓ “Types don’t match the docs or the API behavior”

This indicates a spec / SDK version mismatch.

Why this happens

The SDK was generated from an earlier OpenAPI spec

The API evolved but the SDK hasn’t been updated yet

What to do

Check the installed SDK version

Upgrade when a newer version is available

Do not patch generated types manually

Reality

Generated SDKs mirror the spec — nothing more.

❓ “Optional fields or enums behave oddly”

This is normal OpenAPI → TypeScript behavior.

What to expect

Optional fields may be undefined

Enums are typically string unions

Runtime validation is not enforced

Best practice

Validate inputs in your backend

Treat SDK types as guidance, not guarantees

Python SDK Issues

❓ “`pip install` doesn’t fetch a newer SDK”

First, verify what PyPI actually has:

Attempt an upgrade:

If the version does not change:

A newer version is not available in the registry yet.

This is expected behavior.

❓ “Module not found / wrong version installed”

This usually indicates a virtual environment mismatch.

Verify

Then reinstall explicitly:

If python and pip point to different locations, nothing else matters.

Java SDK Issues

❓ “Maven resolves an older SDK version”

Maven caches aggressively by design.

Force refresh

If needed, clear the local cache:

❓ “401 / 403 when resolving the dependency”

This is almost always a credentials issue.

Check

~/.m2/settings.xml exists

<server><id> matches the one used in pom.xml

Token is valid and scoped correctly

Reality

Maven errors rarely explain auth failures clearly.
Assume credentials first.

❓ “The SDK builds, but feels awkward to use”

This is expected.

Java SDKs are generated, not handcrafted.

Recommended approach

Treat the SDK as a transport/client layer

Wrap it inside your own service abstraction

Do not expose generated models directly across your codebase

Common API-Level Pitfalls

❓ “I get `400 / XF_VALIDATION_ERROR` without much detail”

Likely causes

Invalid JSON payload

Missing required fields

Incorrect data types

What to do

Log the full error response

Validate request payloads before sending

Don’t assume the SDK validates inputs

❓ “Conversation history feels noisy or irrelevant”

This is expected if conversations are reused indefinitely.

What to do

Start a new conversation when the topic changes

Don’t reuse conversation IDs blindly

Memory grows unless you reset context

Blunt Advice (Worth Reading Once)

SDKs are helpers, not abstractions

Version numbers matter more than code changes

Stable user identity is critical

Cache invalidation causes most confusion

Most issues are integration or expectation gaps, not platform bugs

Before You Open a Support Ticket

Check these five things:

Installed SDK version vs registry version

Stability of user_id

Correctness of floor_id

Environment variables

Dependency cache state

Roughly 80% of issues resolve here.

General FAQs (Applies to All SDKs)#

❓ “My API calls succeed, but responses don’t reflect newly added content”#

❓ “The AI responds, but ignores what the user said previously”#

❓ “Sometimes the AI answers without using floor content”#

❓ “Is FloorMemory just RAG?”#

Node.js / JavaScript SDK Issues#

❓ “Running npm install doesn’t give me the latest SDK”#

❓ “It works locally but fails in production”#

TypeScript SDK Issues#

❓ “Types don’t match the docs or the API behavior”#

❓ “Optional fields or enums behave oddly”#

Python SDK Issues#

❓ “pip install doesn’t fetch a newer SDK”#

❓ “Module not found / wrong version installed”#

Java SDK Issues#

❓ “Maven resolves an older SDK version”#

❓ “401 / 403 when resolving the dependency”#

❓ “The SDK builds, but feels awkward to use”#

Common API-Level Pitfalls#

❓ “I get 400 / XF_VALIDATION_ERROR without much detail”#

❓ “Conversation history feels noisy or irrelevant”#

Blunt Advice (Worth Reading Once)#

Before You Open a Support Ticket#

General FAQs (Applies to All SDKs)

❓ “My API calls succeed, but responses don’t reflect newly added content”

❓ “The AI responds, but ignores what the user said previously”

❓ “Sometimes the AI answers without using floor content”

❓ “Is FloorMemory just RAG?”

Node.js / JavaScript SDK Issues

❓ “Running `npm install` doesn’t give me the latest SDK”

❓ “It works locally but fails in production”

TypeScript SDK Issues

❓ “Types don’t match the docs or the API behavior”

❓ “Optional fields or enums behave oddly”

Python SDK Issues

❓ “`pip install` doesn’t fetch a newer SDK”

❓ “Module not found / wrong version installed”

Java SDK Issues

❓ “Maven resolves an older SDK version”

❓ “401 / 403 when resolving the dependency”

❓ “The SDK builds, but feels awkward to use”

Common API-Level Pitfalls

❓ “I get `400 / XF_VALIDATION_ERROR` without much detail”

❓ “Conversation history feels noisy or irrelevant”

Blunt Advice (Worth Reading Once)

Before You Open a Support Ticket