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 following table, ID means any of user_id, agent_id, or thread_id together with its corresponding exact-match flag.

Search Scope Resolution by API Layer

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.

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

Results

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.

property content

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

property formatted_content

• Return Type: str

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

• Returns: XML-safe rendering that includes the default visible fields for a search result.
• Return type: str

property id

• Return Type: str | None
• Description: Return the stable identifier of the matched record, when available.

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 timestamp

• Return Type: str | None
• Description: Return the record timestamp, if available.