The Aletheia Proxy

Overview

The Aletheia Proxy (Memory Router) acts as a middleware between your application and your LLM provider. It intercepts standard OpenAI-style chat completion requests, retrieves the most relevant memories for the specified user, and injects them into the system prompt before forwarding the request to the upstream model.

This allows you to add Aletheia's persistent memory to any existing agent or application by simply changing the `base_url`.

How it works

1. Your app sends a request to `/v1/chat/completions` on the Aletheia engine.
2. Aletheia extracts the `user` field from the payload to identify the `entity_id`.
3. It performs a high-precision semantic lookup based on the latest user message.
4. The system prompt is augmented with a structured `[ALETHEIA PERSISTENT MEMORY]` block.
5. The augmented request is forwarded to OpenAI (or your configured provider).
6. The final response is returned to your application.

Usage Example

To use the proxy, simply point your OpenAI client to your Aletheia instance. The `user` parameter is mapped to Aletheia's `entity_id`.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3000/v1",
    api_key="YOUR_ALETHEIA_API_KEY"
)

# Aletheia will automatically retrieve memories for 'user-42'
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What was the name of that coffee I liked?"}],
    user="user-42" 
)

Configuration

The proxy behavior can be tuned using the following environment variables on the Aletheia engine:

• OPENAI_API_KEY: Your upstream provider key.
• ALETHEIA_PROXY_TARGET_URL: The upstream endpoint (defaults to OpenAI).
• ALETHEIA_PORT: The local port Aletheia is running on (for loopback lookups).