Context and memory

A context in the Agentic Framework makes use of memory from previous text and data in the conversation so far. Think of it as a thread that maintains conversation history. Understanding how context works is essential for building effective integrations that maintain continuity across multiple messages.

Diagram showing context and memory flow in the Agentic Framework

What is a context

A context (identified by a server-generated contextId) is a logical grouping of related messages, tasks, and artifacts, providing context across a multi-turn conversation. It enables you to associate multiple tasks with a single patient encounter, call, or workflow, ensuring continuity and proper scoping of shared knowledge. The contextId is always created on the server. You never generate it client-side. This ensures proper state management and prevents conflicts. In v2, contexts are first-class resources with their own API endpoints. You can inspect and delete contexts independently of agents. Contexts are created implicitly when you send a message; there is no create or update endpoint.

Context listing (GET /v2/agentic/contexts) is in private preview — use GET /v2/agentic/contexts/{contextId} to retrieve a specific context.

Context API endpoints

Operation	Method and path
List contexts	`GET /v2/agentic/contexts`
Get a context	`GET /v2/agentic/contexts/{contextId}`
Delete a context	`DELETE /v2/agentic/contexts/{contextId}`
Export traces	`GET /v2/agentic/contexts/{contextId}/trace`
List tasks in a context	`GET /v2/agentic/contexts/{contextId}/tasks`
Get a task in a context	`GET /v2/agentic/contexts/{contextId}/tasks/{taskId}`

Listing contexts

The GET /v2/agentic/contexts listing endpoint is in private preview — it returns an empty list. Use GET /v2/agentic/contexts/{contextId} to retrieve a specific context.

GET /v2/agentic/contexts returns a paginated list of contexts. You can filter by:

agentId: Restrict to contexts owned by a specific agent
from: Inclusive lower bound on createdAt (RFC 3339)
to: Exclusive upper bound on createdAt (RFC 3339)

Getting a context

GET /v2/agentic/contexts/{contextId} returns the context’s metadata together with its tasks, oldest first. Each task carries its full message history; the user’s prompt for a task is the ROLE_USER message within that task’s history. Use the historyLength query parameter to cap the number of history messages returned per task.

Deleting a context

DELETE /v2/agentic/contexts/{contextId} deletes the context and its associated data. This is irreversible. See Work with contexts for a detailed guide.

Data isolation and scoping

Contexts provide strict data isolation. Data can never leak across contexts. Each contextId creates a completely isolated conversation scope. Messages, tasks, artifacts, and any data within one context are completely inaccessible to agents working in a different context. This ensures:

Privacy and security: Patient data from one encounter cannot accidentally be exposed to another encounter
Data integrity: Information from different workflows remains properly separated
Compliance: You can confidently scope sensitive data to specific contexts without risk of cross-contamination

When you need to share information across contexts, you must explicitly pass it via data parts in your messages. There is no automatic data sharing between contexts.

Using context for automatic memory management

The simplest way to use context is to let the framework automatically manage conversation memory:

First message: Send your message without a contextId. The server creates a new context automatically.
Response: The server’s response includes the newly created contextId in the task or message object.
Subsequent messages: Include that contextId in your requests. Memory from previous messages in that context is automatically managed and available to the agent.

When you include a contextId in your request, the agent has access to all previous messages, artifacts, and state within that specific context only. Data from other contexts is completely isolated and inaccessible.

Standalone requests

If you don’t want automatic memory management, always send messages without a contextId. Each message is treated as a standalone request without access to prior conversation history. This is useful for one-off queries, testing, and scenarios where you want explicit control over what context is included.

Passing additional context with each request

In addition to automatic memory management via contextId, you can pass additional context in each request by including data parts in your message. This is useful when you want to provide specific structured data, summaries, or other context that should be considered for that particular request.

Example: Passing additional context as a data part

{
  "message": {
    "role": "ROLE_USER",
    "parts": [
      {
        "text": "Generate a summary of this patient encounter"
      },
      {
        "data": {
          "patientId": "pat_12345",
          "encounterDate": "2026-05-19",
          "chiefComplaint": "Chest pain",
          "vitalSigns": {
            "bloodPressure": "120/80",
            "heartRate": 72,
            "temperature": 98.6
          }
        }
      }
    ]
  }
}

This approach allows you to:

Provide structured data (patient records, clinical facts, etc.) alongside text
Include summaries or distilled information from external sources
Pass metadata or configuration that should be considered for this specific request
Combine automatic memory (via contextId) with explicit context (via data parts)

How memory works

The Agentic Framework uses an intelligent memory system that automatically indexes content within a context. Semantic retrieval requires a memory connector to be attached to the agent.

Automatic semantic retrieval (just-in-time prompt injection) is in private preview. The framework automatically indexes all text and data parts, but retrieval requires a memory connector and an explicit search_memory tool call by the LLM — it is not injected automatically.

Automatic indexing

Every text part and data part you send in messages is automatically indexed and stored in the context’s memory. This includes text content from user and agent messages, structured data from data part objects, artifacts generated by tasks, and any other content that flows through the context.

Semantic retrieval

The memory system operates like a RAG (Retrieval Augmented Generation) pipeline. When a memory connector is attached to the agent and the agent decides to call the search_memory tool:

Semantic search: The tool performs semantic search across all indexed content in the context’s memory
Relevant retrieval: It retrieves the most semantically relevant information based on the current query or task
Agent integration: The retrieved content is returned to the LLM as tool output, making it available for reasoning

The agent must choose to call the search_memory tool; the framework does not automatically inject retrieved context into prompts.

Context vs. reference task IDs

The framework provides two mechanisms for linking related work:

contextId: Groups multiple related messages, tasks, and artifacts together. This provides automatic memory management and is sufficient for most use cases.
referenceTaskIds: An optional list of specific past task IDs within the same context that should be treated as explicit inputs or background. These are scoped to a context; they reference tasks within the same contextId.

In most situations, you can ignore referenceTaskIds since the automatic memory provided by contextId is sufficient. Use referenceTaskIds only when you need to explicitly direct the agent to pay attention to specific tasks or artifacts within the context.

Context TTL and expiration

The expiresAt field is in private preview — not yet persisted by the server. Contexts persist until explicitly deleted.

Contexts can have an expiration time (expiresAt). When a context expires, it is automatically cleaned up. A null expiresAt means the context does not expire.

Ephemeral agents (with lifecycle: "ephemeral") may have shorter context TTLs. Persistent agents (with lifecycle: "persistent") typically have longer-lived contexts. Check the expiresAt field on context responses to understand the lifetime of a specific context.

Trace export

You can export OpenInference-format traces for a context to inspect the agent’s reasoning, connector calls, and tool usage:

GET /v2/agentic/contexts/{contextId}/trace

Traces contain spans for LLM calls, connector invocations, and tool usage, with attributes like llm.token_count.total, tool.name, and input.value. This is useful for debugging, performance analysis, and compliance auditing. See Export traces for a detailed guide.

Context and interaction IDs

If you are using contexts alongside Corti’s internal interaction representation (for example, when integrating with other Corti products that use interactionId), note that these two concepts are currently not linked:

contextId (from the Agentic Framework) and interactionId (from Corti’s internal systems) are separate concepts that you need to map yourself in your application
There is no automatic association between a Corti interactionId and an Agentic Framework contextId

Recommended approach: Use a fresh context per interaction. Store the mapping between your interactionId and contextId(s) in your own application state. If you need to share data across multiple contexts within the same interaction, explicitly pass it via data part objects.

Next steps

Learn how to work with contexts via the API
Read about exporting traces for observability
Understand core concepts for the full vocabulary

Quickstart

Concepts

Guides

Reference

Registry Connectors

Agent SDK

v1 Documentation (archived)

What is a context

Context API endpoints

Listing contexts

Getting a context

Deleting a context

Data isolation and scoping

Using context for automatic memory management

Standalone requests

Passing additional context with each request

How memory works

Automatic indexing

Semantic retrieval

Context vs. reference task IDs

Context TTL and expiration

Trace export

Context and interaction IDs

Next steps

​What is a context

​Context API endpoints

​Listing contexts

​Getting a context

​Deleting a context

​Data isolation and scoping

​Using context for automatic memory management

​Standalone requests

​Passing additional context with each request

​How memory works

​Automatic indexing

​Semantic retrieval

​Context vs. reference task IDs

​Context TTL and expiration

​Trace export

​Context and interaction IDs

​Next steps

What is a context

Context API endpoints

Listing contexts

Getting a context

Deleting a context

Data isolation and scoping

Using context for automatic memory management

Standalone requests

Passing additional context with each request

How memory works

Automatic indexing

Semantic retrieval

Context vs. reference task IDs

Context TTL and expiration

Trace export

Context and interaction IDs

Next steps