core.memory.turn_store

In-memory vector store for memory recall over PermanentHistory turns.

Stores (text, embedding, turn, metadata) tuples in parallel lists and provides cosine-similarity search. Designed for Tier 1 scale (<100K turns); Chroma/Qdrant backends are a future concern for larger workloads.

In-memory vector store for memory recall over PermanentHistory turns.

Stores (text, embedding, turn, metadata) tuples in parallel lists and provides cosine-similarity search. Designed for Tier 1 scale (<100K turns); Chroma/Qdrant backends are a future concern for larger workloads.

cosine_similarity(a, b)

Cosine similarity between two equal-length float vectors.

Thin wrapper around Embeddings.cosine_similarity() so that turn_store consumers don’t need to import the Embeddings class just to compute similarity. Returns 0.0 when either vector has zero magnitude.

Parameters:

• a (list[float]) – First vector.

• b (list[float]) – Second vector. Must be the same length as a.

Returns:

Cosine similarity in [-1.0, 1.0].

Return type:

float

class TurnVectorStore

Bases: object

Append-only in-memory store of embedded turns with cosine search.

Entries are stored in four parallel lists keyed by an integer index. add() returns the index of the appended entry; that index is preserved on the corresponding TurnHit returned by search().

Search is O(N) over all stored entries. Adequate for Tier 1 scale; a vector-index backend (Chroma/Qdrant) is a future concern.

add(text, embedding, turn, metadata=None)

Append an entry and return its integer index.

Parameters:

• text (str) – Plain text that was embedded.

• embedding (list[float]) – Float vector returned by the embedding backend.

• turn (dict[str, Any]) – Raw turn dict (mirrors PermanentHistory turn shape).

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

Returns:

The integer index of the newly appended entry.

Return type:

int

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

Return up to top_k turns ranked by cosine similarity.

Parameters:

• query_embedding (list[float]) – Embedded query vector.

• top_k (int) – Maximum hits to return.

• threshold (float | None) – Optional minimum cosine similarity. Hits below this score are excluded. None means no floor.

Returns:

Hits sorted by score descending. Empty list if the store is empty or all hits fall below threshold.

Return type:

list[TurnHit]

iter_entries()

Yield all entries as Entry tuples in insertion order.

Used by Memory.reindex() and persist_store() to read the store’s full contents without exposing the underlying lists.

Return type:

Iterator[Entry]

count()

Number of entries currently in the store.

Return type:

int

clear()

Remove all entries. Subsequent count() returns 0.

Return type:

None

Classes

class TurnVectorStore

Bases: object

Append-only in-memory store of embedded turns with cosine search.

Entries are stored in four parallel lists keyed by an integer index. add() returns the index of the appended entry; that index is preserved on the corresponding TurnHit returned by search().

Search is O(N) over all stored entries. Adequate for Tier 1 scale; a vector-index backend (Chroma/Qdrant) is a future concern.

add(text, embedding, turn, metadata=None)

Append an entry and return its integer index.

Parameters:

• text (str) – Plain text that was embedded.

• embedding (list[float]) – Float vector returned by the embedding backend.

• turn (dict[str, Any]) – Raw turn dict (mirrors PermanentHistory turn shape).

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

Returns:

The integer index of the newly appended entry.

Return type:

int

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

Return up to top_k turns ranked by cosine similarity.

Parameters:

• query_embedding (list[float]) – Embedded query vector.

• top_k (int) – Maximum hits to return.

• threshold (float | None) – Optional minimum cosine similarity. Hits below this score are excluded. None means no floor.

Returns:

Hits sorted by score descending. Empty list if the store is empty or all hits fall below threshold.

Return type:

list[TurnHit]

iter_entries()

Yield all entries as Entry tuples in insertion order.

Used by Memory.reindex() and persist_store() to read the store’s full contents without exposing the underlying lists.

Return type:

Iterator[Entry]

count()

Number of entries currently in the store.

Return type:

int

clear()

Remove all entries. Subsequent count() returns 0.

Return type:

None

Functions

cosine_similarity(a, b)

Cosine similarity between two equal-length float vectors.

Thin wrapper around Embeddings.cosine_similarity() so that turn_store consumers don’t need to import the Embeddings class just to compute similarity. Returns 0.0 when either vector has zero magnitude.

Parameters:

• a (list[float]) – First vector.

• b (list[float]) – Second vector. Must be the same length as a.

Returns:

Cosine similarity in [-1.0, 1.0].

Return type:

float