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, recent messages, and relevant memories.

This article 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 durable 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 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.

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
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="YOUR DB CONNECT STRING",
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)

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,
    },
)

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 and the remaining result capacity can be filled by the normal all-memory-types search. The final relevant records are always capped by max_relevant_results.

Supported keys are "memory", "fact", "guideline", and "preference". Omit min_relevant_results_by_type to keep the default all-memory-types retrieval behavior.

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

Per-type retrieval can run one all-memory-types fill search plus one search for each requested record type. By default, up to five of these searches can run at the same time. To reduce backend fanout 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,
    },
)

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 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
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="YOUR DB CONNECT STRING",
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)

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,
    },
)

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,
    },
)