calute.memory.base

calute.memory.base#

Base memory classes for Calute memory system.

class calute.memory.base.Memory(storage: Any | None = None, max_items: int | None = None, enable_embeddings: bool = False)[source]#

Bases: ABC

Abstract base class for all Calute memory implementations.

Subclasses must implement save(), search(), retrieve(), update(), delete(), and clear(). The base class provides shared infrastructure: an ordered _items list, an _index mapping memory IDs to items, and the get_context() / get_statistics() convenience methods.

abstract clear() → None[source]#

Remove all memory items from this store.

abstract delete(memory_id: str | None = None, filters: dict[str, Any] | None = None) → int[source]#

Delete memory items by ID or filter criteria.

Parameters

  • memory_id – Specific memory UUID to delete.

  • filters – Optional key-value criteria for bulk deletion.

Returns

Number of items deleted.

get_context(limit: int = 10, format_type: str = 'text') → str[source]#

Get formatted context from memories.

Parameters

  • limit – Number of recent items to include

  • format_type – Format type (text, json, markdown)

Returns

Formatted context string

get_statistics() → dict[str, Any][source]#

Return aggregate statistics about stored memory items.

Returns

total_items, max_items, memory_types (counts per type), unique_agents, unique_users, and unique_conversations.

Return type

Dictionary with keys

abstract retrieve(memory_id: str | None = None, filters: dict[str, Any] | None = None, limit: int = 10) → calute.memory.base.MemoryItem | list[calute.memory.base.MemoryItem] | None[source]#

Retrieve specific memory items by ID or filter criteria.

Parameters

  • memory_id – Specific memory UUID to retrieve.

  • filters – Optional key-value criteria for bulk retrieval.

  • limit – Maximum number of items to return when using filters.

Returns

Single MemoryItem if memory_id is provided and found, list of MemoryItem when using filters, or None if not found.

abstract save(content: str, metadata: dict[str, Any] | None = None, **kwargs) → MemoryItem[source]#

Save a memory item.

Parameters

  • content – Text content to store.

  • metadata – Optional key-value metadata to attach.

  • **kwargs – Additional implementation-specific fields.

Returns

The newly created MemoryItem.

abstract search(query: str, limit: int = 10, filters: dict[str, Any] | None = None, **kwargs) → list[calute.memory.base.MemoryItem][source]#

Search for relevant memories matching a query.

Parameters

  • query – Natural-language or keyword query string.

  • limit – Maximum number of results to return.

  • filters – Optional key-value criteria to narrow results.

  • **kwargs – Additional implementation-specific parameters.

Returns

List of matching MemoryItem instances, ordered by relevance.

abstract update(memory_id: str, updates: dict[str, Any]) → bool[source]#

Update an existing memory item with new field values.

Parameters

  • memory_id – UUID of the memory item to update.

  • updates – Dictionary of attribute names and new values.

Returns

True if the update succeeded, False if the item was not found.

class calute.memory.base.MemoryItem(content: str, memory_type: str = 'general', timestamp: ~datetime.datetime = <factory>, metadata: dict[str, typing.Any] = <factory>, agent_id: str | None = None, task_id: str | None = None, conversation_id: str | None = None, user_id: str | None = None, relevance_score: float = 1.0, access_count: int = 0, last_accessed: datetime.datetime | None = None, embedding: list[float] | None = None, memory_id: str = <factory>)[source]#

Bases: object

Individual memory item with comprehensive metadata.

content#

The text content stored in this memory item.

Type

str

memory_type#

Category label for the memory (e.g., “general”, “short_term”).

Type

str

timestamp#

When the memory was created.

Type

datetime.datetime

metadata#

Arbitrary key-value data attached to this item.

Type

dict[str, Any]

agent_id#

Identifier of the agent that created this memory.

Type

str | None

task_id#

Identifier of the task associated with this memory.

Type

str | None

conversation_id#

Identifier of the conversation this memory belongs to.

Type

str | None

user_id#

Identifier of the user associated with this memory.

Type

str | None

relevance_score#

Search relevance score (0.0-1.0).

Type

float

access_count#

Number of times this item has been retrieved.

Type

int

last_accessed#

Timestamp of the most recent access.

Type

datetime.datetime | None

embedding#

Optional dense vector embedding for semantic search.

Type

list[float] | None

memory_id#

Unique UUID string for this memory item.

Type

str

access_count: int = 0#
agent_id: str | None = None#
content: str#
conversation_id: str | None = None#
embedding: list[float] | None = None#
classmethod from_dict(data: dict[str, Any]) → MemoryItem[source]#

Create a MemoryItem from a dictionary, converting ISO strings to datetimes.

Parameters

data – Dictionary as produced by to_dict().

Returns

A new MemoryItem populated from the supplied data.

last_accessed: datetime.datetime | None = None#
memory_id: str#
memory_type: str = 'general'#
metadata: dict[str, Any]#
relevance_score: float = 1.0#
task_id: str | None = None#
timestamp: datetime#
to_dict() → dict[str, Any][source]#

Convert this memory item to a JSON-serialisable dictionary.

Returns

Dictionary representation with all fields, converting datetimes to ISO 8601 strings.

user_id: str | None = None#
Contents