ReflexioDeveloper Docs
Hosted Enterprise startGitHubWebsite
Menu
GitHubWebsitellms.txt
Local OSS

Local OSS Get Started

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

Local OSS Get Started

Local OSS This path runs the open-source reflexio-ai package 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:-http://localhost:8081}/api/get_config" \
	  -H "User-Agent: my-agent-reflexio"

You can also pass the URL directly:

from reflexio import ReflexioClient

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

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

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",
)
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."}
    ]
  }'
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."

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

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 user-profiles regenerate --user-id user_123 --wait
reflexio user-playbooks regenerate --agent-version agent-v0 --wait
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