Emend
Getting Started

Local OSS Get Started

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

This path runs the open-source emend-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 Emend 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 Emend

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

pip install emend-aiuv add emend-ai

After installation, confirm the CLI is available:

emend --version

2. Configure an LLM Provider

Emend 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:

emend setup init

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

3. Start the Local Backend

Start the open-source backend:

emend services start

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

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

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

Check that the server is reachable:

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

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

4. Connect from Python

from emend import EmendClient client = EmendClient()  # reads EMEND_URLconfig = client.get_config() print(config)

You can also pass the URL directly:

from emend import EmendClient client = EmendClient(url_endpoint="http://localhost:8081")

5. Publish an Interaction

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

When your agent used Emend 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 Emend learning was injected.

Detailed API spec: publish_interaction.

from emend import InteractionData, EmendClient, UserActionType client = EmendClient() 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",)

What this interaction teaches Emend

  • 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

Emend 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 Emend 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 emend import EmendClient client = EmendClient() # 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.

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 emend import EmendClient client = EmendClient()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"""Emend context: Profiles:{profile_context or "- No profiles yet."} User playbooks:{playbook_context or "- No playbooks yet."}"""

8. Stop the Server

When you are done:

emend services stop

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

Next Steps

PreviousHosted Enterprise Get StartedNext Account Setup