Pipeline Presets

What are Pipeline Presets?

A pipeline preset is a named, reusable bundle of knobs that configure how Trix answers a memory request. One preset describes:

• Retrieval — strategy (hybrid / semantic / full-text), top_k, relevance threshold, reranking, query expansion.
• Generation — model allow-list, temperature, max tokens (chat routes only).
• Post-processing — answer format (conversational / extractive), citation behavior.
• Ingestion — per-stage gating for mega-summary, scoped-fact, session-summary, episode-fact.
• Graph / hierarchy / consolidation blocks for the endpoints that consume them.

Presets apply to 17 endpoints: /v1/chat, /v1/ai/chat, /v1/memories?q=, /v1/search, /v1/search/aggregate, the five /v1/graph/* routes, the three /v1/hierarchy/* routes, /v1/deep-recall, /v1/agent/consolidate, /v1/agent/conflicts/detect, and the two visual-search variants. Every route accepts the same pipeline=<name> parameter.

The 3-Tier Resolver (ADR-109a)

When a request reaches any pipeline-aware endpoint, the server runs the following resolver in order and stops at the first match:

1. Caller — explicit pipeline=<name> on the request.
2. Space — default stored on the target space (POST /v1/spaces/:id/default-pipeline/:name).
3. Account — default stored on the account (POST /v1/pipeline-presets/:name/set-default).
4. None — no preset applies; the server uses its built-in hybrid fallback.

Model Tiers & Routing

For chat and answer generation you can ask for a capability tier instead of pinning a specific model. Pass tier=<name> on /v1/chat and Trix resolves it to a concrete model:

• FASTEST — lowest latency
• CHEAPEST — lowest cost
• BALANCED — a sensible default across cost, speed, and quality
• POWER — a stronger model for harder reasoning
• BEST — the highest-quality model available

Each tier carries declarative price and latency bands and spans providers (OpenAI, Anthropic, Google, Mistral, xAI). Routing is provider-health-aware — a degraded endpoint is de-prioritized automatically. Omit the tier and the dynamic router picks the best-fitting tier for each message.

Managing Defaults (CLI)

Set an account-level default:

# Show, set, clear the account default
trix pipeline default show
trix pipeline default set longmem-v1
trix pipeline default clear

# Per-space defaults beat account defaults
trix spaces default set --space-id my-space --name personabench-v1
trix spaces default show --space-id my-space
trix spaces default clear --space-id my-space

The trix pipeline list command highlights the current account default with an inline "(account default)" badge.

Observability

Every pipeline-aware response includes two headers so callers can see which preset applied without a dry-run:

$ curl -I "https://api.trixdb.com/v1/search?q=hello" -H "Authorization: Bearer $TRIX_API_KEY"
HTTP/2 200
x-pipeline-name: longmem-v1
x-pipeline-source: account      # caller | space | account

For a dry run without firing a real search, use the _resolve endpoint (or the matching CLI / SDK helpers):

// TypeScript SDK — Agent.resolvePipeline
const r = await client.agent.resolvePipeline({ spaceId: 'my-space' });
console.log(r.name, r.source); // 'longmem-v1', 'space'

Creating a Preset

Presets are JSON documents validated against pipelineSchema. The minimum required fields are name, version, and retrieval:

{
  "name": "longmem-v1",
  "version": 1,
  "description": "High-recall retrieval tuned for long-memory workloads",
  "retrieval": {
    "strategy": "hybrid",
    "top_k": 40,
    "min_relevance_score": 0.15
  },
  "generation": {
    "temperature": 0.2,
    "max_tokens": 512
  },
  "post_processing": {
    "answer_format": "extractive"
  }
}

# Create from a JSON file
trix pipeline create --file=./longmem-v1.json

# Or from stdin
cat longmem-v1.json | trix pipeline create --stdin

# Manage
trix pipeline list
trix pipeline get longmem-v1
trix pipeline delete longmem-v1