Search

This page presents the developer-facing scoping helpers together with the concrete Oracle search result type.

Scope Resolution

For each scope field, you can do one of three things:

• omit it to use the default of that API layer. In Python signatures and in SearchScope, this omitted state is represented by NOT_SET_MARKER.
• specify a concrete ID to use that value;
• specify None to mean the record is unscoped on that dimension. For example, agent_id=None means the record is not tied to one agent.

Each stored record has three independent scope fields: user_id, agent_id, and thread_id. Each field may hold a concrete ID or None.

Examples:

• thread_id=None means the record is not tied to one thread.
• agent_id=None means the record is not tied to one agent.
• user_id="u1", agent_id=None, thread_id=None means the record is scoped to user u1, but not to any specific agent or thread.

The same scoping rules apply to both synchronous and asynchronous search APIs.

In the table below, ID means any of user_id, agent_id, or thread_id together with its corresponding exact-match flag.

Search scope resolution by API layer

Case	thread.search()	OracleAgentMemory.search()	store.search()
ID omitted	Uses the thread defaults: exact user_id and agent_id, plus the current thread_id with exact_thread_match=False.	Uses the client defaults. Omitted user_id is rejected. Omitted agent_id and thread_id stay broad.	Uses the store defaults: ID=None and exact_*_match=False, so that dimension is not filtered.
Explicit value, including None + exact_*_match=False	That dimension is not filtered. Records whose value matches the specified one may rank higher than other records.	For user_id, rejected because client searches require explicit exact user scoping. For agent_id and thread_id, that dimension is not filtered. Records whose value matches the specified one may rank higher than other records.	That dimension is not filtered. Records whose value matches the specified one may rank higher than other records.
Explicit ID + exact_*_match=True	Matches that ID exactly.	Matches that ID exactly.	Matches that ID exactly.
Explicit None + exact_*_match=True	Matches only records unscoped on that dimension.	Matches only records unscoped on that dimension.	Matches only records unscoped on that dimension.

Use explicit None together with exact_*_match=True when you want only records unscoped on that dimension and the API permits it. Omit the field when you want the operation default instead.

Lifecycle-status filtering

All persisted records have a lifecycle status. Search accepts include_invalid_results on the store, client, and thread APIs. On client and thread APIs it defaults to NOT_SET_MARKER, which resolves to including valid and invalid records in search results. The lower-level store API resolves its Boolean default to the same behavior. Pass False to omit records whose status is RecordStatus.INVALID.

Graph expansion

Pass num_hops from 0 through 5 to the store, client, or thread search API to attach linked memory context to each direct memory result. Traversal follows relations in either direction, preserves the stored relation orientation, and returns a shortest-path tree through each record’s linked_results sequence. Direct message, document, and actor-profile matches remain in the ranked result set but are not graph-expanded. In particular, searchable image descriptions can return image records without making DOCUMENT a memory-link vertex. Scope, metadata, record-type, and expiration filters apply to every linked memory. include_invalid_results continues to control only top-level search matches; it does not change which linked memories are included. max_linked_results caps the total linked memories attached to each direct result across all hops. It defaults to 100; pass 0 to omit linked context.

Scopes

class oracleagentmemory.apis.scope.Scope

Bases: object

Represents a scope for information insertion or searches.

• Parameters:
  • user_id str | None
  • agent_id str | None
  • thread_id str | None

user_id

End-user ID. NOT_SET_MARKER means the field was omitted and should be resolved by the operation-specific default. Explicit None is preserved and interpreted by the operation-specific rules. Higher-level client APIs such as OracleAgentMemory.search() may require the user scope to be explicit. In those APIs, None may be used to target unscoped records only.

• Type: str | None

agent_id

Agent ID. NOT_SET_MARKER means the field was omitted and should be resolved by the operation-specific default. Explicit None is preserved and interpreted by the operation-specific rules.

• Type: str | None

thread_id

Thread ID. NOT_SET_MARKER means the field was omitted and should be resolved by the operation-specific default. Explicit None is preserved and interpreted by the operation-specific rules.

• Type: str | None

class oracleagentmemory.apis.searchscope.SearchScope

Bases: Scope

Represents the scope for a search query and therefore constrains what can be returned.

• Parameters:
  • user_id str | None
  • agent_id str | None
  • thread_id str | None
  • exact_user_match bool
  • exact_agent_match bool
  • exact_thread_match bool

user_id

End-user ID. When the resolved exact_user_match value is True, this ID is matched exactly, including None. When it is False, the user dimension is unconstrained. NOT_SET_MARKER is replaced by an operation-specific default. Higher-level client APIs such as OracleAgentMemory.search() may require the user scope to be explicit. In those APIs, None targets only unscoped records when exact_user_match resolves to True.

• Type: str | None

agent_id

Agent ID. When the resolved exact_agent_match value is True, this ID is matched exactly, including None. When it is False, the agent dimension is unconstrained. NOT_SET_MARKER is replaced by a default value depending on the operation using the scope.

• Type: str | None

thread_id

Thread ID. When the resolved exact_thread_match value is True, this ID is matched exactly, including None. When it is False, the thread dimension is unconstrained. NOT_SET_MARKER is replaced by a default value depending on the operation using the scope.

• Type: str | None

exact_user_match

Whether to match the resolved user_id exactly. True matches exactly, including None. False leaves the user dimension unconstrained. NOT_SET_MARKER is replaced by a default depending on the operation. Higher-level client APIs such as OracleAgentMemory.search() may require this to remain True.

• Type: bool

exact_agent_match

Whether to match the resolved agent_id exactly. True matches exactly, including None. False leaves the agent dimension unconstrained. NOT_SET_MARKER is replaced by a default depending on the operation.

• Type: bool

exact_thread_match

Whether to match the resolved thread_id exactly. True matches exactly, including None. False leaves the thread dimension unconstrained. NOT_SET_MARKER is replaced by a default depending on the operation.

• Type: bool

Search Configuration

class oracleagentmemory.core.MemorySearchConfig

Bases: ISearchConfig

Base configuration for memory post-search behavior.

• Parameters:
  • token_budget int | None
  • soft_token_budget int | None

Optional target size for formatted search output.

Complete results are kept in rank order through the first result that reaches or exceeds this budget. The first result is therefore retained when no hard token_budget prevents it from being returned.

Optional hard limit for the estimated size of formatted search output.

Complete results are kept in rank order while their cumulative estimate fits the budget. If the first result does not fit, no results are returned.

class oracleagentmemory.core.TopKMemorySearchConfig

Bases: _RerankingMemorySearchConfig

Search configuration with a fixed maximum of direct results.

• Parameters:
  • token_budget int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidates int
  • max_results int

Maximum number of direct results retrieved before reranking.

class oracleagentmemory.core.PruningEvaluationMode

Bases: str, Enum

Controls how extensively search results are evaluated during pruning.

EXHAUSTIVE = ‘exhaustive’

Evaluate every candidate result individually. This provides the most complete evaluation but has the highest latency and LLM usage.

EXTENDED = ‘extended’

Evaluate a broader portion of the results before deciding which ones to retain, at the cost of additional latency and LLM usage.

FAST = ‘fast’

Prioritize low latency by stopping evaluation early when further checks are unlikely to change which results are retained.

class oracleagentmemory.core.PruningMemorySearchConfig

Bases: _RerankingMemorySearchConfig

Search configuration that removes less relevant direct results.

Direct-result limits are supplied on each search or context-card call and applied before reranking and pruning.

• Parameters:
  • token_budget int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidates int
  • evaluation_mode PruningEvaluationMode
  • num_probe_points int
  • protected_fraction float
  • pruner ILlm

How extensively search results are evaluated during pruning.

When omitted, PruningEvaluationMode.FAST is used.

Number of ranked-result regions evaluated in FAST or EXTENDED mode.

This parameter cannot be set when evaluation_mode is PruningEvaluationMode.EXHAUSTIVE.

Fraction of highest-ranked direct results protected from pruning.

For example, 0.1 protects the top 10 percent of direct results.

LLM used to decide which direct results to remove.

Results

class oracleagentmemory.core.SearchResultFormatConfig

Bases: object

Control portable search-result rendering options.

Implementations can provide a subclass with additional rendering options.

• Parameters: include_invalid_results bool – Whether invalid linked records include their content. When False, invalid-only branches are omitted, while invalid records on a path to a valid record retain their status and link context. Omit to use True.

class oracleagentmemory.core.OracleSearchResultFormatConfig

Bases: SearchResultFormatConfig

Control Oracle search-result rendering options.

• Parameters:
  • show_thread_id bool – Whether to include the record’s thread identifier. Omit to use False.
  • show_distance bool – Whether to include estimated relevance. Omit to use False.
  • show_timestamp bool – Whether to include record timestamps. Omit to use True.
  • show_role bool – Whether to include message roles. Omit to use True.
  • show_user_id bool – Whether to include record user identifiers. Omit to use False.
  • show_agent_id bool – Whether to include record agent identifiers. Omit to use False.
  • show_status bool – Whether to include record lifecycle statuses. Omit to use True.
  • show_metadata bool – Whether to include caller metadata and the memory invalidation reason, when present. Each entry uses its metadata key as an XML tag and renders its value as a string. Omit to use False.
  • include_invalid_results bool

class oracleagentmemory.core.OracleSearchResult

Bases: SearchResult

Search result returned by an Oracle thread.

• Parameters:
  • distance float – Distance from the query vector (smaller is better).
  • record Record – A record object containing the metadata information about the persisted entry.
  • id str | None – Optional identifier associated with the stored record.
  • linked_results list tuple[[RecordRelation, SearchResult]] | None – Optional graph-linked child results. Each pair contains the stored RecordRelation and the result reached through it.
  • format_config SearchResultFormatConfig – Default rendering options used by formatted_content and by format_content() when no options are supplied.

property content

• Return Type: str
• Description: Return the primary textual content for the matched record.

method format_content

Render this result and its graph context as XML-safe prompt text.

• Parameters: format_config SearchResultFormatConfig – Rendering options for this call. Omit to use this result’s default configuration. In a supplied configuration, omitted options fall back to the corresponding options in that default configuration.
• Returns: XML-safe result rendering.
• Return type: str

property formatted_content

• Return Type: str

• Description: Return the default XML-safe rendering used in prompts.

• Returns: XML-safe rendering that uses this result’s default configuration.
• Return type: str

property id

• Return Type: str

  None

• Description: Return the stable identifier of the matched record, when available.

property linked_results

• Return Type: list[tuple[RecordRelation, SearchResult]]
• Description: Return linked results in their recursive shortest-path tree.

property metadata

• Return Type: dict[str, Any]

  None

• Description: Return record metadata, if available.

property record

• Return Type: Record
• Description: Return the matched record.

The returned value may be a plain Record or a ScopedRecord subclass. Use isinstance(result.record, ScopedRecord) before reading public scope identifiers.

property status

• Return Type: RecordStatus

  None

• Description: Return the lifecycle status for the matched record.

property timestamp

• Return Type: str

  None

• Description: Return the record timestamp, if available.