> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations & Memory

> Multi-turn conversations with cross-session memory.

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:

```typescript theme={null}
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:

```typescript theme={null}
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

```bash theme={null}
curl https://www.hitheo.ai/api/v1/conversations \
  -H "Authorization: Bearer $THEO_API_KEY"
```

### Get a Conversation

```bash theme={null}
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](/security/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.