Customize Context Card Content

A context card provides compact context about a conversation that an agent can use when generating a response. It can include a conversation thread summary, relevant stored messages, and relevant memories.

This guide explains how to customize the content returned in Oracle AI Agent Memory context cards.

Context cards returned by get_context_card() can also include retrieval topics and relevant records. Use context cards when an agent needs continuity across a long conversation but does not need the full transcript sent back to the model. This can reduce input token usage, keep the agent focused, and reduce the need for some agent-level tool calls by placing relevant memory in the prompt context up front.

For a full prompt-compaction workflow with LangGraph, see Use Oracle Agent Memory Short-Term APIs with LangGraph. For API details, see OracleThread and Context Cards.

Note: Use context-card customization when the default retrieval results do not include the right mix of record types. For example, an application can reserve space for user preferences or response guidelines when general facts would otherwise dominate the results.

To configure result limits, reranking, pruning, or token budgets for both searches and context cards, see Improve Search Result Relevance.

Request Minimum Results by Record Type

By default, context-card retrieval searches across all memory-like record types at once. For example, if facts or general memories crowd out preferences or guidelines, pass min_relevant_results_by_type to ask for minimum counts for specific record types.

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="provider/model_id")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_CARD_CONTENT"

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id
)

thread = memory.create_thread(
    thread_id="context_card_customization_demo",
    user_id="user_123",
    agent_id="assistant_456",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Extract restaurant preferences as preference records and assistant "
            "response-style instructions as guideline records."
        )
    ),
)
thread.add_messages(
    [
        {
            "role": "user",
            "content": "I need vegetarian dinner recommendations for Friday.",
        },
        {
            "role": "assistant",
            "content": "I can compare concise options and tradeoffs.",
        },
    ]
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)

prompt_context = card.content
print(prompt_context)

The rendered card is XML-like prompt text. The exact records depend on your stored data, but the <relevant_information> section can include the requested types before the remaining results from the all-memory-types search:

<context_card>
  <summary>
    User is planning dinner recommendations.
  </summary>
  <topics>
    <topic>pizza planning</topic>
    <topic>dinner</topic>
  </topics>
  <relevant_information>
    <preference>
      <content>User prefers vegetarian restaurants.</content>
    </preference>
    <guideline>
      <content>Offer concise recommendations with clear tradeoffs.</content>
    </guideline>
    <memory>
      <content>User is comparing pizza places for Friday.</content>
    </memory>
  </relevant_information>
  <recent_messages>
    ...
  </recent_messages>
</context_card>

The minimums are best effort. If there are not enough matching records for a requested type, the call still succeeds. Matches from any supported memory-like record type can use the result slots that remain. The final relevant records are always capped by max_relevant_results.

Supported keys are "memory", "fact", "guideline", "preference", and "message". Message results are searched only in the current thread; the other record types retain the normal user/agent search scope. Omit min_relevant_results_by_type to keep the default retrieval behavior.

When building a context card, Oracle Agent Memory searches memory-like records separately from messages in the current thread. When reranking or pruning is configured, it is applied separately to each set of results before the sets are combined. When min_relevant_results_by_type is provided, each requested record type is searched separately. Reranking or pruning, when configured, is also applied separately to the results of each search. Another search across all memory-like record types can then use any result slots that remain.

By comparison, if reranking or pruning is configured for a regular search that requests multiple record_types, it is applied once to the combined search results.

When max_relevant_results is omitted, Oracle Agent Memory uses the default relevant-results budget unless the requested minimum total is larger. In that case, the effective budget expands to fit the requested minimum total.

Tune Type Search Concurrency

Building a context card can run one search for each requested record type, plus one search across all memory-like record types to use any result slots that remain. By default, up to five of these searches can run at the same time. To reduce the number of simultaneous searches for a live thread handle, pass context_card_type_search_concurrency when creating or reopening the thread. This value is not persisted with the thread row:

thread = memory.get_thread(
    "context_card_customization_demo",
    context_card_type_search_concurrency=2,
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)

Conclusion

In this guide we learned how to request minimum context-card result counts for specific memory-like record types and how to tune the parallel search fanout used by per-type retrieval.

→ Having learned how to customize context-card retrieval, you may now proceed to Use Oracle Agent Memory Short-Term APIs with LangGraph.

Full Code

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Customize Context Card Content
#-----------------------------------------------------------------

##Reserve relevant results by record type

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="provider/model_id")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_CARD_CONTENT"

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id
)

thread = memory.create_thread(
    thread_id="context_card_customization_demo",
    user_id="user_123",
    agent_id="assistant_456",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Extract restaurant preferences as preference records and assistant "
            "response-style instructions as guideline records."
        )
    ),
)
thread.add_messages(
    [
        {
            "role": "user",
            "content": "I need vegetarian dinner recommendations for Friday.",
        },
        {
            "role": "assistant",
            "content": "I can compare concise options and tradeoffs.",
        },
    ]
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)

prompt_context = card.content
print(prompt_context)

##Tune type search concurrency

thread = memory.get_thread(
    "context_card_customization_demo",
    context_card_type_search_concurrency=2,
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)