Agents

An agent is a server-side configuration that decides how Truememory handles a chat request: which system prompt pipeline runs, which server-side tools are available, whether memory is read and written, and whether safety checks apply. You pick one per request with the X-Agent-Id header; if you never send the header, you get the general-purpose chatbot and can ignore this page entirely.

All requests require a Bearer token from Truememory Auth.

Selecting an Agent

Pass the X-Agent-Id header:

curl -X POST https://your-tie-host/v1/chat/completions \
  -H "X-Agent-Id: research-assistant" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"model": "anthropic/claude-sonnet-4-5", "messages": [{"role": "user", "content": "Hello"}]}'

If omitted, the default agent (chatbot) is used.

Available Agents

• Memory: shared — memories are accessible across all agents that use the shared pool.
• Memory: isolated — memories are scoped to that specific agent. See Memory for details.
• Safety: LlamaGuard — user inputs and agent outputs are checked against Meta’s Llama Guard content safety classifier before processing. Requests flagged as unsafe are rejected.

Memory scope is configured per agent — clients cannot override it. All agents support client-side tool calling via the tools parameter.

Onboarding Agent

A unified identity-collection agent that runs the same field set across all apps. Use it to collect a user’s identity fields through a natural one-question-at-a-time conversation, before the user has memory established. See the full guide at Platform → Onboarding.

What it collects (unified field set):

Apps can override the question text for any unified field and append their own app-specific questions — all via skill_instructions. An app with its own flow can also skip the unified fields it doesn’t list (include_unified_fields: false), add its own rules, and drop the final confirmation turn (confirm_before_complete: false) — see Asking only your own questions.

skill_instructions format (JSON):

{
  "acknowledge_source_app": true,
  "questions": [
    { "id": "preferred_name", "question": "What should we call you?" },
    { "id": "location", "question": "Where in the world are you based?" },
    { "id": "currentFocus", "question": "What are you focused on right now?" }
  ],
  "already_captured": {
    "preferred_name": "Julio"
  }
}

Merge rules: Truememory always collects all unified fields — apps cannot drop them. Apps control question wording and order. App-specific questions always appear after unified fields.

Observable events (in SSE stream):

The onboarding agent emits four observable tool calls through OpenAI-compatible streaming chunks (same shape as any chat-completions tool call):

After each field is answered — appears inside a delta.tool_calls chunk:

{"choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_abc","type":"function","function":{"name":"capture_field","arguments":"{\"field_id\":\"location\",\"value\":\"Asia/Kuala_Lumpur\"}"}}]}}]}

When the user explicitly opts out of an optional question — store as an opt-out signal:

{"choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_skp","type":"function","function":{"name":"skip_field","arguments":"{\"field_id\":\"currentFocus\",\"reason\":\"privacy\"}"}}]}}]}

When all fields are collected — terminal success event:

{"choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_xyz","type":"function","function":{"name":"onboarding_complete","arguments":"{\"fields\":{\"preferred_name\":\"Julio\",\"date_of_birth\":\"1995-05-23\",\"location\":\"Kuala Lumpur\"}}"}}]}}]}

User stopped early OR safety cap fired — terminal partial event:

{"choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_abr","type":"function","function":{"name":"onboarding_aborted","arguments":"{\"fields\":{\"preferred_name\":\"Julio\"},\"reason\":\"user_stopped\"}"}}]}}]}

• capture_field — per-field progress event for live UI feedback (checkmarks, progress dots). Values may still be corrected by the user, so don’t persist on this event.
• skip_field — fires when the user opts out of an optional question. The field will be absent from the final onboarding_complete payload. Persist as an opt-out flag if you need to remember the user’s choice.
• onboarding_complete — terminal success event. Only persist on this event.
• onboarding_aborted — terminal partial event (user opted out, malformed config, or 20-turn safety cap). Treat as partial data; route to a fallback rather than auto-persisting. Inspect reason to distinguish — "max_turns_exceeded (...)" indicates the safety cap fired.

After onboarding_complete, your app shows the user a confirmation screen. On confirm, write to auth metadata — split by ownership:

• Unified fields (preferred_name, date_of_birth, location) → PATCH /auth/me (with metadata field)
• App-specific fields (anything else) → PATCH /auth/me/app-metadata?app=your_app

Both endpoints take the user’s Truememory Bearer token — the same Authorization: Bearer $TOKEN you use for chat completions. See Platform → Onboarding for the full payload shapes.

Example request:

curl -X POST https://your-tie-host/v1/chat/completions \
  -H "X-Agent-Id: onboarding" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hi"}],
    "stream": true,
    "persona_id": "your-companion-persona-id",
    "skill_instructions": "{\"questions\": [{\"id\": \"location\", \"question\": \"Where in the world are you?\"}], \"already_captured\": {}}"
  }'

The onboarding agent has no memory — it runs before the user’s memory graph is established. Confirmed field values should be written by your app backend to auth metadata after the user confirms on the confirmation screen.

Eliza (Wellness Coach)

App-specific agent for the Vibrantly app: evidence-based nutrition guidance with meal and supplement logging via client-side tools (your app defines them in tools and executes the returned tool_calls — see Tool calling). Other apps should not select this agent; its behavior is owned by Vibrantly.

Message Compression

Moved — compression is a per-request chat feature, not an agent concern. See Message compression.

Query GET /info to see all agents on your instance:

{
  "agents": [
    {
      "key": "chatbot",
      "description": "A simple chatbot.",
      "memory_enabled": true,
      "memory_scope": "shared"
    },
    {
      "key": "eliza",
      "description": "An AI wellness coach for the Vibrantly app — nutrition guidance, meal logging, and supplement tracking.",
      "memory_enabled": true,
      "memory_scope": "shared"
    },
    {
      "key": "research-assistant",
      "description": "A research assistant with web search and calculator.",
      "memory_enabled": true,
      "memory_scope": "shared"
    }
  ],
  "default_agent": "chatbot"
}