core.memory.types

Types for the memory vector recall feature.

Defines the result and storage shapes used by TurnVectorStore and the higher-level Memory facade (added in L2).

Types for the memory vector recall feature.

Defines the result and storage shapes used by TurnVectorStore and the higher-level Memory facade (added in L2).

class EmbeddingBackend(*args, **kwargs)[source]

Bases: Protocol

Duck-typed contract for an embedding backend used by Memory.

Embeddings satisfies this natively; tests can supply any object with matching embed and aembed signatures (e.g., FakeEmbeddings).

embed(texts)[source]

Compute embeddings for one or more texts (synchronous).

Parameters:: texts (list[str])
Return type:: list[list[float]]

async aembed(texts)[source]

Compute embeddings for one or more texts (asynchronous).

Parameters:: texts (list[str])
Return type:: list[list[float]]

class TurnHit(score, turn, turn_index, text, metadata)[source]

Bases: object

A single ranked result returned by TurnVectorStore.search.

Parameters:

score (float)
turn (dict[str, Any])
turn_index (int)
text (str)
metadata (dict[str, Any])

score

Cosine similarity in [-1.0, 1.0] between the query embedding and the stored turn’s embedding. Sorted descending by search().

Type:: float

turn

The raw turn dict stored at index time. Mirrors the PermanentHistory turn shape: {"role": str, "content": [{"type": "text", "text": str}], "timestamp": float, "metadata": dict}.

Type:: dict[str, Any]

turn_index

Position of the entry in TurnVectorStore at the time of the search. Stable within a single search() call for a given store; may shift after clear().

Type:: int

text

Pre-extracted plain text (typically the Q+A pair) that was embedded. Equal to the string passed to add(text=...).

Type:: str

metadata

Caller-provided metadata attached at index time. Always present (possibly empty dict). Tier 2 will populate user_id / session_id / agent_id here.

Type:: dict[str, Any]

score: float

turn: dict[str, Any]

turn_index: int

text: str

metadata: dict[str, Any]

class Entry(text, embedding, turn, metadata)[source]

Bases: NamedTuple

Storage tuple yielded by TurnVectorStore.iter_entries.

Fields mirror what was passed to add() at index time. Used by Memory.reindex() (L2) and persist_store() (L3) to read the store’s full contents without reaching into private state.

Parameters:

text (str)
embedding (list[float])
turn (dict[str, Any])
metadata (dict[str, Any])

text

The plain text that was embedded.

Type:: str

embedding

The float vector returned by the embedding backend.

Type:: list[float]

turn

The raw turn dict.

Type:: dict[str, Any]

metadata

The caller-provided metadata dict.

Type:: dict[str, Any]

text: str: Alias for field number 0

embedding: list[float]: Alias for field number 1

turn: dict[str, Any]: Alias for field number 2

metadata: dict[str, Any]: Alias for field number 3

Classes

class EmbeddingBackend(*args, **kwargs)[source]

Bases: Protocol

Duck-typed contract for an embedding backend used by Memory.

Embeddings satisfies this natively; tests can supply any object with matching embed and aembed signatures (e.g., FakeEmbeddings).

embed(texts)[source]

Compute embeddings for one or more texts (synchronous).

Parameters:: texts (list[str])
Return type:: list[list[float]]

async aembed(texts)[source]

Compute embeddings for one or more texts (asynchronous).

Parameters:: texts (list[str])
Return type:: list[list[float]]

class Entry(text, embedding, turn, metadata)[source]

Bases: NamedTuple

Storage tuple yielded by TurnVectorStore.iter_entries.

Fields mirror what was passed to add() at index time. Used by Memory.reindex() (L2) and persist_store() (L3) to read the store’s full contents without reaching into private state.

Parameters:

text (str)
embedding (list[float])
turn (dict[str, Any])
metadata (dict[str, Any])

text

The plain text that was embedded.

Type:: str

embedding

The float vector returned by the embedding backend.

Type:: list[float]

turn

The raw turn dict.

Type:: dict[str, Any]

metadata

The caller-provided metadata dict.

Type:: dict[str, Any]

text: str: Alias for field number 0

embedding: list[float]: Alias for field number 1

turn: dict[str, Any]: Alias for field number 2

metadata: dict[str, Any]: Alias for field number 3

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class TurnHit(score, turn, turn_index, text, metadata)[source]

Bases: object

A single ranked result returned by TurnVectorStore.search.

Parameters:

score (float)
turn (dict[str, Any])
turn_index (int)
text (str)
metadata (dict[str, Any])

score

Cosine similarity in [-1.0, 1.0] between the query embedding and the stored turn’s embedding. Sorted descending by search().

Type:: float

turn

The raw turn dict stored at index time. Mirrors the PermanentHistory turn shape: {"role": str, "content": [{"type": "text", "text": str}], "timestamp": float, "metadata": dict}.

Type:: dict[str, Any]

turn_index

Position of the entry in TurnVectorStore at the time of the search. Stable within a single search() call for a given store; may shift after clear().

Type:: int

text

Pre-extracted plain text (typically the Q+A pair) that was embedded. Equal to the string passed to add(text=...).

Type:: str

metadata

Caller-provided metadata attached at index time. Always present (possibly empty dict). Tier 2 will populate user_id / session_id / agent_id here.

Type:: dict[str, Any]

score: float

turn: dict[str, Any]

turn_index: int

text: str

metadata: dict[str, Any]