Get Started

Local OSS

Run Reflexio locally, publish an interaction, and retrieve learned context.

Local OSS This path runs the open-source reflexio-ai package on your machine.

Prefer to automate this?

Give your coding agent this prompt while it is working in your application’s repository:

text

Follow this skill to integrate Reflexio into my agent:
https://github.com/ReflexioAI/reflexio/blob/main/skills/integrate-reflexio/SKILL.md
Use the Local OSS setup on my own 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.

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:

Terminal

reflexio --version

Configure an LLM Provider

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

Terminal

export OPENAI_API_KEY="your-openai-key"

Or run the interactive setup wizard:

Terminal

reflexio setup init

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

Start the Local Backend

Start the open-source backend:

Terminal

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:

Terminal

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

Check that the server is reachable:

Terminal

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

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

Connect from Python

Python

from reflexio import ReflexioClient

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

print(config)

The Python client uses url_endpoint, then REFLEXIO_URL, then the managed-cloud URL. IS_TEST_ENV does not select a local endpoint. If it is active or unrecognized and no explicit nonblank endpoint is supplied, client construction fails before opening a transport; set the local URL explicitly when upgrading old test setups.

Terminal

curl -X GET "${REFLEXIO_URL:-http://localhost:8081}/api/get_config" \
	  -H "User-Agent: my-agent-reflexio"

You can also pass the URL directly:

Python

from reflexio import ReflexioClient

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

Publish an Interaction

Publish the full turn after your agent responds, including user feedback. Reflexio stores the interaction immediately and runs extraction asynchronously.

When your agent used Reflexio context for a response, include every injected learning in that response's retrieved_learnings. For evaluated sessions, this unlocks detailed per-learning relevance and impact analysis and provides attribution data for future retrieved-learning optimization. The example IDs below represent learnings retrieved before this turn; omit the field only when no Reflexio learning was injected.

Detailed API spec: publish_interaction.

Python

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,
            retrieved_learnings=[
                {"kind": "profile", "learning_id": "prof-abc123"},
                {"kind": "user_playbook", "learning_id": "42"},
            ],
        ),
        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",
)

Terminal

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.",
        "retrieved_learnings": [
          {"kind": "profile", "learning_id": "prof-abc123"},
          {"kind": "user_playbook", "learning_id": "42"}
        ]
      },
      {"role": "User", "content": "That'\''s far too bulky for constant travel — next time skip the gaming laptops and prioritize battery life and weight."}
    ]
  }'

Terminal

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",
        "retrieved_learnings": [
          {"kind": "profile", "learning_id": "prof-abc123"},
          {"kind": "user_playbook", "learning_id": "42"}
        ]
      },
      {
        "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."

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 quickstart 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.

Python

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.

Terminal

reflexio user-profiles regenerate --user-id user_123 --wait
reflexio user-playbooks regenerate --agent-version agent-v0 --wait

Terminal

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 '{}'

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.

Python

from reflexio import ReflexioClient

client = ReflexioClient()
user_id = "user_123"
session_id = "session_001"

context = client.search(
    query="laptop preferences and how to advise this user",
    user_id=user_id,
    session_id=session_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."}
"""

Terminal

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

Terminal

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",
    "session_id": "session_001",
    "query": "laptop preferences and how to advise this user",
    "top_k": 5,
    "entity_types": ["profiles", "user_playbooks", "agent_playbooks"]
  }
JSON

Stop the Server

When you are done:

Terminal

reflexio services stop

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

Next Steps

CLI Reference - detailed Local OSS commands, service lifecycle, environment variables, 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

Publishing Interactions

Working with User Profiles

Collecting and Using Playbooks

API Reference