Getting Started

Installation & Setup Routes

Orbit supports two clear setup routes: Cloud (we host it) and Self-Hosted (you run it). Pick one path and follow the exact steps below.

Choose your route

Orbit Cloud (Hosted)

Fastest path. Orbit runs the API/runtime. You install the SDK and use your Orbit API key.

Best for: Teams that want production memory immediately without running infrastructure.

Self-Hosted Orbit

You run Orbit API + Postgres + metrics stack yourself via Docker and your own env config.

Best for: Teams that need local development control, private-network deployment, or custom infra policy.

Setup with AIReady-to-copy prompt

Tell the AI exactly what orbit.your stack looks like

Hit the floating AI helper or this block directly. Mention your route (Cloud vs Self-hosted), preferred adapter, and mention verified metadata (fact inference + contradiction guard). The assistant returns a complete snippet you can drop into your repo.

setup-prompt.txt

Prompt:
Build a Python Orbit integration (MemoryEngine) with the Ollama adapter.
Include ingest + retrieve calls for entity_id 'alice' and show how to tag conflict guards.
Document .env vars needed for Cloud or Local runtimes.

Need extra context? The metadata blueprint outlines every keyword and stack component that keeps your prompt sharp and SEO-ready.

Step 0 (Common): Install SDK

terminal

pip install orbit-memory

Optional extras for provider adapters:

pip install orbit-memory[anthropic]Anthropic adapter

pip install orbit-memory[gemini]Google Gemini adapter

pip install orbit-memory[ollama]Ollama adapter

pip install orbit-memory[llm-adapters]All adapters

Route A: Orbit Cloud (Hosted by Orbit)

1) Create/get your Orbit API key

From Orbit dashboard (/dashboard), create a project API key (for example: orbit_pk_...).

2) Add project env

.env

ORBIT_API_KEY=orbit_pk_your_key_here
ORBIT_BASE_URL=https://orbit-api-ic4qh4dzga-uc.a.run.app

3) Initialize SDK client

app.py

import os
from orbit import MemoryEngine

engine = MemoryEngine(
    api_key=os.getenv("ORBIT_API_KEY"),
    base_url=os.getenv("ORBIT_BASE_URL", "https://orbit-api-ic4qh4dzga-uc.a.run.app"),
)

4) Smoke test ingest + retrieve

smoke_test.py

engine.ingest(
    content="User likes quick vegetarian meals",
    event_type="preference_stated",
    entity_id="demo-user",
)

result = engine.retrieve(
    query="What should I remember for meal planning?",
    entity_id="demo-user",
    limit=5,
)
print(len(result.memories))

Route B: Self-Hosted Orbit (Local/Own Infra)

1) Clone and start the stack

terminal

git clone https://github.com/Intina47/orbit.git
cd orbit
docker compose up --build

2) Generate local JWT

terminal

python scripts/generate_jwt.py \
  --secret orbit-dev-secret-change-me \
  --issuer orbit \
  --audience orbit-api \
  --subject local-dev

3) Add project env

.env

ORBIT_JWT_TOKEN=<paste-generated-token>
ORBIT_API_BASE_URL=http://localhost:8000
ORBIT_JWT_ISSUER=orbit
ORBIT_JWT_AUDIENCE=orbit-api

4) Verify Orbit API is healthy

terminal

curl http://localhost:8000/v1/health
curl http://localhost:8000/v1/metrics

5) Initialize SDK client

app.py

import os
from orbit import MemoryEngine

engine = MemoryEngine(
    api_key=os.getenv("ORBIT_JWT_TOKEN"),
    base_url=os.getenv("ORBIT_API_BASE_URL", "http://localhost:8000"),
)

Usage paths afterwards

Orbit Cloud (API-first)

SDK talks directly to Orbit API; no infra for you to manage.
Use `ORBIT_API_KEY` from the dashboard, skip JWT wiring.
Great for pilot projects that scale from 0→100 users quickly.

Self-hosted + Local QA

Run Docker compose, connect SDK to `localhost:8000`.
Use generated JWT tokens for auth and keep data in your Postgres.
Perfect for offline demos or security-heavy environments.

Hybrid (ship data, keep keys local)

Ingest events via Orbit Cloud, host retrieval workers nearby.
Use metadata tags to route conflict-guarded facts to safer prompts.
Let Orbit learn personalization while you control audit logs.

Integration modes after setup

Python SDK

Python app, fastest integration

from orbit import MemoryEngine

REST API

Polyglot services or gateway architecture

POST /v1/ingest, GET /v1/retrieve, POST /v1/feedback

OpenClaw Plugin

OpenClaw agent runtime with plugin slots

integrations/openclaw-memory/

Setup validation checklist

SDK installed successfully (pip install orbit-memory).

You can initialize MemoryEngine with your chosen route credentials.

A test ingest call returns stored=True.

A test retrieve call returns memories without auth/network errors.

Feedback endpoint works for at least one memory_id.

Quickstart ->