OSS

Open Source Get Started

Run open-source Reflexio locally, publish an interaction, and retrieve learned context from your own server.

Open Source Get Started

OSS This path is for the open-source reflexio-ai package running on your machine.

Before You Start

You need:

Python 3.12 or newer
One LLM provider API key for extraction, such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY
A terminal where you can keep the local Reflexio server running

The default open-source setup starts a FastAPI backend on http://localhost:8081, uses local SQLite storage, and runs without authentication.

1. Install Reflexio

Install the full open-source package. It includes the Python SDK, the reflexio CLI, and the local FastAPI server.

pippip install reflexio-ai

uvuv add reflexio-ai

After installation, confirm the CLI is available:

reflexio --version

2. Configure an LLM Provider

Reflexio uses an LLM to extract profiles and playbooks from published interactions. You can either export a key yourself:

export OPENAI_API_KEY="your-openai-key"

Or run the interactive setup wizard:

reflexio setup init

Choose Local SQLite when prompted for storage. The wizard writes settings to ~/.reflexio/.env.

3. Start the Local Backend

Start the open-source backend:

reflexio services start

In the default setup, the API listens on http://localhost:8081. Keep this command running while you use Reflexio.

In another terminal, point the SDK and CLI at your local server:

export REFLEXIO_URL="http://localhost:8081"

Check that the server is reachable:

curl -H "User-Agent: my-agent-reflexio" "http://localhost:8081/health"

No REFLEXIO_API_KEY is required for the default open-source server.

4. Connect from Python

from reflexio import ReflexioClient

client = ReflexioClient()  # reads REFLEXIO_URL
config = client.get_config()

print(config)

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

You can also pass the URL directly:

from reflexio import ReflexioClient

client = ReflexioClient(url_endpoint="http://localhost:8081")

Publish the full turn after your agent responds, including any user feedback. A single interaction drives both kinds of learning: durable facts about the user become profiles (memory), and corrective feedback becomes user playbooks (behavioral steering). In the example below, the user's stated role and travel routine ("a backend software engineer who travels for work most weeks") yield a profile, and their pushback on the bulky gaming laptop yields a playbook. Reflexio stores the interaction immediately; extraction runs asynchronously on your local server.

Detailed API spec: publish_interaction.

from reflexio import InteractionData, ReflexioClient, UserActionType

client = ReflexioClient()

client.publish_interaction(
    user_id="user_123",
    interactions=[
        InteractionData(
            role="User",
            content="I'm a backend software engineer and I travel for work most weeks. Can you recommend a laptop under $1,500?",
            user_action=UserActionType.NONE,
        ),
        InteractionData(
            role="Agent",
            content="Sure — here's a powerful gaming laptop with 32 GB RAM, just under $1,500.",
            user_action=UserActionType.NONE,
        ),
        InteractionData(
            role="User",
            content="That's far too bulky for constant travel — next time skip the gaming laptops and prioritize battery life and weight.",
            user_action=UserActionType.NONE,
        ),
    ],
    source="local-demo",
    session_id="session_001",
)

reflexio publish \
  --user-id user_123 \
  --source local-demo \
  --session-id session_001 \
  --data '{
    "interactions": [
      {"role": "User", "content": "I'\''m a backend software engineer and I travel for work most weeks. Can you recommend a laptop under $1,500?"},
      {"role": "Agent", "content": "Sure — here'\''s a powerful gaming laptop with 32 GB RAM, just under $1,500."},
      {"role": "User", "content": "That'\''s far too bulky for constant travel — next time skip the gaming laptops and prioritize battery life and weight."}
    ]
  }'

curl -X POST "http://localhost:8081/api/publish_interaction" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
    "user_id": "user_123",
    "interaction_data_list": [
      {
        "role": "User",
        "content": "I'm a backend software engineer and I travel for work most weeks. Can you recommend a laptop under $1,500?",
        "user_action": "none"
      },
      {
        "role": "Agent",
        "content": "Sure — here's a powerful gaming laptop with 32 GB RAM, just under $1,500.",
        "user_action": "none"
      },
      {
        "role": "User",
        "content": "That's far too bulky for constant travel — next time skip the gaming laptops and prioritize battery life and weight.",
        "user_action": "none"
      }
    ],
    "source": "local-demo",
    "session_id": "session_001"
  }
JSON

What this interaction teaches Reflexio

Profile (durable memory): "Backend software engineer who travels for work most weeks."
User playbook (behavioral steering): "When recommending a laptop for software development, avoid bulky gaming models — prioritize battery life and weight."

6. Trigger Extraction for This Example

Reflexio extracts automatically once a user accumulates a full sliding window of interactions — by default window_size is 10. This walkthrough published only a few, so automatic extraction has not fired yet. To see results right away, trigger extraction manually for this demo.

Demo only — don't do this in production

You normally never call these. In production you just keep publishing interactions, and Reflexio extracts on its own once each user reaches the window. The manual triggers below exist only so this short walkthrough produces a profile and a playbook immediately — don't wire them into your publish path.

Detailed API spec: manual_profile_generation, manual_playbook_generation.

from reflexio import ReflexioClient

client = ReflexioClient()

# Force extraction now so this short demo produces results immediately.
client.manual_profile_generation(user_id="user_123")
client.manual_playbook_generation()  # uses the same default agent version as publish

# Extraction runs asynchronously — give it a few seconds before searching.

reflexio api POST /api/manual_profile_generation --data '{"user_id": "user_123"}'
reflexio api POST /api/manual_playbook_generation --data '{}'

curl -X POST "http://localhost:8081/api/manual_profile_generation" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Content-Type: application/json" \
  --data '{"user_id": "user_123"}'

curl -X POST "http://localhost:8081/api/manual_playbook_generation" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Content-Type: application/json" \
  --data '{}'

7. Retrieve Context

Before the next response, search for learned context and add it to your agent prompt. One unified search returns the profile and playbook you just extracted.

Detailed API spec: search.

from reflexio import ReflexioClient

client = ReflexioClient()
user_id = "user_123"

context = client.search(
    query="laptop preferences and how to advise this user",
    user_id=user_id,
    top_k=5,
    entity_types=["profiles", "user_playbooks", "agent_playbooks"],
)

profile_context = "\n".join(f"- {profile.content}" for profile in context.profiles)
playbook_context = "\n".join(f"- {playbook.content}" for playbook in context.user_playbooks)

prompt_context = f"""Reflexio context:

Profiles:
{profile_context or "- No profiles yet."}

User playbooks:
{playbook_context or "- No playbooks yet."}
"""

reflexio context \
  --user-id user_123 \
  --agent-version agent-v0 \
  --query "laptop preferences and how to advise this user"

curl -X POST "http://localhost:8081/api/search" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
    "user_id": "user_123",
    "query": "laptop preferences and how to advise this user",
    "top_k": 5,
    "entity_types": ["profiles", "user_playbooks", "agent_playbooks"]
  }
JSON

8. Stop the Server

When you are done:

reflexio services stop

Or stop the foreground services start process with Ctrl-C.

Next Steps

CLI Reference - detailed self-hosted CLI commands, service lifecycle, env vars, diagnostics, and setup
Configuration - tune LLM, embedding, extractor, playbook, and evaluation settings
Publishing Interactions - publish richer interaction payloads
API Reference - Python SDK methods and schemas