Skip to main content
Theo maintains conversation history so the model has context from previous turns. Pass a conversation_id to continue an existing conversation.

​
Starting a Conversation

The first request creates a new conversation automatically: 
const res = await theo.complete({
  prompt: "I'm building a SaaS for project management. Help me plan the tech stack.",
});

// Save the conversation ID for follow-ups
const conversationId = res.metadata?.conversation_id;

​
Continuing a Conversation

Pass the conversation_id to maintain context: 
const followUp = await theo.complete({
  prompt: "What database should I use for this?",
  conversation_id: conversationId,
});
// → Theo knows you're talking about a project management SaaS

​
Conversation API

​
List Conversations

curl https://www.hitheo.ai/api/v1/conversations \
  -H "Authorization: Bearer $THEO_API_KEY"

​
Get a Conversation

curl https://www.hitheo.ai/api/v1/conversations/{conversationId} \
  -H "Authorization: Bearer $THEO_API_KEY"
Returns the full message history with metadata.

​
How Theo Remembers

Beyond the verbatim turns in a single conversation, Theo runs a memory protocol (MCIR) that lets it carry relevant context across sessions — automatically, with no manual tagging.
  • Automatic capture. Facts, preferences, decisions, and unresolved questions are captured as they come up in normal conversation.
  • Relevance-first recall. Only memories relevant to your current request are surfaced — recall is scoped to what you’re asking, not a plain keyword match.
  • Per-owner scoping. Memory is isolated to the right owner (user, account, or organization). One tenant’s memory is never visible to another.
  • Freshness & decay. Stale or superseded memories lose weight over time and are revalidated before they influence a response, so old context doesn’t linger forever.
  • Durable user facts. Anything a user explicitly declares as a standing fact is preserved and exempt from decay.
  • Provenance. Every memory the model uses is traceable to where it came from.
You don’t call a separate API for this — it applies to every completion automatically. Pass conversation_id to keep turns linked within a thread; cross-thread recall happens on its own when prior context is relevant.

​
Proactive Recall & Open Loops

When you start a new conversation, Theo can proactively surface a short, relevant summary of prior related threads instead of starting cold. It also tracks open loops — unresolved questions or tasks — so a later follow-up can pick up where you left off.

​
Cross-Channel Memory

Theo’s memory is channel-agnostic. Whether a user interacts via the API, the web playground, a voice session, an embedded widget, or a channel adapter, Theo carries context across all of them. Continuity follows the user, not the surface.

​
Privacy

Theo does not train models on your memory. Memory is scoped per owner with tenant isolation, and user-declared facts can be marked durable. See Data Privacy for retention details.

​
Semantic Cache

Identical prompts (same text, same mode, same skills) hit the semantic cache and return instantly at zero cost. Cache hits are marked in the response metadata.