core.memory.memory

High-level facade combining an Embeddings backend with a TurnVectorStore.

Provides synchronous and asynchronous methods for indexing completed turns (Q+A pairs), semantic search, and re-embedding with a new model. The L4 integration layer wires this into FFAI via HistoryRecorder.

High-level facade combining an Embeddings backend with a TurnVectorStore.

Provides synchronous and asynchronous methods for indexing completed turns (Q+A pairs), semantic search, and re-embedding with a new model. The L4 integration layer wires this into FFAI via HistoryRecorder.

class Memory(embeddings, store=None)

Bases: object

Semantic recall over completed conversation turns.

Wraps an EmbeddingBackend and a TurnVectorStore. Provides two indexing entry points:

• index_turn() / aindex_turn() — extract text from a structured turn dict via turn["content"][0]["text"].

• index_turn_text() / aindex_turn_text() — embed an arbitrary caller-supplied string while still storing the structured turn dict alongside. Used by HistoryRecorder (L4) to embed the Q+A pair (f"{prompt}\n{response}") rather than just the response.

Parameters:

• embeddings (EmbeddingBackend) – Embedding backend (LiteLLM API model or local local/... model). Any object implementing EmbeddingBackend is accepted.

• store (TurnVectorStore | None) – Optional TurnVectorStore. Defaults to a fresh instance. Public and settable so callers can swap in a store loaded from Parquet (L3).

index_turn(turn, metadata=None)

Embed turn["content"][0]["text"] and store the turn.

Parameters:

• turn (dict[str, Any]) – Turn dict mirroring PermanentHistory shape. Must contain content[0]["text"].

• metadata (dict[str, Any] | None) – Optional caller metadata. Defaults to empty dict.

Returns:

The integer index of the stored entry.

Return type:

int

index_turn_text(text, turn, metadata=None)

Embed an arbitrary text and store the structured turn.

Use this when the embedded text differs from turn["content"][0]["text"] — e.g., when embedding the Q+A pair (f"{prompt}\n{response}") while still storing the response as the canonical turn content.

Parameters:

• text (str) – The plain text to embed.

• turn (dict[str, Any]) – The structured turn dict to store alongside.

• metadata (dict[str, Any] | None) – Optional caller metadata.

Returns:

The integer index of the stored entry.

Return type:

int

async aindex_turn(turn, metadata=None)

Async variant of index_turn().

Parameters:

• turn (dict[str, Any])

• metadata (dict[str, Any] | None)

Return type:

int

async aindex_turn_text(text, turn, metadata=None)

Async variant of index_turn_text().

Parameters:

• text (str)

• turn (dict[str, Any])

• metadata (dict[str, Any] | None)

Return type:

int

search(query, top_k=5, threshold=None)

Embed query and return ranked hits from the store.

Parameters:

• query (str) – Plain-text query.

• top_k (int) – Maximum hits to return.

• threshold (float | None) – Optional minimum cosine similarity.

Returns:

List of TurnHit sorted by score descending.

Return type:

list

async asearch(query, top_k=5, threshold=None)

Async variant of search().

Parameters:

• query (str)

• top_k (int)

• threshold (float | None)

Return type:

list

reindex(new_embeddings)

Re-embed all stored texts with a new embedding model.

Reads all entries via TurnVectorStore.iter_entries(), clears the store, and re-adds each entry with the new embedding. The turn dicts and metadata are preserved verbatim. After reindexing, self._embeddings is updated so subsequent search() calls embed queries with the new model.

Parameters:

new_embeddings (EmbeddingBackend) – The new embedding backend to use.

Return type:

None

count()

Number of turns currently indexed.

Return type:

int

clear()

Remove all indexed turns.

Return type:

None

Classes

class Memory(embeddings, store=None)

Bases: object

Semantic recall over completed conversation turns.

Wraps an EmbeddingBackend and a TurnVectorStore. Provides two indexing entry points:

• index_turn() / aindex_turn() — extract text from a structured turn dict via turn["content"][0]["text"].

• index_turn_text() / aindex_turn_text() — embed an arbitrary caller-supplied string while still storing the structured turn dict alongside. Used by HistoryRecorder (L4) to embed the Q+A pair (f"{prompt}\n{response}") rather than just the response.

Parameters:

• embeddings (EmbeddingBackend) – Embedding backend (LiteLLM API model or local local/... model). Any object implementing EmbeddingBackend is accepted.

• store (TurnVectorStore | None) – Optional TurnVectorStore. Defaults to a fresh instance. Public and settable so callers can swap in a store loaded from Parquet (L3).

index_turn(turn, metadata=None)

Embed turn["content"][0]["text"] and store the turn.

Parameters:

• turn (dict[str, Any]) – Turn dict mirroring PermanentHistory shape. Must contain content[0]["text"].

• metadata (dict[str, Any] | None) – Optional caller metadata. Defaults to empty dict.

Returns:

The integer index of the stored entry.

Return type:

int

index_turn_text(text, turn, metadata=None)

Embed an arbitrary text and store the structured turn.

Use this when the embedded text differs from turn["content"][0]["text"] — e.g., when embedding the Q+A pair (f"{prompt}\n{response}") while still storing the response as the canonical turn content.

Parameters:

• text (str) – The plain text to embed.

• turn (dict[str, Any]) – The structured turn dict to store alongside.

• metadata (dict[str, Any] | None) – Optional caller metadata.

Returns:

The integer index of the stored entry.

Return type:

int

async aindex_turn(turn, metadata=None)

Async variant of index_turn().

Parameters:

• turn (dict[str, Any])

• metadata (dict[str, Any] | None)

Return type:

int

async aindex_turn_text(text, turn, metadata=None)

Async variant of index_turn_text().

Parameters:

• text (str)

• turn (dict[str, Any])

• metadata (dict[str, Any] | None)

Return type:

int

search(query, top_k=5, threshold=None)

Embed query and return ranked hits from the store.

Parameters:

• query (str) – Plain-text query.

• top_k (int) – Maximum hits to return.

• threshold (float | None) – Optional minimum cosine similarity.

Returns:

List of TurnHit sorted by score descending.

Return type:

list

async asearch(query, top_k=5, threshold=None)

Async variant of search().

Parameters:

• query (str)

• top_k (int)

• threshold (float | None)

Return type:

list

reindex(new_embeddings)

Re-embed all stored texts with a new embedding model.

Reads all entries via TurnVectorStore.iter_entries(), clears the store, and re-adds each entry with the new embedding. The turn dicts and metadata are preserved verbatim. After reindexing, self._embeddings is updated so subsequent search() calls embed queries with the new model.

Parameters:

new_embeddings (EmbeddingBackend) – The new embedding backend to use.

Return type:

None

count()

Number of turns currently indexed.

Return type:

int

clear()

Remove all indexed turns.

Return type:

None