calute.memory.entity_memory

calute.memory.entity_memory#

Entity memory for tracking information about specific entities.

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

Bases: Memory

Memory system for tracking entities (people, organisations, concepts).

Maintains a lightweight knowledge graph of entities and their relationships. Entities are automatically extracted from stored text using pattern-matching heuristics (capitalised phrases and quoted strings), and relationships are detected from common verb patterns (e.g. “works at”, “knows”, “created”).

entities#

Dictionary mapping entity names to tracking metadata including first_seen, last_seen, frequency, and contexts (snippet list).

relationships#

Dictionary mapping relation types (e.g. "knows") to lists of (entity1, entity2) tuples.

entity_mentions#

Dictionary mapping entity names to lists of memory IDs in which that entity was mentioned.

Example

>>> from calute.memory import EntityMemory
>>> em = EntityMemory()
>>> item = em.save("Alice works at Acme Corp")
>>> em.get_entity_info("Alice")
{'first_seen': ..., 'frequency': 1, ...}
clear() → None[source]#

Clear all memories, entities, relationships, and mention tracking.

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

Delete a memory item and update entity mention tracking.

Removes the item from the in-memory index and list, cleans up entity mention references, and deletes from the storage backend if configured.

Note

Filter-based bulk deletion is accepted by the signature for interface compatibility but is not currently implemented.

Parameters

  • memory_id – UUID of the specific memory item to delete.

  • filters – Reserved for future filter-based bulk deletion.

Returns

Number of items deleted (0 or 1).

get_entity_info(entity: str) → dict[str, Any][source]#

Get comprehensive information about an entity.

Collects the entity’s tracking metadata, all memory IDs that mention it, and its direct relationships (both outgoing and inverse incoming).

Parameters

entity – The entity name to look up (case-sensitive).

Returns

  • All stored tracking fields (first_seen, last_seen, frequency, contexts) if the entity exists.

  • "mentions": list of memory IDs referencing this entity.

  • "relationships": list of dicts with "relation" and "target" keys describing outgoing and inverse relations.

Return type

Dictionary containing

Get entities related to the given entity via relationship traversal.

Uses breadth-first search to find connected entities up to max_depth hops away in the relationship graph.

Parameters

  • entity – Starting entity name

  • max_depth – Maximum relationship hops to traverse

Returns

Set of related entity names

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 memory items by ID or filter criteria.

When memory_id is provided, performs an O(1) index lookup. Otherwise iterates through items and applies attribute-based filters.

Parameters

  • memory_id – UUID of a specific memory item to retrieve.

  • filters – Optional key-value criteria matched against item attributes (e.g. {"agent_id": "agent-1"}). Items where any specified attribute does not match are excluded.

  • limit – Maximum number of items to return when using filter-based retrieval.

Returns

A single MemoryItem when memory_id is provided (or None if not found), or a list of matching items.

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

Save a memory item and extract entities from its content.

Entities are either provided explicitly or extracted automatically via _extract_entities(). Relationships between co-occurring entities are also detected and recorded.

Parameters

  • content – Text content to store. Entity extraction heuristics are applied to this text when entities is not provided.

  • metadata – Optional key-value metadata to attach. An "entities" key is added automatically with the resolved entity list.

  • entities – Pre-identified entity names. When None, entities are extracted from content using pattern matching.

  • **kwargs – Additional keyword arguments (currently unused).

Returns

The newly created MemoryItem with entity metadata.

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

Search for memories related to specific entities.

Entities are first extracted from the query (or taken from entity_filter), and then all stored items are scored by the fraction of target entities they mention. Items with no overlapping entities are excluded unless no target entities were identified, in which case a simple substring match is used instead.

Parameters

  • query – Natural-language query. Entity names are extracted from this text when entity_filter is not provided.

  • limit – Maximum number of results to return.

  • filters – Optional key-value criteria matched against item attributes (e.g. {"agent_id": "agent-1"}).

  • entity_filter – Explicit list of entity names to search for. Overrides automatic extraction from query.

  • **kwargs – Additional keyword arguments (currently unused).

Returns

List of MemoryItem instances sorted by relevance (entity overlap ratio), with at most limit entries.

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

Update a memory item and re-extract entities if content changes.

When the "content" field is included in updates, the old entity mentions are removed and new entities are extracted from the updated content. Changes are persisted to storage if configured.

Parameters

  • memory_id – UUID of the memory item to update.

  • updates – Dictionary mapping attribute names to their new values. When "content" is present, entity mention tracking is refreshed automatically.

Returns

True if the item was found and updated, False if memory_id was not found in the index.

Contents