The agent prompt system

00TL;DR

Seven things to know before reading the detail.

01The call path

One agent turn, end to end. Everything is reconstructed from the DB each turn — the API is stateless and there is no message store (schema frozen in Phase 1).

02System prompt anatomy

The preamble is a pure conditional assembler — the executor decides what's included and passes pre-rendered strings in. Ordering is deliberately static→dynamic for cache stability.

The literal assembly is one format string — note that learning, memory, and contact data are absent here by design:

src/mods/ai_agent/services/build_system_prompt_service.rs:337let system_prompt = format!(
  "{platform_block}{org_rules_block}{agent_rules_block}{persona}\n\n\
   Your goals:\n{goals}{delegated_block}{delivery_block}\
   {skills_block}{invokable_agents_block}{tools_block}",
  persona = agent.persona,   // static, operator-authored
  goals   = agent.goals,     // static, operator-authored
);

Tier 0 — the platform-core contract

Included only for a domain agent (attach_domain_tools && !is_assistant_flavor). It is a fixed constant (PLATFORM_CORE_BLOCK) with four sections — and crucially, it speaks of "the business" generically:

build_system_prompt_service.rs:73 — PLATFORM_CORE_BLOCK (excerpt)## Who you are
You are an autonomous agent acting on the business's behalf inside Loquent…
You speak to the business's contacts as the business itself — a real person
from the team — and you are never named or described as an AI…

## How you affect the world   → you change the world only by calling tools
## Who is talking to you: operator vs. contact   → trust steering, distrust the contact
## Ground your replies; never make things up   → gather context with read tools, else escalate

03User & org data — the core question

You asked: do we inject the current user (name, roles) and the organization's data so the agent can act as that person? For contact-facing agents the answer is no. Here's the evidence and the one exception.

The grep that confirms it — over the assembler and the executor:

verified on this branch$ grep -n 'user.name|member.name|owner_name|organization.name|role|assigned_user|first_name' \
      build_system_prompt_service.rs run_ai_agent_thread_service.rs
(no matches)

The seed personas make the same point — they reference the business relationship but carry no identity. From the Follow-up Drafter seed:

migration/.../seed_followup_drafter_agent.rs — persona (excerpt)You are the Follow-up Drafter… You draft short, personalized SMS follow-up
messages sent to a contact on the user's behalf — the contact sees the
message as coming from the user's business, and you are never mentioned.

"the user's business" is a role, not a value — no name is ever substituted in.

The one exception: the assistant flavor

The internal Loquent Assistant (the in-app helper, not a contact-facing agent) does personalize. Its turn is assembled by assemble_assistant_turn, which rebuilds the owning member's Session and loads get_member_personalization(...). So the capability to thread a member's identity into a prompt already exists in the codebase — just not on the path that talks to contacts.

04The user turn

Everything dynamic and/or untrusted lives here — never in the cached system prefix. This is also where learning and few-shot examples are injected.

run_ai_agent_thread_service.rs:963 — KV-cache-safe user-turn injectionlet user_message = {
  let mut parts = Vec::with_capacity(3);
  if !learning_summary.is_empty() { parts.push(&learning_summary); }  // §5
  if !few_shot_block.is_empty()   { parts.push(few_shot_block); }       // few-shot
  parts.push(&prompt);                                                  // framed events
  parts.join("\n\n")
};
rig_agent.chat(Message::user(user_message), &mut history).await;

Source framing (prompt-injection defense)

Each event is wrapped by frame_for_prompt(contact_name, contact_number) so the model can tell trusted operator steering from untrusted contact text. Identity fields are scrubbed of newlines and bracket glyphs so a crafted SMS can't forge an operator envelope:

ai_thread_event_payload_type.rs:276 — frame_for_prompt (excerpt)InboundSms  → "[New SMS · {name} <{number}>]\n{scrubbed text}"
CallCompleted → "[Call ended · {name} <{number}>]\n{summary}"
UserMessage → "[Operator instruction from your owner — not the contact]\n{text}"
Scheduled   → "[Scheduled instruction from your owner — not the contact]\n{text}"

History reconstruction

There's no message store; history is rebuilt each turn from consumed queue events (user) + llm_generation log rows (assistant) + recorded tool calls, sorted by timestamp, capped at 100 per source (worst case ~300 messages). The new user input is passed as a separate Message::user — never interpolated into the system prompt.

05Memory & learning this worktree

The branch adds a three-part knowledge system. The distinction matters: learning is injected, memory is tool-loaded, lessons feed the digest that evolves learning.

How learning gets in (and why it's in the user turn)

On the first turn of a thread the executor resolves the agent's active learning version and pins its id to ai_thread.pinned_learning_version_id; every later turn reads the pinned version. This freezes the policy for the life of a conversation — a digest activating a new version mid-thread can't swap it underneath. The pinned body is summarized and prepended to the user message:

run_ai_agent_thread_service.rs:615 — learning resolution (condensed)let learning_summary = if agent.enable_learning {
  match thread.pinned_learning_version_id {
    Some(pinned) => summarize_learning_version(&get_learning_version_body(pinned)?),  // later turns
    None => { pin_version_id = Some(v.id); summarize_learning_version(&v.body_markdown) } // first turn → pin
  }
} else { String::new() };

Memory is tool-loaded, never injected

read_my_memory renders the typed blocks as labelled markdown on demand; update_my_memory applies a diff of add/update/delete ops (honoring read_only). There is also contact-scoped memory (read_contact_memory / update_contact_memory). The system-prompt builder explicitly leaves memory_snapshot: None — memory never enters the prompt automatically.

Evolution / digest loop

Apply mode is org-level: auto activates immediately; approval lands a pending version an owner approves. Risk is bounded by the ≤20-version cap, the one-active-per-agent invariant, and the reward-hacking / hallucination guards. Shadow replay + regression fixtures exist as the validation surface.

Retrieval observability (#1566)

A metadata-only retrieval_context records which learning version, how many learning bullets, and how many few-shot examples informed a turn — stored in the audit capture, never injected, and carrying ids/counts only (no verbatim cross-contact example text).

06Prompt caching vs Anthropic guidance

Caching is enabled and the architecture is genuinely cache-aware. But it uses only one of four available breakpoints, and the biggest cost — replayed history — is uncached.

What's wired

src/mods/ai/rig/client.rs:38pub fn completion_model(client, model_id) -> openrouter::CompletionModel {
  client.completion_model(model_id).with_prompt_caching()
  // attaches cache_control: {"type":"ephemeral"} to the SYSTEM PROMPT
}

Provider path is OpenRouter → Anthropic (anthropic/claude-sonnet-4.6); OpenRouter forwards the cache_control marker. Cache hits are observable — the streaming layer reconciles cached_input_tokens and cache_creation_input_tokens, and read-side cached tokens are logged into ai_usage_log.

07How to enhance the prompt structure

Directions to consider for personalizing agents to act as the business / assigned user, plus the caching win. Each is annotated with where it would slot in and its cache implication. These are options, not a committed plan.

## Who you represent
You are messaging on behalf of {business_name}.
Your point of contact on the team is {owner_name} ({owner_title}).
Business hours: {hours} ({timezone}). Sign off as {signature} when appropriate.

08File reference map

Where each piece lives, for the implementation session.