Integration Guide
The practical Orbit contract for production apps. Keep this loop tight and your memory quality will climb instead of drift.
Credential note
If you run Orbit Cloud, create an API key in Dashboard and pass it as api_key. For self-hosted, use JWT.
Core integration contract
Every successful Orbit integration does these three things:
Ingest both sides of the conversation
Send user events and assistant responses. A memory engine with one eye closed is still half blind.
Use a stable entity_id
Keep entity_id consistent per user or owner scope across ingest and retrieve.
Send feedback continuously
Retrieval quality improves when Orbit receives positive and negative outcomes, not just events.
Minimal SDK flow
from orbit import MemoryEngine
engine = MemoryEngine(api_key="<jwt-token>", base_url="http://localhost:8000")
# 1) store user signal
engine.ingest(
content="I still do not understand Python for loops.",
event_type="user_question",
entity_id="alice",
)
# 2) retrieve context
results = engine.retrieve(
query="What should I know about alice before answering?",
entity_id="alice",
limit=5,
)
# 3) store outcome signal
if results.memories:
engine.feedback(
memory_id=results.memories[0].memory_id,
helpful=True,
outcome_value=1.0,
)Retrieval quality guidelines
Filter by entity_id whenever personalization matters.
Start with limit=5 and only increase when you have evidence.
Ingest assistant responses, not only user prompts.
Keep event types semantically consistent across services.
Use feedback for both good and bad outcomes.
When metadata.inference_provenance.clarification_required is true, ask a clarification question before using that memory in safety-sensitive responses.
Inspect inference provenance metadata during QA and incident review.